@0xmaxma/claude-gateway 1.3.24 → 1.3.31

package/mcp/tools/telegram/receiver-server.ts

@@ -28,15 +28,22 @@ import { randomBytes } from 'crypto'
 import { readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, statSync, renameSync, realpathSync, chmodSync, existsSync } from 'fs'
 import { homedir } from 'os'
 import { join, extname, sep } from 'path'
+import { execFileSync } from 'child_process'
 import { createWorkingStateManager, drainOrphanForwards } from './typing'
+// Import compiled dist/, not raw src/ — src/ is not published (files: ["mcp/"]),
+// so a src/ import crashes this bun-run receiver on installed packages (the bug
+// that silenced every bot on systemd installs). Enforced by
+// tests/unit/mcp-no-src-imports.test.ts.
+import { formatTurnIncident, type TurnIncident } from '../../../dist/agent/turn-trace.js'
+import { createIncidentStore } from '../../../dist/agent/incident-store.js'
+import type { RecoveryOutcome } from '../../../dist/agent/incident.js'
 import { initDedupDir, isDuplicate as _isDuplicate, pruneDedup as _pruneDedup } from './dedup'
-import { hasMarkdown, toTelegramHtml } from './pure'
+import { hasMarkdown, toTelegramHtml, migrateAccess } from './pure'
 
 // Standalone fallback: default state dir to ~/.claude/channels/telegram
 const STATE_DIR = process.env.TELEGRAM_STATE_DIR ?? join(homedir(), '.claude', 'channels', 'telegram')
 const ACCESS_FILE = join(STATE_DIR, 'access.json')
 const APPROVED_DIR = join(STATE_DIR, 'approved')
-const AWAITING_OWNER_FILE = join(STATE_DIR, 'awaiting-owner')
 const ENV_FILE = join(STATE_DIR, '.env')
 
 // Load .env fallback when token not injected via env block (standalone mode).
@@ -105,6 +112,70 @@ let botUsername = ''
 
 const TYPING_DIR = join(STATE_DIR, 'typing')
 
+// ─── Incident store (Epic #195, Phase 2) ────────────────────────────────────
+// Persist turn-trace stalls as scrubbed on-disk bundles, deduped by fingerprint
+// (stage + failure class + CLI version) with escalation. The store owns all
+// disk IO; the pure decision logic lives in src/agent/incident.ts.
+const INCIDENTS_DIR = join(homedir(), '.claude-gateway', 'incidents')
+
+// The Claude CLI version is part of the fingerprint. Resolve it once and cache
+// it — a new version is a new fingerprint, and the receiver is restarted when
+// the CLI is updated, so a per-process cache is safe.
+let cachedCliVersion: string | null = null
+function getCliVersion(): string {
+  if (cachedCliVersion !== null) return cachedCliVersion
+  try {
+    const out = execFileSync('claude', ['--version'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    const m = out.trim().match(/^(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/)
+    cachedCliVersion = m ? m[1] : 'unknown'
+  } catch {
+    cachedCliVersion = 'unknown'
+  }
+  return cachedCliVersion
+}
+
+// Gateway version, best-effort, for manifest context only (not fingerprinted).
+function readGatewayVersion(): string {
+  for (const rel of ['../../../package.json', '../../package.json']) {
+    try {
+      const raw = readFileSync(join(__dirname, rel), 'utf8')
+      const v = (JSON.parse(raw) as { version?: string }).version
+      if (typeof v === 'string' && v.length > 0) return v
+    } catch {
+      // try next candidate
+    }
+  }
+  return 'unknown'
+}
+
+const incidentStore = createIncidentStore({
+  dir: INCIDENTS_DIR,
+  fs: { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync },
+  now: () => Date.now(),
+  channel: 'telegram',
+  gatewayVersion: readGatewayVersion(),
+  getCliVersion,
+})
+
+// Prune old bundles at startup and daily thereafter (retention is enforced in
+// the store; this just triggers it periodically).
+try {
+  incidentStore.prune()
+} catch {
+  // Non-fatal: a prune failure must not stop the receiver from serving.
+}
+setInterval(() => {
+  try {
+    incidentStore.prune()
+  } catch {
+    /* non-fatal */
+  }
+}, 24 * 60 * 60 * 1000).unref()
+
 const typingManager = createWorkingStateManager(
   TYPING_DIR,
   {
@@ -118,25 +189,126 @@ const typingManager = createWorkingStateManager(
       ]),
   },
   { mkdirSync, writeFileSync, existsSync, rmSync, readFileSync, statSync },
+  // Turn-trace watchdog sink (Epic #195, Phase 2): persist a scrubbed incident
+  // bundle, then notify the affected chat only when the escalation rules say so
+  // (quiet on the first stall, louder once a fingerprint repeats). Any failure
+  // here is swallowed — incident bookkeeping must never break the live channel.
+  (incident, evidence) => {
+    process.stderr.write(`telegram channel: ${formatTurnIncident(incident)}\n`)
+    try {
+      const result = incidentStore.record(incident, evidence)
+      if (result.escalation.notify) {
+        void notifyIncident(incident.chatId, result)
+        incidentStore.markNotified(result.id, result.escalation.level)
+      }
+      // Cross-process recovery bridge (Epic #195, Phase 3b): for stages whose
+      // recovery lives in the runner (session/CLI), ask it to attempt recovery
+      // and persist the outcome. Fire-and-forget — recovery must never block the
+      // channel, and it is a no-op unless the operator enabled autoRecover.
+      void attemptRecover(incident, result.id)
+    } catch (err) {
+      process.stderr.write(
+        `telegram channel: incident persist failed: ${String(err)}\n`,
+      )
+    }
+  },
 )
 
+// Stages whose recovery must run in the runner process (live session control):
+// session injection, CLI startup, and no-output progress wedges. Inbound
+// (channel ingress) and delivery/dispatch (transport) are receiver-side and are
+// not bridged here.
+const RUNNER_RECOVERABLE_STAGES: ReadonlySet<string> = new Set(['inject', 'startup', 'progress'])
+
+// A stable-per-turn key for the runner's intervention budget. Uses the stalled
+// stage's start second (at − sinceMs), so repeated detections of the SAME wedged
+// turn share a budget while a genuinely new turn gets a fresh one.
+function recoveryTurnKey(incident: TurnIncident): string {
+  const startSec = Math.round((incident.at - incident.sinceMs) / 1000)
+  return `${incident.chatId}:${startSec}`
+}
+
+// Ask the runner to attempt recovery for a session/CLI-stage stall, then persist
+// the returned outcome to the incident bundle. Best-effort and non-blocking.
+async function attemptRecover(incident: TurnIncident, incidentId: string): Promise<void> {
+  if (!CALLBACK_URL_BASE) return
+  if (!RUNNER_RECOVERABLE_STAGES.has(incident.stage)) return
+  try {
+    const res = await fetch(CALLBACK_URL_BASE + '/recover', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        incidentId,
+        chatId: incident.chatId,
+        stage: incident.stage,
+        failureClass: incident.failureClass,
+        turnKey: recoveryTurnKey(incident),
+      }),
+    })
+    if (!res.ok) return
+    const data = (await res.json()) as { ok?: boolean; outcome?: RecoveryOutcome }
+    if (data.ok && data.outcome) {
+      incidentStore.appendRecovery(incidentId, data.outcome)
+    }
+  } catch (err) {
+    process.stderr.write(`telegram channel: recover POST failed: ${String(err)}\n`)
+  }
+}
+
+// Short, content-free notice for a stalled turn. No message text or chat id is
+// echoed back — only the pipeline stage and (on repeat) the occurrence count.
+async function notifyIncident(
+  chatId: string,
+  result: { escalation: { level: string }; occurrences: number; manifest: { stage: string } },
+): Promise<void> {
+  const stage = result.manifest.stage
+  let text: string
+  if (result.escalation.level === 'investigate') {
+    text =
+      `⚠️ Recurring stall detected at the "${stage}" stage ` +
+      `(${result.occurrences}× recently). This looks like a persistent issue — ` +
+      `it has been logged for investigation.`
+  } else {
+    // Neutral wording: automatic recovery only runs when the operator has
+    // enabled gateway.selfHealing.autoRecover (off by default), and the receiver
+    // cannot see that runner-side flag — so do not promise it here.
+    text =
+      `⚠️ A turn stalled at the "${stage}" stage and has been logged.`
+  }
+  try {
+    await bot.api.sendMessage(chatId, text)
+  } catch {
+    // Best-effort notify; the incident is already persisted regardless.
+  }
+}
+
 type PendingEntry = {
   senderId: string
   chatId: string
   createdAt: number
   expiresAt: number
   replies: number
-}
-
-type GroupPolicy = {
-  requireMention: boolean
-  allowFrom: string[]
+  // Absent ⇒ 'dm'. 'group' entries hold a group id in chatId; approval pushes
+  // it into groupAllowlist (mirrors LINE).
+  kind?: 'dm' | 'group'
 }
 
 type Access = {
-  dmPolicy: 'open' | 'pairing' | 'allowlist' | 'disabled'
+  dmPolicy: 'open' | 'allowlist' | 'disabled'
+  // Orthogonal pairing toggle (mirrors LINE). Only meaningful when
+  // dmPolicy === 'allowlist': true ⇒ unknown senders get a one-time code and
+  // land in pending; false ⇒ silently dropped (pure allowlist).
+  pairing: boolean
   allowFrom: string[]
-  groups: Record<string, GroupPolicy>
+  // Group access tier (mirrors LINE): base policy, allowlisted group ids, and a
+  // single requireMention gate. `pairing` governs group code-minting too.
+  groupPolicy: 'open' | 'allowlist' | 'disabled'
+  groupAllowlist: string[]
+  requireMention: boolean
+  // Migration-only artifact — mirrors pure.ts Access — keep in sync. Enforced
+  // in gate() below so migrating a pre-split file can't silently widen a
+  // group that was previously restricted to specific senders.
+  legacyGroupAllowFrom?: Record<string, string[]>
   pending: Record<string, PendingEntry>
   mentionPatterns?: string[]
   // delivery/UX config — optional, defaults live in the reply handler
@@ -152,9 +324,12 @@ type Access = {
 
 function defaultAccess(): Access {
   return {
-    dmPolicy: 'pairing',
+    dmPolicy: 'allowlist',
+    pairing: true,
     allowFrom: [],
-    groups: {},
+    groupPolicy: 'allowlist',
+    groupAllowlist: [],
+    requireMention: true,
     pending: {},
     ackReaction: '👀',
   }
@@ -181,18 +356,8 @@ function assertSendable(f: string): void {
 function readAccessFile(): Access {
   try {
     const raw = readFileSync(ACCESS_FILE, 'utf8')
-    const parsed = JSON.parse(raw) as Partial<Access>
-    return {
-      dmPolicy: parsed.dmPolicy ?? 'pairing',
-      allowFrom: parsed.allowFrom ?? [],
-      groups: parsed.groups ?? {},
-      pending: parsed.pending ?? {},
-      mentionPatterns: parsed.mentionPatterns,
-      ackReaction: parsed.ackReaction,
-      replyToMode: parsed.replyToMode,
-      textChunkLimit: parsed.textChunkLimit,
-      chunkMode: parsed.chunkMode,
-    }
+    const parsed = JSON.parse(raw) as Partial<Access> & { dmPolicy?: string }
+    return migrateAccess(parsed) as Access
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code === 'ENOENT') return defaultAccess()
     try {
@@ -212,7 +377,7 @@ function loadAccess(): Access {
 function assertAllowedChat(chat_id: string): void {
   const access = loadAccess()
   if (access.allowFrom.includes(chat_id)) return
-  if (chat_id in access.groups) return
+  if (access.groupAllowlist.includes(chat_id)) return
   throw new Error(`chat ${chat_id} is not allowlisted — add via /telegram:access`)
 }
 
@@ -238,47 +403,20 @@ function pruneExpired(a: Access, now?: number): boolean {
 type GateResult =
   | { action: 'deliver'; access: Access }
   | { action: 'drop' }
-  | { action: 'pair'; code: string; isResend: boolean }
+  | { action: 'pair'; code: string; isResend: boolean; isGroup?: boolean }
 
 function gate(ctx: Context): GateResult {
   const access = loadAccess()
   const pruned = pruneExpired(access)
   if (pruned) saveAccess(access)
 
-  if (access.dmPolicy === 'disabled') return { action: 'drop' }
-
   const from = ctx.from
   if (!from) return { action: 'drop' }
   const senderId = String(from.id)
   const chatType = ctx.chat?.type
 
-  // Owner init-pairing sentinel: first private message auto-approves sender as owner.
-  if (chatType === 'private') {
-    try {
-      const stat = statSync(AWAITING_OWNER_FILE)
-      const age = Date.now() - stat.mtimeMs
-      if (age < 10 * 60 * 1000) {
-        // Sentinel is valid — approve this sender as owner
-        if (!access.allowFrom.includes(senderId)) access.allowFrom.push(senderId)
-        saveAccess(access)
-        rmSync(AWAITING_OWNER_FILE, { force: true })
-        // Write approved file so receiver sends confirmation message
-        mkdirSync(APPROVED_DIR, { recursive: true })
-        writeFileSync(join(APPROVED_DIR, senderId), String(ctx.chat!.id))
-        return { action: 'deliver', access }
-      } else {
-        rmSync(AWAITING_OWNER_FILE, { force: true })
-      }
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
-        // Unexpected I/O error — deny to be safe rather than silently allowing
-        return { action: 'drop' }
-      }
-      // ENOENT — no sentinel, continue normal gate logic
-    }
-  }
-
   if (chatType === 'private') {
+    if (access.dmPolicy === 'disabled') return { action: 'drop' }
     if (access.dmPolicy === 'open') {
       if (!access.allowFrom.includes(senderId)) {
         access.allowFrom.push(senderId)
@@ -287,11 +425,13 @@ function gate(ctx: Context): GateResult {
       return { action: 'deliver', access }
     }
     if (access.allowFrom.includes(senderId)) return { action: 'deliver', access }
-    if (access.dmPolicy === 'allowlist') return { action: 'drop' }
+    // Base policy is 'allowlist' ('open'/'disabled' handled above). Pairing is
+    // the orthogonal toggle: off ⇒ pure allowlist (drop strangers, no code).
+    if (!access.pairing) return { action: 'drop' }
 
     // pairing mode — check for existing non-expired code for this sender
     for (const [code, p] of Object.entries(access.pending)) {
-      if (p.senderId === senderId) {
+      if ((p.kind ?? 'dm') === 'dm' && p.senderId === senderId) {
         // Reply twice max (initial + one reminder), then go silent.
         if ((p.replies ?? 1) >= 2) return { action: 'drop' }
         p.replies = (p.replies ?? 1) + 1
@@ -299,8 +439,8 @@ function gate(ctx: Context): GateResult {
         return { action: 'pair', code, isResend: true }
       }
     }
-    // Cap pending at 3. Extra attempts are silently dropped.
-    if (Object.keys(access.pending).length >= 3) return { action: 'drop' }
+    // Cap pending per-kind at 3. Extra attempts are silently dropped.
+    if (countPending(access, 'dm') >= 3) return { action: 'drop' }
 
     const code = randomBytes(3).toString('hex') // 6 hex chars
     const now = Date.now()
@@ -310,6 +450,7 @@ function gate(ctx: Context): GateResult {
       createdAt: now,
       expiresAt: now + 60 * 60 * 1000, // 1h
       replies: 1,
+      kind: 'dm',
     }
     saveAccess(access)
     return { action: 'pair', code, isResend: false }
@@ -317,14 +458,42 @@ function gate(ctx: Context): GateResult {
 
   if (chatType === 'group' || chatType === 'supergroup') {
     const groupId = String(ctx.chat!.id)
-    const policy = access.groups[groupId]
-    if (!policy) return { action: 'drop' }
-    const groupAllowFrom = policy.allowFrom ?? []
-    const requireMention = policy.requireMention ?? true
-    if (groupAllowFrom.length > 0 && !groupAllowFrom.includes(senderId)) {
+    if (access.groupPolicy === 'disabled') return { action: 'drop' }
+
+    if (access.groupPolicy === 'allowlist' && !access.groupAllowlist.includes(groupId)) {
+      // Unknown group. Pairing off ⇒ silent drop. On ⇒ mint a code keyed on the
+      // group id and post it here; a member relays it to the admin (mirrors LINE).
+      if (!access.pairing) return { action: 'drop' }
+      for (const [code, p] of Object.entries(access.pending)) {
+        if (p.kind === 'group' && p.chatId === groupId) {
+          if ((p.replies ?? 1) >= 2) return { action: 'drop' }
+          p.replies = (p.replies ?? 1) + 1
+          saveAccess(access)
+          return { action: 'pair', code, isResend: true, isGroup: true }
+        }
+      }
+      if (countPending(access, 'group') >= 3) return { action: 'drop' }
+      const code = randomBytes(3).toString('hex') // 6 hex chars
+      const now = Date.now()
+      access.pending[code] = {
+        senderId,
+        chatId: groupId,
+        createdAt: now,
+        expiresAt: now + 60 * 60 * 1000, // 1h
+        replies: 1,
+        kind: 'group',
+      }
+      saveAccess(access)
+      return { action: 'pair', code, isResend: false, isGroup: true }
+    }
+
+    // Allowlisted (or open policy) → enforce any legacy per-sender restriction
+    // that survived migration, then the single mention gate.
+    const legacyAllowed = access.legacyGroupAllowFrom?.[groupId]
+    if (legacyAllowed && legacyAllowed.length > 0 && !legacyAllowed.includes(senderId)) {
       return { action: 'drop' }
     }
-    if (requireMention && !isMentioned(ctx, access.mentionPatterns)) {
+    if (access.requireMention !== false && !isMentioned(ctx, access.mentionPatterns)) {
       return { action: 'drop' }
     }
     return { action: 'deliver', access }
@@ -333,6 +502,15 @@ function gate(ctx: Context): GateResult {
   return { action: 'drop' }
 }
 
+/** Count pending entries of a given kind (absent kind ⇒ 'dm'). */
+function countPending(access: Access, kind: 'dm' | 'group'): number {
+  let n = 0
+  for (const p of Object.values(access.pending)) {
+    if ((p.kind ?? 'dm') === kind) n++
+  }
+  return n
+}
+
 function isMentioned(ctx: Context, extraPatterns?: string[]): boolean {
   const entities = ctx.message?.entities ?? ctx.message?.caption_entities ?? []
   const text = ctx.message?.text ?? ctx.message?.caption ?? ''
@@ -750,6 +928,17 @@ type AttachmentMeta = {
   name?: string
 }
 
+// Pairing reply shown to an un-allowlisted sender: their one-time code plus
+// the instruction to report it to the admin. Shared by handleInbound (normal
+// message) and the /start command so both hand the code out identically.
+function pairingReplyText(code: string, isResend: boolean, isGroup = false): string {
+  const lead = isResend ? 'Still waiting for approval.' : 'This bot is private.'
+  const share = isGroup
+    ? 'Share this code with an admin to enable me in this group.'
+    : 'Share this code with the admin to get access.'
+  return `${lead}\n\nPairing code: ${code}\n\n${share}`
+}
+
 async function handleInbound(
   ctx: Context,
   text: string,
@@ -767,10 +956,11 @@ async function handleInbound(
   if (result.action === 'drop') return
 
   if (result.action === 'pair') {
-    const lead = result.isResend ? 'Still pending' : 'Pairing required'
-    await ctx.reply(
-      `${lead} — run in Claude Code:\n\n/telegram:access pair ${result.code}`,
-    )
+    // LINE-style: hand the user their code and let the admin approve it from
+    // the web UI. The user does NOT run any command (they may not have Claude
+    // Code at all) — they just report the code to the admin, who verifies it
+    // matches what's shown in Pending and clicks Approve.
+    await ctx.reply(pairingReplyText(result.code, result.isResend, result.isGroup))
     return
   }
 
@@ -915,18 +1105,21 @@ if (!SEND_ONLY) {
 
 bot.command('start', async ctx => {
   if (ctx.chat?.type !== 'private') return
-  const access = loadAccess()
-  if (access.dmPolicy === 'disabled') {
-    await ctx.reply(`This bot isn't accepting new connections.`)
+  // Route /start through the same gate as a first message so a new user gets
+  // their pairing code immediately (LINE-style), instead of an instruction to
+  // send another message. The literal "/start" text is never relayed to Claude.
+  const result = gate(ctx)
+  if (result.action === 'pair') {
+    await ctx.reply(pairingReplyText(result.code, result.isResend))
     return
   }
-  await ctx.reply(
-    `This bot bridges Telegram to a Claude Code session.\n\n` +
-    `To pair:\n` +
-    `1. DM me anything — you'll get a 6-char code\n` +
-    `2. In Claude Code: /telegram:access pair <code>\n\n` +
-    `After that, DMs here reach that session.`
-  )
+  if (result.action === 'deliver') {
+    // Already allowlisted (or an open-policy bot) — nothing to pair.
+    await ctx.reply(`You're paired. Just send me a message and it reaches the assistant.`)
+    return
+  }
+  // drop — dmPolicy disabled, or pure allowlist (pairing off) for an unknown sender.
+  await ctx.reply(`This bot isn't accepting new connections right now.`)
 })
 
 bot.command('help', async ctx => {
@@ -969,7 +1162,7 @@ bot.command('status', async ctx => {
   for (const [code, p] of Object.entries(access.pending)) {
     if (p.senderId === senderId) {
       await ctx.reply(
-        `Pending pairing — run in Claude Code:\n\n/telegram:access pair ${code}`
+        `Pending approval.\n\nYour pairing code: ${code}\n\nShare it with the admin to get access.`
       )
       return
     }

package/mcp/tools/telegram/skills/access/SKILL.md

@@ -63,22 +63,58 @@ APPROVED_DIR = {STATE_DIR}/approved
 
 ```json
 {
-  "dmPolicy": "pairing",
+  "dmPolicy": "allowlist",
+  "pairing": true,
   "allowFrom": ["<senderId>", ...],
-  "groups": {
-    "<groupId>": { "requireMention": true, "allowFrom": [] }
-  },
+  "groupPolicy": "allowlist",
+  "groupAllowlist": ["<groupId>", ...],
+  "requireMention": true,
+  "legacyGroupAllowFrom": { "<groupId>": ["<senderId>", ...] },
   "pending": {
     "<6-char-code>": {
       "senderId": "...", "chatId": "...",
-      "createdAt": <ms>, "expiresAt": <ms>
+      "createdAt": <ms>, "expiresAt": <ms>,
+      "kind": "dm"
     }
   },
   "mentionPatterns": ["@mybot"]
 }
 ```
 
-Missing file = `{dmPolicy:"pairing", allowFrom:[], groups:{}, pending:{}}`.
+`dmPolicy` is the base access policy: `open` | `allowlist` | `disabled`.
+`pairing` is an **orthogonal on/off toggle** (mirrors LINE), only meaningful
+when `dmPolicy`/`groupPolicy` is `allowlist`: `true` ⇒ an unknown sender or
+group gets a one-time 6-char code that lands in `pending` for the admin to
+approve; `false` ⇒ silently dropped (pure allowlist).
+
+The **group tier** mirrors LINE: `groupPolicy` (`open` | `allowlist` |
+`disabled`) is the base policy for groups, `groupAllowlist` holds the approved
+group ids (negative numbers, e.g. `-1001234567890`), and `requireMention` (a
+single boolean) gates whether the bot answers in an allowlisted group only when
+@mentioned. A `pending` entry with `"kind": "group"` is a group knock — its
+`chatId` is the group id and `pair`-ing it adds that id to `groupAllowlist`
+(not `allowFrom`). Entries with no `kind` (or `"kind": "dm"`) are DM knocks.
+
+**Group delivery caveat (Telegram Privacy Mode).** Allowlisting a group only
+decides how the gate *responds* — it does nothing if Telegram never delivers the
+message. Bots default to **Privacy Mode ON** (`getMe` →
+`can_read_all_group_messages: false`), so in a group the bot only receives
+`/commands`, @mentions of its username, and replies to its own messages; plain
+messages are filtered out before the gateway sees them. And bot commands are
+DM-only (dropped in groups). So a group can be correctly allowlisted yet stay
+silent, and an unknown group may never mint a pairing code. Tell the user to
+**promote the bot to Admin in the group** (an admin bot receives everything
+regardless of Privacy Mode) or **disable Privacy Mode in BotFather and re-add the
+bot**. This is a Telegram-side setting — `/telegram:access` cannot change it.
+
+`legacyGroupAllowFrom` is a **migration-only artifact**, not a live feature —
+it's how a pre-split file's per-group sender restriction survives migration
+(the old schema could lock a group to specific senders; the current model has
+no per-user group tier). If present, it's enforced silently in addition to
+`requireMention`. Preserve this key as-is whenever you read/rewrite the file —
+never invent, edit, or add entries to it; there is no command for that.
+
+Missing file = `{dmPolicy:"allowlist", pairing:true, allowFrom:[], groupPolicy:"allowlist", groupAllowlist:[], requireMention:true, pending:{}}`.
 
 ---
 
@@ -89,22 +125,27 @@ Parse `$ARGUMENTS` (space-separated). If empty or unrecognized, show status.
 ### No args — status
 
 1. Read `{STATE_DIR}/access.json` (handle missing file).
-2. Show: dmPolicy, allowFrom count and list, pending count with codes +
-   sender IDs + age, groups count.
+2. Show: dmPolicy, the pairing toggle (on/off), allowFrom count and list,
+   pending count with codes + sender IDs + kind (dm/group) + age, groupPolicy,
+   requireMention, and the groupAllowlist count and list.
 
 ### `pair <code>`
 
 1. Read `{STATE_DIR}/access.json`.
 2. Look up `pending[<code>]`. If not found or `expiresAt < Date.now()`,
    tell the user and stop.
-3. Extract `senderId` and `chatId` from the pending entry.
-4. Add `senderId` to `allowFrom` (dedupe).
-5. Delete `pending[<code>]`.
-6. Write the updated access.json.
-7. `mkdir -p {STATE_DIR}/approved` then write
-   `{STATE_DIR}/approved/<senderId>` with `chatId` as the
-   file contents. The channel server polls this dir and sends "you're in".
-8. Confirm: who was approved (senderId).
+3. **Kind-aware.** If the entry's `kind` is `"group"`:
+   - Add its `chatId` (the group id) to `groupAllowlist` (dedupe).
+   - Delete `pending[<code>]`, write access.json. **No** `approved/` file (a
+     group has no single recipient — the bot silently starts answering there).
+   - Confirm which group id was allowed.
+   Otherwise (DM knock, `kind` absent or `"dm"`):
+   - Add `senderId` to `allowFrom` (dedupe).
+   - Delete `pending[<code>]`, write access.json.
+   - `mkdir -p {STATE_DIR}/approved` then write
+     `{STATE_DIR}/approved/<senderId>` with `chatId` as the file contents. The
+     channel server polls this dir and sends "you're in".
+   - Confirm who was approved (senderId).
 
 ### `deny <code>`
 
@@ -123,19 +164,48 @@ Parse `$ARGUMENTS` (space-separated). If empty or unrecognized, show status.
 
 ### `policy <mode>`
 
-1. Validate `<mode>` is one of `pairing`, `allowlist`, `disabled`.
+1. Validate `<mode>` is one of `open`, `allowlist`, `disabled`.
+   (Pairing is no longer a policy value — it's the separate `pairing` toggle
+   below. `allowlist` + `pairing on` is the capture-unknown-users mode.)
 2. Read (create default if missing), set `dmPolicy`, write.
 
-### `group add <groupId>` (optional: `--no-mention`, `--allow id1,id2`)
+### `pairing <on|off>`
+
+Toggle the orthogonal pairing code layer (only affects `dmPolicy: "allowlist"`).
+
+1. Validate `<value>` is `on` or `off`.
+2. Read (create default if missing), set `pairing` to `true`/`false`, write.
+3. Confirm. When `on`: unknown senders receive a one-time code and appear in
+   `pending` for you to `pair`. When `off`: unknown senders are dropped
+   silently (pure allowlist).
+
+### `group policy <mode>`
+
+1. Validate `<mode>` is one of `open`, `allowlist`, `disabled`.
+2. Read (create default if missing), set `groupPolicy`, write.
+   (`allowlist` + `pairing on` is the capture-unknown-groups mode: an unknown
+   group gets a pairing code posted in it.)
+
+### `group allow <groupId>`
 
 1. Read (create default if missing).
-2. Set `groups[<groupId>] = { requireMention: !hasFlag("--no-mention"),
-   allowFrom: parsedAllowList }`.
-3. Write.
+2. Add `<groupId>` to `groupAllowlist` (dedupe). Write.
+   (Group ids are negative numbers, e.g. `-1001234567890`.)
+
+### `group deny <groupId>`
+
+1. Read, filter `groupAllowlist` to exclude `<groupId>`, also delete
+   `legacyGroupAllowFrom[<groupId>]` if present (so a later re-add doesn't
+   resurrect a stale restriction), write.
+
+### `group mention <on|off>`
 
-### `group rm <groupId>`
+Toggle the single group mention gate (`requireMention`).
 
-1. Read, `delete groups[<groupId>]`, write.
+1. Validate `<value>` is `on` or `off`.
+2. Read (create default if missing), set `requireMention` to `true`/`false`, write.
+3. Confirm. When `on`: the bot answers in an allowlisted group only when
+   @mentioned (or replied to). When `off`: it answers every message there.
 
 ### `set <key> <value>`