instar 1.3.485 → 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.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.

package/upgrades/side-effects/outbound-advisory-inform-only.md

@@ -0,0 +1,252 @@
+<!-- DRAFT — completed in Phase 4 of /instar-dev. Phase 1 principle check + Phase 2 plan recorded below first. -->
+
+# Side-Effects Review — Outbound advisory: jargon + raw-file-path gaps for automated senders (inform-only)
+
+**Version / slug:** `outbound-advisory-inform-only`
+**Date:** `2026-06-11`
+**Author:** `echo (instar-dev agent)`
+**Second-pass reviewer:** `required — outbound-messaging decision surface (Phase 5)`
+
+## Phase 1 — Principle check (recorded before any code)
+
+**Does this change involve a decision point?** YES — it touches the outbound-messaging
+pipeline, the single most sensitive decision surface in instar. The signal-vs-authority
+principle applies directly, and the design (per the converged + approved spec
+`docs/specs/outbound-jargon-filepath-gap.md`, r2) was shaped around it:
+
+- `detectRawFilePath` (new) and `detectJargon` (re-scoped) are pure DETECTORS — regex,
+  cheap, fail-open, no blocking power. They feed the EXISTING authority
+  (`MessagingToneGate.review`) as signals. No new rule, no re-scoped block rule.
+- The preflight advisory is honestly named in the spec as a "default-withhold the sender
+  always resolves" — the sending agent keeps final authority (fix or `--ack-advisory`,
+  both always deliver past the advisory layer). It never consults a judge, never
+  escalates against the sender, fails open on every error path.
+- The repeated-ignore escalation informs the OPERATOR (one deduped Attention item),
+  gates nothing.
+- Governing operator constraint (Justin, 2026-06-10): zero new blocking authority.
+  r1's deterministic 422 floor was DELETED in r2 for exactly this reason.
+
+## Phase 2 — Plan (recorded before any code)
+
+**Build location:** fresh worktree `.worktrees/echo-outbound-advisory-build`, branch
+`echo/outbound-advisory-build`, based off `JKHeadley/main` @ v1.3.484 (verified:
+`git remote -v` = JKHeadley https, `package.json` 1.3.484, git identity
+`Instar Agent (echo) <echo@instar.local>`).
+
+**Implementation order:**
+1. `detectRawFilePath` detector (sibling of `localhost-link.ts`, same linear-regex discipline) + unit tests.
+2. `messageKind` union widening (`'automated'`) in all five cited sites + `renderMessageKind` branch.
+3. `checkOutboundMessage`: always-compute jargon for non-`reply` kinds (drop the `options.jargon` opt-in; fix the one vestigial caller); feed `signals.filePath`.
+4. `POST /messaging/preflight` + `GET /messaging/advisory-log` + server-side single-writer JSONL audit + in-memory escalation index + Attention escalation (fixed sourceContext).
+5. Scheduler env injection: BOTH SessionManager spawn env blocks (headless + rerouted-interactive) + JobScheduler `runScriptJob` env (`INSTAR_MESSAGE_KIND`, `INSTAR_JOB_SLUG`, `INSTAR_SENDER_CLASS`).
+6. `telegram-reply.sh` template: metadata forwarding in BOTH body builders, preflight loop + `--ack-advisory`, curl timeout ms→s clamp, queue metadata column in BOTH script queue writers (quote-safe).
+7. `PendingRelayStore` COLUMN_ADDS metadata column + `DeliveryFailureSentinel.postReply` threading + redrive exemption via `X-Instar-DeliveryId` validated against a real queue row.
+8. Relay-hop forwarding (3-layer widening) so kind/senderClass/ack survive the cross-machine hop.
+9. `/telegram/reply`: read `metadata.messageKind` → `checkOutboundMessage`; `acked` audit row; kindless-job-send + class-spoof breadcrumbs; senderClass validation against the job definition.
+10. Config plumbing via LiveConfig (live re-read; `?? true` defaults — rollback without restart).
+11. PostUpdateMigrator: current live telegram-reply SHA → allowlist; CLAUDE.md template section (add advisory awareness, remove hand-curl example); `migrateFrameworkShadowCapabilities` marker.
+12. All three test tiers per spec §6; release fragment; this artifact completed; trace; commit; PR; CI; merge (Phase 7 auto-merge on green).
+
+**Decision points touched:** outbound `/telegram/reply` pipeline (signals only), new preflight route (advisory only), Attention queue (operator-inform only).
+**Existing detectors/authorities interacted with:** `detectJargon`, `detectLocalhostLink`, `MessagingToneGate.review` (B2/B12 untouched in scope), grounding-before-messaging hook (independent layer, unchanged).
+**Rollback path:** `messaging.outboundAdvisory.enabled:false` + `messaging.outboundFloor.jargonAlways:false` (live config, no restart); scheduler env injection inert without script/route consumers; queue column is nullable + idempotent-ALTER (legacy rows fine).
+
+## Summary of the change
+
+Implements the converged + approved spec `docs/specs/outbound-jargon-filepath-gap.md` (r2): structural
+`automated` message-kind stamping at job spawn (SessionManager both lanes + JobScheduler script env),
+the jargon signal single-sourced for non-reply kinds, a new `detectRawFilePath` signal detector, an
+inform-only preflight advisory in `telegram-reply.sh` backed by `POST /messaging/preflight` +
+`GET /messaging/advisory-log`, a server-side single-writer audit with repeated-ignore escalation, kind
+metadata threading through the durable relay queue / sentinel redrive / cross-machine relay hop, and
+full migration parity (SHA allowlist + CLAUDE.md + shadow mirrors). Files: `src/core/raw-file-path.ts`
+(new), `src/messaging/OutboundAdvisory.ts` (new), `src/core/MessagingToneGate.ts`,
+`src/server/routes.ts`, `src/server/AgentServer.ts`, `src/core/SessionManager.ts`,
+`src/scheduler/JobScheduler.ts`, `src/templates/scripts/telegram-reply.sh`,
+`src/messaging/pending-relay-store.ts`, `src/monitoring/delivery-failure-sentinel.ts`,
+`src/messaging/TelegramAdapter.ts`, `src/core/TelegramRelay.ts`, `src/core/PostUpdateMigrator.ts`,
+`src/scaffold/templates.ts` + three test tiers.
+
+## Decision-point inventory
+
+- `evaluateOutbound` / `checkOutboundMessage` (routes.ts) — **modify (signals only)** — two new SIGNALS (jargon for non-reply kinds, filePath for all kinds) feed the EXISTING authority; no decision logic changed; block/allow remains solely the authority's.
+- `MessagingToneGate.review` — **pass-through** — receives the new kind + signals as context; rules untouched (no B12 re-scope, no new rule).
+- `POST /messaging/preflight` (new) — **add (advisory only)** — deterministic detectors, returns advisories; CANNOT refuse a send (the server delivers regardless — proven by test).
+- `telegram-reply.sh` preflight loop — **add (default-withhold the sender always resolves)** — honestly named per spec §2.4: the first flagged attempt does not deliver; resolution (fix or ack) belongs exclusively to the sender; fail-OPEN on every error path.
+- Repeated-ignore escalation — **add (operator-inform only)** — one deduped Attention item; gates nothing.
+- Observability breadcrumbs in `/telegram/reply` — **add (log lines only)** — never affect delivery; wrapped in a try/catch.
+
+---
+
+## 1. Over-block
+
+The server holds NO new block surface — `/telegram/reply` delivers a raw-path automated message
+exactly as before (test-proven). The script-side withhold can over-fire two ways:
+
+- `detectRawFilePath` false positive (e.g. a legitimate user-actionable path in a power-user setup):
+  costs the sender one `--ack-advisory` re-run; the message still delivers unchanged. Bounded cost,
+  stated in the spec's risk table.
+- `detectJargon` false positive on an automated send: same single-re-run cost. Jargon is deliberately
+  NOT computed for conversational replies, so the over-block tail the operator has repeatedly warned
+  about cannot grow on the main path.
+
+A genuinely-flagged localhost link is the one case `--ack-advisory` cannot deliver — but that block
+belongs to the PRE-EXISTING localhost guard (untouched); the advisory's static guidance states this
+honestly rather than promising ack-delivery.
+
+## 2. Under-block
+
+- A job that hand-curls `/telegram/reply` (bypassing the script) sends kindless and skips the
+  preflight entirely — named residual (§2.1/§2.5), bounded by the kindless-job-send breadcrumb and the
+  removal of the hand-curl example from the CLAUDE.md template. Accepted by design (sender sovereignty).
+- `isProxy`/`isSystemTemplate`/`willRelay` system-composed sends skip `checkOutboundMessage` today and
+  are untouched — there is no sender to inform. Named residual.
+- A one-shot sender that ignores its advisory drops that one message with no re-fire behind it; the
+  per-slug aggregate escalation is the bound. Accepted residual cost of inform-only, per the operator's
+  explicit constraint.
+- `detectRawFilePath` misses path shapes outside its three alternatives (e.g. bare relative
+  `foo/bar.txt` with an unknown top dir, Windows `C:\` paths). Deliberate precision-first scope —
+  the LLM authority's B2 judgment still covers them on gated kinds.
+
+## 3. Level-of-abstraction fit
+
+Correct layers throughout: the detector is a cheap deterministic sibling of `localhost-link.ts` in
+`src/core/`; the signals feed the EXISTING authority instead of running parallel to it (the spec's
+grounding correction explicitly rejected a new gate); the advisory loop lives in the mandated relay
+script (the only place that can inform the sender BEFORE delivery without giving the server veto
+power); the audit/escalation live server-side where the single-writer guarantee is enforceable. The
+kind is stamped at the SPAWNER (the only layer that structurally knows a session is a job).
+
+## 4. Signal vs authority compliance
+
+**Required reference:** docs/signal-vs-authority.md
+
+- [x] No — this change produces signals consumed by an existing smart gate.
+
+`detectRawFilePath` and the re-scoped `detectJargon` are pure detectors feeding
+`MessagingToneGate.review`. The preflight advisory holds no blocking authority: its withhold is always
+and only resolved by the sender, never escalates, never consults a judge, and fails open on every
+error path — the spec names it honestly as a "default-withhold the sender always resolves" rather than
+claiming "no authority at all". r1's deterministic 422 floor was DELETED per the operator's
+inform-only constraint; no block rule was added or re-scoped anywhere in this change.
+
+## 5. Interactions
+
+- **Shadowing:** the preflight runs BEFORE the send, script-side; the existing pipeline (localhost
+  guard, tone gate, dedup, length cap) runs unchanged server-side afterward. One send can legitimately
+  receive two differently-shaped interventions (grounding hook + advisory) — independent layers; the
+  advisory text never claims to be the only check.
+- **Double-fire:** the `acked` audit row is written ONLY on successful delivery, so an
+  acked-then-queued send audits once, after the redrive — verified that the queue carries
+  `advisoryAck` whole, closing the escalation false-fire on transient delivery failures.
+- **Races:** the escalation index is in-memory single-process (write-time, no poller); restart resets
+  are accepted, stated best-effort observability. JSONL appends are single `appendFileSync` calls
+  (O_APPEND).
+- **Feedback loops:** the escalation raises Attention items through `createAttentionItem` with a
+  FIXED sourceContext and stable per-signature ids (id-dedup prevents re-raise loops). **Corrected
+  after the second-pass review:** HIGH/URGENT items are EXEMPT from the per-source topic budget, so
+  the original all-HIGH design would have been an un-budgeted topic-per-signature flood for a
+  topic-varying sender. Iterated: per-signature items are NORMAL (the budget genuinely binds — a
+  burst-invariant test feeds escalations through the REAL AttentionTopicGuard and asserts allowed
+  topics ≤ the budget); the per-slug aggregate is the single loud HIGH bound (one deduped item per
+  slug); once a slug's aggregate has fired, further per-signature items for that slug are suppressed.
+- The sentinel's `postReply` signature widened with optional trailing params — all existing callers
+  and test doubles remain compatible (verified by the full suite).
+
+## 6. External surfaces
+
+- **Other agents on the machine:** job sessions of every framework (claude/codex/gemini) get the new
+  env vars — inert unless the relay script consumes them. The CLAUDE.md awareness section reaches
+  Codex/Gemini via the shadow-capability mirror.
+- **Install base:** the `telegram-reply.sh` re-deploy rides the SHA-gated migrator; user-modified
+  scripts are never stomped (`.new` + degradation event, existing behavior). The queue column arrives
+  via idempotent ALTER on every writer — legacy rows read null metadata and ride the delivery-id
+  breadcrumb exemption.
+- **External systems:** no new egress. The preflight is a localhost call; detectors are local regex.
+- **Persistent state:** new `logs/outbound-advisory.jsonl` (size-rotated, single `.1` rollover); new
+  nullable `message_metadata` column in the pending-relay SQLite (additive, no migration needed for
+  rollback).
+- **Timing:** the preflight adds one localhost round-trip (~ms) + ~100ms of process spawns per
+  automated send; bounded by the clamped curl timeout; the conversational path is untouched.
+
+## 7. Rollback cost
+
+- **Hot levers (live config, NO restart):** `messaging.outboundAdvisory.enabled:false` disables the
+  preflight + escalation; `messaging.outboundFloor.jargonAlways:false` reverts the jargon signal.
+  Both are read per-request through LiveConfig.
+- **Code revert:** the scheduler env injection is inert without the script/route consumers, so a
+  partial rollback degrades safely in any order.
+- **Data:** the JSONL audit and the nullable queue column need no cleanup on rollback (additive,
+  null-tolerant readers).
+- **User visibility during rollback:** none — worst case, automated sends simply stop being advised.
+
+## Conclusion
+
+The review confirms the design holds the operator's governing constraint structurally: zero new
+blocking authority anywhere in the server; the only withhold lives script-side, is always resolvable
+by the sender alone, and fails open on every error path (each proven by a test, not asserted). The
+named residuals (hand-curl bypass, system-composed sends, one-shot drops) are bounded by breadcrumbs
+and the escalation, and are the accepted cost of inform-only — the operator chose this trade
+explicitly. One design change came out of testing: the fix-landing resolution threshold was tuned to
+0.4 Jaccard after measuring the founding incident shape (~0.47) vs the gaming heartbeat (~0.06).
+Clear to ship pending the required second-pass review (outbound-messaging decision surface).
+
+---
+
+## Second-pass review (required — outbound messaging surface)
+
+**Reviewer:** subagent (claude, independent second-pass)
+**Independent read of the artifact: concern → resolved → concur (re-confirmed below)**
+
+First-pass verdict (verbatim): the core inform-only claims all verified adversarially against the
+code (no new server-side blocking authority; no silent drop — the NOT-SENT line precedes every
+withhold; fail-open complete across curl failure/timeout/non-200/malformed-JSON/missing-python3/
+disabled; secret-safety bounds hold at all four echo sites; queue/redrive/relay threading and
+migration parity verified). Three concerns were raised:
+
+1. **(Load-bearing) The §5 flood-bound claim was FALSE as written:** per-signature escalations were
+   HIGH, and HIGH bypasses BOTH the per-source budget and the universal topic budget — a
+   topic-varying sender would have produced K un-budgeted HIGH topics (the 2026-06-05 flood shape);
+   the spec-required burst proof test was missing, which is exactly why the false claim survived.
+   **Resolution (implemented):** per-signature items demoted to NORMAL (budget-eligible); per-slug
+   aggregate kept as the single deduped HIGH; per-signature suppressed once the slug aggregate has
+   fired; burst-invariant test added driving 10 distinct misbehaving signatures through the REAL
+   `AttentionTopicGuard` and asserting allowed topics ≤ the budget, plus a suppression test.
+2. **Two §6 assertions were absent.** **Resolution (implemented):** non-telegram (slack) automated
+   send asserted to receive the jargon + filePath signals (with the slack route now threading
+   `metadata.messageKind`, mirroring telegram); the Tier-2-location nit (route tests under
+   `tests/unit/` driving a real express app) stands with this note.
+3. **(Disclosed, no action)** the 0.4 Jaccard fix-landing threshold can under-resolve a heavy
+   rewrite; bounded to NORMAL/budgeted items by resolution 1.
+
+**Re-confirmation (independent, after the iteration):** concur — "All three resolutions verified in
+code and tests against the real `AttentionTopicGuard` (35/35 green)"; the burst test was verified
+non-vacuous (a revert to HIGH fails both assertions). The one cosmetic nit (a stale test-header
+comment) was fixed in the same pass.
+
+---
+
+## Evidence pointers
+
+- `tests/unit/telegram-reply-advisory-script.test.ts` — the REAL shipped script under bash + recording
+  curl shim: NOT-SENT literal/exit-0, ack annotation, fail-open ×2, legacy-body byte-shape, ms→s clamp,
+  queue metadata on HTTP-000.
+- `tests/unit/raw-file-path.test.ts` (26) · `tests/unit/outbound-advisory.test.ts` (17) ·
+  `tests/unit/outbound-advisory-routes.test.ts` (15) · `tests/unit/pending-relay-metadata.test.ts` (4) ·
+  `tests/unit/relay-kind-forward.test.ts` (2) · spawn-env assertions in
+  `tests/unit/session-manager-behavioral.test.ts`.
+- `tests/e2e/outbound-advisory-alive.test.ts` (5) — production-init alive + auth + on-disk audit +
+  live kill switch.
+
+---
+
+## Post-CI follow-up (same PR)
+
+The no-silent-fallbacks ratchet (CI shard 3) correctly demanded that every spec-mandated fail-open
+catch be a TRACKED decision: all are now annotated `@silent-fallback-ok` with the spec-section
+justification (fail-open is the §0 operator constraint, not an accident), plus one documented
+scanner-window false positive on a pre-existing 500-responder catch. No behavior change.
+
+CI round 2: one source-inspection test (`slack-thread-session-wiring`) used a fixed 1600-char
+extraction window that the slack route's new messageKind threading overflowed — window widened to
+2400 with a comment naming the cause. No behavior change.