instar 1.3.984 → 1.3.986

package/dist/core/claudeReadinessProbe.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Readiness classification for a framework TUI pane tail.
+ *
+ * WHY THIS EXISTS AS ITS OWN MODULE
+ * ---------------------------------
+ * On 2026-07-26 a user's message was injected into a freshly-spawned Claude Code
+ * pane 15 seconds before that pane could accept input. The paste was swallowed by
+ * the TUI still painting itself, and the delivery was logged as a SUCCESS
+ * (`Injected initial message into "…" (915 chars, after stabilization delay)`).
+ * The message reached the agent only because an unrelated start-hook backstop
+ * re-read recent history.
+ *
+ * The cause was the readiness probe, not the injector. It accepted a bare
+ * slash-command mention anywhere in the captured tail:
+ *
+ *     if (/\/(effort|model|fast)/.test(tail)) return true;
+ *
+ * Claude Code's startup banner advertises slash commands IN PROSE — the pane that
+ * fooled it carried "…Run /model and select Fable to use it." So the probe matched
+ * a promotional line and declared a still-booting pane ready. A string matcher
+ * fooled by its own subject: the banner that proves the app is NOT yet accepting
+ * input was read as proof that it is.
+ *
+ * THOSE CLAUSES ARE DELETED, NOT TUNED. The first fix attempt kept them and
+ * required "status-bar shape" (line-start, or directly after an interpunct).
+ * Second-pass review falsified that:
+ *   - The banner uses the same shape. `⚠ CLAUDE.md is over the … limit · /memory
+ *     to free up context` and `+1 more · /status` are BANNER lines in interpunct
+ *     shape. The only thing separating them from a status bar was that `memory`
+ *     and `status` fall outside the three-word set — i.e. still vocabulary, and a
+ *     plausible `· /model to opt in` promo line matched outright.
+ *   - The line-start branch reinstated the Anthropic-copy dependency it claimed to
+ *     remove: at a fixed pane width an edit shifting the wrap by ~14 characters
+ *     puts `/model` at column 0 and the original defect returns.
+ * A signal that cannot separate an ADVERT for a command from a STATUS BAR showing
+ * one carries no information about readiness. Widening the genuinely structural
+ * markers below costs nothing and covers the same panes.
+ *
+ * WHY THE ANSWER IS NOT A BOOLEAN
+ * -------------------------------
+ * There are three consumers and they want OPPOSITE responses to the two ways a
+ * pane can fail to be ready:
+ *   - the spawn/inject path — must not type into a pane that is still painting,
+ *     and must not type into a MENU (see below);
+ *   - `waitForClaudeReadyWithRetry` — waits, then falls back;
+ *   - the Slack stuck-session path (`server.ts`) — calls this on an ALREADY-LIVE
+ *     session and KILLS it when the answer is not-ready.
+ * A bare `false` tells that third caller "kill this" for a pane that is merely
+ * mid-boot or politely waiting on a question. So the probe reports WHICH state it
+ * saw and each caller applies its own policy. `isReadyPromptTail` is retained as
+ * the boolean façade for callers that genuinely only want "can I type now".
+ *
+ * THE MENU CASE (found by the operator, 2026-07-26)
+ * -------------------------------------------------
+ * Claude Code paints the SAME `❯` glyph on a menu's focused option as it uses for
+ * the input box (`PermissionPromptAutoResolver.SELECTOR_GLYPH`). So a session
+ * sitting on a startup question read as READY. This is strictly worse than the
+ * banner case: text typed at a banner is lost, but text typed at a menu is not —
+ * Enter SELECTS AN OPTION, so an arriving message can answer a permission question
+ * on the operator's behalf. A menu is therefore classified as its own state, never
+ * as ready, no matter which glyphs it carries.
+ *
+ * Kept pure (text in, verdict out) so it is testable without tmux, and so the
+ * regression fixtures are the literal pane text that caused each finding.
+ *
+ * RULE 3.1 RATIONALE (state-detection; registry:
+ * `specs/provider-portability/06-state-detector-registry.md`)
+ * ------------------------------------------------------------------------------
+ * - **Criticality:** silent-corruption-if-wrong — the worst class, demonstrated
+ *   twice. A false `ready` on a painting pane loses a user message AND writes a
+ *   success line for it; a false `ready` on a menu is worse still, because Enter
+ *   SELECTS an option, so an arriving message can answer a permission question on
+ *   the operator's behalf.
+ * - **Frequency:** per-spawn and per-inject, plus per-stuck-check on the Slack
+ *   path.
+ * - **Stability:** UNSTABLE. Claude Code's TUI is a private surface. This is not a
+ *   theoretical rating — the 2026-07-26 incident WAS an upstream copy change (a
+ *   Fable-5 promo line) turning a passing detector into a failing one, and the
+ *   menu case is an upstream glyph reuse.
+ * - **Fallback:** partial and asymmetric. The spawn path has an extended wait and
+ *   a blind-inject-if-alive fallback; the loss on 2026-07-26 was caught only by
+ *   the start hook's unanswered-message backstop, which is an unrelated path and
+ *   cannot be relied on as this detector's safety net. The Slack path's not-ready
+ *   branch is DESTRUCTIVE (kill + respawn), so a wrong answer there costs a live
+ *   session, not a delay.
+ * - **→ Verdict: deterministic + canary REQUIRED.** This module ships the
+ *   deterministic half plus regression fixtures carrying the literal pane text of
+ *   both known failures. It does NOT ship a canary, so it detects the two shapes
+ *   that already bit us and not the next drift. Canary tracked as CMT-1044.
+ *   <!-- tracked: CMT-1044 -->
+ */
+/**
+ * What a captured pane tail shows.
+ *
+ * - `ready`        — an input surface is drawn and accepting input.
+ * - `menu`         — a numbered selection menu is focused. NOT ready, and NOT a
+ *                    stuck session: something is waiting on an answer. A caller
+ *                    that kills on not-ready must not kill on this.
+ * - `not-ready`    — no input surface found (typically still painting).
+ */
+export type PaneReadiness = 'ready' | 'menu' | 'not-ready';
+/**
+ * True when the tail shows a FOCUSED selection menu.
+ *
+ * Requires the selector glyph to sit ON a numbered option line, AND at least two
+ * numbered option lines overall. Both halves are load-bearing:
+ *
+ *   - "glyph on the option line" separates a menu from the input box. The box
+ *     renders `❯` alone on its own line; a menu renders `❯ 1. Yes`. Testing only
+ *     "the tail contains ❯ somewhere" would classify ordinary assistant output
+ *     that happens to list `1.` and `2.` above the prompt as a menu, stalling a
+ *     genuinely ready session — an over-block on the inject path.
+ *   - "at least two options" separates a menu from a single numbered line of
+ *     ordinary output.
+ *
+ * This mirrors `PermissionPromptAutoResolver`'s requirement (a line whose lead
+ * glyphs contain ❯ whose text is `N.` + a label) rather than inventing a second,
+ * divergent notion of what a menu looks like.
+ */
+export declare function tailShowsMenu(tail: string): boolean;
+/**
+ * Classify a captured pane tail.
+ *
+ * `tail` is the joined last-N non-blank lines of a `capture-pane` read. Never pass
+ * the whole scrollback: a banner that has scrolled far above the prompt is not
+ * evidence either way, and older content only adds false-positive surface.
+ */
+export declare function classifyPaneReadiness(tail: string): PaneReadiness;
+/**
+ * Boolean façade: can text be typed into this pane right now?
+ *
+ * A menu answers `false` — correct for every caller that is about to type. A
+ * caller whose not-ready branch is DESTRUCTIVE (kill/respawn) must use
+ * `classifyPaneReadiness` instead and leave a `menu` pane alone.
+ */
+export declare function isReadyPromptTail(tail: string): boolean;
+//# sourceMappingURL=claudeReadinessProbe.d.ts.map

package/dist/core/claudeReadinessProbe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claudeReadinessProbe.d.ts","sourceRoot":"","sources":["../../src/core/claudeReadinessProbe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC;AA6B3D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUnD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAejE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD"}

package/dist/core/claudeReadinessProbe.js

@@ -0,0 +1,181 @@
+/**
+ * Readiness classification for a framework TUI pane tail.
+ *
+ * WHY THIS EXISTS AS ITS OWN MODULE
+ * ---------------------------------
+ * On 2026-07-26 a user's message was injected into a freshly-spawned Claude Code
+ * pane 15 seconds before that pane could accept input. The paste was swallowed by
+ * the TUI still painting itself, and the delivery was logged as a SUCCESS
+ * (`Injected initial message into "…" (915 chars, after stabilization delay)`).
+ * The message reached the agent only because an unrelated start-hook backstop
+ * re-read recent history.
+ *
+ * The cause was the readiness probe, not the injector. It accepted a bare
+ * slash-command mention anywhere in the captured tail:
+ *
+ *     if (/\/(effort|model|fast)/.test(tail)) return true;
+ *
+ * Claude Code's startup banner advertises slash commands IN PROSE — the pane that
+ * fooled it carried "…Run /model and select Fable to use it." So the probe matched
+ * a promotional line and declared a still-booting pane ready. A string matcher
+ * fooled by its own subject: the banner that proves the app is NOT yet accepting
+ * input was read as proof that it is.
+ *
+ * THOSE CLAUSES ARE DELETED, NOT TUNED. The first fix attempt kept them and
+ * required "status-bar shape" (line-start, or directly after an interpunct).
+ * Second-pass review falsified that:
+ *   - The banner uses the same shape. `⚠ CLAUDE.md is over the … limit · /memory
+ *     to free up context` and `+1 more · /status` are BANNER lines in interpunct
+ *     shape. The only thing separating them from a status bar was that `memory`
+ *     and `status` fall outside the three-word set — i.e. still vocabulary, and a
+ *     plausible `· /model to opt in` promo line matched outright.
+ *   - The line-start branch reinstated the Anthropic-copy dependency it claimed to
+ *     remove: at a fixed pane width an edit shifting the wrap by ~14 characters
+ *     puts `/model` at column 0 and the original defect returns.
+ * A signal that cannot separate an ADVERT for a command from a STATUS BAR showing
+ * one carries no information about readiness. Widening the genuinely structural
+ * markers below costs nothing and covers the same panes.
+ *
+ * WHY THE ANSWER IS NOT A BOOLEAN
+ * -------------------------------
+ * There are three consumers and they want OPPOSITE responses to the two ways a
+ * pane can fail to be ready:
+ *   - the spawn/inject path — must not type into a pane that is still painting,
+ *     and must not type into a MENU (see below);
+ *   - `waitForClaudeReadyWithRetry` — waits, then falls back;
+ *   - the Slack stuck-session path (`server.ts`) — calls this on an ALREADY-LIVE
+ *     session and KILLS it when the answer is not-ready.
+ * A bare `false` tells that third caller "kill this" for a pane that is merely
+ * mid-boot or politely waiting on a question. So the probe reports WHICH state it
+ * saw and each caller applies its own policy. `isReadyPromptTail` is retained as
+ * the boolean façade for callers that genuinely only want "can I type now".
+ *
+ * THE MENU CASE (found by the operator, 2026-07-26)
+ * -------------------------------------------------
+ * Claude Code paints the SAME `❯` glyph on a menu's focused option as it uses for
+ * the input box (`PermissionPromptAutoResolver.SELECTOR_GLYPH`). So a session
+ * sitting on a startup question read as READY. This is strictly worse than the
+ * banner case: text typed at a banner is lost, but text typed at a menu is not —
+ * Enter SELECTS AN OPTION, so an arriving message can answer a permission question
+ * on the operator's behalf. A menu is therefore classified as its own state, never
+ * as ready, no matter which glyphs it carries.
+ *
+ * Kept pure (text in, verdict out) so it is testable without tmux, and so the
+ * regression fixtures are the literal pane text that caused each finding.
+ *
+ * RULE 3.1 RATIONALE (state-detection; registry:
+ * `specs/provider-portability/06-state-detector-registry.md`)
+ * ------------------------------------------------------------------------------
+ * - **Criticality:** silent-corruption-if-wrong — the worst class, demonstrated
+ *   twice. A false `ready` on a painting pane loses a user message AND writes a
+ *   success line for it; a false `ready` on a menu is worse still, because Enter
+ *   SELECTS an option, so an arriving message can answer a permission question on
+ *   the operator's behalf.
+ * - **Frequency:** per-spawn and per-inject, plus per-stuck-check on the Slack
+ *   path.
+ * - **Stability:** UNSTABLE. Claude Code's TUI is a private surface. This is not a
+ *   theoretical rating — the 2026-07-26 incident WAS an upstream copy change (a
+ *   Fable-5 promo line) turning a passing detector into a failing one, and the
+ *   menu case is an upstream glyph reuse.
+ * - **Fallback:** partial and asymmetric. The spawn path has an extended wait and
+ *   a blind-inject-if-alive fallback; the loss on 2026-07-26 was caught only by
+ *   the start hook's unanswered-message backstop, which is an unrelated path and
+ *   cannot be relied on as this detector's safety net. The Slack path's not-ready
+ *   branch is DESTRUCTIVE (kill + respawn), so a wrong answer there costs a live
+ *   session, not a delay.
+ * - **→ Verdict: deterministic + canary REQUIRED.** This module ships the
+ *   deterministic half plus regression fixtures carrying the literal pane text of
+ *   both known failures. It does NOT ship a canary, so it detects the two shapes
+ *   that already bit us and not the next drift. Canary tracked as CMT-1044.
+ *   <!-- tracked: CMT-1044 -->
+ */
+/**
+ * Status-bar / footer strings that only exist once the TUI has finished starting.
+ *
+ * Sourced from the probes already trusted for this elsewhere in the tree
+ * (`SessionReaper`, the interactive-pool adapter config) rather than invented
+ * here, so the readiness question gets one vocabulary instead of four. Verified
+ * absent from the boot banner. `bypass permissions` alone covered only ONE of
+ * Claude Code's permission-mode footers — a session in auto-accept mode shows
+ * none of it — which is why the `❯`-is-always-present assumption was load-bearing
+ * before and is not now.
+ */
+const AT_PROMPT_FOOTERS = [
+    'bypass permissions',
+    '? for shortcuts',
+    'shift+tab to cycle',
+    'auto-accept edits',
+];
+/**
+ * A menu option line: an optional glyph run, then `N.` or `N)` and a label.
+ * Matches the shape Claude Code uses for approval / consent / trust prompts.
+ */
+const MENU_OPTION_RE = /^[^\w\n]{0,4}\s*\d+[.)]\s+\S/;
+/** The selector cursor Claude Code paints on the focused option — and on nothing else. */
+const SELECTOR_GLYPH = '❯';
+/**
+ * True when the tail shows a FOCUSED selection menu.
+ *
+ * Requires the selector glyph to sit ON a numbered option line, AND at least two
+ * numbered option lines overall. Both halves are load-bearing:
+ *
+ *   - "glyph on the option line" separates a menu from the input box. The box
+ *     renders `❯` alone on its own line; a menu renders `❯ 1. Yes`. Testing only
+ *     "the tail contains ❯ somewhere" would classify ordinary assistant output
+ *     that happens to list `1.` and `2.` above the prompt as a menu, stalling a
+ *     genuinely ready session — an over-block on the inject path.
+ *   - "at least two options" separates a menu from a single numbered line of
+ *     ordinary output.
+ *
+ * This mirrors `PermissionPromptAutoResolver`'s requirement (a line whose lead
+ * glyphs contain ❯ whose text is `N.` + a label) rather than inventing a second,
+ * divergent notion of what a menu looks like.
+ */
+export function tailShowsMenu(tail) {
+    if (!tail || !tail.includes(SELECTOR_GLYPH))
+        return false;
+    let options = 0;
+    let glyphOnOption = false;
+    for (const line of tail.split('\n')) {
+        if (!MENU_OPTION_RE.test(line))
+            continue;
+        options++;
+        if (line.includes(SELECTOR_GLYPH))
+            glyphOnOption = true;
+    }
+    return glyphOnOption && options >= 2;
+}
+/**
+ * Classify a captured pane tail.
+ *
+ * `tail` is the joined last-N non-blank lines of a `capture-pane` read. Never pass
+ * the whole scrollback: a banner that has scrolled far above the prompt is not
+ * evidence either way, and older content only adds false-positive surface.
+ */
+export function classifyPaneReadiness(tail) {
+    if (!tail)
+        return 'not-ready';
+    // A menu is checked FIRST and wins over every positive marker below, because it
+    // carries the same `❯` the input box does. Typing here selects an option.
+    if (tailShowsMenu(tail))
+        return 'menu';
+    // The framework prompt character. Codex uses ›; keeping this probe Claude-only
+    // previously delayed continuation bootstraps to the full timeout.
+    if (tail.includes(SELECTOR_GLYPH) || tail.includes('›'))
+        return 'ready';
+    // Footer/status-bar strings that only render once the TUI is up.
+    if (AT_PROMPT_FOOTERS.some(marker => tail.includes(marker)))
+        return 'ready';
+    return 'not-ready';
+}
+/**
+ * Boolean façade: can text be typed into this pane right now?
+ *
+ * A menu answers `false` — correct for every caller that is about to type. A
+ * caller whose not-ready branch is DESTRUCTIVE (kill/respawn) must use
+ * `classifyPaneReadiness` instead and leave a `menu` pane alone.
+ */
+export function isReadyPromptTail(tail) {
+    return classifyPaneReadiness(tail) === 'ready';
+}
+//# sourceMappingURL=claudeReadinessProbe.js.map

package/dist/core/claudeReadinessProbe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claudeReadinessProbe.js","sourceRoot":"","sources":["../../src/core/claudeReadinessProbe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AAaH;;;;;;;;;;GAUG;AACH,MAAM,iBAAiB,GAAG;IACxB,oBAAoB;IACpB,iBAAiB;IACjB,oBAAoB;IACpB,mBAAmB;CACpB,CAAC;AAEF;;;GAGG;AACH,MAAM,cAAc,GAAG,8BAA8B,CAAC;AAEtD,0FAA0F;AAC1F,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1D,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,aAAa,GAAG,KAAK,CAAC;IAC1B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QACzC,OAAO,EAAE,CAAC;QACV,IAAI,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC;YAAE,aAAa,GAAG,IAAI,CAAC;IAC1D,CAAC;IACD,OAAO,aAAa,IAAI,OAAO,IAAI,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,IAAI,CAAC,IAAI;QAAE,OAAO,WAAW,CAAC;IAE9B,gFAAgF;IAChF,0EAA0E;IAC1E,IAAI,aAAa,CAAC,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC;IAEvC,+EAA+E;IAC/E,kEAAkE;IAClE,IAAI,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IAExE,iEAAiE;IACjE,IAAI,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAAE,OAAO,OAAO,CAAC;IAE5E,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,qBAAqB,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC;AACjD,CAAC"}

package/package.json

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

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-26T08:47:20.129Z",
-  "instarVersion": "1.3.984",
+  "generatedAt": "2026-07-26T18:49:10.482Z",
+  "instarVersion": "1.3.986",
   "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": {
@@ -1538,7 +1538,7 @@
       "type": "subsystem",
       "domain": "sessions",
       "sourcePath": "src/core/SessionManager.ts",
-      "contentHash": "4fb46f8df9bd47f899f51c13d25057a158d21b00bacec8bbecd75b3414c64b95",
+      "contentHash": "3f88cbed25892776b9eaa258ff68b7eb7b8b676713ea01280899ee8f5b282e96",
       "since": "2025-01-01"
     },
     "subsystem:auto-updater": {
@@ -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="$*"