instar 1.3.484 → 1.3.486

package/src/templates/scripts/telegram-reply.sh

@@ -18,6 +18,28 @@
 #   --stdin-base64    Decode stdin/argument text from base64 before sending.
 #                     Use this for content that may contain shell syntax or
 #                     heredoc delimiters such as a literal EOF line.
+#   --ack-advisory    Acknowledge a preflight advisory and send the message
+#                     unchanged. The preflight still runs (so the override is
+#                     audited) but never withholds. FLAG ONLY — there is
+#                     deliberately no env form (a standing env export would be
+#                     a blanket pre-ack that silently disables the inform
+#                     layer; spec outbound-jargon-filepath-gap §2.4(4)).
+#
+# Outbound advisory preflight (inform-only — spec outbound-jargon-filepath-gap §2.4):
+#   When this send comes from an automated LLM job session (the scheduler
+#   stamps INSTAR_MESSAGE_KIND=automated + INSTAR_SENDER_CLASS=llm-session
+#   into the session env — the model types nothing), the script first asks
+#   the server's deterministic detectors about the text. If they flag
+#   something (raw file path, dev jargon, localhost link), the message is
+#   NOT sent yet: the advisory prints to stdout (so the agent reads it in
+#   its transcript) and the script exits 0. The agent then either fixes the
+#   text and re-runs, or re-runs with --ack-advisory to send unchanged.
+#   The advisory layer NEVER blocks: the ack path always delivers past it,
+#   and every error path (server down, timeout, bad JSON) proceeds straight
+#   to the send as if the preflight returned nothing. Script-class senders
+#   (INSTAR_SENDER_CLASS=script) skip the preflight — there is no agent to
+#   inform. Conversational sessions have none of these env vars and are
+#   completely unaffected.
 #
 # Port resolution (in order):
 #   1. INSTAR_PORT environment variable (explicit operator override).
@@ -33,6 +55,7 @@
 
 FORMAT=""
 STDIN_BASE64=0
+ACK_ADVISORY=0
 
 # Parse leading flags before positional args.
 while [ $# -gt 0 ]; do
@@ -49,6 +72,10 @@ while [ $# -gt 0 ]; do
       STDIN_BASE64=1
       shift
       ;;
+    --ack-advisory)
+      ACK_ADVISORY=1
+      shift
+      ;;
     --)
       shift
       break
@@ -117,11 +144,14 @@ v = c.get('authToken', '')
 print(v if isinstance(v, str) else '')
 print(c.get('projectName', ''))
 print(c.get('port', ''))
+t = (((c.get('messaging') or {}).get('outboundAdvisory') or {}).get('timeoutMs', ''))
+print(t if isinstance(t, (int, float)) else '')
 " 2>/dev/null)
   CONFIG_AUTH=$(printf '%s\n' "$CONFIG_VALUES" | sed -n '1p')
   [ -z "$AUTH_TOKEN" ] && AUTH_TOKEN="$CONFIG_AUTH"
   AGENT_ID=$(printf '%s\n' "$CONFIG_VALUES" | sed -n '2p')
   CONFIG_PORT=$(printf '%s\n' "$CONFIG_VALUES" | sed -n '3p')
+  CONFIG_ADVISORY_TIMEOUT_MS=$(printf '%s\n' "$CONFIG_VALUES" | sed -n '4p')
 fi
 
 if [ -n "$INSTAR_PORT" ]; then
@@ -133,21 +163,162 @@ else
   echo "WARN: telegram-reply.sh — no INSTAR_PORT env and no port in .instar/config.json; falling back to 4040" >&2
 fi
 
-# Build JSON body (text + optional format).
-JSON_BODY=$(python3 -c '
+# ── Outbound advisory preflight (inform-only; spec outbound-jargon-filepath-gap §2.4) ──
+# Validate the scheduler-stamped env values against the literal enums BEFORE
+# use (an unexpected value forwards nothing — the server additionally coerces
+# unknowns server-side).
+MESSAGE_KIND=""
+case "${INSTAR_MESSAGE_KIND:-}" in
+  reply|health-alert|unknown|automated) MESSAGE_KIND="$INSTAR_MESSAGE_KIND" ;;
+esac
+SENDER_CLASS=""
+case "${INSTAR_SENDER_CLASS:-}" in
+  script|llm-session) SENDER_CLASS="$INSTAR_SENDER_CLASS" ;;
+esac
+# Job slug rides the metadata for server-side audit keying; charset-clamped
+# here so it can never carry quotes/injection into a JSON or SQL context.
+JOB_SLUG=$(printf '%s' "${INSTAR_JOB_SLUG:-}" | tr -c 'A-Za-z0-9._-' '_' | head -c 128)
+
+ADVISORY_CODES_CSV=""
+if [ "$MESSAGE_KIND" = "automated" ] && [ "$SENDER_CLASS" = "llm-session" ]; then
+  # Timeout: config messaging.outboundAdvisory.timeoutMs (default 2000ms),
+  # converted ms→SECONDS for curl --max-time with ceil division, clamped to
+  # [1, 10]. A raw `--max-time 2000` would be a ~33-minute fail-HANG and
+  # `$((MS/1000))` on values <1000 would yield 0 = no timeout — both invert
+  # the fail-open contract.
+  ADV_MS="${CONFIG_ADVISORY_TIMEOUT_MS:-2000}"
+  case "$ADV_MS" in (*[!0-9]*|'') ADV_MS=2000 ;; esac
+  ADV_SECS=$(( (ADV_MS + 999) / 1000 ))
+  [ "$ADV_SECS" -lt 1 ] && ADV_SECS=1
+  [ "$ADV_SECS" -gt 10 ] && ADV_SECS=10
+
+  # Preflight body via python3 (already a hard dependency of this script). If
+  # python3 is unavailable the preflight is skipped entirely — fail-open.
+  PREFLIGHT_BODY=$(PF_TOPIC="$TOPIC_ID" PF_SLUG="$JOB_SLUG" PF_KIND="$MESSAGE_KIND" python3 -c '
+import sys, json, os
+print(json.dumps({
+  "text": sys.stdin.read(),
+  "messageKind": os.environ.get("PF_KIND", "automated"),
+  "topicId": int(os.environ.get("PF_TOPIC") or 0),
+  "jobSlug": os.environ.get("PF_SLUG", ""),
+}))
+' <<<"$MSG" 2>/dev/null)
+
+  if [ -n "$PREFLIGHT_BODY" ]; then
+    PREFLIGHT_CURL=(-s -X POST "http://localhost:${PORT}/messaging/preflight"
+      -H 'Content-Type: application/json'
+      --max-time "$ADV_SECS"
+      -d "$PREFLIGHT_BODY")
+    if [ -n "$AUTH_TOKEN" ]; then
+      PREFLIGHT_CURL+=(-H "Authorization: Bearer ${AUTH_TOKEN}")
+    fi
+    if [ -n "$AGENT_ID" ]; then
+      PREFLIGHT_CURL+=(-H "X-Instar-AgentId: ${AGENT_ID}")
+    fi
+    PREFLIGHT_RESP=$(curl "${PREFLIGHT_CURL[@]}" 2>/dev/null)
+
+    # Parse advisories — every failure mode (empty/timeout/malformed/disabled)
+    # yields an empty result and the send proceeds (fail-OPEN end-to-end).
+    ADVISORY_RENDERED=$(printf '%s' "$PREFLIGHT_RESP" | python3 -c '
 import sys, json
+try:
+    resp = json.load(sys.stdin)
+    advisories = resp.get("advisories") or []
+except Exception:
+    advisories = []
+codes = ",".join(a.get("code", "") for a in advisories if isinstance(a, dict) and a.get("code"))
+print(codes)
+for a in advisories:
+    if not isinstance(a, dict):
+        continue
+    print("- " + str(a.get("code", "")))
+    m = a.get("match")
+    if m:
+        # Inert, delimited, quoted token under a fixed label — never spliced
+        # into instruction-shaped prose (injection-pinned rendering).
+        print("  detected: " + json.dumps(str(m)[:120]))
+    g = a.get("guidance")
+    if g:
+        print("  guidance: " + str(g))
+' 2>/dev/null)
+    ADVISORY_CODES_CSV=$(printf '%s\n' "$ADVISORY_RENDERED" | sed -n '1p')
+    ADVISORY_DETAIL=$(printf '%s\n' "$ADVISORY_RENDERED" | sed '1d')
+
+    if [ -n "$ADVISORY_CODES_CSV" ] && [ "$ACK_ADVISORY" != "1" ]; then
+      # Inform the sender BEFORE the user sees anything. The FIRST line is
+      # machine-unmissable and literal (the E2E asserts this exact string).
+      # Exit 0 is deliberate: non-zero means delivery failure and triggers
+      # queue/retry semantics in callers; an advisory is neither — the message
+      # was deliberately not yet sent and the next move belongs to the agent.
+      echo "NOT SENT — advisory (fix and re-run, or re-run with --ack-advisory to send unchanged)"
+      echo ""
+      echo "The outbound advisory flagged this automated message BEFORE delivery:"
+      printf '%s\n' "$ADVISORY_DETAIL"
+      echo ""
+      echo "Next move (yours — the advisory layer never blocks):"
+      echo "  1. FIX: revise the message and re-run this script (preferred)."
+      echo "  2. SEND AS-IS: re-run with --ack-advisory to deliver unchanged (the override is audited)."
+      exit 0
+    fi
+  fi
+fi
+
+# ── Serialized kind metadata — computed ONCE, shared by both body builders
+# AND both queue writers (a queued send must carry the metadata whole so the
+# sentinel redrive doesn't mis-kind it / drop an ack — spec §2.5). Every
+# component is enum-validated or charset-clamped above, so this fragment is
+# safe to interpolate into JSON and (parameterized) SQL contexts.
+METADATA_JSON=""
+if [ -n "$MESSAGE_KIND" ] || [ -n "$SENDER_CLASS" ] || [ -n "$JOB_SLUG" ]; then
+  META_PARTS=""
+  [ -n "$MESSAGE_KIND" ] && META_PARTS="\"messageKind\":\"${MESSAGE_KIND}\""
+  if [ -n "$SENDER_CLASS" ]; then
+    [ -n "$META_PARTS" ] && META_PARTS="${META_PARTS},"
+    META_PARTS="${META_PARTS}\"senderClass\":\"${SENDER_CLASS}\""
+  fi
+  if [ -n "$JOB_SLUG" ]; then
+    [ -n "$META_PARTS" ] && META_PARTS="${META_PARTS},"
+    META_PARTS="${META_PARTS}\"jobSlug\":\"${JOB_SLUG}\""
+  fi
+  if [ "$ACK_ADVISORY" = "1" ] && [ "$MESSAGE_KIND" = "automated" ] && [ "$SENDER_CLASS" = "llm-session" ]; then
+    # REQUIRED annotation (§2.4(4)) — how the server audits "acked" as the
+    # single writer. Carries the overridden codes, including [] for a
+    # preemptive ack on a clean message (itself a signal).
+    ACK_CODES_JSON=$(printf '%s' "$ADVISORY_CODES_CSV" | tr -cd 'A-Z_,' | awk -F',' '{out=""; for(i=1;i<=NF;i++){if($i!=""){out=out (out==""?"":",") "\""$i"\""}} print "["out"]"}')
+    [ -z "$ACK_CODES_JSON" ] && ACK_CODES_JSON="[]"
+    [ -n "$META_PARTS" ] && META_PARTS="${META_PARTS},"
+    META_PARTS="${META_PARTS}\"advisoryAck\":true,\"advisoryCodes\":${ACK_CODES_JSON}"
+  fi
+  METADATA_JSON="{${META_PARTS}}"
+fi
+
+# Build JSON body (text + optional format + optional kind metadata). A
+# conversational session (no kind env) produces the identical body it
+# always did.
+JSON_BODY=$(B_META="$METADATA_JSON" python3 -c '
+import sys, json, os
 msg = sys.argv[1]
 fmt = sys.argv[2]
 body = {"text": msg}
 if fmt:
     body["format"] = fmt
+meta_raw = os.environ.get("B_META", "")
+if meta_raw:
+    try:
+        body["metadata"] = json.loads(meta_raw)
+    except Exception:
+        pass
 print(json.dumps(body))
 ' "$MSG" "$FORMAT" 2>/dev/null)
 
 if [ -z "$JSON_BODY" ]; then
   # Fallback if python3 not available: basic escape, no format override.
+  # BOTH builders must carry the kind fields, or a python-degraded agent
+  # silently drops them and the incident class recurs (spec §2.1).
   ESCAPED=$(printf '%s' "$MSG" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\n/\\n/g')
-  JSON_BODY="{\"text\":\"${ESCAPED}\"}"
+  META_FIELD=""
+  [ -n "$METADATA_JSON" ] && META_FIELD=",\"metadata\":${METADATA_JSON}"
+  JSON_BODY="{\"text\":\"${ESCAPED}\"${META_FIELD}}"
 fi
 
 # Assemble curl args. Always include X-Instar-AgentId when we can resolve it
@@ -293,6 +464,7 @@ except Exception:
       Q_PORT="$PORT" \
       Q_ATTEMPTED_AT="$ATTEMPTED_AT" \
       Q_TRUNCATED="$TRUNCATED" \
+      Q_METADATA="$METADATA_JSON" \
       Q_DB_PATH="$QUEUE_DB" \
       python3 -c '
 import os, sqlite3, sys, json, datetime
@@ -324,7 +496,8 @@ try:
       state TEXT NOT NULL,
       claimed_by TEXT,
       status_history TEXT NOT NULL DEFAULT "[]",
-      truncated INTEGER NOT NULL DEFAULT 0
+      truncated INTEGER NOT NULL DEFAULT 0,
+      message_metadata TEXT
     )""")
     # Idempotent column add for older schemas.
     try:
@@ -332,6 +505,13 @@ try:
     except sqlite3.OperationalError as e:
         if "duplicate column name" not in str(e):
             raise
+    # message_metadata (kind/senderClass/advisoryAck) — the redrive must carry
+    # the metadata whole (spec outbound-jargon-filepath-gap §2.5). Idempotent.
+    try:
+        conn.execute("ALTER TABLE entries ADD COLUMN message_metadata TEXT")
+    except sqlite3.OperationalError as e:
+        if "duplicate column name" not in str(e):
+            raise
     conn.execute("CREATE INDEX IF NOT EXISTS idx_state_next ON entries(state, next_attempt_at)")
     conn.execute("CREATE INDEX IF NOT EXISTS idx_text_hash_topic ON entries(text_hash, topic_id)")
     # 5s dedup window (spec § 2b step 2).
@@ -355,8 +535,8 @@ try:
           delivery_id, topic_id, text_hash, text, format,
           http_code, error_body, attempted_port,
           attempted_at, attempts, next_attempt_at,
-          state, claimed_by, status_history, truncated
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 1, NULL, "queued", NULL, ?, ?)""",
+          state, claimed_by, status_history, truncated, message_metadata
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 1, NULL, "queued", NULL, ?, ?, ?)""",
         (
             os.environ["Q_DELIVERY_ID"],
             int(os.environ["Q_TOPIC_ID"]),
@@ -369,6 +549,7 @@ try:
             os.environ["Q_ATTEMPTED_AT"],
             initial_history,
             int(os.environ.get("Q_TRUNCATED", "0")),
+            os.environ.get("Q_METADATA") or None,
         ),
     )
     conn.commit()
@@ -386,6 +567,15 @@ except Exception as exc:
       # with IF NOT EXISTS so this is safe even if the Python path
       # partially ran.
       printf '%s' "$QUEUE_TEXT" > "${QUEUE_DB}.tmp.text"
+      # message_metadata rides via a temp file + readfile (same pattern as the
+      # text BLOB) so no shell value is ever interpolated into SQL — the
+      # metadata is enum-built, but the no-raw-interpolation rule holds anyway
+      # (spec outbound-jargon-filepath-gap §2.5).
+      META_SQL_VALUE="NULL"
+      if [ -n "$METADATA_JSON" ]; then
+        printf '%s' "$METADATA_JSON" > "${QUEUE_DB}.tmp.meta"
+        META_SQL_VALUE="CAST(readfile('${QUEUE_DB}.tmp.meta') AS TEXT)"
+      fi
       sqlite3 "$QUEUE_DB" >/dev/null 2>&1 <<SQL
 PRAGMA journal_mode=WAL;
 PRAGMA synchronous=NORMAL;
@@ -405,22 +595,24 @@ CREATE TABLE IF NOT EXISTS entries (
   state TEXT NOT NULL,
   claimed_by TEXT,
   status_history TEXT NOT NULL DEFAULT '[]',
-  truncated INTEGER NOT NULL DEFAULT 0
+  truncated INTEGER NOT NULL DEFAULT 0,
+  message_metadata TEXT
 );
+ALTER TABLE entries ADD COLUMN message_metadata TEXT;
 CREATE INDEX IF NOT EXISTS idx_state_next ON entries(state, next_attempt_at);
 CREATE INDEX IF NOT EXISTS idx_text_hash_topic ON entries(text_hash, topic_id);
 INSERT OR IGNORE INTO entries (
   delivery_id, topic_id, text_hash, text, format,
   http_code, error_body, attempted_port, attempted_at,
-  attempts, state, status_history, truncated
+  attempts, state, status_history, truncated, message_metadata
 ) VALUES (
   '$DELIVERY_ID', $TOPIC_ID, '$TEXT_HASH',
   CAST(readfile('${QUEUE_DB}.tmp.text') AS BLOB), $( [ -n "$FORMAT" ] && printf "'%s'" "$FORMAT" || echo "NULL"),
   $HTTP_CODE, NULL, $PORT, '$ATTEMPTED_AT',
-  1, 'queued', '[]', $TRUNCATED
+  1, 'queued', '[]', $TRUNCATED, $META_SQL_VALUE
 );
 SQL
-      rm -f "${QUEUE_DB}.tmp.text" 2>/dev/null
+      rm -f "${QUEUE_DB}.tmp.text" "${QUEUE_DB}.tmp.meta" 2>/dev/null
       chmod 600 "$QUEUE_DB" 2>/dev/null
     fi
 

package/upgrades/1.3.485.md

@@ -0,0 +1,31 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixes the two live bugs from 2026-06-08 testing that left cross-machine dashboard streaming connecting-but-blank with no recovery (POOL-DASHBOARD-STREAM-SPEC, shipped #950–#970):
+
+- **Closed-proxy eviction** (`WebSocketManager.peerProxyFor`): a peer's stream proxy that reached `closed` — after the bounded reconnect failed, or after the 60s idle grace once the last viewer left — stayed cached forever, and a closed proxy silently ignores every later subscribe while the server still answered `subscribed`. One hiccup (or one minute of nobody watching) made that machine permanently unstreamable until a server restart. The get-or-create chokepoint now evicts a closed proxy and opens a fresh episode with its own bounded reconnect budget (P19 no-storm guarantee preserved: reconnects remain one-per-episode, new episodes only on explicit user subscribes).
+- **Cross-machine scrollback** (`history` relay): the terminal-history fetch only ever captured locally — structurally empty for a session owned by another machine. It now relays upstream for remote-subscribed sessions exactly like input/key (spec §2.2: capture happens ONLY on the owning machine), via a new read-only `PeerStreamProxy.relayFrame`; the dashboard client sends `machineId` on history requests for remote tiles.
+- **Honest history miss**: the "no output for session" reply was a sessionless error frame, which the peer fan-out structurally drops; it now carries `session` + `code:'session-not-found'` and renders in the terminal (§2.4 failure honesty).
+
+The serving side of the protocol is unchanged — an updated machine streaming from a not-yet-updated peer degrades to exactly today's behavior at worst. The remote-input default-off security gate is untouched.
+
+## What to Tell Your User
+
+- "Watching one machine's terminal from another machine's dashboard now actually shows the terminal — including scrolling back through its history — and if the link between machines hiccups, clicking the session again recovers it instead of staying dead until a restart."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Remote session scrollback | Automatic — scroll up in any remote session's terminal in the dashboard |
+| Stream recovery after a dropped peer link | Automatic — re-clicking the session tile opens a fresh, bounded connection episode |
+
+## Evidence
+
+- 7 new unit tests (5 behavior + 2 regression guards) across `tests/unit/WebSocketManager.test.ts` and `tests/unit/PeerStreamProxy.test.ts`; each behavior test was run against the UNFIXED code first and failed for the stated reason (missing relayFrame, ignored re-subscribe after closed, sessionless error), then green with the fix.
+- Full unit suite green in the worktree; `pnpm build` clean.
+- Live verification on the real laptop + Mac Mini (a Mini session terminal rendering on the laptop dashboard, then recovery after an induced link drop) — performed post-deploy, results recorded in topic 13481.

package/upgrades/1.3.486.md

@@ -0,0 +1,38 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Implements `docs/specs/outbound-jargon-filepath-gap.md` (r2, converged + approved) — the durable Structure-over-Willpower fix for the 2026-06-10 incident where a background job sent the operator a reminder containing dev jargon and a raw repo path, bypassing both standing standards because nothing told the infrastructure the message was an automated alert. One PR, no deferrals:
+
+- **Structural message kind (§2.1)** — the scheduler stamps `INSTAR_MESSAGE_KIND=automated` + `INSTAR_JOB_SLUG` + `INSTAR_SENDER_CLASS` into job session environments (BOTH `SessionManager.spawnSession` spawn lanes — headless AND rerouted-interactive — plus `JobScheduler.runScriptJob` with `senderClass=script`). The model types nothing; interactive sessions get none of these and stay `'reply'`. The `messageKind` union widens with `'automated'` (single-sourced as `MessageKind` in MessagingToneGate; all five prior sites now use it) + a `renderMessageKind` branch describing the kind to the authority. NO new block rule and NO B12 re-scope — the operator constraint is zero new blocking power.
+- **Jargon signal single-sourced (§2.2)** — `evaluateOutbound` computes `detectJargon` itself for non-`reply` kinds (`health-alert | automated`), replacing the `options.jargon` caller opt-in (the one vestigial caller is cleaned up). Conversational replies deliberately get NO jargon signal (over-block scope). Live-config kill switch `messaging.outboundFloor.jargonAlways` (absence = on).
+- **Raw-file-path SIGNAL (§2.3)** — new `detectRawFilePath` (`src/core/raw-file-path.ts`), a linear-regex sibling of `localhost-link.ts`: indexOf prescreen, bounded segments, never matches inside an `http(s)://` URL, match echo bounded to 120 chars and stopping before `?` (an adjacent secret can never ride along), fail-OPEN at every call site. Feeds `signals.filePath` to the existing authority on all kinds — anchoring the B2_FILE_PATH judgment it already has.
+- **The preflight advisory (§2.4)** — `telegram-reply.sh` (template) gains an inform-only preflight, active ONLY for `automated` + `llm-session` senders: it calls the new `POST /messaging/preflight` (deterministic detectors only, no LLM; 64KB cap; runtime enum coercion at both boundaries) and on findings prints an advisory whose FIRST line is the literal `NOT SENT — advisory (fix and re-run, or re-run with --ack-advisory to send unchanged)` and exits 0 — the message is withheld until the SENDER resolves it (fix, or `--ack-advisory`, both always deliver past the advisory layer). Fail-OPEN end-to-end: route down / timeout / malformed JSON / disabled → the send proceeds untouched. The curl timeout converts config ms→seconds with ceil + a [1,10]s clamp (a raw `--max-time 2000` would be a ~33-minute fail-HANG). Flag-only ack (no env form — a standing pre-ack would silently disable the inform layer).
+- **Server-side single-writer audit + escalation (§2.4(5–6))** — every preflight outcome is one JSONL line in `logs/outbound-advisory.jsonl` (`clean|advised|acked`; `acked` written only by `/telegram/reply` when a send carries the REQUIRED `metadata.advisoryAck` + overridden codes); size-rotated; read via the new `GET /messaging/advisory-log` (bounded tail, never the whole file). An in-memory write-time index drives the repeated-ignore escalation: N unresolved advised per signature (default 3) or per-slug aggregate across topics (default 5) raises ONE deduped HIGH Attention item with the FIXED `sourceContext: outbound-advisory-escalation` (P17 — the per-source topic budget genuinely binds); an interleaved clean heartbeat does NOT reset the count (reset-gaming closed); a near-identical clean re-send (the fix landing) resolves it; habitual `--ack-advisory` overriding raises the preemptive-ack consumer (NORMAL).
+- **The kind survives every hop (§2.5)** — BOTH `telegram-reply.sh` body builders (python3 + sed fallback) forward `metadata.{messageKind,senderClass,jobSlug}`; BOTH script queue writers AND `PendingRelayStore` gain a nullable `message_metadata` column via the existing idempotent-ALTER conventions (a pre-column legacy DB upgrades on open — tested); the `DeliveryFailureSentinel` redrive forwards the metadata whole (an acked-then-queued send still lands its `acked` row — no escalation false-fire on transient delivery failure); the cross-machine relay hop (`sendToTopic → outboundRelay → relayOutbound`) carries it to the holder. Observability breadcrumbs (never gates): kindless send to a job-session topic (exempt for a redrive whose `X-Instar-DeliveryId` matches a REAL queue row), automated send with no recent preflight row (class-spoof visibility), declared `script` class on a non-script job.
+- **Migration parity (§5)** — the current live `telegram-reply.sh` SHA (`3e30b2cd…`) joins `TELEGRAM_REPLY_PRIOR_SHIPPED_SHAS` so deployed stock scripts actually receive the new template; CLAUDE.md template + `migrateClaudeMd` gain the "Outbound advisory for automated messages" awareness section; the hand-curl `/telegram/reply` example is REPLACED by the relay-script form (no printed map to the bypass); the section is registered in `migrateFrameworkShadowCapabilities` markers[] (Codex/Gemini mirrors) and the feature-delivery-completeness guard.
+
+## What to Tell Your User
+
+- "My background jobs' messages now get a quality check before they reach you: if an automated reminder contains a raw file path, internal dev jargon, or a link that only works on my machine, the job is told to fix it BEFORE you ever see it — and the fix guidance is built in. Nothing can get stuck: the check informs the sender, it never blocks, and if a job keeps ignoring its own feedback you get one consolidated heads-up instead of silence."
+- "Your normal conversations with me are completely unaffected — this only touches messages composed by scheduled background jobs."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Advisory preflight on automated sends | Automatic — scheduler-stamped; job models type nothing |
+| `--ack-advisory` send-as-is override | Re-run `telegram-reply.sh --ack-advisory …` after an advisory (audited) |
+| Advisory audit trail | `GET /messaging/advisory-log?limit=50` (Bearer-authed) |
+| Repeated-ignore escalation | Automatic — one deduped Attention item per misbehaving job |
+| Rollback levers (live, no restart) | `messaging.outboundAdvisory.enabled:false` · `messaging.outboundFloor.jargonAlways:false` |
+
+## Evidence
+
+- Founding incident reproduction shape covered end-to-end: the REAL shipped `telegram-reply.sh` run under bash with a recording curl shim proves (1) a raw-path automated send does NOT deliver on the first call, prints the LITERAL `NOT SENT — advisory…` first line, exits 0; (2) corrected text delivers; (3) `--ack-advisory` delivers the original and the send body carries `advisoryAck` + codes; (4) preflight network-failure AND malformed-JSON both DELIVER (fail-open proof); (5) a conversational session makes NO preflight call and produces the byte-identical legacy body (`tests/unit/telegram-reply-advisory-script.test.ts`, 12 tests).
+- 26 detector tests incl. a 4KB-pathological-input bounded-time ReDoS test and the adjacent-secret echo bound (`raw-file-path.test.ts`); 17 audit/escalation tests incl. the reset-gaming case (interleaved clean does NOT reset) and the per-slug topic-varying aggregate (`outbound-advisory.test.ts`); 15 route tests incl. "the server DELIVERS a raw-path automated message exactly as today — never blocks" (`outbound-advisory-routes.test.ts`); queue pre-column-DB ALTER + sentinel metadata-forward tests (`pending-relay-metadata.test.ts`); relay-hop body test (`relay-kind-forward.test.ts`); spawn-lane env assertions (`session-manager-behavioral.test.ts`).
+- Tier-3 alive: the REAL AgentServer on the production init path answers `POST /messaging/preflight` 200-with-advisories and `GET /messaging/advisory-log` 200, enforces Bearer auth (401 without), writes the JSONL where documented, and the live-config kill switch flips the preflight off WITHOUT a restart (`tests/e2e/outbound-advisory-alive.test.ts`, 5 tests).
+- `tsc --noEmit` exit 0; full unit suite green before push.