switchroom 0.19.2 → 0.19.3

package/telegram-plugin/tests/auth-add-flow.test.ts

@@ -60,6 +60,10 @@ import {
   handleAuthCommand,
   isAuthAdmin,
   validateAuthAddLabel,
+  readdPrecheckError,
+  runReaddPrecheck,
+  formatGrantedScopesReply,
+  REQUIRED_USAGE_SCOPE,
 } from '../gateway/auth-command.js'
 import {
   pendingAuthAddFlows,
@@ -111,6 +115,7 @@ function makeMockTmuxOps(opts: {
 } = {}): AuthAddTmuxOps & {
   newSessionCalls: Array<{ socket: string; session: string; env: Record<string, string>; cmd: string }>
   sendCalls: Array<{ socket: string; session: string; text: string }>
+  sendKeyCalls: Array<{ socket: string; session: string; key: string }>
   killCalls: Array<{ socket: string; session: string }>
   captureCallCount: number
   sessionAlive: boolean
@@ -123,12 +128,14 @@ function makeMockTmuxOps(opts: {
   let sessionAlive = opts.initialSessionAlive ?? true
   const newSessionCalls: Array<{ socket: string; session: string; env: Record<string, string>; cmd: string }> = []
   const sendCalls: Array<{ socket: string; session: string; text: string }> = []
+  const sendKeyCalls: Array<{ socket: string; session: string; key: string }> = []
   const killCalls: Array<{ socket: string; session: string }> = []
   let captureCallCount = 0
 
   const mock = {
     get newSessionCalls() { return newSessionCalls },
     get sendCalls() { return sendCalls },
+    get sendKeyCalls() { return sendKeyCalls },
     get killCalls() { return killCalls },
     get captureCallCount() { return captureCallCount },
     get sessionAlive() { return sessionAlive },
@@ -149,6 +156,9 @@ function makeMockTmuxOps(opts: {
       sendCalls.push({ socket, session, text })
       mock.onSend?.(socket, session, text)
     },
+    sendKey(socket: string, session: string, key: string) {
+      sendKeyCalls.push({ socket, session, key })
+    },
     hasSession(socket: string, session: string): boolean {
       void socket; void session
       return sessionAlive
@@ -166,12 +176,12 @@ function makeMockTmuxOps(opts: {
 describe('parseAuthCommand — /auth add and /auth cancel', () => {
   it('recognises "/auth add <label>" with a valid label', () => {
     const p = parseAuthCommand('/auth add alice@example.com')
-    expect(p).toEqual({ kind: 'add', label: 'alice@example.com' })
+    expect(p).toEqual({ kind: 'add', label: 'alice@example.com', replace: false })
   })
 
   it('recognises gmail-tag labels (the + character)', () => {
     const p = parseAuthCommand('/auth add alice+work@example.com')
-    expect(p).toEqual({ kind: 'add', label: 'alice+work@example.com' })
+    expect(p).toEqual({ kind: 'add', label: 'alice+work@example.com', replace: false })
   })
 
   it('treats "/auth add" with no label as a help reply', () => {
@@ -191,7 +201,7 @@ describe('parseAuthCommand — /auth add and /auth cancel', () => {
     // whitespace is the parser's contract — the validator catches
     // shape violations on the first token.
     const p = parseAuthCommand('/auth add foo bar')
-    expect(p).toEqual({ kind: 'add', label: 'foo' })
+    expect(p).toEqual({ kind: 'add', label: 'foo', replace: false })
   })
 
   it('rejects an over-length label (>64 chars)', () => {
@@ -260,7 +270,7 @@ describe('isAuthAdmin', () => {
 describe('handleAuthCommand — add/cancel are gateway-routed (defensive contract)', () => {
   it('returns a "not routed" error for parsed.kind === "add" so the contract is loud if a future refactor forgets the gateway dispatch', async () => {
     const reply = await handleAuthCommand(
-      { kind: 'add', label: 'foo' },
+      { kind: 'add', label: 'foo', replace: false },
       {
         agentName: 'clerk',
         isAdmin: true,
@@ -272,7 +282,7 @@ describe('handleAuthCommand — add/cancel are gateway-routed (defensive contrac
 
   it('refuses /auth add for non-admin before the not-routed branch', async () => {
     const reply = await handleAuthCommand(
-      { kind: 'add', label: 'foo' },
+      { kind: 'add', label: 'foo', replace: false },
       {
         agentName: 'other',
         isAdmin: false,
@@ -657,6 +667,161 @@ describe('mocked-broker addAccount integration sketch', () => {
       expect(addAccountSpy).toHaveBeenCalledTimes(1)
     })
   })
+
+  it('readd threads replace=true through to the broker addAccount verb', async () => {
+    const fakeCredentials = {
+      claudeAiOauth: {
+        accessToken: 'sk-ant-oat01-test-' + 'x'.repeat(40),
+        expiresAt: Date.now() + 3600_000,
+        scopes: ['org:create_api_key', 'user:profile', 'user:inference'],
+      },
+    }
+    const addAccountSpy = vi.fn(async (label: string, _c: typeof fakeCredentials, replace?: boolean) => ({
+      label,
+      replace,
+    }))
+    // Plain add → replace false; readd → replace true. Both round-trip.
+    const added = await addAccountSpy('pooled@example.com', fakeCredentials, false)
+    const readded = await addAccountSpy('pooled@example.com', fakeCredentials, true)
+    expect(added.replace).toBe(false)
+    expect(readded.replace).toBe(true)
+    expect(addAccountSpy).toHaveBeenCalledTimes(2)
+  })
+})
+
+/* ── 9b. /auth readd parser + precheck + scope reply (PR C) ────────────── */
+
+describe('parseAuthCommand — /auth readd and add --replace', () => {
+  it('parses "/auth readd <label>" as an add with replace=true', () => {
+    expect(parseAuthCommand('/auth readd pooled@example.com')).toEqual({
+      kind: 'add',
+      label: 'pooled@example.com',
+      replace: true,
+    })
+  })
+
+  it('parses "/auth add <label> --replace" as replace=true too', () => {
+    expect(parseAuthCommand('/auth add pooled@example.com --replace')).toEqual({
+      kind: 'add',
+      label: 'pooled@example.com',
+      replace: true,
+    })
+  })
+
+  it('plain "/auth add <label>" stays replace=false', () => {
+    expect(parseAuthCommand('/auth add fresh@example.com')).toEqual({
+      kind: 'add',
+      label: 'fresh@example.com',
+      replace: false,
+    })
+  })
+
+  it('"/auth readd" with no label is a help reply', () => {
+    const p = parseAuthCommand('/auth readd')
+    expect(p?.kind).toBe('help')
+    if (p?.kind === 'help') expect(p.reason).toMatch(/Usage: \/auth readd/)
+  })
+
+  it('rejects an unknown flag on add/readd', () => {
+    const p = parseAuthCommand('/auth add foo --wipe')
+    expect(p?.kind).toBe('help')
+    if (p?.kind === 'help') expect(p.reason).toMatch(/Unknown flag/i)
+  })
+
+  it('is case-insensitive on the readd verb', () => {
+    expect(parseAuthCommand('/auth READD foo')).toEqual({ kind: 'add', label: 'foo', replace: true })
+  })
+})
+
+describe('readdPrecheckError — exists gate', () => {
+  it('readd of a NONEXISTENT label errors clearly', () => {
+    const err = readdPrecheckError('ghost@example.com', true, false)
+    expect(err).toMatch(/no account named/i)
+    expect(err).toMatch(/ghost@example\.com/)
+  })
+
+  it('readd of an EXISTING label passes (null)', () => {
+    expect(readdPrecheckError('pooled@example.com', true, true)).toBeNull()
+  })
+
+  it('plain add of an EXISTING label errors and points at readd', () => {
+    const err = readdPrecheckError('pooled@example.com', false, true)
+    expect(err).toMatch(/already exists/i)
+    expect(err).toMatch(/\/auth readd/)
+  })
+
+  it('plain add of a NEW label passes (null)', () => {
+    expect(readdPrecheckError('fresh@example.com', false, false)).toBeNull()
+  })
+})
+
+describe('runReaddPrecheck — broker-backed wrapper (extracted from gateway.ts)', () => {
+  const clientWith = (labels: string[]) => ({
+    listState: async () => ({ accounts: labels.map((label) => ({ label })) }) as any,
+  })
+
+  it('readd of an EXISTING label queries the broker and passes (null)', async () => {
+    const err = await runReaddPrecheck(
+      async () => clientWith(['pooled@example.com']) as any,
+      'pooled@example.com',
+      true,
+    )
+    expect(err).toBeNull()
+  })
+
+  it('readd of a NONEXISTENT label surfaces the precheck error', async () => {
+    const err = await runReaddPrecheck(
+      async () => clientWith([]) as any,
+      'ghost@example.com',
+      true,
+    )
+    expect(err).toMatch(/no account named/i)
+  })
+
+  it('plain add of an EXISTING label surfaces the precheck error', async () => {
+    const err = await runReaddPrecheck(
+      async () => clientWith(['pooled@example.com']) as any,
+      'pooled@example.com',
+      false,
+    )
+    expect(err).toMatch(/already exists/i)
+  })
+
+  it('best-effort: null client (broker unreachable) skips the precheck (null)', async () => {
+    const err = await runReaddPrecheck(async () => null, 'x@example.com', true)
+    expect(err).toBeNull()
+  })
+
+  it('best-effort: a throwing broker is swallowed and skips the precheck (null)', async () => {
+    const err = await runReaddPrecheck(
+      async () => ({ listState: async () => { throw new Error('broker down') } }) as any,
+      'x@example.com',
+      false,
+    )
+    expect(err).toBeNull()
+  })
+})
+
+describe('formatGrantedScopesReply — scope-in-reply (structured, no scraping)', () => {
+  it('lists granted scopes and confirms when user:profile is present', () => {
+    const r = formatGrantedScopesReply(['org:create_api_key', 'user:profile', 'user:inference'])
+    expect(r.hasUsageScope).toBe(true)
+    expect(r.text).toContain('user:profile')
+    expect(r.text).toMatch(/unlocked/i)
+  })
+
+  it('warns LOUDLY when user:profile is absent (the setup-token footgun)', () => {
+    const r = formatGrantedScopesReply(['user:inference'])
+    expect(r.hasUsageScope).toBe(false)
+    expect(r.text).toMatch(/MISSING/)
+    expect(r.text).toContain(REQUIRED_USAGE_SCOPE)
+  })
+
+  it('warns when the token reports no scopes at all', () => {
+    const r = formatGrantedScopesReply(undefined)
+    expect(r.hasUsageScope).toBe(false)
+    expect(r.text).toMatch(/No scopes reported/i)
+  })
 })
 
 /* ── 10. Help text mentions add + cancel ─────────────────────────────── */
@@ -773,6 +938,9 @@ printf '{\\n  "claudeAiOauth": {\\n    "accessToken": "${fakeAccessToken}",\\n
       send(_socket, session, text) {
         return realOps.send(tmuxSocket, session, text)
       },
+      sendKey(_socket, session, key) {
+        return realOps.sendKey(tmuxSocket, session, key)
+      },
       hasSession(_socket, session) {
         return realOps.hasSession(tmuxSocket, session)
       },
@@ -816,6 +984,200 @@ printf '{\\n  "claudeAiOauth": {\\n    "accessToken": "${fakeAccessToken}",\\n
   }, 30_000)
 })
 
+/* ── 12. via-claude broad-scope minter (PR B) ─────────────────────────── */
+
+describe('startAccountAuthSession — via-claude mode (broad scope)', () => {
+  // The picker-rendered broad-scope authorize URL (org:create_api_key +
+  // user:profile + user:inference …). This is what `claude` (not setup-token)
+  // emits after "Claude account with subscription".
+  const BROAD_URL =
+    'https://claude.com/cai/oauth/authorize?code=true&client_id=x&response_type=code' +
+    '&scope=org%3Acreate_api_key+user%3Aprofile+user%3Ainference+user%3Asessions%3Aclaude_code' +
+    '&code_challenge=AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-z&state=s'
+
+  it('defaults to via-claude mode: spawns bare `claude` (NOT `claude setup-token`) and reports mode', async () => {
+    const mock = makeMockTmuxOps({ captureResponses: [BROAD_URL] })
+    const result = await startAccountAuthSession('broad@example.com', {
+      home: workspace,
+      tmuxOps: mock,
+      urlTimeoutMs: 3_000,
+    })
+    expect(result.mode).toBe('via-claude')
+    // cmd must be the bare login picker, not setup-token (setup-token mints
+    // only user:inference, which server: agents refuse).
+    expect(mock.newSessionCalls[0].cmd).toBe('claude')
+    expect(mock.newSessionCalls[0].cmd).not.toMatch(/setup-token/)
+    cleanScratchDir(result.scratchDir)
+  })
+
+  it('dispatches the pre-paste picker choreography (theme + login-method Enter) via sendKey before the URL', async () => {
+    // Pane walks: theme picker → login-method picker → URL. Each fires one
+    // Enter via sendKey (bare key, never the literal-code `send`).
+    const mock = makeMockTmuxOps({
+      captureResponses: [
+        'Choose the text style that looks best with your terminal',
+        'Select login method:\n  1. Claude account with subscription',
+        BROAD_URL,
+      ],
+    })
+    const result = await startAccountAuthSession('picker@example.com', {
+      home: workspace,
+      tmuxOps: mock,
+      urlTimeoutMs: 5_000,
+    })
+    // Two pre-paste Enters dispatched via sendKey, both bare "Enter".
+    expect(mock.sendKeyCalls.map((c) => c.key)).toEqual(['Enter', 'Enter'])
+    // The literal-code `send` (which would echo a secret) is NOT used pre-paste.
+    expect(mock.sendCalls).toHaveLength(0)
+    expect(result.loginUrl).toMatch(/^https:\/\/claude\.com\/cai\/oauth\/authorize\?/)
+    cleanScratchDir(result.scratchDir)
+  })
+
+  it('surfaces both URL shapes the picker can render (claude.ai/ and claude.com/cai/)', async () => {
+    for (const url of [
+      'https://claude.ai/oauth/authorize?client_id=x&code=true&scope=user%3Aprofile',
+      BROAD_URL,
+    ]) {
+      const mock = makeMockTmuxOps({ captureResponses: [`\x1b[0m${url}\nPaste code here:\n`] })
+      const result = await startAccountAuthSession('urlshape', {
+        home: workspace,
+        tmuxOps: mock,
+        urlTimeoutMs: 3_000,
+      })
+      expect(result.loginUrl).toContain('/oauth/authorize?')
+      expect(result.loginUrl).not.toMatch(/\s/) // line-wrap collapsed
+      cleanScratchDir(result.scratchDir)
+    }
+  })
+
+  it('setup-token mode is still available and uses `claude setup-token` with no picker dispatch', async () => {
+    const url =
+      'https://claude.com/cai/oauth/authorize?code=true&client_id=y&response_type=code&code_challenge=AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-z'
+    const mock = makeMockTmuxOps({ captureResponses: [url] })
+    const result = await startAccountAuthSession('narrow@example.com', {
+      home: workspace,
+      tmuxOps: mock,
+      urlTimeoutMs: 3_000,
+      mode: 'setup-token',
+    })
+    expect(result.mode).toBe('setup-token')
+    expect(mock.newSessionCalls[0].cmd).toBe('claude setup-token')
+    expect(mock.sendKeyCalls).toHaveLength(0) // no picker choreography
+    cleanScratchDir(result.scratchDir)
+  })
+})
+
+describe('submitAccountAuthCode — via-claude broad-scope + blind post-paste Enter (PR B)', () => {
+  function makeFlow(scratchDir: string, mode: 'via-claude' | 'setup-token'): PendingAuthAddFlow {
+    return {
+      label: 'broad@example.com',
+      scratchDir,
+      tmuxSocket: 'switchroom-test',
+      tmuxSession: 'auth-add-broad-abc123',
+      startedAt: Date.now(),
+      mode,
+    }
+  }
+
+  it('returns the minted broad scopes (user:profile present) and NEVER captures after the code', async () => {
+    const scratchDir = mkdtempSync(join(workspace, 'broad-'))
+    const credPath = join(scratchDir, '.credentials.json')
+    const broadCreds = JSON.stringify({
+      claudeAiOauth: {
+        accessToken: 'sk-ant-oat01-test-' + 'e'.repeat(40),
+        refreshToken: 'sk-ant-ort01-test',
+        expiresAt: Date.now() + 8 * 3600_000,
+        scopes: [
+          'org:create_api_key',
+          'user:profile',
+          'user:inference',
+          'user:sessions:claude_code',
+          'user:mcp_servers',
+          'user:file_upload',
+        ],
+        subscriptionType: 'max',
+      },
+    })
+    const mock = makeMockTmuxOps({ initialSessionAlive: true })
+    let sendCalled = false
+    let captureAfterSend = false
+    mock.onSend = () => {
+      sendCalled = true
+      writeFileSync(credPath, broadCreds, 'utf8')
+    }
+    mock.onCapture = () => { if (sendCalled) captureAfterSend = true }
+
+    const creds = await submitAccountAuthCode(makeFlow(scratchDir, 'via-claude'), 'browser-code-xyz', {
+      pollIntervalMs: 20,
+      pollTimeoutMs: 3_000,
+      tmuxOps: mock,
+    })
+
+    // The actual mission outcome: user:profile made it through.
+    expect(creds.claudeAiOauth.scopes).toContain('user:profile')
+    expect(creds.claudeAiOauth.scopes).toEqual(
+      expect.arrayContaining(['org:create_api_key', 'user:profile', 'user:inference']),
+    )
+    // Invariant preserved: no capture-pane after the code paste.
+    expect(captureAfterSend).toBe(false)
+    expect(mock.captureCallCount).toBe(0)
+  })
+
+  it('dispatches BLIND Enter key-presses after the code (no capture) to clear picker screens', async () => {
+    const scratchDir = mkdtempSync(join(workspace, 'blind-'))
+    const credPath = join(scratchDir, '.credentials.json')
+    const mock = makeMockTmuxOps({ initialSessionAlive: true })
+    // Materialise creds only AFTER the blind Enters have had a chance to fire
+    // (mimics a picker screen Enter-gating the credentials flush).
+    let ticks = 0
+    mock.onSend = () => {
+      // schedule cred write a few polls later via the poll loop below
+      ticks = 0
+    }
+    // Use a tight blind-enter schedule so the test is fast.
+    const submitP = submitAccountAuthCode(makeFlow(scratchDir, 'via-claude'), 'code-abc', {
+      pollIntervalMs: 10,
+      pollTimeoutMs: 3_000,
+      tmuxOps: mock,
+      blindEnterDelaysMs: [15, 30],
+    })
+    // Write creds after the blind Enters would have fired.
+    const timer = setInterval(() => {
+      ticks++
+      if (ticks >= 6) {
+        writeFileSync(credPath, JSON.stringify({
+          claudeAiOauth: { accessToken: 'sk-ant-oat01-test-' + 'f'.repeat(40), scopes: ['user:profile'] },
+        }), 'utf8')
+        clearInterval(timer)
+      }
+    }, 10)
+    const creds = await submitP
+    clearInterval(timer)
+    // Blind Enters were dispatched via sendKey, and capture-pane never was.
+    expect(mock.sendKeyCalls.every((c) => c.key === 'Enter')).toBe(true)
+    expect(mock.sendKeyCalls.length).toBeGreaterThanOrEqual(1)
+    expect(mock.captureCallCount).toBe(0)
+    expect(creds.claudeAiOauth.scopes).toContain('user:profile')
+  })
+
+  it('setup-token mode dispatches NO blind Enters (session exits on its own)', async () => {
+    const scratchDir = mkdtempSync(join(workspace, 'st-'))
+    const credPath = join(scratchDir, '.credentials.json')
+    const mock = makeMockTmuxOps({ initialSessionAlive: true })
+    mock.onSend = () => {
+      writeFileSync(credPath, JSON.stringify({
+        claudeAiOauth: { accessToken: 'sk-ant-oat01-test-' + 'g'.repeat(40), scopes: ['user:inference'] },
+      }), 'utf8')
+    }
+    await submitAccountAuthCode(makeFlow(scratchDir, 'setup-token'), 'code', {
+      pollIntervalMs: 20,
+      pollTimeoutMs: 2_000,
+      tmuxOps: mock,
+    })
+    expect(mock.sendKeyCalls).toHaveLength(0)
+  })
+})
+
 /* ── helpers ─────────────────────────────────────────────────────────── */
 
 function randomHex(): string {

package/telegram-plugin/tests/auth-snapshot-format.test.ts

@@ -1199,3 +1199,44 @@ describe('#2494 — renderAuthSnapshotFormat2 row rendering (out_of_credits demo
     expect(out).not.toContain('All accounts blocked');
   });
 });
+
+// ── retired / org-blocked (in-service classification, PR1) ────────────
+describe('classifyHealth — retired / org-blocked precedence', () => {
+  // A retired/org-disabled account must NEVER read as available: config and
+  // entitlement outrank the quota windows for any non-active account.
+  const healthyQ = quota({ fiveHourUtilizationPct: 5, sevenDayUtilizationPct: 10 });
+
+  it('non-active account with inService:false → retired, even on healthy quota', () => {
+    expect(classifyHealth(snap({ inService: false, quota: healthyQ }))).toBe('retired');
+  });
+  it('non-active account with entitlementBlocked → org-blocked', () => {
+    expect(classifyHealth(snap({ entitlementBlocked: true, quota: healthyQ }))).toBe('org-blocked');
+  });
+  it('entitlement block outranks retirement', () => {
+    expect(
+      classifyHealth(snap({ inService: false, entitlementBlocked: true, quota: healthyQ })),
+    ).toBe('org-blocked');
+  });
+  it('absent inService defaults to in-service (a pre-field broker is never falsely retired)', () => {
+    expect(classifyHealth(snap({ quota: healthyQ }))).toBe('healthy');
+  });
+  it('the active account keeps its quota-derived health even if inService is false', () => {
+    // active is in-service by definition; the guard skips retirement for it.
+    expect(classifyHealth(snap({ isActive: true, inService: false, quota: healthyQ }))).toBe('healthy');
+  });
+});
+
+describe('recommendation — excludes retired/org-blocked accounts', () => {
+  it('a retired account (even with healthy quota) is never offered as a switch target', () => {
+    // active is throttling; the only OTHER account is retired but at 0% util.
+    // Without the exclusion it would be recommended as a healthy switch target;
+    // with it, the retired account is invisible → "no healthy alternative".
+    const snaps: AccountSnapshot[] = [
+      snap({ label: 'a@x', isActive: true, quota: quota({ fiveHourUtilizationPct: 90 }) }),
+      snap({ label: 'retired@x', inService: false, quota: quota({ fiveHourUtilizationPct: 0 }) }),
+    ];
+    const out = recommendation(snaps, NOW);
+    expect(out).not.toContain('retired@x');
+    expect(out).toContain('no healthy alternative');
+  });
+});

package/telegram-plugin/tests/flushed-turn-supersede.test.ts

@@ -21,8 +21,10 @@ import { describe, it, expect } from 'vitest'
 import {
   decideSupersede,
   decideSupersedeCorrection,
+  flushedAnswerMatchesReply,
   FlushedTurnSupersedeRegistry,
   DEFAULT_SUPERSEDE_TTL_MS,
+  SUPERSEDE_MATCH_MIN_CONTAINMENT_CHARS,
   type FlushedTurnRecord,
 } from '../flushed-turn-supersede.js'
 
@@ -264,3 +266,118 @@ describe('FlushedTurnSupersedeRegistry — record / peek / take lifecycle', () =
     expect(reg.peek('chat1', undefined, { liveTurnId: 'turn-A', now: 5000 }).reason).toBe('no-record')
   })
 })
+
+/**
+ * #3429 — async handback edit-in-place supersede of a flush-delivered message
+ * can fail to surface client-side.
+ *
+ * The flush ends its turn synchronously BEFORE recording, so EVERY superseding
+ * reply is a late reply — and an async sub-agent handback landing within the
+ * 60 s TTL with no live gateway turn resolves the flush-delivered ENDED turn
+ * as its owner via the latest-ended tier, the SAME identity as the turn's own
+ * canonical late replay. Identity-only supersede then consumed the record and
+ * EDITED the flushed message in place with the handback's unrelated content
+ * (msgs 10482/10486, 2026-07-20) — Telegram edits never push-notify, so the
+ * handback silently failed to surface AND the flushed answer was destroyed.
+ *
+ * The content gate: `replyText` is compared against the record's flushed text
+ * (`flushedAnswerMatchesReply` — whitespace-normalized equality, or containment
+ * with a minimum-length guard on the contained side). Same answer → supersede
+ * (the wanted correction); different content → 'new-content', send fresh,
+ * record NOT consumed.
+ */
+describe('#3429 — flushedAnswerMatchesReply (content discriminator)', () => {
+  const ANSWER = 'The deploy is green: all 12 services rolled out and health checks pass.'
+  const FLUSH_BLOB = `Let me check the rollout status.\n\n${ANSWER}`
+
+  it('matches whitespace-normalized equality', () => {
+    expect(flushedAnswerMatchesReply(ANSWER, ANSWER)).toBe(true)
+    expect(flushedAnswerMatchesReply(`${ANSWER}\n`, ANSWER.replace(': ', ':  '))).toBe(true)
+  })
+
+  it('matches the classic containment class: flush = narration+answer ⊇ clean reply', () => {
+    expect(flushedAnswerMatchesReply(FLUSH_BLOB, ANSWER)).toBe(true)
+  })
+
+  it('matches reverse containment: reply ⊇ partially-delivered flush text', () => {
+    expect(flushedAnswerMatchesReply(ANSWER, FLUSH_BLOB)).toBe(true)
+  })
+
+  it('does NOT match genuinely different content (the handback)', () => {
+    const handback =
+      'Worker finished: PR #3430 is up with the fix for the vault broker timeout, ' +
+      'tests are green, ready for your review.'
+    expect(flushedAnswerMatchesReply(FLUSH_BLOB, handback)).toBe(false)
+  })
+
+  it('short containment below the minimum-length guard does NOT match ' +
+    '(a coincidental substring must never claim a handback)', () => {
+    const shortReply = 'rolled out'
+    expect(shortReply.length).toBeLessThan(SUPERSEDE_MATCH_MIN_CONTAINMENT_CHARS)
+    expect(FLUSH_BLOB.includes(shortReply)).toBe(true)
+    expect(flushedAnswerMatchesReply(FLUSH_BLOB, shortReply)).toBe(false)
+  })
+
+  it('short EQUAL texts still match (equality has no length floor)', () => {
+    expect(flushedAnswerMatchesReply('yes, done', 'yes, done')).toBe(true)
+  })
+})
+
+describe('#3429 — decideSupersede new-content gate', () => {
+  const FLUSHED = 'Narration first.\n\nHere is the finished summary of the incident you asked about.'
+  const HANDBACK =
+    'Sub-agent handback: the researcher finished and found three root causes, ' +
+    'written up in the report at /tmp/report.md — want the highlights?'
+
+  it('same-turn same-answer late reply still supersedes (the wanted correction)', () => {
+    const d = decideSupersede(rec({ text: FLUSHED }), {
+      liveTurnId: 'turn-A',
+      replyText: 'Here is the finished summary of the incident you asked about.',
+      now: 1_000_010,
+    })
+    expect(d.supersede).toBe(true)
+    expect(d.reason).toBe('supersede')
+    expect(d.recordText).toBe(FLUSHED)
+  })
+
+  it('CORE #3429: same turn identity + DIFFERENT content → new-content, NO supersede', () => {
+    const d = decideSupersede(rec({ text: FLUSHED }), {
+      liveTurnId: 'turn-A',
+      replyText: HANDBACK,
+      now: 1_000_010,
+    })
+    expect(d.supersede).toBe(false)
+    expect(d.reason).toBe('new-content')
+    expect(d.deleteMessageIds).toEqual([])
+    expect(d.recordText).toBe(FLUSHED)
+  })
+
+  it('legacy identity-only callers (no replyText) keep the pre-#3429 behaviour', () => {
+    const d = decideSupersede(rec({ text: FLUSHED }), { liveTurnId: 'turn-A', now: 1_000_010 })
+    expect(d.supersede).toBe(true)
+  })
+
+  it('take() does NOT consume the record on new-content — the genuine replay ' +
+    'can still correct the flushed message afterwards', () => {
+    const reg = new FlushedTurnSupersedeRegistry()
+    const now = 1_000_000
+    reg.record('chat9', undefined, { turnId: 'turn-F', messageIds: [7001], text: FLUSHED }, now)
+
+    // The handback lands first: new-content, nothing consumed, nothing deleted.
+    const d1 = reg.take('chat9', undefined, { liveTurnId: 'turn-F', replyText: HANDBACK, now: now + 10_000 })
+    expect(d1.supersede).toBe(false)
+    expect(d1.reason).toBe('new-content')
+
+    // The turn's own canonical replay lands later: record still there, supersede
+    // fires and consumes it.
+    const d2 = reg.take('chat9', undefined, {
+      liveTurnId: 'turn-F',
+      replyText: 'Here is the finished summary of the incident you asked about.',
+      now: now + 20_000,
+    })
+    expect(d2.supersede).toBe(true)
+    expect(d2.deleteMessageIds).toEqual([7001])
+    // Now consumed.
+    expect(reg.peek('chat9', undefined, { liveTurnId: 'turn-F', now: now + 21_000 }).reason).toBe('no-record')
+  })
+})