instar 1.3.314 → 1.3.315

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.314",
+  "version": "1.3.315",
   "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-06-05T18:49:31.951Z",
-  "instarVersion": "1.3.314",
+  "generatedAt": "2026-06-05T19:05:04.256Z",
+  "instarVersion": "1.3.315",
   "entryCount": 199,
   "entries": {
     "hook:session-start": {
@@ -418,7 +418,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -426,7 +426,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -434,7 +434,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -442,7 +442,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -450,7 +450,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -458,7 +458,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -466,7 +466,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -474,7 +474,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -482,7 +482,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -490,7 +490,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -498,7 +498,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -506,7 +506,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -514,7 +514,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -522,7 +522,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -530,7 +530,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -538,7 +538,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -546,7 +546,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -554,7 +554,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -562,7 +562,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -570,7 +570,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -578,7 +578,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -586,7 +586,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -594,7 +594,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -602,7 +602,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -610,7 +610,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -618,7 +618,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -626,7 +626,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -634,7 +634,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -642,7 +642,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -650,7 +650,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -658,7 +658,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -666,7 +666,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -674,7 +674,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -682,7 +682,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -690,7 +690,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -698,7 +698,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -706,7 +706,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -714,7 +714,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -722,7 +722,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -730,7 +730,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -738,7 +738,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -746,7 +746,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -754,7 +754,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -770,7 +770,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "26dde9a216b2facadce61a94d60df46175292843555fdf095cf7dd6075420a82",
+      "contentHash": "5c3d0c3cc5bc87d76aa8560c569c883d93f3874d00f121df15663cb4549837a4",
       "since": "2025-01-01"
     },
     "cli:init": {

package/upgrades/1.3.315.md

@@ -0,0 +1,41 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The server now refuses to deliver any agent→user message that contains a
+clickable machine-local link (`http://localhost:…`, `127.x.x.x`, `0.0.0.0`,
+`[::1]`). Users are almost never on the machine the agent's server runs on —
+such links are unopenable from their device. The send is rejected with a 422
+whose error text tells the agent exactly how to fix it: fetch the public
+tunnel URL (`GET /tunnel`) and substitute, or omit the link and say it will
+follow. Prose mentions of localhost/ports still pass — only clickable links
+are policed.
+
+## What to Tell Your User
+
+Nothing to configure. If you ever asked your agent for a dashboard or view
+link and received a localhost address you couldn't open — that mistake is
+now structurally impossible; you'll always get the public tunnel link.
+
+## Summary of New Capabilities
+
+- Localhost-link guard at the outbound message chokepoint (all user-facing
+  channels: Telegram, Slack, WhatsApp, iMessage). Deterministic, independent
+  of the LLM tone gate, active even where no gate is configured.
+- Agent guidance lives in the rejection itself: the 422 names the offending
+  link and the remediation, so the failure self-corrects in one round trip.
+- Rare deliberate sends of a raw local URL (operator explicitly asked):
+  resend with `metadata.allowLocalhostLink: true` on `/telegram/reply`.
+- Maturity: stable (deterministic guard + tests; no config surface).
+
+## Evidence
+
+Born from a real 2026-06-05 incident: an agent sent its operator
+`http://localhost:4040/dashboard` over Telegram — unopenable from the phone,
+and the port belonged to a DIFFERENT agent on the same machine. 25 tests
+green (20 detector cases incl. the incident string and boundary hostnames
+like localhost.example.com; 5 route-level cases over real HTTP proving 422 +
+no-send, tunnel-link pass, and the escape hatch); `tsc --noEmit` clean.

package/upgrades/localhost-link-guard.eli16.md

@@ -0,0 +1,32 @@
+# Localhost-Link Guard — Plain-English Overview
+
+> The one-line version: the server now refuses to send a user any message containing a `localhost` link, because the user is almost never sitting on the machine that link points at.
+
+## The problem in one breath
+
+An agent shared its dashboard with the operator by sending `http://localhost:4040/dashboard` over Telegram. The operator was on his phone — a localhost link points at *the phone itself*, so it can never work. Worse, the port was wrong too (it belonged to a different agent on the same machine). The operator called for a strong rule: never send localhost links to a user, ever.
+
+## What already exists
+
+- **The outbound message gate** — every agent-authored message to a user already passes through one checkpoint on the server before it reaches Telegram (or Slack/WhatsApp/iMessage). An LLM reviewer there catches tone problems and technical leakage.
+- **The tunnel** — every agent already has a public HTTPS address (the Cloudflare tunnel) that works from any device. That is the link users should always get.
+- **Hard deterministic checks** — some rules don't need an LLM's judgment: a message over 4096 characters is rejected flat. This guard joins that family.
+
+## What this adds
+
+A deterministic check at that same chokepoint: if an outgoing user message contains a clickable `http(s)://localhost`, `127.x.x.x`, `0.0.0.0`, or `[::1]` link, the send is rejected with a clear explanation telling the agent to use the public tunnel URL instead (and exactly how to fetch it). The agent gets corrected at the moment of the mistake — no memory or willpower required, and it works fleet-wide the moment a server updates.
+
+- Only **clickable links** are policed. Prose like "my server listens on port 4042" or "the localhost config" passes — the rule is about links a user might tap, not about discussing local machinery.
+- Hostnames that merely *start* with localhost (like `localhost.example.com`) are not flagged — the matcher requires a real loopback host.
+- A narrow escape hatch exists for the rare case where the operator explicitly asks to see the raw local URL: the sender can mark the message `allowLocalhostLink: true` and it goes through.
+- The guard runs even on installs that have no LLM tone gate configured at all — it's independent of that machinery.
+
+## What does NOT change
+
+- Nothing about how tunnel links are generated or shared.
+- Agent-to-agent (Threadline) messages are untouched — this is strictly the agent→user path.
+- System-template messages (sentinel alerts etc.) were already reviewed at code-review time and keep their existing bypass.
+
+## Why a hard block instead of a warning
+
+A localhost link in a user-bound message has no legitimate reading — the user cannot open it. Warning-and-send would still deliver a broken link; rejecting forces the agent to re-send with the working one. The rejection message itself teaches the fix, so the failure is self-correcting in one round trip.

package/upgrades/side-effects/localhost-link-guard.md

@@ -0,0 +1,58 @@
+# Side-effects review — localhost-link guard at the outbound message chokepoint
+
+Operator-mandated STRONG RULE (Justin, 2026-06-05, after receiving
+`http://localhost:4040/dashboard` on his phone — unopenable AND the wrong
+agent's port): never send a machine-local link to a user.
+
+## 1. The change
+
+- **`src/core/localhost-link.ts`** (new) — `detectLocalhostLink(text)`:
+  deterministic regex over SCHEME-BEARING links only
+  (`http(s)://localhost | 127.x.x.x | 0.0.0.0 | [::1]`, any port/path), with a
+  host-boundary lookahead so loopback-looking PREFIXES of public hostnames
+  (`localhost.example.com`) do NOT match. Prose mentions ("port 4042",
+  "localhost config") never match — only clickable links are policed.
+- **`src/server/routes.ts`** — `checkOutboundMessage()` (the SINGLE authority
+  for agent→user delivery across telegram/slack/whatsapp/imessage call sites)
+  gains a deterministic block BEFORE the tone-gate availability early-return:
+  detected link → 422 `{ blockedBy: 'localhost-link-guard', match, error }`
+  with remediation in the error text (fetch `GET /tunnel`, substitute, or omit
+  + follow up). New option `allowLocalhostLink` (deny-by-default escape hatch)
+  plumbed from `metadata.allowLocalhostLink` at the `/telegram/reply` call
+  site only.
+
+## 2. Why a hard deterministic block (not a tone-gate signal)
+
+Per docs/signal-vs-authority.md, detectors whose verdict needs conversational
+judgment emit signals for the LLM authority. A loopback link in a user-bound
+message has NO legitimate reading — like the 4096-length check, it's a fact,
+not a judgment. Blocking also makes the failure self-correcting: the 422 text
+tells the sending agent exactly how to fix and re-send.
+
+## 3. Blast radius
+
+- All user-facing channel sends that flow through `checkOutboundMessage`
+  enforce the rule the moment a server updates — fleet-wide, no migration
+  needed (server-side change only; no template/hook/config surface).
+- Paths that SKIP `checkOutboundMessage` keep their existing behavior:
+  proxy messages (`metadata.isProxy`), matched system templates, and
+  standby→holder relays (the holder gates on receipt, so the rule still
+  applies there).
+- False-positive risk: bounded by the scheme requirement + host boundary;
+  the unit matrix covers tunnel links, prose mentions, path-embedded
+  "localhost", `ssh://` schemes, and `localhost.example.com` as passes.
+- Agent ergonomics: a blocked agent sees the remediation in the error; the
+  escape hatch requires an explicit per-message opt-in, so it cannot become
+  ambient.
+
+## 4. Test coverage
+
+- `tests/unit/localhost-link.test.ts` — 20 cases: 9 detection shapes
+  (ports, paths, case, IPv6, bare host, the real incident string, markdown
+  punctuation boundaries) + 11 pass shapes (tunnel/public links, prose,
+  boundary hostnames, empty).
+- `tests/unit/localhost-link-guard-route.test.ts` — 5 route-level cases over
+  real HTTP against `createRoutes` with NO tone gate configured: 422 +
+  `blockedBy` + no send for localhost/127.0.0.1; 200 + send for tunnel link
+  and prose; escape hatch honored.
+- `npx tsc --noEmit` clean.