instar 1.3.50 → 1.3.52

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-28T04:22:02.259Z",
-  "instarVersion": "1.3.50",
+  "generatedAt": "2026-05-28T06:51:41.833Z",
+  "instarVersion": "1.3.52",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {
@@ -409,7 +409,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -417,7 +417,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -425,7 +425,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -433,7 +433,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -441,7 +441,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -449,7 +449,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -457,7 +457,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -465,7 +465,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -473,7 +473,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -481,7 +481,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -489,7 +489,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -497,7 +497,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -505,7 +505,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -513,7 +513,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -521,7 +521,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -529,7 +529,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -537,7 +537,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -545,7 +545,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -553,7 +553,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -561,7 +561,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -569,7 +569,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -577,7 +577,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -585,7 +585,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -593,7 +593,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -601,7 +601,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -609,7 +609,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -617,7 +617,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -625,7 +625,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -633,7 +633,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -641,7 +641,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -649,7 +649,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -657,7 +657,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -665,7 +665,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -673,7 +673,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -681,7 +681,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -689,7 +689,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -697,7 +697,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -705,7 +705,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -713,7 +713,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -721,7 +721,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -729,7 +729,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -737,7 +737,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -745,7 +745,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -761,7 +761,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "dc3bf7dc7f07613be4717b02dc3dfa5ffae4a5e8faa1c401ab1947c010002afb",
+      "contentHash": "02158bbab251ccad90f9db38cdfc4836f3d5560fa553f32abba30732b11f4f05",
       "since": "2025-01-01"
     },
     "cli:init": {
@@ -1457,7 +1457,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "d018d7dbd90c5f2564b2049376658c077e506fdc26c36689f4debe0d4e1d5c3e",
+      "contentHash": "1b85f747d68975a430434c51a1958c48dca6652021fcc2ce877bf7ccff172c9a",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {

package/upgrades/1.3.51.md

@@ -0,0 +1,62 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: minor -->
+
+## What Changed
+
+**Same-machine a2a transport via `/a2a/inbox`.** PR #462 + #464 shipped the
+receiver wiring + lifeline-forward dispatch path. Dogfood then surfaced the
+root cause they couldn't reach: **Telegram structurally blocks bot-to-bot
+delivery**. From the Bot API FAQ: "bots will not be able to see messages from
+other bots regardless of mode." Echo's mentor bot can SEND to a chat, but no
+other bot's `getUpdates` ever receives those messages — privacy mode,
+`can_read_all_group_messages`, admin status, none of it overrides the rule.
+
+This PR adds the canonical same-machine transport: a new `/a2a/inbox` HTTP
+endpoint. The mentor side, on `deliverToMentee`, looks up the mentee in the
+local `AgentRegistry`; if it finds a registered local peer, it POSTs the
+a2a-marker text directly to peer:port/a2a/inbox. The inbox handler invokes
+the same `dispatchAgentMessageHook` that polling + telegram-forward use, so
+the receiver wiring is the same code path. The Telegram bot path is preserved
+as a fallback (currently unreachable for cross-machine peers due to the same
+block — a separate architectural problem tracked as future work).
+
+The flow end-to-end (same-machine):
+
+1. Echo's mentor runner calls `deliverToMentee('codex-cli', body)`.
+2. Echo finds `instar-codex-cli` in AgentRegistry → POSTs to
+   `http://localhost:PORT/a2a/inbox` with the marker + body.
+3. Inbox auth-checks via `verifyAgentToken` (same trust model as
+   `/messages/relay-agent`).
+4. Inbox invokes `ctx.telegram.dispatchAgentMessageHook(...)` with
+   `senderIsBot: true` (peers holding our token are bots by construction).
+5. The mentee receiver hook (installed via `config.mentee.enabled`) routes to
+   the `mentor` role-handler → spawn session → reply path via
+   `sendAgentMessage(role='mentor-reply', corr=<id>)`.
+
+**Migration parity** is automatic: no new config keys, the `mentee` block from
+PR #462 is unchanged, and the inbox route is additive.
+
+## What to Tell Your User
+
+For agents on the same machine, mentor cycles now actually deliver. The
+earlier release set up the receiver hook correctly but couldn't reach it in
+production — Telegram itself blocks bots from seeing each other's messages.
+This update routes mentor deliveries directly between local instar servers
+when possible, so the round-trip works end-to-end. No config changes needed.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| `POST /a2a/inbox` | Same-machine a2a transport. Bearer must match the target agent's per-agent token (from AgentRegistry). Payload: `{ text, topicId, senderAgent, senderIsBot?, senderBotId? }`. Returns `{ ok, agentMessage: true/false, reason? }`. |
+| Automatic same-machine routing in `deliverToMentee` | When the mentee is registered as a local peer, the mentor delivers via HTTP `/a2a/inbox` instead of the Telegram bot path. Telegram bot fallback preserved for cross-machine (currently doesn't deliver due to the bot-to-bot block; tracked). |
+
+## Evidence
+
+12 new tests, all green: 8 integration on the `/a2a/inbox` route (auth
+shape, 401 cases, 503 no-adapter, 400 bad input, 200 routed, 200 not-routed,
+senderIsBot default), 4 E2E lifecycle (hook installed at boot, route alive,
+auth-gated, full claim path with the recording adapter). `tsc --noEmit`
+clean. Side-effects review:
+`upgrades/side-effects/a2a-inbox-http-transport.md`.

package/upgrades/1.3.52.md

@@ -0,0 +1,39 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**"Open this" topics now arrive named + summarized.** When you promote a Threadline
+conversation into its own topic ("open this" in the Threadline hub), the new topic used to
+get a crude name (the first ~5 words of the cold message) and a single generic "tied to this
+topic" marker — an unlabelled, empty room. Now an LLM names the topic from what the
+conversation is actually about and writes a short orientation summary as the first message
+(who the other agent is, what it's about, where it stands), so you walk in oriented.
+
+This is strictly additive on top of the deterministic "open this" intercept. It NEVER fails
+the bind: if the LLM can't run (timeout, daily spend cap, rate-limit, scrubbed output, or
+the deps aren't wired in your build), "open this" degrades to a deterministic templated brief
+(peer · message count · last activity · latest line) — and only falls back to the bare marker
+when there's literally no conversation behind the entry yet. The LLM is a generator, never a
+gate. The naming/summary call runs on the shared interactive LLM lane (you're waiting on it)
+with a 3.5s ceiling, ~1 cent per call, governed by the existing daily spend cap.
+
+Credential scrubbing uses value-pattern detection (actual `sk-…`/`xoxb-…`/`ghp_…`/key blocks),
+not bare english words — so a legitimate technical topic ("token refresh triage", "API key
+rotation") is named normally, while a pasted secret never lands in your chat-list title or the
+first message.
+
+## What to Tell Your User
+
+Nothing to do — it's automatic. Next time you "open this" in the Threadline topic, the new
+topic shows up with a real name and a short summary of the conversation inside it, instead of
+an empty room. "Tie this to <existing topic>" is unchanged. (The topic takes a few seconds to
+appear while the summary is generated; if the model is slow you still get an instant plain brief.)
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| "Open this" topics are LLM-named + summarized | In the Threadline hub topic, say "open this" — the new topic gets an LLM-generated name and a summary of the conversation as its first message. Automatic; no command or flag. |
+| Always-contextful fallback | If the LLM can't run (timeout / daily cap / unwired), the new topic still gets a deterministic templated brief (peer · message count · last activity · latest line) instead of the old empty marker. The bind never fails on LLM trouble. |

package/upgrades/side-effects/a2a-inbox-http-transport.md

@@ -0,0 +1,128 @@
+# Side-Effects Review — same-machine a2a transport via `/a2a/inbox`
+
+**Spec:** `docs/specs/MENTOR-LIVE-READINESS-SPEC.md` §Recipient side. Third
+fast-follow to PR #462 (receiver wiring) + PR #464 (lifeline-forward
+dispatch). Closes the bot-to-bot-block gap surfaced by dogfood.
+
+**Root cause being addressed:** Telegram Bot API structurally blocks
+bot-to-bot delivery: "Bots talking to each other could potentially get stuck
+in unwelcome loops. To avoid this, we decided that bots will not be able to
+see messages from other bots regardless of mode." (Bot API FAQ.) The spec
+assumed `Echo's mentor bot → Codey's primary bot via shared chat → Codey's
+lifeline forwards` would work. Empirically it doesn't — verified by sending
+4 marker messages to topic 458, Codey's bot poll-offset never advances past
+them, his lifeline-forward stays silent.
+
+**Change:** Three production files + two test files.
+- `src/server/routes.ts` (+ ~70 LoC: new `/a2a/inbox` POST route)
+- `src/server/middleware.ts` (+ 2 LoC: skip the API bearer middleware for
+  `/a2a/inbox` — uses per-agent token like `/messages/relay-agent`)
+- `src/server/AgentServer.ts` (+ ~75 LoC: same-machine path in
+  `deliverToMentee` via AgentRegistry + `fetch` to peer's `/a2a/inbox`,
+  before the Telegram bot fallback)
+- `tests/integration/a2a-inbox-route.test.ts` (new, 8)
+- `tests/e2e/a2a-inbox-lifecycle.test.ts` (new, 4)
+
+## What changed
+
+1. **`POST /a2a/inbox`** on every instar server. Accepts:
+   `{ text, topicId, senderAgent?, senderIsBot?, senderBotId?, fromUserId? }`.
+   Auth: Bearer token must match the target agent's per-agent token
+   (`verifyAgentToken` — same shape as `/messages/relay-agent`). Behaviour:
+   - 401 if bearer is missing or wrong
+   - 503 if no `ctx.telegram` adapter is configured at all (no hook surface)
+   - 400 if `text` (string) or `topicId` (number) are missing / malformed
+   - 200 `{ ok, agentMessage: true }` when the adapter's
+     `dispatchAgentMessageHook` claims the message
+   - 200 `{ ok, agentMessage: false, reason: 'not-routed' }` when the hook
+     refuses (no marker / malformed / not-allowlisted / not-allowed-role).
+     The route is dedicated to a2a — non-routable messages are NOT forwarded
+     to user-message handling.
+   - `senderIsBot` defaults to `true` if omitted — local peers holding our
+     agent token are bots by construction (the spoof defense is satisfied
+     by the bearer-token check upstream).
+2. **Auth middleware bypass for `/a2a/inbox`** — alongside the existing
+   `/messages/relay-agent` and `/messages/relay-machine` bypasses, since the
+   inbox enforces its own per-agent-token auth in-handler. Without this
+   bypass the API bearer middleware (using `config.authToken`) would 403
+   the request, because the caller holds the TARGET's per-agent token,
+   not the API bearer.
+3. **Same-machine routing in `deliverToMentee`** — before the existing
+   Telegram bot delivery, the method now:
+   - Imports `listAgents` from AgentRegistry + `getAgentToken` from the
+     token manager (lazy-imported inside the closure to avoid loading the
+     registry on every server boot).
+   - Looks up the mentee by `name === menteeAgent && name !== self.config.projectName`
+     (anti-self-target).
+   - If a local peer with a port is found AND we have the peer's token,
+     POSTs to `http://localhost:PORT/a2a/inbox` with the marker text +
+     sender context. On `agentMessage: true`, marks the outstanding-prompt
+     tracker as sent and audits a `transport: 'a2a-inbox-local'` row in
+     the sent-ledger.
+   - On any failure (no peer, no token, HTTP error, hook refused) logs and
+     falls through to the existing Telegram bot path (preserved unchanged
+     for cross-machine; currently unreachable due to the same bot-to-bot
+     block — a separate cross-machine transport is future work).
+   - The anti-ping-pong check (`outstanding.canSendTo`) runs ONCE before
+     either transport so the same correlation key gates both paths.
+
+## The seven questions
+
+1. **Over-block.** N/A. The inbox is a NEW dedicated endpoint; the route
+   refuses non-routable traffic with `agentMessage: false` but never
+   forwards to user handling. No existing route's behaviour changes.
+2. **Under-block.** Spoof defense is intact: per-agent token bearer auth
+   gates the route. `senderIsBot` defaulting to `true` is correct because
+   the peer authenticated with the target's own token — the spoof defense
+   it would otherwise enforce is satisfied earlier by the bearer check.
+   Anti-ping-pong: `outstanding.canSendTo` runs before either transport so
+   one outstanding prompt blocks both paths.
+3. **Level-of-abstraction fit.** Mirrors `/messages/relay-agent`'s pattern
+   exactly: own route, own auth, dispatch into existing in-process state.
+   No new abstraction.
+4. **Signal vs authority.** Inbox DECIDES route-or-drop via the hook (the
+   hook's existing routing matrix is the spec); audit ledger captures the
+   result. `deliverToMentee` DECIDES transport (local vs Telegram). All
+   audited; no silent paths.
+5. **Interactions.** Reuses AgentRegistry + AgentTokenManager (same APIs
+   already used by `/messages/relay-agent`). Reuses
+   `getOrCreateA2aLedger` + `getOrCreateMentorOutstanding` from the mentor
+   sender side. Reuses `dispatchAgentMessageHook` from PR #464. No new
+   shared mutable state.
+6. **External surfaces.** One new HTTP route (`/a2a/inbox`). One new
+   audit-ledger transport value (`'a2a-inbox-local'`). No new config keys.
+7. **Rollback cost.** Trivial — revert removes the route, the middleware
+   bypass, and the same-machine branch in `deliverToMentee`. The Telegram
+   bot path is untouched and preserved.
+
+## Testing
+
+12 new tests, all green (`tsc --noEmit` clean):
+
+- **Tier 2 integration (8):** `a2a-inbox-route` covers the auth + input-
+  validation matrix (401 missing bearer, 401 wrong bearer, 503 no adapter,
+  400 missing text, 400 bad topicId, 200 routed, 200 not-routed, 200 with
+  default senderIsBot:true).
+- **Tier 3 E2E lifecycle (4):** `a2a-inbox-lifecycle` covers full server
+  boot with the mentee receiver wiring + the inbox route alive (not 404),
+  auth-gated, and the full claim path that proves the inbox invokes the
+  adapter dispatcher end-to-end on the real production init path.
+
+A unit-tier slice for the same-machine branch in `deliverToMentee` is
+deferred — covered transitively by the E2E + the existing unit suite for
+`OutstandingPromptTracker` + the new integration test for the inbox route.
+A dedicated unit on the `deliverToMentee` branch would require mocking
+`fetch` + AgentRegistry + getAgentToken — defensible to add later but the
+behaviour is already tested at the boundary.
+
+## Migration parity
+
+No new config keys. The route registers unconditionally; if no
+`config.mentee.enabled` block is set on the receiver, the adapter has no
+hook installed and the route returns `agentMessage: false`. The
+`/messages/relay-agent` precedent is identical (always-registered route,
+behaviour depends on installed state).
+
+The `deliverToMentee` change is purely additive — when no local peer is
+registered, behaviour is byte-for-byte the same as before. No PostUpdateMigrator
+change required.