instar 1.3.983 → 1.3.985

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-26T07:12:22.087Z",
-  "instarVersion": "1.3.983",
+  "generatedAt": "2026-07-26T17:59:55.648Z",
+  "instarVersion": "1.3.985",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1242,7 +1242,7 @@
       "type": "template",
       "domain": "operations",
       "sourcePath": "src/templates/scripts/telegram-reply.sh",
-      "contentHash": "a2cf02154a6023725f15480a575f54a5231278c70396cd12051b7d7055b72d98",
+      "contentHash": "4464581188f5c736a62edac5e6a2edecfcfcd365557a18e514b741731bed6e0b",
       "since": "2025-01-01"
     },
     "template:whatsapp-reply.sh": {
@@ -1562,7 +1562,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

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

@@ -4,6 +4,12 @@
 # Usage:
 #   ./telegram-reply.sh TOPIC_ID "message text"
 #   ./telegram-reply.sh --format markdown TOPIC_ID "**bold**"
+#
+#   EVERY FLAG GOES BEFORE THE TOPIC ID. Flag parsing stops at the topic id, so
+#   anything after it is message text. A flag in the wrong position used to be
+#   sent to the user as literal text with its effect silently dropped; it is now
+#   refused. Correct:
+#     ./telegram-reply.sh --tone-ack B2_FILE_PATH --tone-reason "why" TOPIC_ID "msg"
 #   echo "message text" | ./telegram-reply.sh TOPIC_ID
 #   cat <<'EOF' | ./telegram-reply.sh TOPIC_ID
 #   Multi-line message here
@@ -25,6 +31,24 @@
 #                     a blanket pre-ack that silently disables the inform
 #                     layer; spec outbound-jargon-filepath-gap §2.4(4)).
 #
+#   Tone-gate advisory reactions (answering a 422 `tone-gate-advisory`). BOTH
+#   forms are recorded as evidence that tunes the gate; neither is optional
+#   once you have been handed a decisionRef.
+#   --tone-complied <RULE>     You agreed with the nudge and revised the text.
+#                              Grades the check `right`.
+#   --tone-ack <RULE>          You disagree and are sending unchanged. Grades
+#                              the check `wrong`. REQUIRES --tone-reason: a
+#                              reasonless ack is refused and nothing sends,
+#                              because that reason IS the tuning evidence.
+#   --tone-reason "<why>"      Why the nudge is wrong in this case.
+#   --tone-decision-ref <REF>  The decisionRef from the 422, so the reaction
+#                              joins the verdict it answers.
+#
+#   Example (note the ordering — flags first, topic id last):
+#     ./telegram-reply.sh --tone-ack B2_FILE_PATH \
+#       --tone-reason "the operator asked for the path explicitly" \
+#       --tone-decision-ref DQ-1234 29723 "the message"
+#
 # 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
@@ -133,6 +157,43 @@ if [ -z "$TOPIC_ID" ]; then
   exit 1
 fi
 
+# A flag placed AFTER the topic id was silently swallowed into the message.
+#
+# The parse loop above stops at the first non-flag argument (the topic id), so
+# everything from there on becomes message text via `MSG="$*"` below. A
+# misplaced `--tone-ack` was therefore SENT TO THE USER as visible message body
+# while the override it was meant to carry never reached the server — and,
+# because the flags never applied, the tone gate re-reviewed the send and its
+# verdict was then misread as absurd. That is how a CORRECT check came to be
+# graded `wrong` in the decision-quality data on 2026-07-26. The record is
+# durable; the cause was two characters of argument order.
+#
+# The asymmetry is the defect: a flag-shaped token BEFORE the topic id is fatal
+# ("Unknown flag", above), but after it the script was maximally permissive.
+# Refuse flag-shaped tokens in both positions. This also catches a TYPO'd flag
+# (`--tone-akc`), which is the realistic case and was equally silent.
+#
+# Deliberately strict: any `--*` argument. A message that genuinely needs such a
+# token as literal text goes through stdin, which is the documented primary path
+# and is unaffected by this check ($# is 0 there).
+for _arg in "$@"; do
+  case "$_arg" in
+    --*)
+      echo "Refused: '$_arg' appears AFTER the topic id." >&2
+      echo "" >&2
+      echo "Flags are only parsed BEFORE the topic id. Placed here it would have been" >&2
+      echo "sent to the user as literal message text, and its effect silently dropped." >&2
+      echo "" >&2
+      echo "  Correct:  telegram-reply.sh --tone-ack RULE --tone-reason \"why\" $TOPIC_ID \"message\"" >&2
+      echo "  You ran:  telegram-reply.sh $TOPIC_ID ... $_arg ..." >&2
+      echo "" >&2
+      echo "If '$_arg' is genuinely part of the message text, pipe the message on stdin:" >&2
+      echo "  cat <<'EOF' | telegram-reply.sh $TOPIC_ID" >&2
+      exit 1
+      ;;
+  esac
+done
+
 # Read message from args or stdin
 if [ $# -gt 0 ]; then
   MSG="$*"

package/upgrades/1.3.982.md

@@ -42,6 +42,17 @@ genuinely reads live state.
 
 ## What to Tell Your User
 
+> **CORRECTION (2026-07-26, after release).** The paragraph below over-claimed and is kept
+> visible rather than quietly rewritten. **The change is forward-only.** Promises about
+> behaviour recorded from now on stay open, and the runaway tally stopped for all of them —
+> but promises that already existed **keep the verdict they were last stamped with**, because
+> the fix works by declining to reach a verdict, which means it never revisits one. Measured
+> on a live install after deploy: 98 behavioural records still showed 74 "kept" and 24
+> "broken", unchanged. So if you had behavioural commitments before upgrading, their old and
+> untrustworthy verdicts are still on screen, and the health line will still count those 74 as
+> verified. Clearing them needs a deliberate decision (rewriting stored records, or having the
+> display refuse a verdict for anything unverifiable) and has not been made.
+
 If you track commitments, promises about behaviour now show as **pending** rather than
 verified or violated, with both counters at zero. That is more honest, not a regression:
 nothing was ever watching whether those promises were kept, so "verified" was reassurance
@@ -69,10 +80,14 @@ commitment"`. Live store corroboration: 74/74 with the field `verified`, 24/24 w
 
 **Observed after,** same scenarios against the built code:
 
+**Scope note added 2026-07-26:** every row below was measured on a **newly created** commitment.
+A row that already existed before the upgrade keeps its stored verdict — see the correction above.
+
 | scenario | before | after (25 sweeps) |
 |---|---|---|
-| behavioural, `behavioralRule` set | `verified`, +1 tick per sweep | `pending`, verifications 0, violations 0 |
-| behavioural, field absent | `violated`, +1 tick per sweep | `pending`, verifications 0, violations 0 |
+| behavioural, `behavioralRule` set (NEW row) | `verified`, +1 tick per sweep | `pending`, verifications 0, violations 0 |
+| behavioural, field absent (NEW row) | `violated`, +1 tick per sweep | `pending`, verifications 0, violations 0 |
+| behavioural row that PREDATES the change | `verified` or `violated`, ticking | ticking stops; **stored verdict unchanged** |
 | rules file deleted | produced a verdict | no verdict; file self-heals; status unchanged |
 | health, 1 behavioural row | `"1 commitment(s) tracked, all verified"` | `"1 commitment(s) tracked — 0 verified, 1 not automatically verifiable (no violations)"`, status `healthy` |
 

package/upgrades/1.3.984.md

@@ -0,0 +1,116 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+**Thirty source files were invisible to `grep`. A search across them returned nothing,
+and nothing read as "there is nothing there."**
+
+`grep` classifies a file as binary if it contains a NUL (0x00) byte, and on a binary file
+it emits **nothing at all** — not a match, not a `Binary file X matches` line, not even a
+`0` under `-c`. Thirty tracked text files each carried one, so every grep-based audit over
+`src/` silently skipped them. A search that examined two-thirds of the tree was
+byte-for-byte indistinguishable from one that examined all of it and found nothing wrong.
+
+Twenty-two were live source. Among them: `blockerSettleAuthority.ts` (the gate that
+decides whether a blocker is genuinely unresolvable), `SessionOwnership.ts`,
+`GreenPrAutoMerger.ts`, `PermissionPromptAutoResolver.ts` (an always-on safety floor), all
+three `ExternalHog*` modules — and `StandardsEnforcementAuditor.ts`, the module that
+audits whether our standards carry structural guards. The auditor of guarantees was itself
+invisible to the standard search instrument.
+
+**A second consequence, worse in kind.** Git applies the same rule but only sniffs the
+first 8000 bytes. For the **11 files** whose NUL fell inside that window, `git diff`
+rendered `Bin 5407 -> 5412 bytes` instead of a line diff — so pull requests touching
+safety-critical authority code were reviewed **without the reviewer being shown the
+changed lines**. For the other 19, git saw text while `grep` did not. The two instruments
+disagreed on the same tree, which is exactly why this survived so long: whichever one you
+happened to reach for decided what you believed.
+
+**None of it was corruption.** Every byte was a deliberate composite-key or hash
+separator — the classic collision-proof choice, since a NUL cannot occur inside a model
+name or a framework name:
+
+```ts
+const key = `${row.model}<a literal 0x00 byte>${row.framework}`;
+```
+
+The delimiter is correct. Writing it as the byte rather than its escape is the entire
+defect. All thirty now use the six-character escape, which denotes the identical
+character — so runtime behaviour is unchanged, and every hash derived from these
+separators is byte-identical. Four sites feed them into digests
+(`relayContentDedup`, `blockerSettleAuthority`, `UnionReader`, `ExternalHogArmMarker`);
+this was the primary risk and it was verified rather than assumed. No migration, no cache
+invalidation, no re-keying.
+
+A new ratchet, `tests/unit/no-raw-nul-bytes-in-source.test.ts`, fails the build if one
+returns. It reads bytes via `readFileSync` and never shells out to a search tool, so it
+cannot be blinded by the defect it detects. It carries no exemption list, because no case
+needs one: any runtime NUL a program wants is expressible as an escape.
+
+**What this does not do:** it fixes one silent instrument, not the class. Other raw
+control bytes (ESC, BEL) remain in a few hostile-input test fixtures — deliberately, after
+verifying empirically that they do **not** cause the grep skip. Only 0x00 does. A lint
+should enforce exactly the failure it is named for, and widening this one for tidiness
+would have added churn while claiming safety it does not provide.
+
+## What to Tell Your User
+
+Nothing changes in how the agent behaves — this is a source-text and build-time fix with
+no route, setting, or visible surface.
+
+What it does change is trustworthiness of process: for months, searching the codebase for
+a given pattern could quietly skip thirty files and report a clean result, and for eleven
+of those files a code review showed "binary file changed" instead of the actual lines. Any
+past conclusion of the form "we don't do X anywhere" may have been drawn from an
+instrument that wasn't looking. Those files are readable again, and a check now fails the
+build if it recurs.
+
+## Summary of New Capabilities
+
+- Thirty text files that were invisible to `grep` — twenty-two of them live source,
+  including several safety-critical authority modules — are searchable again.
+- Eleven files that rendered as binary diffs in code review now show reviewable lines.
+- A build-time ratchet refuses any text file containing a raw NUL byte, naming the file
+  and the consequence rather than emitting a bare assertion failure.
+- The ratchet proves its own detector on every run, so a check that has gone dead is
+  distinguishable from one that has nothing to report.
+
+## Evidence
+
+**Reproduction (before):** `grep -c export src/monitoring/blockerSettleAuthority.ts`
+printed nothing — no count, no error, exit status indistinguishable from a clean miss.
+`file` reported the same TypeScript source as `data`, not text. Three one-line fixtures
+isolate the cause: a clean file and a file containing ESC + BEL both return 1 match; a
+file differing only by one NUL byte returns nothing at all.
+
+**Observed after,** same scenarios against the fixed tree:
+
+| scenario | before | after |
+|---|---|---|
+| `grep -c export` on `blockerSettleAuthority.ts` | *(silent)* | `1` |
+| `grep -c export` on `StandardsEnforcementAuditor.ts` | *(silent)* | `13` |
+| `grep -c export` on `FeatureMetricsLedger.ts` | *(silent)* | `20` |
+| `file` on those sources | `data` | `ASCII text` |
+| `git diff` on the 11 early-NUL files | `Bin NNNN -> NNNN bytes` | reviewable line diff |
+| runtime value of the separator | U+0000 | U+0000 (unchanged) |
+| digests derived from the separator | — | byte-identical, verified |
+| ratchet against a reintroduced NUL | *(no check existed)* | fails, names the file |
+
+**Tests:** `tests/unit/no-raw-nul-bytes-in-source.test.ts` (4 new). One asserts the
+detector flags a raw-byte file and clears an escaped one — a dead-check guard, since a
+lint that has never objected is output-identical to a lint that cannot object. One asserts
+the escape decodes to exactly the raw byte, so the behaviour-preserving claim is checked
+rather than stated. One scans the tree. One asserts the scan examined more than 500 files,
+so a scan that walked the wrong roots cannot pass forever by finding nothing.
+
+Verified by reintroducing a raw NUL into `FeatureMetricsLedger.ts`: the lint exits 1,
+names the file, and states the consequence. `npx tsc --noEmit` clean; the full unit suite
+runs 39,046 tests with no failure attributable to this change.
+
+**Provenance note.** This was found only because a *different* investigation produced a
+suspiciously empty search result that was about to be written up as "no such mechanism
+exists in the codebase." That search had skipped twenty-two files. The finding was
+manufactured by the defect, and has been retracted and superseded rather than deleted.

package/upgrades/1.3.985.md

@@ -0,0 +1,109 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+**A flag placed after the topic id was sent to the user as literal message text, and the
+setting it carried was silently dropped.**
+
+`telegram-reply.sh` parses flags in a loop that breaks at the first non-flag argument — the
+topic id. Everything after that becomes the message via `MSG="$*"`. So
+`telegram-reply.sh 29723 --tone-ack B15 --tone-reason "why"` sent the user the literal text
+`--tone-ack B15 --tone-reason why`, while the tone-advisory override never reached the
+server. Both failures were silent; the script exited 0.
+
+This is measured, not inferred. The pre-fix template is captured verbatim as a test fixture
+(at the same SHA now registered in the migrator's shipped-SHA allowlist) and run against a
+stub of the reply route: exit 0, received text containing `--tone-ack`, and no
+`toneAdvisoryAck` in the metadata.
+
+**The cost was a corrupted measurement.** Because the override never applied, the tone gate
+re-reviewed the send as an ordinary message whose text now began with option noise. The
+verdict looked absurd, was read as a malfunction, and a **correct** check was graded `wrong`
+in the decision-quality data — the data used to decide which checks to trust. That record is
+durable and is not retracted by this change.
+
+**The root cause was not the script.** These flags were documented nowhere agent-facing:
+not in the script's own usage header (which covers `--format` and `--stdin-base64`), and not
+in the agent instructions, which document the HTTP `metadata.*` fields while simultaneously
+mandating "ALWAYS the relay script, never a hand-rolled curl". The bridge between the two
+did not exist, so the invocation had to be guessed — and the script accepted the guess
+without complaint. A capability shipped without instructions, plus a tool that stayed silent
+on the only usage an uninstructed caller would try.
+
+An inconsistency underneath made the fix obvious once seen: the script **already** treated an
+unrecognised flag-shaped token as fatal when it appeared *before* the topic id. It was strict
+about nonsense in one position and fully permissive about a real flag in the other. Both
+positions are now treated the same.
+
+Three parts, because the chain had three links:
+
+1. **The script refuses** a `--*` argument after the topic id, printing the correct ordering
+   and the corrected command. Nothing is sent.
+2. **A typo'd flag is caught too** (`--tone-akc`) — the realistic mistake, and equally silent
+   before. The guard matches the *shape*, not a list of known names, which is what makes it
+   useful rather than decorative.
+3. **The flags are documented** — in the script's usage header and in the agent instructions,
+   with a worked example showing flags before the topic id.
+
+**What this does not do:** it does not retract the false grade from 2026-07-26. Whether a
+mistaken grade can be corrected at all — and whether correcting one erases the evidence that
+it was ever made, which would be the opposite defect — is a separate open question, and is
+deliberately not answered here. It also fixes only this script; `slack-reply.sh` and
+`whatsapp-reply.sh` share the parse-then-break shape but carry no tone flags today, so they
+are named rather than swept in.
+
+## What to Tell Your User
+
+If a stray double-dash option ever appeared in the middle of one of my messages to you, that
+was this: a setting that belonged in the plumbing ended up in the text, and whatever it was
+supposed to do quietly didn't happen. It can't reach you as text any more — the send is
+refused and corrected instead.
+
+The part worth knowing: one of those settings is how I record that I disagree with one of my
+own safety checks. When it silently failed to apply, I misread the result and marked a check
+as faulty when it had actually been right. So this wasn't only cosmetic — it put a wrong
+entry in the records used to judge whether those checks are any good. That entry is still
+there; this stops more from being created.
+
+## Summary of New Capabilities
+
+- A flag placed after the topic id is refused with an actionable message naming the correct
+  ordering, instead of being sent to the user as literal text with its effect dropped.
+- A misspelled flag after the topic id is caught by the same guard.
+- The tone-advisory reaction flags (`--tone-ack`, `--tone-reason`, `--tone-complied`,
+  `--tone-decision-ref`) are documented in the script's usage header and in the agent
+  instructions, with a worked example.
+- Existing agents receive both the new script and the new documentation — the doc block is
+  sniffed on its own marker so an agent that already carries the surrounding section is not
+  skipped.
+
+## Evidence
+
+**Reproduction (before),** the pre-fix template against a stub reply route:
+
+| invocation | exit | text received by the user | override applied |
+|---|---|---|---|
+| `… 4242 --tone-ack B15 --tone-reason because` | `0` | `--tone-ack B15 --tone-reason because` | no |
+
+**Observed after,** same stub:
+
+| invocation | before | after |
+|---|---|---|
+| flag after the topic id | sent as message text, exit 0 | refused, exit 1, **zero requests sent** |
+| typo'd flag after the topic id | sent as message text, exit 0 | refused, exit 1, zero requests |
+| flags before the topic id | worked | works — text clean, `toneAdvisoryAck` + reason present |
+| message on stdin containing a flag-shaped token | sent verbatim | sent verbatim (stdin is not inspected) |
+| unknown flag before the topic id | `Unknown flag`, exit 1 | unchanged |
+
+**Tests:** `tests/integration/telegram-reply-misplaced-flag.test.ts` (6) runs the real
+template — and the pre-fix fixture — against a stub route, so "was it sent as text?" is
+answered by the received payload rather than by reading the script.
+`tests/unit/PostUpdateMigrator-toneAdvisoryFlagPosition.test.ts` (3) covers migration parity,
+including the load-bearing case: an agent that already carries the tone-advisory section must
+still receive the invocation guidance. That test was verified to FAIL when the second
+migration block is disabled, so it cannot pass whether or not the migration exists. The full
+telegram-reply and template-SHA surface (10 files, 51 tests) passes unchanged;
+`npx tsc --noEmit` clean.

package/upgrades/side-effects/behavioural-promise-unverifiable.md

@@ -100,8 +100,23 @@ explicit in code: absence of a verdict is reported as absence, never as either o
   between them causes no change in expiry behaviour — checked before editing.
 - **PromiseBeacon / overdue surfacing** operate on open commitments; `pending` keeps them
   visible, which is the stated intent of the precedent ("should NAG, not vanish").
-- No persistence change, no migration, no config key. Existing rows re-evaluate to
-  `pending` on the next sweep without a data rewrite.
+- No persistence change, no migration, no config key.
+- ~~Existing rows re-evaluate to `pending` on the next sweep without a data rewrite.~~
+  **CORRECTED 2026-07-26 — this was FALSE and is struck rather than deleted.** The
+  behavioural branch returns BEFORE the `switch` in `verifyOne`, so `mutateSync` never runs
+  and a pre-existing row is never touched. **The change is FORWARD-ONLY.**
+  Verified on the live store after deploy: 98 behavioural rows still read **74 `verified` /
+  24 `violated`**, unchanged. What the change DID do, measured over two reads 75s apart:
+  tick accumulation stopped dead (one row frozen at 163,135 where it had been climbing every
+  minute). What it did NOT do: clear the 98 stale verdicts — so the false comfort this change
+  set out to remove is still displayed for every row that predates it, and `getHealth`, which
+  now counts actual `verified` rows, will report those 74 stale stamps as verified.
+  Remedy is an open operator decision, not a reflex: either a migration resetting behavioural
+  rows to `pending` (a data rewrite this very section claimed was unnecessary) or a read
+  surface that refuses a verdict for a never-verifiable row whatever is stored.
+  **Found by reading the live surface for the exact case the change fixed** — no test caught
+  it, and the suite was green. An artifact that over-claims is the same defect class as the
+  bug it documents, which is why the wrong sentence stays visible above.
 
 ## 6. External surfaces