switchroom 0.19.41 → 0.19.43

package/telegram-plugin/tests/tg-post-retry-attribution.test.ts

@@ -0,0 +1,196 @@
+/**
+ * A reply that was rate-limited and then DELIVERED on retry must not raise a
+ * fleet-health delivery-failure alert (#3931).
+ *
+ * ── The bug ──────────────────────────────────────────────────────────────
+ * `installTgPostLogger` is a grammy API transformer, so it runs INSIDE the
+ * function the retry policy calls — it observes one POST ATTEMPT, never the
+ * logical send's outcome. A 429 that `createRetryApiCall` slept and retried
+ * successfully therefore left a `tg-post method=sendRichMessage … status=err`
+ * line in the gateway log, and fleet-health's `reply-delivery-failure`
+ * signature (`src/fleet-health/detect.ts`) matches per LINE. Result: a
+ * severity-3 "the answer never reached the principal" escalation for an answer
+ * the operator had already read. Under flood pressure (the class of event that
+ * produces 429s in the first place) that is the alarm that fires most.
+ *
+ * ── The fix these tests pin ──────────────────────────────────────────────
+ * The retry policy publishes its attempt context; the transformer labels an
+ * attempt the policy is about to repeat `status=retry`. `status=err` now means
+ * the logical send is OVER and nothing landed. Nothing is suppressed — the
+ * retry lines are still written, they just no longer masquerade as outcomes.
+ *
+ * These tests drive a REAL grammy `Bot` (a mock-`api` harness sits above the
+ * transformer layer, so it would be a false guard) through the REAL retry
+ * policy, and feed the REAL emitted lines to the REAL detector.
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { Bot } from 'grammy'
+import { installTgPostLogger } from '../shared/bot-runtime.js'
+import { createRetryApiCall, willRetryTelegramFailure } from '../retry-api-call.js'
+import { detectGatewayFindings, scanAgent } from '../../src/fleet-health/detect.js'
+
+/** A real Bot whose transport answers with `envelopes[i]` for the i-th call. */
+function makeBot(envelopes: Array<Record<string, unknown>>): Bot {
+  let i = 0
+  const fakeFetch = (async () => {
+    const envelope = envelopes[Math.min(i, envelopes.length - 1)]
+    i++
+    // A Bot API rejection is an HTTP 200 carrying `ok:false` — which is
+    // precisely why it RESOLVES the transformer chain (see #3927).
+    return { ok: true, status: 200, json: async () => envelope } as unknown as Response
+  }) as unknown as typeof fetch
+
+  const bot = new Bot('123456:TEST_TOKEN', {
+    botInfo: {
+      id: 123456,
+      is_bot: true,
+      first_name: 'Test',
+      username: 'test_bot',
+      can_join_groups: false,
+      can_read_all_group_messages: false,
+      supports_inline_queries: false,
+      can_connect_to_business: false,
+      has_main_web_app: false,
+    },
+    client: { fetch: fakeFetch },
+  })
+  installTgPostLogger(bot)
+  return bot
+}
+
+const OK_ENVELOPE = {
+  ok: true,
+  result: { message_id: 7, date: 0, chat: { id: 4242, type: 'private' } },
+}
+const FLOOD_429 = {
+  ok: false,
+  error_code: 429,
+  description: 'Too Many Requests: retry after 3',
+  parameters: { retry_after: 3 },
+}
+
+/**
+ * Send one user-facing reply through the production composition
+ * (retry policy → transformer → wire) and return the gateway log lines it
+ * produced, shaped exactly as `gateway-supervisor.log` carries them.
+ */
+async function gatewayLinesForReply(
+  envelopes: Array<Record<string, unknown>>,
+): Promise<{ lines: string[]; threw: boolean }> {
+  const written: string[] = []
+  const spy = vi.spyOn(process.stderr, 'write').mockImplementation(((chunk: unknown) => {
+    written.push(String(chunk))
+    return true
+  }) as unknown as typeof process.stderr.write)
+  let threw = false
+  try {
+    const bot = makeBot(envelopes)
+    // The real policy, with sleeping stubbed out so a 3s flood-wait doesn't
+    // cost the suite 3 seconds. Everything else is production behaviour.
+    const robustApiCall = createRetryApiCall({ sleep: async () => {} })
+    await robustApiCall(() =>
+      bot.api.sendRichMessage(4242, { markdown: 'the answer' }),
+    ).catch(() => {
+      threw = true
+    })
+  } finally {
+    spy.mockRestore()
+  }
+  const lines = written
+    .filter((l) => l.startsWith('tg-post '))
+    .map((l) => `2026-08-01T12:00:00Z gateway: ${l.trimEnd()}`)
+  return { lines, threw }
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('#3931 — a retried-and-delivered reply raises no delivery-failure alert', () => {
+  it('429-then-ok: fleet-health sees zero reply-delivery-failures and does not escalate', async () => {
+    const { lines, threw } = await gatewayLinesForReply([FLOOD_429, OK_ENVELOPE])
+
+    // Ground truth: the reply WAS delivered. If this ever fails, the fixture
+    // stopped modelling the scenario and the assertions below mean nothing.
+    expect(threw).toBe(false)
+    expect(lines).toHaveLength(2)
+    expect(lines[1]).toContain('status=ok')
+
+    // THE outcome: the detector raises nothing, and the agent is not escalated.
+    const { gw_hits, findings } = detectGatewayFindings('alpha', lines.join('\n'))
+    expect(gw_hits['reply-delivery-failure']).toBe(0)
+    expect(findings.filter((f) => f.signal === 'reply-delivery-failure')).toHaveLength(0)
+    expect(scanAgent('alpha', '', lines.join('\n')).escalate).toBe(false)
+
+    // The evidence is not hidden — the rate-limit attempt is still on the log,
+    // honestly labelled as an attempt rather than an outcome.
+    expect(lines[0]).toContain('status=retry')
+    expect(lines[0]).toContain('code=429')
+  })
+
+  it('an ok:true reply is untouched — no retry tier leaks onto the happy path', async () => {
+    const { lines, threw } = await gatewayLinesForReply([OK_ENVELOPE])
+    expect(threw).toBe(false)
+    expect(lines).toHaveLength(1)
+    expect(lines[0]).toContain('status=ok')
+    expect(lines[0]).toContain('err=- code=- desc=-')
+  })
+})
+
+describe('#3931 — a genuinely undelivered reply still escalates', () => {
+  it('a terminal 403 escalates', async () => {
+    const { lines, threw } = await gatewayLinesForReply([
+      { ok: false, error_code: 403, description: 'Forbidden: bot was blocked by the user' },
+    ])
+    expect(threw).toBe(true)
+    expect(lines).toHaveLength(1)
+    expect(lines[0]).toContain('status=err')
+
+    expect(detectGatewayFindings('alpha', lines.join('\n')).gw_hits['reply-delivery-failure']).toBe(1)
+    expect(scanAgent('alpha', '', lines.join('\n')).escalate).toBe(true)
+  })
+
+  it('a 429 on EVERY attempt (retries exhausted, nothing landed) escalates exactly once', async () => {
+    const { lines, threw } = await gatewayLinesForReply([FLOOD_429])
+    expect(threw).toBe(true)
+    // Three attempts: two survivable, the last one terminal.
+    expect(lines).toHaveLength(3)
+    expect(lines.filter((l) => l.includes('status=retry'))).toHaveLength(2)
+    expect(lines.filter((l) => l.includes('status=err'))).toHaveLength(1)
+
+    // One alert for one lost answer — not one per attempt.
+    expect(detectGatewayFindings('alpha', lines.join('\n')).gw_hits['reply-delivery-failure']).toBe(1)
+    expect(scanAgent('alpha', '', lines.join('\n')).escalate).toBe(true)
+  })
+})
+
+describe('willRetryTelegramFailure — the predicate mirrors the retry loop', () => {
+  const ctx = { attempt: 0, maxRetries: 3, maxFloodSleepMs: 120_000 }
+
+  it('is false with no enclosing retry policy (a raw bot.api.* call is its own outcome)', () => {
+    expect(willRetryTelegramFailure({ errorCode: 429, retryAfterSec: 3 }, undefined)).toBe(false)
+  })
+
+  it('is false on the last attempt — the loop falls through to give-up', () => {
+    expect(
+      willRetryTelegramFailure({ errorCode: 429, retryAfterSec: 3 }, { ...ctx, attempt: 2 }),
+    ).toBe(false)
+  })
+
+  it('is false for a 429 over the in-process sleep ceiling (FLOOD_WAIT_ACTIVE, not retried)', () => {
+    expect(willRetryTelegramFailure({ errorCode: 429, retryAfterSec: 15908 }, ctx)).toBe(false)
+  })
+
+  it('is true for a 429 under the ceiling and for a transient transport error', () => {
+    expect(willRetryTelegramFailure({ errorCode: 429, retryAfterSec: 3 }, ctx)).toBe(true)
+    expect(willRetryTelegramFailure({ message: 'ECONNRESET' }, ctx)).toBe(true)
+  })
+
+  it('is false for the error classes the loop rethrows immediately', () => {
+    expect(willRetryTelegramFailure({ errorCode: 400, message: 'Bad Request' }, ctx)).toBe(false)
+    expect(willRetryTelegramFailure({ errorCode: 403 }, ctx)).toBe(false)
+    // Local disk exhaustion must NOT look retryable — retrying it is what
+    // trips the flood ban in the first place (#2923).
+    expect(willRetryTelegramFailure({ message: 'ENOSPC: no space left on device' }, ctx)).toBe(false)
+  })
+})

package/telegram-plugin/tests/tool-activity-summary.test.ts

@@ -14,7 +14,13 @@ import {
   STEP_TIMER_MIN_MS,
   type SessionActivityHeader,
 } from "../tool-activity-summary.js";
-import { STATUS_ROLLING_LINES, STATUS_LINE_MAX } from "../status-no-truncate.js";
+import { STATUS_ROLLING_LINES, STATUS_LINE_MAX, NESTED_PREFIX } from "../status-no-truncate.js";
+
+// The nested (foreground sub-agent) child-block indent. Asserted through the
+// constant, never as a literal: #3668 replaced its ASCII spaces with U+2800
+// (Telegram left-trims a leading ASCII/Zs run off a content line), and a test
+// that hardcodes the bytes pins the defect instead of the behaviour.
+const NP = NESTED_PREFIX;
 import { COLLAPSE_SAFE_SEPARATOR } from "../card-format.js";
 
 /** The pinned-card collapse separator (#3666) every status-card line now
@@ -352,29 +358,29 @@ describe("renderActivityFeedWithNested — foreground sub-agent nesting (Model A
     expect(out).toContain("~~_✓ Delegating: review the migration_~~");
     expect(out).not.toContain("**→ Delegating");
     // The live → step is the newest nested child line; earlier child = italic.
-    expect(out).toContain("   ↳ ~~_Reading schema.ts_~~");
-    expect(out).toContain("   ↳ **→ Looking for foreign keys**");
+    expect(out).toContain(NP + "~~_Reading schema.ts_~~");
+    expect(out).toContain(NP + "**→ Looking for foreign keys**");
   });
 
   it("windows the nested block to STATUS_ROLLING_LINES with a '↳ +N earlier…' header", () => {
     const total = STATUS_ROLLING_LINES + 3;
     const child = Array.from({ length: total }, (_, i) => `step ${i + 1}`);
     const out = renderActivityFeedWithNested(["Delegating: x"], child)!;
-    expect(out).toContain(`   ↳ _+${total - STATUS_ROLLING_LINES} earlier…_`);
+    expect(out).toContain(`${NP}_+${total - STATUS_ROLLING_LINES} earlier…_`);
     // newest nested line is the live → step
-    expect(out).toContain(`   ↳ **→ step ${total}**`);
+    expect(out).toContain(`${NP}**→ step ${total}**`);
     // the oldest (collapsed) lines are not rendered verbatim
     expect(out).not.toContain("step 1<");
   });
 
   it("renders the child block even when the parent feed is empty", () => {
     const out = renderActivityFeedWithNested([], ["Reading a.ts"]);
-    expect(out).toBe("   ↳ **→ Reading a.ts**");
+    expect(out).toBe(NP + "**→ Reading a.ts**");
   });
 
   it("markdown-escapes nested child text (emphasis specials only)", () => {
     const out = renderActivityFeedWithNested(["Delegating: x"], ["touch a_b & 2 * 3"])!;
-    expect(out).toContain("   ↳ **→ touch a\\_b & 2 \\* 3**");
+    expect(out).toContain(NP + "**→ touch a\\_b & 2 \\* 3**");
   });
 
   it("final=true: the nested newest step renders done (✓), not in-progress (→)", () => {
@@ -383,7 +389,7 @@ describe("renderActivityFeedWithNested — foreground sub-agent nesting (Model A
       ["Reading schema.ts", "Looking for foreign keys"],
       true,
     )!;
-    expect(out).toContain("   ↳ ~~_Looking for foreign keys_~~"); // newest now struck italic done
+    expect(out).toContain(NP + "~~_Looking for foreign keys_~~"); // newest now struck italic done
     expect(out).not.toContain("→"); // no in-progress arrow in the finalized feed
   });
 
@@ -400,7 +406,7 @@ describe("renderActivityFeedWithNested — foreground sub-agent nesting (Model A
       false,
       " · 22s",
     )!;
-    expect(out).toContain("   ↳ **→ Looking for foreign keys · 22s**");
+    expect(out).toContain(NP + "**→ Looking for foreign keys · 22s**");
     expect(out).not.toContain("Reading schema.ts · "); // only the newest line ticks
   });
 
@@ -567,7 +573,7 @@ describe("rolling window + +N earlier — renderActivityFeedWithNested", () => {
       expect(out).not.toContain(`Parent ${i}`);
     }
     expect(out).toContain(`_✓ +${totalParent - STATUS_ROLLING_LINES} earlier…_`);
-    expect(out).toContain("   ↳ **→ Child step B**");
+    expect(out).toContain(NP + "**→ Child step B**");
   });
 
   it("many child lines → only the last STATUS_ROLLING_LINES child lines render with a ↳ +N earlier header", () => {
@@ -582,8 +588,8 @@ describe("rolling window + +N earlier — renderActivityFeedWithNested", () => {
     for (let i = 1; i < firstVisible; i++) {
       expect(out).not.toContain(`Child ${i}`);
     }
-    expect(out).toContain(`   ↳ _+${totalChild - STATUS_ROLLING_LINES} earlier…_`);
-    expect(out).toContain(`   ↳ **→ Child ${totalChild}**`);
+    expect(out).toContain(`${NP}_+${totalChild - STATUS_ROLLING_LINES} earlier…_`);
+    expect(out).toContain(`${NP}**→ Child ${totalChild}**`);
   });
 
   it("STATUS_LINE_MAX=200: a 250-char child line is clipped to 200 (both surfaces)", () => {
@@ -600,7 +606,7 @@ describe("rolling window + +N earlier — renderActivityFeedWithNested", () => {
     const child = Array.from({ length: STATUS_ROLLING_LINES }, () => bigLine);
     const out = renderActivityFeedWithNested(parent, child)!;
     expect(out.length).toBeLessThanOrEqual(4096);
-    expect(out).toContain("   ↳ ");
+    expect(out).toContain(NP);
   });
 });
 
@@ -678,11 +684,11 @@ describe("extreme-edge: single oversized line with markdown specials & && _ *",
     expect(out.length).toBeLessThanOrEqual(4000);
     expect(isValidMarkdown(out)).toBe(true);
     // Must contain the nested prefix.
-    expect(out).toContain("   ↳ ");
+    expect(out).toContain(NP);
     // Regression guard: an operator-precedence bug made wrapperOverhead a string
     // (NESTED_PREFIX + n) → NaN budget → slice(0, NaN) === "" → the child content
-    // was silently discarded, leaving only "   ↳ **→ **". The empty-wrapper
-    // output still satisfies the toContain("   ↳ ") check above, so assert that
+    // was silently discarded, leaving only `${NESTED_PREFIX}**→ **`. The empty-wrapper
+    // output still satisfies the toContain(NP) check above, so assert that
     // real child content actually survives.
     expect(out).toContain("Child step");
     expect(out.length).toBeGreaterThan(100);
@@ -1025,7 +1031,7 @@ describe("renderActivityFeed — header param (main-session card fix)", () => {
     // Parent step is done-styled (child is the live step).
     expect(out).toContain("~~_✓ Delegating: review_~~");
     // Child step is the in-progress step.
-    expect(out).toContain("   ↳ **→ Reading schema.ts**");
+    expect(out).toContain(NP + "**→ Reading schema.ts**");
   });
 });
 

package/telegram-plugin/tool-activity-summary.ts

@@ -389,13 +389,14 @@ export function renderStatusCard(opts: StatusCardOpts): string | null {
    *                          an already-escaped markdown escape is never sliced.
    */
   const deepest = Math.max(1, escapedBody.length)
+  /** The collapsed parent trail, kept at every shrink level below level 0. */
+  const markerSection: CardSection = {
+    steps: [],
+    window: 1,
+    placeholder: parentMarker ?? undefined,
+  }
   return fitCardToBudget((level) => {
     if (level === 0) return { spec: fullSpec() }
-    const markerSection: CardSection = {
-      steps: [],
-      window: 1,
-      placeholder: parentMarker ?? undefined,
-    }
     if (level < escapedBody.length) {
       return {
         spec: {
@@ -427,39 +428,66 @@ export function renderStatusCard(opts: StatusCardOpts): string | null {
     }
   }, deepest)
 
+  /** The deepest shrink level's spec, for a given already-wrapped body line. */
+  function deepestSpec(bodyLine: string): CardSpec {
+    return {
+      chrome,
+      sections: [markerSection, { steps: [], window: 1, placeholder: bodyLine }],
+      footer,
+    }
+  }
+
+  /** Wrap an ALREADY-ESCAPED newest step in its bullet chrome. */
+  function wrapNewest(escaped: string): string {
+    return final
+      ? `${bodyIndent}_✓ ${escaped}_`
+      : `${bodyIndent}**→ ${escaped}${liveSuffix}**`
+  }
+
   /**
-   * The deepest shrink level's single bullet. Charges the fixed header/footer
-   * (and the parent marker) against `STATUS_CARD_CHAR_BUDGET`, then clips the
-   * RAW newest text to what is left, re-checking after escaping because
-   * escaping can expand the string (`&` → `&amp;`).
+   * The deepest shrink level's single bullet: clip the RAW newest text to
+   * whatever the fixed chrome/footer leaves of `STATUS_CARD_CHAR_BUDGET`,
+   * escape, then re-measure — escaping can expand the string (`&` → `&amp;`).
+   *
+   * Everything is measured by RENDERING the level's real spec (#3833). The
+   * previous arithmetic estimate charged `[...chrome, ...footer].join('\n')`,
+   * but the renderer is `stackCard`, which emits a collapse separator plus a
+   * two-space GFM hard break at every line boundary — 4 chars, not 1 — and it
+   * also charges the marker line and the section boundaries the estimate only
+   * partly counted. That under-count let a card render OVER the wire budget.
+   * Measuring with the renderer cannot drift from it by construction.
    */
   function truncatedNewestLine(): string {
-    const fixedCost = [...chrome, ...footer].join('\n').length
     const rawNewest = rawBody.length > 0 ? cleanStepLine(rawBody[rawBody.length - 1]) : ''
-    const wrapperOverhead = final
-      ? (bodyIndent + '_✓ _').length
-      : (bodyIndent + '**→ **').length + liveSuffix.length
-    const headerFooterCost =
-      fixedCost +
-      (fixedCost > 0 ? 1 : 0) +
-      (parentMarker != null ? parentMarker.length + 1 : 0)
-    const budget = STATUS_CARD_CHAR_BUDGET - headerFooterCost - wrapperOverhead
-    let raw = rawNewest.slice(0, Math.max(0, budget))
-    let newest = escapeMarkdown(raw)
-    while (
-      raw.length > 0 &&
-      wrapperOverhead + headerFooterCost + newest.length > STATUS_CARD_CHAR_BUDGET
-    ) {
-      const excess = wrapperOverhead + headerFooterCost + newest.length - STATUS_CARD_CHAR_BUDGET
-      raw = raw.slice(0, Math.max(0, raw.length - excess - 1))
-      newest = escapeMarkdown(raw)
+    const empty = wrapNewest('')
+    const fixedCost = renderCardSpec(deepestSpec(empty)).length
+    const budget = STATUS_CARD_CHAR_BUDGET - fixedCost
+    // Chrome alone is over budget (a 40k-char worker description, #3682). No
+    // amount of body clipping helps; `fitCardToBudget`'s hard-truncate backstop
+    // is what keeps the card under the wire limit in that case.
+    if (budget <= 0) return empty
+    let raw = clipRaw(rawNewest, budget)
+    let line = wrapNewest(escapeMarkdown(raw))
+    for (;;) {
+      const excess = renderCardSpec(deepestSpec(line)).length - STATUS_CARD_CHAR_BUDGET
+      if (excess <= 0 || raw.length === 0) return line
+      // Dropping k RAW chars drops at least k escaped chars (escaping never
+      // shrinks), so this strictly converges.
+      raw = clipRaw(raw, Math.max(0, raw.length - excess))
+      line = wrapNewest(escapeMarkdown(raw))
     }
-    return final
-      ? `${bodyIndent}_✓ ${newest}_`
-      : `${bodyIndent}**→ ${newest}${liveSuffix}**`
   }
 }
 
+/**
+ * Slice raw (pre-escape) text to `n` chars without leaving a dangling lone
+ * high surrogate — an unpaired surrogate is invalid UTF-16 on the wire.
+ */
+function clipRaw(text: string, n: number): string {
+  const out = text.slice(0, Math.max(0, n))
+  return /[\uD800-\uDBFF]$/.test(out) ? out.slice(0, -1) : out
+}
+
 /** Subtle horizontal rule between the running feed and the finished result. */
 const WORKER_RESULT_RULE = '─────'
 /** Hard cap on the terminal result paragraph. */

package/telegram-plugin/uat/scenarios/jtbd-foreground-subagent-activity-dm.test.ts

@@ -51,8 +51,9 @@ const FG_DISPATCH_PROMPT =
   `one-line summary." Wait for the foreground sub-agent to finish, then send ` +
   `me a brief reply telling me it's done.`;
 
-// The nested foreground block renders each child line prefixed with "↳"
-// (NESTED_PREFIX = "   ↳ "), newest as a bold "→ …" current step. Telegram
+// The nested foreground block renders each child line prefixed with a three
+// U+2800 indent then "↳" (NESTED_PREFIX; #3668 replaced the old ASCII spaces,
+// which Telegram left-trims), newest as a bold "→ …" current step. Telegram
 // strips the bold but keeps the literal ↳ / → glyphs in message text.
 const NESTED_RE = /↳/;
 

package/vendor/hindsight-memory/CHANGELOG.md

@@ -54,6 +54,34 @@
 
 ### Changed (switchroom divergence)
 
+- **Recall/retain hygiene guard-rail batch** (`scripts/recall.py`,
+  `scripts/subagent_retain.py`, `scripts/lib/content.py`, `scripts/tests/**`).
+  Closes guard-rail debt in the fork's hook scripts before extending them:
+  - **#3766** — `shape_recall_query` no longer drops a single-char SUBJECT
+    ('C', 'R', a single-digit version) before the stopword fallback runs. The
+    `len(t) > 1` guard moved into the fallback, so a single-char content word
+    survives while single-char stopwords are still removed.
+  - **#3578** — `_overlap_tokens` (the #3369 transcript-fallback tokenizer) now
+    accumulates alphanumeric runs (`isalnum`), so issue numbers, ports and
+    versions ('3993', ':9077', 'v0') carry signal and match symmetrically on
+    both the query and transcript sides. A lone digit is still dropped as noise.
+  - **#3994** — the sidechain volume gate counts ONLY the chars the text-only
+    retain path keeps (`retained_text_char_count` → `_extract_text_content`),
+    not the `tool_use` inputs the payload drops. Gate and payload now measure
+    the same char set, so a tool-heavy / prose-light fork that used to clear the
+    gate and retain a near-empty document is now correctly skipped. The
+    2,000-char floor was re-measured against the corrected metric —
+    `docs/measurements/subagent-volume-gate-3994.md`, replay harness
+    `scripts/tests/data/replay_volume_gate_3994.py`.
+  - **#4001** — the "window formatted to empty despite clearing the gate" skip
+    now emits an unconditional stderr line, not a debug-only log that was silent
+    in shipped settings.
+  - **#3999 / #3777** — rewrote the vacuous sidechain config-mutation test to
+    assert on the config object the code actually receives (RED when the copy
+    fix is deleted), and restored direct characterisation of `_overlap_tokens`
+    (`scripts/tests/test_overlap_tokens.py`) that was deleted with the removed
+    lexical gate while the tokenizer stayed load-bearing.
+
 - **`MAX_DIRECTIVES` 15 → 30, and truncation is no longer SILENT**
   (`scripts/lib/directives.py`). Live fleet active-directive counts were 24
   (assistant), 17 (klanker), 15 (carrie) against a client-side cap of 15, so the

package/vendor/hindsight-memory/docs/measurements/subagent-volume-gate-3994.md

@@ -0,0 +1,84 @@
+# Sub-agent volume-gate recalibration — #3994
+
+## What changed
+
+`subagent_retain.py`'s volume gate decides whether a terminating sub-agent's
+sidechain window is worth an LLM-backed retain. Its char floor
+(`MIN_NON_TOOL_RESULT_CHARS = 2000`) used to be measured by a metric
+(`non_tool_result_char_count`) that summed assistant/user **text** PLUS every
+`tool_use` block's `name` + serialized `input`.
+
+But the sidechain retain runs on the **text-only** path (`retainToolCalls =
+False`), so `tool_use` inputs are **not** in the stored payload. The gate and
+the payload measured different things: a tool-heavy / prose-light fork could
+clear the gate on tool-command volume and then retain a near-empty document.
+
+The gate now counts exactly what the text-only path keeps, via
+`retained_text_char_count` → `lib.content._extract_text_content` (assistant
+`text` blocks, channel-message tool_use text, plain-string user turns). Gate and
+payload now measure the identical char set.
+
+## Re-measuring the 2,000-char floor
+
+Because the metric shrank (it no longer counts tool chars), the floor had to be
+re-measured against the corrected count — not carried over blind.
+
+**Replay harness:** `scripts/tests/data/replay_volume_gate_3994.py`
+(re-runnable; `--dir <path>` replays real `*.jsonl` sidechain transcripts,
+default is a deterministic synthetic corpus parameterized by the empirical
+distributions already measured and cited in the code).
+
+**Data source note.** Fleet sidechain transcripts are private agent memory and
+are not committed to this repo, so the committed run uses the
+distribution-parameterized synthetic corpus (seed 1994): 120 real workers drawn
+across the measured klanker text-only size range (p10 5,035 / p50 10,058 / p90
+26,040; 0 empty / 0 < 500 over 200 real transcripts — see
+`test_subagent_retain_learnings.py::TextOnlyPathIsNotEmpty`), 60 trivial 10-second
+forks, and 40 tool-heavy / prose-light forks (the exact shape this change exists
+to reject). An operator re-runs it against ground truth with `--dir`.
+
+## Result (committed run, `python3 scripts/tests/data/replay_volume_gate_3994.py --json`)
+
+| metric | value |
+|---|---|
+| corpus | 220 transcripts (120 real / 60 trivial / 40 tool-heavy-prose-light) |
+| old gate passed but actual payload < 500 chars | **40** |
+| new gate passed but actual payload < 500 chars | **0** |
+| gate-passers' payload size (new, floor 2000) | min 5,591 / p10 8,293 / p50 13,968 / p90 24,672 |
+
+Floor sweep (real workers newly skipped vs. the old 2000 gate ; empty-ish forks
+now correctly skipped):
+
+| floor | real workers newly skipped | empty-ish forks now skipped |
+|---|---|---|
+| 500  | 0 | 40 |
+| 1000 | 0 | 40 |
+| 1500 | 0 | 40 |
+| **2000** | **0** | **40** |
+| 3000 | 0 | 40 |
+| 5000 | **2** | 40 |
+
+## Decision: keep the floor at 2,000
+
+The two populations separate cleanly under the corrected metric. Every
+gate-passer has a text-only payload of **≥ 5,591 chars** (p10 8,293) — real
+workers cluster an order of magnitude above the floor — while the entire
+trivial / tool-heavy-prose-light fork population falls below it. Any floor in
+`[500, 3000]` yields the same decision on this corpus, so 2,000 is not a knife
+edge: it sits in the wide flat middle. Pushing to 5,000 begins clipping genuine
+short-but-real workers (2 lost), so 2,000 stays as the conservative,
+well-separated choice.
+
+The headline win: **40 forks the old gate passed to a near-empty (< 500 char)
+retain are now correctly skipped, and zero real workers are lost.**
+
+## Guarding tests
+
+- `test_subagent_retain.py::VolumeGate::test_tool_heavy_prose_light_fork_now_skips`
+  — a tool-heavy / prose-light fork that PASSED the old gate now FAILS (RED if
+  the metric reverts to counting `tool_use` inputs).
+- `test_subagent_retain.py::VolumeGate::test_char_count_is_text_only`
+  — `retained_text_char_count` counts only `_extract_text_content` chars.
+- `test_subagent_retain_learnings.py::ProseFreeSidechainIsSkipped`
+  — the prose-free degenerate case is now SKIPPED by the gate (the retain path's
+  own guarantee that gate-passers always carry retainable prose).