instar 1.3.124 → 1.3.125

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.124",
+  "version": "1.3.125",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

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

package/upgrades/1.3.125.md

@@ -0,0 +1,62 @@
+# Instar Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Fixed the ROOT of duplicate agent-to-agent replies: `POST /messages/relay-agent`
+now responds at the accept boundary instead of after the session spawn.** The
+co-located inbound handler used to AWAIT `handleInboundMessage` — a session
+spawn/resume that routinely takes 9-30 s — before responding. But the sender
+(`MessageRouter.relay`) uses a 5-second fetch timeout and reads only whether the
+request succeeded. So whenever the receiver's spawn outran 5 s, the sender gave
+up, retried with a fresh message id, and the receiver spawned a SECOND session →
+a duplicate reply. The content-hash dedup shipped earlier is the symptom
+backstop; this removes the cause. The handler now responds `{ ok:true,
+accepted:true, threadline:{accepted:true, async:true} }` the instant the message
+is accepted + gated, and runs the spawn in the background. Everything that must
+happen first — the dedup, the reply-waiter resolution, and the warrants-reply
+gate (including its suppress short-circuit) — still runs synchronously before the
+response. Scoped to the co-located path; the cross-machine relay-funnel path
+(which has retry-on-error semantics to preserve) is tracked separately.
+
+## Summary of New Capabilities
+
+- No new capability — a robustness fix. Agent-to-agent messages on the same
+  machine no longer risk a duplicate reply when the receiver's session spawn is
+  slower than the sender's 5-second delivery timeout.
+
+## What to Tell Your User
+
+Agents talking to each other on the same machine no longer occasionally send the
+same reply twice. The cause was that a receiving agent waited until it had fully
+spun up a session — up to half a minute — before telling the sender the message
+arrived, but the sender only waits five seconds and would resend. Now the
+receiver acknowledges the moment the message is safely accepted and does the
+slow work in the background, so the sender never times out and never resends.
+Nothing changes for you; the real reply still arrives as before, just without the
+occasional duplicate.
+
+## Evidence
+
+**Reproduction / root cause.** Confirmed in the code: the co-located sender
+`MessageRouter.relayToAgent` (`src/messaging/MessageRouter.ts:486-510`) wraps its
+POST to `/messages/relay-agent` in `AbortSignal.timeout(5000)` and returns only
+`response.ok`. The receiver's handler awaited `handleInboundMessage` (a 9-30 s
+session spawn) before responding, so any spawn over 5 s aborted the sender's
+fetch → the sender retried with a fresh `message.id`, which slips past the
+id-based relay dedup → a second spawn and a duplicate reply. (The 2026-05-30
+duplicate-reply incidents on the echo↔codey loop are this path.)
+
+**Before / after.** Before: the response is sent only after the full spawn. After:
+the response is `{accepted:true, async:true}` sent at the accept boundary, with
+the spawn running in the background. The rewritten integration test holds the
+background handler open and asserts the HTTP response returns while the handler
+is still mid-spawn (`router-start` present, `router-end` not yet) — i.e. the
+sender is no longer made to wait. The handler still runs to completion in the
+background (not dropped); a background rejection still yields HTTP 200; the
+reply-waiter resolution and the warrants-reply gate's suppress short-circuit stay
+green; the content-hash dedup suite and the keystone gate-before-spawn wiring
+test stay green. An independent second-pass reviewer audited the change (it
+touches inbound messaging) and confirmed correctness after one artifact-honesty
+correction.

package/upgrades/side-effects/relay-agent-accept-boundary.md

@@ -0,0 +1,128 @@
+# Side-Effects Review — relay-agent accept-boundary (duplicate-reply root)
+
+**Version / slug:** `relay-agent-accept-boundary`
+**Date:** 2026-05-30
+**Author:** Echo (instar-dev agent)
+**Second-pass reviewer:** REQUIRED (inbound agent-to-agent messaging path) — verdict appended below
+
+## Summary of the change
+
+`POST /messages/relay-agent` (`src/server/routes.ts`) now responds at the accept
+boundary — `{ ok:true, accepted:true, threadline:{accepted:true, async:true} }`
+— instead of awaiting `handleInboundMessage` (a 9-30 s session spawn) before
+responding. The spawn runs in the background (`void` + logged `.then`/`.catch`).
+This removes the duplicate-reply ROOT: the co-located sender
+(`MessageRouter.relay`) uses `AbortSignal.timeout(5000)` and reads only
+`response.ok`, so awaiting the spawn past 5 s made it retry with a fresh id →
+duplicate spawn. Scoped to the co-located path only; the relay-funnel path is
+tracked separately.
+
+## Decision-point inventory
+
+- No decision is added or changed. The accept decision (`relay`) and the
+  warrants-reply gate already ran upstream and are unchanged. This only moves
+  WHEN the HTTP response is sent relative to the background spawn —
+  modify (pass-through of the decision, not a new decision).
+
+---
+
+## 1. Over-block
+No block/allow surface added. The change responds *sooner*; it rejects nothing
+it didn't reject before (auth, envelope-validation, dedup, and the
+warrants-reply suppress path are all unchanged and still run before the
+response).
+
+## 2. Under-block
+The warrants-reply gate's suppress→short-circuit is preserved and still runs
+synchronously before the spawn, so a no-reply verdict still prevents the spawn.
+The only thing no longer surfaced synchronously is the spawn OUTCOME
+(spawned/handled/error) — which no caller reads (see §5/§6); it is logged.
+
+## 3. Level-of-abstraction fit
+Correct layer — the fix is at the HTTP handler that owns the request/response
+lifecycle for this path. The decision of WHAT to do (accept, gate, spawn) is
+unchanged; only the response timing within the handler moves.
+
+## 4. Signal vs authority compliance
+Compliant. No authority added. The handler already held the accept + gate
+authority upstream; the change carries no new gate and fails safe (a background
+error is logged, never surfaced as a 500 on an already-sent response).
+
+## 5. Interactions
+- **Sender (`MessageRouter.relay`, src/messaging/MessageRouter.ts:494-505):**
+  reads ONLY `response.ok` within a 5 s `AbortSignal.timeout` — verified. The
+  accept-boundary gives it a fast `ok` and never the spawn fields it never
+  read.
+- **Reply-waiter mechanism:** resolved synchronously BEFORE the response
+  (unchanged) — the actual reply path is decoupled from this response. Tests
+  for waiter-by-threadId stay green.
+- **Content-hash dedup (#573):** runs before the response, unchanged; remains
+  the backstop for any retry that still slips through.
+- **Keystone gate-before-spawn:** the warrants-reply gate still runs before the
+  (now async) spawn; the wiring test asserting that ordering stays green (made
+  formatting-robust).
+- **No double-fire:** the spawn runs exactly once per accepted message, just
+  asynchronously.
+
+## 6. External surfaces
+- The `/messages/relay-agent` response body changes from `{ok, threadline:
+  <spawnResult>}` to `{ok, accepted, threadline:{accepted, async}}`. Audited
+  consumers:
+  - `MessageRouter.relayToAgent` (`src/messaging/MessageRouter.ts:486-510`) —
+    reads ONLY `response.ok` within `AbortSignal.timeout(5000)`. Fully satisfied
+    by the fast `ok`; never read the spawn fields. No behavior change.
+  - **`/threadline/relay-send` local fast-path** (`src/server/routes.ts:13824-
+    13835`) — the SENDER side of this same co-located hop reads
+    `threadline.{injected,spawned,resumed,gateDecision,error,handled}` to build
+    an informational `deliveryOutcome` string (logged + returned to the calling
+    agent's `threadline_send` MCP result via `mcp-http-client` →
+    `ThreadlineMCPServer:575`). With the accept-boundary those fields are
+    `undefined`, so `outcome` falls through to the existing default `'accepted'`
+    (previously e.g. `'spawned new session'`/`'resumed existing thread'`). This
+    is a **cosmetic/observability degradation only**: `delivered` is computed as
+    `!outcome.startsWith('error')`, and `'accepted'` is not an error, so
+    `delivered` stays `true` exactly as before; `outcome` gates no retry, no
+    delivery, no reply-wait. `'accepted'` is also the HONEST value — the local
+    send IS accepted and processing async. (Found by the Phase-5 reviewer; the
+    original draft of this section wrongly claimed `MessageRouter.relay` was the
+    only consumer.)
+- The change is invisible to the sender's actual behavior (fast ack) and to the
+  user (the real reply still arrives via the session, just without a 30 s sender
+  hang and without the occasional duplicate).
+- No new route, no new message.
+
+## 7. Rollback cost
+Trivial — revert the one handler block (re-await + return the result) and the
+test rewrite. No data, no migration. The content-hash dedup stays as the
+symptom backstop regardless.
+
+---
+
+## Phase 5 — Second-pass reviewer verdict
+
+An independent reviewer subagent adversarially audited the artifact AND the
+actual handler code (not just the claims), and **raised one concern — now
+addressed**:
+
+- **Concern (artifact overstatement, not a code bug):** §6's original draft
+  claimed `MessageRouter.relay` + the test suite were the only consumers. The
+  reviewer found a SECOND consumer — the `/threadline/relay-send` local
+  fast-path (`routes.ts:13824-13835`) reads the spawn-outcome fields to compute
+  an informational `deliveryOutcome`. **Resolution:** §6 corrected above to name
+  this consumer and document that it degrades gracefully to the existing
+  `'accepted'` outcome — `delivered` stays `true` (`'accepted'` is not an
+  error), no retry/delivery/correctness impact. The CODE is safe to ship as-is;
+  only the artifact's honesty needed the fix.
+
+- **What the reviewer verified as correct (the core change is sound):** handler
+  ordering preserved — dedup, reply-waiter resolution, and the warrants-reply
+  gate's `suppress`→short-circuit all still run synchronously BEFORE the
+  response; `handleInboundMessage` is called exactly once (never dropped), its
+  rejection caught (can't 500 an already-sent response); the reply-waiter path
+  is decoupled and unbroken; the sole co-located sender reads only `response.ok`
+  within the 5 s timeout, so the accept-boundary genuinely removes the
+  duplicate-reply root; no test breaks; the rewritten test asserts the right
+  things (returns before `router-end`, no spawn fields, background completion,
+  error → still 200).
+
+Verdict after the §6 correction: concern resolved; change is correct and safe.