switchroom 0.18.24 → 0.18.26

package/telegram-plugin/tests/session-model-source.test.ts

@@ -56,6 +56,17 @@ describe('createSessionModelSource — freshest observation wins', () => {
     expect(s.resolve()).toEqual({ model: 'claude-opus-4-8', source: 'transcript' })
   })
 
+  it('#3241 optimistic override: a silently-switched model recorded without a confirmation still wins /status', () => {
+    // Part B — the typed set path records the REQUESTED model optimistically when
+    // the confirmation line was missed. That override, being the freshest write,
+    // must reclaim /status from the stale transcript line just like a confirmed
+    // switch (symptom 4: "/status shows old model" after an in-place typed switch).
+    const s = createSessionModelSource()
+    s.noteTranscriptModel('claude-opus-4-8') // old model's last assistant line
+    s.setOverride('fable') // optimistic record of the requested model (no confirmation read)
+    expect(s.resolve()).toEqual({ model: 'fable', source: 'override' })
+  })
+
   it('getOverride reports the override independent of freshness', () => {
     const s = createSessionModelSource()
     s.setOverride('sr-glm-5')

package/telegram-plugin/tests/session-tail.test.ts

@@ -6,12 +6,65 @@ import {
   projectTranscriptLine,
   projectSubagentLine,
   projectAssistantTextBlocks,
+  sumUsageTokens,
   sanitizeCwdToProjectName,
   getProjectsDirForCwd,
   startSessionTail,
   type SessionEvent,
 } from '../session-tail.js'
 
+describe('sumUsageTokens', () => {
+  it('sums input + output + cache_creation (cache_read excluded)', () => {
+    expect(
+      sumUsageTokens({
+        input_tokens: 100,
+        output_tokens: 50,
+        cache_read_input_tokens: 1000,
+        cache_creation_input_tokens: 200,
+      }),
+    ).toBe(350)
+  })
+
+  it('excludes a large cache_read_input_tokens from the total', () => {
+    // Locks in the deliberate exclusion: replayed cached context must not
+    // inflate the "new work this turn" figure. A future regression that
+    // re-adds cache_read makes this fail.
+    expect(
+      sumUsageTokens({
+        input_tokens: 100,
+        output_tokens: 50,
+        cache_read_input_tokens: 999_999,
+        cache_creation_input_tokens: 200,
+      }),
+    ).toBe(350)
+  })
+
+  it('guards missing fields with 0', () => {
+    expect(sumUsageTokens({ output_tokens: 42 })).toBe(42)
+    expect(sumUsageTokens({})).toBe(0)
+  })
+
+  it('ignores the nested iterations / cache_creation breakdown (no double count)', () => {
+    expect(
+      sumUsageTokens({
+        input_tokens: 2,
+        output_tokens: 3,
+        cache_read_input_tokens: 4,
+        cache_creation_input_tokens: 5,
+        cache_creation: { ephemeral_1h_input_tokens: 5, ephemeral_5m_input_tokens: 0 },
+        iterations: [{ input_tokens: 2, output_tokens: 3 }],
+      }),
+    ).toBe(10)
+  })
+
+  it('returns 0 for null / non-object / non-numeric fields', () => {
+    expect(sumUsageTokens(null)).toBe(0)
+    expect(sumUsageTokens(undefined)).toBe(0)
+    expect(sumUsageTokens('nope')).toBe(0)
+    expect(sumUsageTokens({ input_tokens: 'x', output_tokens: null })).toBe(0)
+  })
+})
+
 describe('sanitizeCwdToProjectName', () => {
   it('replaces non-alphanumeric chars with hyphens', () => {
     expect(sanitizeCwdToProjectName('/home/user/.switchroom/agents/assistant')).toBe(
@@ -381,6 +434,49 @@ describe('projectTranscriptLine', () => {
     })
     expect(projectTranscriptLine(line)).toEqual([{ kind: 'thinking' }])
   })
+
+  it('emits a main-tier usage event with the summed per-message token delta + message.id', () => {
+    const line = JSON.stringify({
+      type: 'assistant',
+      message: {
+        id: 'msg_main_1',
+        model: 'claude-opus-4-8',
+        usage: {
+          input_tokens: 100,
+          output_tokens: 50,
+          cache_read_input_tokens: 1000,
+          cache_creation_input_tokens: 200,
+        },
+        content: [{ type: 'tool_use', id: 'toolu_a', name: 'Read', input: { file_path: '/a' } }],
+      },
+    })
+    const usage = projectTranscriptLine(line).find((e) => e.kind === 'usage')
+    expect(usage).toEqual({ kind: 'usage', messageId: 'msg_main_1', totalTokens: 350 })
+  })
+
+  it('emits no main-tier usage event when the assistant line carries no usage', () => {
+    const line = JSON.stringify({
+      type: 'assistant',
+      message: {
+        id: 'msg_main_2',
+        model: 'claude-opus-4-8',
+        content: [{ type: 'tool_use', id: 'toolu_a', name: 'Read', input: { file_path: '/a' } }],
+      },
+    })
+    expect(projectTranscriptLine(line).some((e) => e.kind === 'usage')).toBe(false)
+  })
+
+  it('carries a null messageId on the main-tier usage event when message.id is absent', () => {
+    const line = JSON.stringify({
+      type: 'assistant',
+      message: {
+        usage: { input_tokens: 5, output_tokens: 5 },
+        content: [{ type: 'text', text: 'working' }],
+      },
+    })
+    const usage = projectTranscriptLine(line).find((e) => e.kind === 'usage')
+    expect(usage).toEqual({ kind: 'usage', messageId: null, totalTokens: 10 })
+  })
 })
 
 // ─── Bug 1 regression: per-file cursor state survives re-attachment ────
@@ -554,6 +650,55 @@ describe('projectSubagentLine', () => {
     expect(events[0].kind).toBe('sub_agent_tool_use')
   })
 
+  it('emits sub_agent_usage with the summed per-message token delta + message.id', () => {
+    const st = { hasEmittedStart: true }
+    const line = JSON.stringify({
+      type: 'assistant',
+      message: {
+        id: 'msg_1',
+        model: 'claude-opus-4-8',
+        usage: {
+          input_tokens: 100,
+          output_tokens: 50,
+          cache_read_input_tokens: 1000,
+          cache_creation_input_tokens: 200,
+        },
+        content: [{ type: 'tool_use', id: 'toolu_a', name: 'Read', input: { file_path: '/a' } }],
+      },
+    })
+    const events = projectSubagentLine(line, 'X', st)
+    const usage = events.find((e) => e.kind === 'sub_agent_usage')
+    expect(usage).toEqual({ kind: 'sub_agent_usage', agentId: 'X', messageId: 'msg_1', totalTokens: 350 })
+  })
+
+  it('emits no sub_agent_usage when the assistant line carries no usage', () => {
+    const st = { hasEmittedStart: true }
+    const line = JSON.stringify({
+      type: 'assistant',
+      message: {
+        id: 'msg_2',
+        model: 'claude-opus-4-8',
+        content: [{ type: 'tool_use', id: 'toolu_a', name: 'Read', input: { file_path: '/a' } }],
+      },
+    })
+    const events = projectSubagentLine(line, 'X', st)
+    expect(events.some((e) => e.kind === 'sub_agent_usage')).toBe(false)
+  })
+
+  it('carries a null messageId when message.id is absent', () => {
+    const st = { hasEmittedStart: true }
+    const line = JSON.stringify({
+      type: 'assistant',
+      message: {
+        usage: { input_tokens: 5, output_tokens: 5 },
+        content: [{ type: 'text', text: 'working' }],
+      },
+    })
+    const events = projectSubagentLine(line, 'X', st)
+    const usage = events.find((e) => e.kind === 'sub_agent_usage')
+    expect(usage).toEqual({ kind: 'sub_agent_usage', agentId: 'X', messageId: null, totalTokens: 10 })
+  })
+
   it('emits sub_agent_tool_use for regular tools; nested Agent fires ONLY nested_spawn', () => {
     const st = { hasEmittedStart: true }
     const line = JSON.stringify({

package/telegram-plugin/tests/subagent-watcher.test.ts

@@ -550,6 +550,56 @@ describe('startSubagentWatcher', () => {
       expect(modelled?.model).toBe('claude-opus-4-8')
     })
 
+    it('accumulates total tokens across assistant messages, deduped by message.id', () => {
+      const progress: Array<{ totalTokens: number }> = []
+      const agentDir = join(tmpRoot, 'agent')
+      const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+      mkdirSync(subagentsDir, { recursive: true })
+      const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
+
+      const h = startWatcherSync({
+        agentDir,
+        onProgress: ({ totalTokens }) => { progress.push({ totalTokens }) },
+      })
+      writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Research the competitors')))
+      h.poll()
+
+      // Message 1 persisted as TWO JSONL lines sharing one message.id + the
+      // SAME usage block (the ≥2.1.x split-message shape). Must count ONCE.
+      const usage1 = {
+        input_tokens: 100,
+        output_tokens: 50,
+        cache_read_input_tokens: 1000,
+        cache_creation_input_tokens: 200,
+      }
+      appendFileSync(jsonlPath, buildJSONL({
+        type: 'assistant',
+        message: { id: 'msg_1', model: 'claude-opus-4-8', usage: usage1, content: [{ type: 'text', text: 'thinking about it' }] },
+      }))
+      appendFileSync(jsonlPath, buildJSONL({
+        type: 'assistant',
+        message: { id: 'msg_1', model: 'claude-opus-4-8', usage: usage1, content: [{ type: 'tool_use', name: 'Read', id: 'r1', input: { file_path: '/x/a.ts' } }] },
+      }))
+      h.poll()
+
+      // A DISTINCT message adds on top; a line with NO usage contributes nothing.
+      appendFileSync(jsonlPath, buildJSONL({
+        type: 'assistant',
+        message: { id: 'msg_2', model: 'claude-opus-4-8', usage: { input_tokens: 2, output_tokens: 40 }, content: [{ type: 'tool_use', name: 'Bash', id: 'r2', input: {} }] },
+      }))
+      appendFileSync(jsonlPath, buildJSONL({
+        type: 'assistant',
+        message: { id: 'msg_3', model: 'claude-opus-4-8', content: [{ type: 'tool_use', name: 'Edit', id: 'r3', input: {} }] },
+      }))
+      h.poll()
+
+      // msg_1 (350, counted once despite two lines; cache_read excluded)
+      // + msg_2 (42) = 392.
+      expect(h.watcher.getRegistry().get('deadbeef')?.totalTokens).toBe(392)
+      const last = progress[progress.length - 1]
+      expect(last.totalTokens).toBe(392)
+    })
+
     it('ignores a synthetic model sentinel, keeping the last real model', () => {
       const agentDir = join(tmpRoot, 'agent')
       const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')

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

@@ -7,7 +7,9 @@ import {
   renderActivityFeed,
   renderActivityFeedWithNested,
   renderActivityHeader,
+  renderCombinedWorkerFeed,
   formatFeedElapsed,
+  formatTokenCount,
   formatStepSuffix,
   STEP_TIMER_MIN_MS,
   type SessionActivityHeader,
@@ -745,6 +747,80 @@ describe("renderActivityHeader — two-line header builder", () => {
     const [, h2synth] = renderActivityHeader("🤖", "Agent", "", 15_000, 7, "running", "<synthetic>");
     expect(h2synth).toBe("_15s · 7 tools_");
   });
+
+  it("inserts the token segment between tool count and model (running)", () => {
+    const [, h2] = renderActivityHeader("🛠", "Worker", "run tests", 120_000, 14, "running", "claude-opus-4-8", 12_400);
+    expect(h2).toBe("_2m00s · 14 tools · 12.4k tok · opus 4.8_");
+  });
+
+  it("inserts the token segment before elapsed on the done line", () => {
+    const [, h2] = renderActivityHeader("🛠", "Worker", "run tests", 65_000, 3, "done", undefined, 940);
+    expect(h2).toBe("_done · 3 tools · 940 tok · 1m05s_");
+  });
+
+  it("omits the token segment when total is 0 / undefined (both variants consistent)", () => {
+    const [, running] = renderActivityHeader("🛠", "Worker", "", 15_000, 7, "running", undefined, 0);
+    expect(running).toBe("_15s · 7 tools_");
+    const [, undef] = renderActivityHeader("🛠", "Worker", "", 15_000, 7, "running");
+    expect(undef).toBe("_15s · 7 tools_");
+    const [, doneZero] = renderActivityHeader("🛠", "Worker", "", 65_000, 3, "done", undefined, 0);
+    expect(doneZero).toBe("_done · 3 tools · 1m05s_");
+  });
+
+  it("renders tokens and model together, in order", () => {
+    const [, h2] = renderActivityHeader("🛠", "Worker", "", 10_000, 2, "running", "sr-glm-5", 1_200_000);
+    expect(h2).toBe("_10s · 2 tools · 1.2M tok · sr-glm-5_");
+  });
+});
+
+describe("formatTokenCount — compact token formatter", () => {
+  it("renders sub-1000 as a raw integer", () => {
+    expect(formatTokenCount(0)).toBe("0");
+    expect(formatTokenCount(1)).toBe("1");
+    expect(formatTokenCount(999)).toBe("999");
+  });
+
+  it("renders >=1000 as one-decimal k at the boundary", () => {
+    expect(formatTokenCount(1000)).toBe("1.0k");
+    expect(formatTokenCount(12_400)).toBe("12.4k");
+    expect(formatTokenCount(999_499)).toBe("999.5k");
+  });
+
+  it("renders >=1e6 as one-decimal M at the boundary", () => {
+    expect(formatTokenCount(1_000_000)).toBe("1.0M");
+    expect(formatTokenCount(1_200_000)).toBe("1.2M");
+  });
+
+  it("promotes the k→M rounding boundary (never renders 1000.0k)", () => {
+    // 999_949 rounds down to 999.9k; from 999_950 the 1-decimal k rounds to
+    // 1000.0 which must roll into the M branch as 1.0M.
+    expect(formatTokenCount(999_949)).toBe("999.9k");
+    expect(formatTokenCount(999_950)).toBe("1.0M");
+    expect(formatTokenCount(999_999)).toBe("1.0M");
+    expect(formatTokenCount(1_000_000)).toBe("1.0M");
+  });
+
+  it("clamps negatives / non-finite to 0", () => {
+    expect(formatTokenCount(-5)).toBe("0");
+    expect(formatTokenCount(Number.NaN)).toBe("0");
+    expect(formatTokenCount(Number.POSITIVE_INFINITY)).toBe("0");
+  });
+});
+
+describe("renderCombinedWorkerFeed — token segment on the row header", () => {
+  it("shows `· N tok` per worker row and omits it at 0", () => {
+    const body = renderCombinedWorkerFeed(
+      [
+        { description: "alpha", elapsedMs: 15_000, toolCount: 3, currentStep: "Reading a.ts", totalTokens: 12_400 },
+        { description: "beta", elapsedMs: 20_000, toolCount: 5, currentStep: "Running tests", totalTokens: 0 },
+      ],
+      { maxRows: 5 },
+    );
+    expect(body).not.toBeNull();
+    expect(body!).toContain("**alpha** _· 15s · 3 tools · 12.4k tok_");
+    expect(body!).toContain("**beta** _· 20s · 5 tools_");
+    expect(body!).not.toContain("beta** _· 20s · 5 tools · 0 tok");
+  });
 });
 
 describe("agent flat path routes through the shared step-feed primitive", () => {
@@ -852,6 +928,39 @@ describe("renderActivityFeed — header param (main-session card fix)", () => {
     expect(nested).toContain("· opus 4.8_");
   });
 
+  it("threads the parent's OWN totalTokens through the flat and nested turn-card paths", () => {
+    const header: SessionActivityHeader = {
+      label: "Agent",
+      elapsedMs: 120_000,
+      toolCount: 14,
+      state: "running",
+      model: "claude-opus-4-8",
+      totalTokens: 12_400,
+    };
+    // Flat path (no foreground sub-agent).
+    const flat = renderActivityFeed(["Searching memory"], false, "", undefined, header)!;
+    expect(flat).toContain("_2m00s · 14 tools · 12.4k tok · opus 4.8_");
+    // Nested path (with a child line) carries the same token segment.
+    const nested = renderActivityFeedWithNested(["Reading"], ["nested step"], false, "", undefined, header)!;
+    expect(nested).toContain("· 12.4k tok ·");
+  });
+
+  it("omits the token segment on the turn card when totalTokens is 0 / undefined", () => {
+    const zero: SessionActivityHeader = {
+      label: "Agent",
+      elapsedMs: 15_000,
+      toolCount: 7,
+      state: "running",
+      totalTokens: 0,
+    };
+    const outZero = renderActivityFeed(["Searching memory"], false, "", undefined, zero)!;
+    expect(outZero).toContain("_15s · 7 tools_");
+    expect(outZero).not.toContain("tok");
+    // undefined behaves identically.
+    const undef: SessionActivityHeader = { label: "Agent", elapsedMs: 15_000, toolCount: 7, state: "running" };
+    expect(renderActivityFeed(["Searching memory"], false, "", undefined, undef)).toBe(outZero);
+  });
+
   it("prepends the done header when final=true", () => {
     const header: SessionActivityHeader = {
       label: "Agent",

package/telegram-plugin/tests/trailing-answer-projector.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect } from 'vitest'
+import { projectTrailingAnswerFromTranscript } from '../session-tail.js'
+
+/**
+ * Pins the crash-survival redelivery transcript projector: recovering the
+ * finished-but-never-sent trailing answer from a session JSONL after a
+ * pre-flush crash, and refusing to redeliver a dangling mid-tool preamble.
+ */
+
+function assistantText(text: string): string {
+  return JSON.stringify({ type: 'assistant', message: { content: [{ type: 'text', text }] } })
+}
+function assistantToolUse(name: string): string {
+  return JSON.stringify({
+    type: 'assistant',
+    message: { content: [{ type: 'tool_use', name, id: 'toolu_x', input: {} }] },
+  })
+}
+function enqueue(text: string): string {
+  return JSON.stringify({ type: 'queue-operation', operation: 'enqueue', content: text })
+}
+/** A real inbound user message line (string content) — a turn separator the
+ *  projection kernel emits NO event for, unlike an `enqueue`. */
+function userMessage(text: string): string {
+  return JSON.stringify({ type: 'user', message: { role: 'user', content: text } })
+}
+/** A tool_result carrier user line — NOT a turn boundary. */
+function toolResult(toolUseId: string): string {
+  return JSON.stringify({
+    type: 'user',
+    message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: toolUseId, content: 'ok' }] },
+  })
+}
+
+describe('projectTrailingAnswerFromTranscript', () => {
+  it('recovers the trailing answer text after the last tool_use', () => {
+    const transcript = [
+      enqueue('what is the deploy status?'),
+      assistantText('Let me check.'),
+      assistantToolUse('Bash'),
+      assistantText('The deploy finished — all three services are green.'),
+    ].join('\n')
+    const r = projectTrailingAnswerFromTranscript(transcript)
+    expect(r.trailingIsText).toBe(true)
+    expect(r.text).toBe('The deploy finished — all three services are green.')
+  })
+
+  it('does NOT treat a dangling tool_use as a redeliverable answer', () => {
+    const transcript = [
+      enqueue('run the migration'),
+      assistantText('On it — running the migration now.'),
+      assistantToolUse('Bash'),
+    ].join('\n')
+    const r = projectTrailingAnswerFromTranscript(transcript)
+    expect(r.trailingIsText).toBe(false)
+    // the preamble was reset by the tool_use; nothing trailing to send
+    expect(r.text).toBe('')
+  })
+
+  it('scopes to the LAST turn only (a prior turn answer is not resurfaced)', () => {
+    const transcript = [
+      enqueue('first question'),
+      assistantText('First answer.'),
+      enqueue('second question'),
+      assistantText('Second answer.'),
+    ].join('\n')
+    const r = projectTrailingAnswerFromTranscript(transcript)
+    expect(r.text).toBe('Second answer.')
+  })
+
+  it('suppresses an isApiErrorMessage synthetic line (never redeliver an error string)', () => {
+    const transcript = [
+      enqueue('do the thing'),
+      JSON.stringify({
+        type: 'assistant',
+        isApiErrorMessage: true,
+        message: { content: [{ type: 'text', text: "You've hit your limit · resets 5pm" }] },
+      }),
+    ].join('\n')
+    const r = projectTrailingAnswerFromTranscript(transcript)
+    expect(r.text).toBe('')
+    expect(r.trailingIsText).toBe(false)
+  })
+
+  // diff-review defect #2 — a real claude .jsonl separates turns with a plain
+  // `type:"user"` message line the kernel ignores, NOT always an interleaved
+  // enqueue queue-operation. Two turns with no intervening tool_use must not
+  // concatenate; only the LAST turn's trailing text is projected.
+  it('breaks turns on a plain user-message separator (no enqueue, no tool_use)', () => {
+    const transcript = [
+      userMessage('first question'),
+      assistantText('First answer.'),
+      userMessage('second question'),
+      assistantText('Second answer.'),
+    ].join('\n')
+    const r = projectTrailingAnswerFromTranscript(transcript)
+    expect(r.text).toBe('Second answer.')
+    expect(r.trailingIsText).toBe(true)
+  })
+
+  it('does NOT treat a tool_result user line as a turn boundary (answer still accretes)', () => {
+    const transcript = [
+      userMessage('do the thing'),
+      assistantToolUse('Bash'),
+      toolResult('toolu_x'),
+      assistantText('All done — the thing is done.'),
+    ].join('\n')
+    const r = projectTrailingAnswerFromTranscript(transcript)
+    expect(r.text).toBe('All done — the thing is done.')
+    expect(r.trailingIsText).toBe(true)
+  })
+
+  it('concatenates multiple trailing text blocks of the final answer', () => {
+    const transcript = [
+      enqueue('q'),
+      assistantToolUse('Read'),
+      assistantText('Part one. '),
+      assistantText('Part two.'),
+    ].join('\n')
+    const r = projectTrailingAnswerFromTranscript(transcript)
+    expect(r.text).toBe('Part one. Part two.')
+    expect(r.trailingIsText).toBe(true)
+  })
+})

package/telegram-plugin/tests/vault-grant-inbound-builders.test.ts

@@ -16,6 +16,8 @@ import { describe, it, expect } from 'vitest'
 import {
   buildVaultGrantApprovedInbound,
   buildVaultGrantApprovedCardText,
+  normalizeGrantReason,
+  MAX_GRANT_REASON_CHARS,
   buildVaultGrantDeniedInbound,
   buildVaultSaveCompletedInbound,
   buildVaultSaveFailedInbound,
@@ -85,6 +87,55 @@ describe('buildVaultGrantApprovedCardText — the [object Object] regression gua
     expect(noFooter.endsWith('(grant `vg_a1b2c3`)')).toBe(true)
   })
 
+  it('renders the reason as a trailing italic clause when provided, before the footer', () => {
+    const text = buildVaultGrantApprovedCardText({
+      ...BASE,
+      reasonEscaped: 'deploy the staging build',
+      footer: '\n_Approver verified by Telegram identity._',
+    })
+    expect(text).toContain('_Reason: deploy the staging build_')
+    // reason clause sits BEFORE the footer (auth-mode note stays last)
+    expect(text.indexOf('_Reason:')).toBeLessThan(text.indexOf('_Approver verified'))
+    // still one clean string
+    const rich = richMessage(text)
+    expect(rich.markdown).toBe(text)
+    expect(rich.markdown).not.toContain('[object Object]')
+  })
+
+  it('omits the reason clause when reason is undefined or empty — no dangling "Reason:" label', () => {
+    const none = buildVaultGrantApprovedCardText(BASE)
+    expect(none).not.toContain('Reason:')
+    expect(none.endsWith('(grant `vg_a1b2c3`)')).toBe(true)
+
+    const empty = buildVaultGrantApprovedCardText({ ...BASE, reasonEscaped: '' })
+    expect(empty).not.toContain('Reason:')
+    expect(empty.endsWith('(grant `vg_a1b2c3`)')).toBe(true)
+  })
+
+  it('reason clause + reason-less both stay clean when combined with a footer', () => {
+    const footer = '\n_Approver verified by Telegram identity._'
+    const withReason = buildVaultGrantApprovedCardText({ ...BASE, reasonEscaped: 'x', footer })
+    expect(withReason.endsWith(footer)).toBe(true)
+    const noReason = buildVaultGrantApprovedCardText({ ...BASE, footer })
+    expect(noReason.endsWith(footer)).toBe(true)
+    expect(noReason).not.toContain('Reason:')
+  })
+
+  it('carries an already-escaped reason verbatim — HTML-special chars stay escaped, no corruption', () => {
+    // The callsite escapes agent-supplied free text with escapeHtmlForTg
+    // BEFORE passing it (same contract as agentEscaped). Simulate that:
+    // `<b> & "co" *_` → escaped form. The builder must not re-corrupt it,
+    // and the single-richMessage wrap must still hold.
+    const escaped = '&lt;b&gt; &amp; drop &amp;&amp; run *_'
+    const text = buildVaultGrantApprovedCardText({ ...BASE, reasonEscaped: escaped })
+    expect(text).toContain(`_Reason: ${escaped}_`)
+    // No raw unescaped angle brackets leaked into the card text.
+    expect(text).not.toContain('<b>')
+    const rich = richMessage(text)
+    expect(rich.markdown).toBe(text)
+    expect(rich.markdown).not.toContain('[object Object]')
+  })
+
   it('DOCUMENTS the original bug: bare-string + richMessage() coerces to [object Object]', () => {
     // Demonstrates why the fix matters — if a future edit reintroduces the
     // "concatenate a string onto the richMessage object" pattern, the result
@@ -94,6 +145,80 @@ describe('buildVaultGrantApprovedCardText — the [object Object] regression gua
   })
 })
 
+describe('normalizeGrantReason — single-line, trimmed, length-capped', () => {
+  it('returns "" for undefined, null, empty, or whitespace-only input (clean no-op)', () => {
+    expect(normalizeGrantReason(undefined)).toBe('')
+    expect(normalizeGrantReason(null)).toBe('')
+    expect(normalizeGrantReason('')).toBe('')
+    expect(normalizeGrantReason('   ')).toBe('')
+    expect(normalizeGrantReason('\n\t  \n')).toBe('')
+  })
+
+  it('collapses newlines and whitespace runs to a single space (protects the _…_ emphasis)', () => {
+    expect(normalizeGrantReason('deploy\nthe   staging\tbuild')).toBe('deploy the staging build')
+    // no newline survives to break the italic clause
+    expect(normalizeGrantReason('a\nb')).not.toContain('\n')
+  })
+
+  it('trims leading/trailing whitespace', () => {
+    expect(normalizeGrantReason('  clone the repo  ')).toBe('clone the repo')
+  })
+
+  it('caps over-long input with a trailing ellipsis, at MAX_GRANT_REASON_CHARS', () => {
+    const long = 'x'.repeat(MAX_GRANT_REASON_CHARS + 50)
+    const out = normalizeGrantReason(long)
+    expect(out.length).toBe(MAX_GRANT_REASON_CHARS)
+    expect(out.endsWith('…')).toBe(true)
+    expect(out.slice(0, -1)).toBe('x'.repeat(MAX_GRANT_REASON_CHARS - 1))
+  })
+
+  it('leaves an at-limit reason untouched (no spurious ellipsis)', () => {
+    const exact = 'y'.repeat(MAX_GRANT_REASON_CHARS)
+    const out = normalizeGrantReason(exact)
+    expect(out).toBe(exact)
+    expect(out.endsWith('…')).toBe(false)
+  })
+
+  it('feeds cleanly through the card builder: whitespace-only → no clause, newline → single-line clause', () => {
+    // whitespace-only normalizes to '' → builder omits the clause
+    const wsCard = buildVaultGrantApprovedCardText({
+      agentEscaped: 'gymbro',
+      scope: 'read',
+      key: 'k',
+      days: 30,
+      grantId: 'vg_x',
+      reasonEscaped: normalizeGrantReason('   ') || undefined,
+    })
+    expect(wsCard).not.toContain('Reason:')
+
+    // newline reason renders as a single-line italic clause, no broken emphasis
+    const nlCard = buildVaultGrantApprovedCardText({
+      agentEscaped: 'gymbro',
+      scope: 'read',
+      key: 'k',
+      days: 30,
+      grantId: 'vg_x',
+      reasonEscaped: normalizeGrantReason('line one\nline two') || undefined,
+    })
+    expect(nlCard).toContain('_Reason: line one line two_')
+    expect(nlCard).not.toContain('\nline two')
+  })
+
+  it('over-long reason renders truncated with ellipsis inside the clause', () => {
+    const reason = normalizeGrantReason('z'.repeat(MAX_GRANT_REASON_CHARS + 100)) || undefined
+    const card = buildVaultGrantApprovedCardText({
+      agentEscaped: 'gymbro',
+      scope: 'read',
+      key: 'k',
+      days: 30,
+      grantId: 'vg_x',
+      reasonEscaped: reason,
+    })
+    expect(card).toContain('…_')
+    expect(card).toContain(`_Reason: ${'z'.repeat(MAX_GRANT_REASON_CHARS - 1)}…_`)
+  })
+})
+
 describe('buildVaultGrantApprovedInbound', () => {
   it('emits the canonical envelope (type, chat_id, user, userId, ts, messageId)', () => {
     const msg = buildVaultGrantApprovedInbound({