switchroom 0.17.10 → 0.18.3

package/telegram-plugin/gateway/inbound-delivery-gate.ts

@@ -116,3 +116,29 @@ export function decideInboundDelivery(
   if (input.turnInFlight) return 'buffer-until-idle'
   return 'deliver'
 }
+
+/**
+ * #2917 — atomic check-and-reserve for per-chat outbound FIFO.
+ *
+ * `decideInboundDelivery` decides deliver-vs-buffer, but on the concurrent
+ * `handleInbound` path that decision and the busy-mark that records "a turn is
+ * now in flight for this chat" are separated by an `await` (attachment
+ * download, composer-clear). Two same-chat inbounds can therefore each read
+ * "idle" during the other's async lead-in and both deliver — the replies then
+ * come back reordered. This helper couples the decision with a `reserve` flag:
+ * a FRESH-TURN deliver must reserve the chat's busy key SYNCHRONOUSLY (before
+ * any await) so the next same-chat inbound sees it and buffers behind it.
+ *
+ * `reserve` is true ONLY for a fresh-turn deliver. Steering / interrupt
+ * inbounds deliver mid-turn WITHOUT starting a turn, so they must not reserve
+ * (reserving would wedge the running turn's key). A buffered decision never
+ * reserves.
+ */
+export function reserveInboundDelivery(
+  input: InboundDeliveryGateInput,
+): { decision: InboundDeliveryDecision; reserve: boolean } {
+  const decision = decideInboundDelivery(input)
+  const reserve =
+    decision === 'deliver' && !input.isSteering && input.isInterrupt !== true
+  return { decision, reserve }
+}

package/telegram-plugin/gateway/model-command.ts

@@ -52,11 +52,14 @@ export const MODEL_ALIASES = ['opus', 'sonnet', 'haiku', 'fable', 'default'] as
  * Shape gate for the model argument. This string is typed literally
  * into the agent's tmux pane, so the gate is strict by construction:
  * one token, alphanumeric start, then alphanumerics plus the chars
- * that appear in real model ids (`.` `_` `-` and the `[1m]`-style
- * variant brackets). No whitespace means no second token can ride
+ * that appear in real model ids (`.` `_` `-` `/` and the `[1m]`-style
+ * variant brackets). `/` is allowed for OpenRouter-style
+ * `sr-vendor/model` ids; it is not a shell metachar inside the
+ * double-quoted `claude --model "$_EFFECTIVE_MODEL"` usage, so it can't
+ * break the launch. No whitespace means no second token can ride
  * along; no control characters means no newline/Enter smuggling.
  */
-const MODEL_ARG_RE = /^[A-Za-z0-9][A-Za-z0-9._\[\]-]{0,99}$/
+const MODEL_ARG_RE = /^[A-Za-z0-9][A-Za-z0-9._/\[\]-]{0,99}$/
 
 export function isValidModelArg(arg: string): boolean {
   return MODEL_ARG_RE.test(arg)
@@ -133,6 +136,18 @@ export interface ModelCommandDeps {
    * mechanism as the `/restart` command (hostd-first, SIGTERM fallback).
    */
   scheduleRestart: (reason: string) => Promise<void>
+  /**
+   * Schedule a session-only switch TO a non-Claude (`sr-*` LiteLLM/OpenRouter)
+   * model. claude's in-REPL `/model` picker rejects unknown `sr-*` ids, so an
+   * inject can't set them. Instead the gateway writes the chosen token to the
+   * `.session-model-override` carrier file and gracefully restarts the agent;
+   * the next boot launches `claude --model <token>` directly (LiteLLM routes
+   * it, no picker validation). Session-only: reverts to the configured default
+   * on the following restart. Wired to the same restart dispatch as
+   * `scheduleRestart`, plus the carrier write. `model` is the full `sr-*` id
+   * (already alias-expanded); `reason` is stamped as the restart reason.
+   */
+  scheduleModelRelaunch: (model: string, reason: string) => Promise<void>
 }
 
 export interface ModelCommandReply {
@@ -152,6 +167,7 @@ function helpText(deps: ModelCommandDeps, reason?: string): ModelCommandReply {
     '\`/model\` — show the configured model',
     `\`/model <name>\` — switch the live session (${MODEL_ALIASES.map(a => `\`${a}\``).join(' · ')} or a full model id)`,
     `_OpenRouter shortcuts:_ ${srAliasExamples}`,
+    '_OpenRouter (sr-\\*) switches restart the session (~30s); Claude switches apply instantly._',
     PERSIST_NOTE,
   )
   return { text: lines.join('\n'), html: true }
@@ -214,6 +230,30 @@ export async function handleModelCommand(
     }
   }
 
+  // Claude → sr-*: an in-place inject can't set a non-Anthropic model — claude's
+  // native `/model` picker rejects the unknown `sr-*` id ("Model not found").
+  // Carry the token across a graceful restart and relaunch `claude --model
+  // sr-*` directly (LiteLLM routes it). Session-only: reverts to the configured
+  // default on the next restart. The sr-* → Claude direction is handled above.
+  if (isSrModel(model)) {
+    try {
+      await deps.scheduleModelRelaunch(model, `user: /model ${model} (session-only relaunch)`)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      return {
+        text: `❌ Could not schedule model switch: ${deps.escapeHtml(msg)}`,
+        html: true,
+      }
+    }
+    return {
+      text: [
+        `Switching to \`${deps.escapeHtml(model)}\` — restarting session (~30s).`,
+        '_Session-only — reverts to the configured default on the next restart._',
+      ].join('\n'),
+      html: true,
+    }
+  }
+
   const verbHtml = `\`/model ${deps.escapeHtml(model)}\``
   let result: InjectResult
   try {
@@ -358,16 +398,31 @@ export const EXTRA_CLAUDE_ALIASES: ReadonlyArray<{ alias: string; label: string
  * Friendly display names for sr-* synthetic model names. An sr-* model in
  * LiteLLM has no entry in `model_group_settings.*.forward_client_headers_to_llm_api`
  * so the Anthropic OAuth credential is NEVER forwarded — safe to route to
- * OpenRouter. Names here are display-only; the raw `sr-*` id is what gets
- * injected into the agent's session. See reference/rfcs/litellm-max-subscription-invariants.md § I6.
+ * OpenRouter. Names here are display-only (used by srFriendlyLabel for /status
+ * and switch confirmations); the raw `sr-*` id is what gets injected into the
+ * agent's session. This table is a SUPERSET of the menu-reachable set
+ * (SR_MODEL_ALIASES): it also labels models that are only reachable by typing
+ * the full `/model sr-<name>` (manual passthrough), so those still get a
+ * friendly name without appearing as a keyboard button.
+ * See reference/rfcs/litellm-max-subscription-invariants.md § I6.
  */
 export const SR_MODEL_LABELS: Record<string, string> = {
   'sr-gemini-2.5-pro': 'Gemini 2.5 Pro',
   'sr-gemini-2.5-flash': 'Gemini 2.5 Flash',
   'sr-deepseek-r1': 'DeepSeek R1',
   'sr-deepseek-v3': 'DeepSeek V3',
-  'sr-glm-5': 'GLM-5',
+  // sr-glm-5 now targets glm-5.2 in the live litellm config — label bumped to match.
+  'sr-glm-5': 'GLM-5.2',
   'sr-codex-5.5': 'Codex 5.5',
+  // OpenRouter coverage (pairs with the live litellm sr-* model_name additions).
+  'sr-gpt-oss-20b': 'GPT-OSS 20B',
+  'sr-gpt-oss-120b': 'GPT-OSS 120B',
+  'sr-gpt-5.5': 'GPT-5.5',
+  'sr-gpt-5-codex': 'GPT-5 Codex',
+  'sr-gpt-5.2-codex': 'GPT-5.2 Codex',
+  'sr-gemini-flash-lite': 'Gemini 3.1 Flash Lite',
+  'sr-minimax-m3': 'MiniMax M3',
+  'sr-deepseek-v4-flash': 'DeepSeek V4 Flash',
 }
 
 /**
@@ -448,10 +503,15 @@ function headerRow(label: string): ModelMenuKeyboardButton[] {
  * requires ANTHROPIC_CUSTOM_HEADERS (a litellm key) to be set on the gateway
  * process. switchroom never sets that env on the gateway, so in production
  * discoverSrModels() always returns [] and the external group was silently
- * empty. The six SR_MODEL_ALIASES targets are the sr-* names the litellm
- * config actually exposes, so seeding from them makes the group reliable
- * without the missing env — while still merging any live results on hosts
- * that do configure discovery.
+ * empty. The six SR_MODEL_ALIASES targets are the CURATED main sr-* set, so
+ * seeding from them makes the group reliable without the missing env — while
+ * still merging any live results on hosts that do configure discovery.
+ *
+ * Deliberately a SUBSET: the litellm config exposes more sr-* models than this
+ * (the full OpenRouter catalogue). Those extras are display-labelled in
+ * SR_MODEL_LABELS and remain typeable via `/model <full-sr-name>` (manual
+ * passthrough — the set path is a shape gate, no whitelist), but they are kept
+ * OUT of SR_MODEL_ALIASES on purpose so the keyboard stays small and curated.
  *
  * Subscription-honest: ONLY the curated sr-* aliases surface as buttons. Raw
  * gpt-4o / openrouter/* dupes / voyage-* embeddings never do.

package/telegram-plugin/package.json

@@ -33,8 +33,14 @@
     "@secretlint/types": "^12.2.0",
     "@xterm/headless": "^6.0.0",
     "grammy": "^1.44",
+    "mdast-util-from-markdown": "^2.0.2",
+    "mdast-util-gfm": "^3.0.0",
+    "micromark-extension-gfm": "^3.0.0",
     "posthog-node": "^5.29.2"
   },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4"
+  },
   "engines": {
     "node": ">=20.11.0"
   },

package/telegram-plugin/quota-watch.ts

@@ -97,9 +97,10 @@ export function emptyAccountState(): QuotaWatchAccountState {
  *   SWITCHROOM_QUOTA_WATCH_FLEET_DEDUP       "0" disables the broker claim
  *                                            (every agent sends, pre-incident
  *                                            behaviour)
- *   SWITCHROOM_QUOTA_WATCH_SEND_ON_PROBE_FAIL "1" restores sending from
- *                                            cached data when the pre-send
- *                                            validation probe fails
+ *
+ * When the pre-send validation probe fails, the alert is unconditionally
+ * suppressed (a quota notification must never carry numbers we could not
+ * verify live); the transition re-evaluates on the next poll tick.
  */
 export interface QuotaWatchTuning {
   /** Cached snapshots older than this are treated as unknown (no opinion). 0 = off. */
@@ -108,8 +109,6 @@ export interface QuotaWatchTuning {
   lateRecoveryMs: number;
   /** Route sends through the broker's claim-notification dedup. */
   fleetDedup: boolean;
-  /** Legacy: send from cached data when the validation probe fails. */
-  sendOnProbeFail: boolean;
 }
 
 export const DEFAULT_QUOTA_WATCH_MAX_STALE_MS = 60 * 60_000;
@@ -133,7 +132,6 @@ export function resolveQuotaWatchTuning(
     maxStaleMs: num(env.SWITCHROOM_QUOTA_WATCH_MAX_STALE_MS, DEFAULT_QUOTA_WATCH_MAX_STALE_MS),
     lateRecoveryMs: num(env.SWITCHROOM_QUOTA_WATCH_LATE_RECOVERY_MS, DEFAULT_QUOTA_WATCH_LATE_RECOVERY_MS),
     fleetDedup: env.SWITCHROOM_QUOTA_WATCH_FLEET_DEDUP !== "0",
-    sendOnProbeFail: env.SWITCHROOM_QUOTA_WATCH_SEND_ON_PROBE_FAIL === "1",
   };
 }
 

package/telegram-plugin/registry/turns-schema.test.ts

@@ -21,6 +21,7 @@ import {
   recordTurnEnd,
   findRecentTurnsForChat,
   getTurnByKey,
+  reapStaleOpenTurns,
 } from './turns-schema.js'
 
 // ---------------------------------------------------------------------------
@@ -157,3 +158,99 @@ describe('getTurnByKey', () => {
     db.close()
   })
 })
+
+// ---------------------------------------------------------------------------
+// reapStaleOpenTurns — mid-session periodic orphan sweep (#2918)
+// ---------------------------------------------------------------------------
+
+describe('reapStaleOpenTurns (#2918 mid-session sweep)', () => {
+  // Helper: force a row's started_at into the past so the TTL gate is met.
+  function ageRow(db: ReturnType<typeof openTurnsDbInMemory>, turnKey: string, startedAt: number): void {
+    db.prepare('UPDATE turns SET started_at = ? WHERE turn_key = ?').run(startedAt, turnKey)
+  }
+
+  it('stamps an ownerless open row aged past the TTL as restart', () => {
+    const db = openTurnsDbInMemory()
+    const now = 1_000_000_000_000
+    recordTurnStart(db, { turnKey: 'dm:dead', chatId: '111' })
+    ageRow(db, 'dm:dead', now - 30 * 60_000) // 30 min old
+    const res = reapStaleOpenTurns(db, {
+      activeTurnKeys: new Set<string>(), // process gone → no live owner
+      ttlMs: 15 * 60_000,
+      now,
+    })
+    expect(res.reaped).toBe(1)
+    expect(res.reapedTurnKeys).toEqual(['dm:dead'])
+    const turn = getTurnByKey(db, 'dm:dead')
+    expect(turn?.ended_at).toBe(now)
+    expect(turn?.ended_via).toBe('restart')
+    db.close()
+  })
+
+  it('NEVER touches a healthy in-flight turn (turn_key in activeTurnKeys)', () => {
+    const db = openTurnsDbInMemory()
+    const now = 1_000_000_000_000
+    recordTurnStart(db, { turnKey: 'dm:live', chatId: '222' })
+    // Even though it is aged well past the TTL, a live owner protects it.
+    ageRow(db, 'dm:live', now - 6 * 60 * 60_000) // 6h "long-running" turn
+    const res = reapStaleOpenTurns(db, {
+      activeTurnKeys: new Set(['dm:live']),
+      ttlMs: 15 * 60_000,
+      now,
+    })
+    expect(res.reaped).toBe(0)
+    const turn = getTurnByKey(db, 'dm:live')
+    expect(turn?.ended_at).toBeNull()
+    expect(turn?.ended_via).toBeNull()
+    db.close()
+  })
+
+  it('does not reap an ownerless row younger than the TTL (race guard)', () => {
+    const db = openTurnsDbInMemory()
+    const now = 1_000_000_000_000
+    recordTurnStart(db, { turnKey: 'dm:fresh', chatId: '333' })
+    ageRow(db, 'dm:fresh', now - 60_000) // 1 min old, ownerless
+    const res = reapStaleOpenTurns(db, {
+      activeTurnKeys: new Set<string>(),
+      ttlMs: 15 * 60_000,
+      now,
+    })
+    expect(res.reaped).toBe(0)
+    expect(getTurnByKey(db, 'dm:fresh')?.ended_at).toBeNull()
+    db.close()
+  })
+
+  it('reaps the dead orphan while sparing a concurrently-live turn', () => {
+    const db = openTurnsDbInMemory()
+    const now = 1_000_000_000_000
+    recordTurnStart(db, { turnKey: 'dm:dead', chatId: '111' })
+    recordTurnStart(db, { turnKey: 'dm:live', chatId: '222' })
+    ageRow(db, 'dm:dead', now - 30 * 60_000)
+    ageRow(db, 'dm:live', now - 30 * 60_000)
+    const res = reapStaleOpenTurns(db, {
+      activeTurnKeys: new Set(['dm:live']),
+      ttlMs: 15 * 60_000,
+      now,
+    })
+    expect(res.reapedTurnKeys).toEqual(['dm:dead'])
+    expect(getTurnByKey(db, 'dm:dead')?.ended_via).toBe('restart')
+    expect(getTurnByKey(db, 'dm:live')?.ended_at).toBeNull()
+    db.close()
+  })
+
+  it('leaves already-ended rows alone (idempotent)', () => {
+    const db = openTurnsDbInMemory()
+    const now = 1_000_000_000_000
+    recordTurnStart(db, { turnKey: 'dm:done', chatId: '444' })
+    ageRow(db, 'dm:done', now - 30 * 60_000)
+    recordTurnEnd(db, { turnKey: 'dm:done', endedVia: 'stop' })
+    const res = reapStaleOpenTurns(db, {
+      activeTurnKeys: new Set<string>(),
+      ttlMs: 15 * 60_000,
+      now,
+    })
+    expect(res.reaped).toBe(0)
+    expect(getTurnByKey(db, 'dm:done')?.ended_via).toBe('stop')
+    db.close()
+  })
+})

package/telegram-plugin/registry/turns-schema.ts

@@ -497,6 +497,84 @@ export function markOrphanedWithTimeoutClassification(
   return { reaped: (timeoutTurnKey ? 1 : 0) + rest.changes, timeoutTurnKey }
 }
 
+export interface ReapStaleOpenTurnsOpts {
+  /**
+   * The set of turn_keys that belong to a turn still LIVE in this process's
+   * memory (the gateway's `currentTurnMap` registry keys plus the singleton
+   * `currentTurn` mirror). A row whose turn_key is in this set is NEVER
+   * reaped — it is a genuinely in-flight turn whose spinner must keep
+   * spinning, however long it runs. This is the load-bearing liveness
+   * predicate: age alone must never reap; only an open row with NO live
+   * owner qualifies.
+   */
+  activeTurnKeys: ReadonlySet<string>
+  /**
+   * Minimum age (ms, measured from `started_at`) before an ownerless open row
+   * is swept. A secondary guard against races — a turn that has JUST started
+   * but not yet populated the live set (or a row recorded microseconds ago) is
+   * protected until it ages past this. Liveness (activeTurnKeys) does the real
+   * work; the TTL only closes the "recorded-but-not-yet-tracked" window.
+   */
+  ttlMs: number
+  /** Injectable clock for tests. */
+  now?: number
+}
+
+export interface ReapStaleOpenTurnsResult {
+  /** Rows stamped `ended_via='restart'` by this sweep. */
+  reaped: number
+  /** The turn_keys that were stamped, for logging / card finalization. */
+  reapedTurnKeys: string[]
+}
+
+/**
+ * Mid-session periodic reaper (#2918). The boot-time
+ * `markOrphanedWithTimeoutClassification` only runs once, right after
+ * `openTurnsDb` — so a turn whose owning process dies MID-session (the SDK
+ * subprocess is SIGKILLed / OOMs / crashes) without a clean `recordTurnEnd`
+ * leaves its row `ended_at IS NULL`, and its activity card keeps spinning
+ * until the NEXT gateway boot (often many hours later). This sweep runs on a
+ * periodic timer inside the live gateway and stamps those ownerless open rows
+ * `ended_via='restart'` (the same clean-interrupt classification the boot
+ * reaper uses for a non-hung orphan) so the stale card can be finalized
+ * without waiting for a restart.
+ *
+ * CORRECTNESS: only rows that are BOTH (a) not owned by any live turn
+ * (`turn_key ∉ activeTurnKeys`) AND (b) older than `ttlMs` are swept. A
+ * healthy in-flight turn — however long it runs — is always in
+ * `activeTurnKeys` and is never touched. Never invents a new state; reuses
+ * `'restart'` so the existing resume/report policy applies unchanged.
+ */
+export function reapStaleOpenTurns(
+  db: SqliteDatabase,
+  opts: ReapStaleOpenTurnsOpts,
+): ReapStaleOpenTurnsResult {
+  const now = opts.now ?? Date.now()
+  const cutoff = now - opts.ttlMs
+  // Candidate = open row aged past the TTL. Liveness is filtered in JS against
+  // the injected active set (avoids brittle SQL IN-list binding).
+  const candidates = db.prepare(`
+    SELECT turn_key FROM turns
+    WHERE ended_at IS NULL AND started_at <= ?
+  `).all(cutoff) as { turn_key: string }[]
+
+  const stamp = db.prepare(`
+    UPDATE turns
+    SET ended_at   = ?,
+        ended_via  = 'restart',
+        updated_at = ?
+    WHERE turn_key = ? AND ended_at IS NULL
+  `)
+
+  const reapedTurnKeys: string[] = []
+  for (const { turn_key } of candidates) {
+    if (opts.activeTurnKeys.has(turn_key)) continue // live — never reap
+    const r = stamp.run(now, now, turn_key) as { changes: number }
+    if (r.changes > 0) reapedTurnKeys.push(turn_key)
+  }
+  return { reaped: reapedTurnKeys.length, reapedTurnKeys }
+}
+
 /**
  * Return the most recent N turns for `chatId` (any state — running or ended),
  * ordered by started_at DESC. Used by the idle-footer renderer to decide

package/telegram-plugin/render/ir.ts

@@ -0,0 +1,209 @@
+// Typed intermediate representation (IR) for the Telegram HTML render engine.
+//
+// This is the parser <-> renderer contract. `parse()` (parse.ts) folds an
+// mdast tree into this shape; a later increment's renderer walks it and emits
+// Telegram Bot API HTML. Increment 1 lands ONLY the parser + this IR — there
+// is no renderer yet.
+//
+// Every node carries `{ start, end }` UTF-16 source offsets copied verbatim
+// from mdast `position.start.offset` / `position.end.offset`. They are UTF-16
+// code-unit indices into the original markdown string, so
+// `source.slice(node.start, node.end)` round-trips to the node's source text.
+//
+// Telegram HTML tag mapping (for the next increment — NOT implemented here):
+//
+//   Inline
+//     plain     -> (raw text, HTML-escaped)
+//     bold      -> <b>…</b>                 (markdown `**…**`)
+//     italic    -> <i>…</i>                 (markdown `*…*`)
+//     underline -> <u>…</u>                 (markdown `__…__`, Bot API 10.1)
+//     strike    -> <s>…</s>                 (markdown `~~…~~`)
+//     spoiler   -> <tg-spoiler>…</tg-spoiler> (markdown `||…||`)
+//     highlight -> <mark>…</mark>           (markdown `==…==`, Bot API 10.1)
+//     code      -> <code>…</code>
+//     link      -> <a href="…">…</a>
+//
+//   Block
+//     paragraph      -> children joined; blocks separated by "\n\n"
+//     heading        -> <b>…</b> (Telegram HTML has no <h1>…<h6>; bold + newlines)
+//     blockquote     -> <blockquote>…</blockquote>
+//                       (expandable === true -> <blockquote expandable>)
+//     code-block     -> <pre><code class="language-…">…</code></pre>
+//     list           -> rendered line-per-item with "•"/"1." bullets
+//                       (Telegram HTML has no <ul>/<ol>)
+//     thematic-break -> a horizontal-rule text line (e.g. "───")
+//     table          -> monospaced <pre> table (Telegram HTML has no <table>)
+
+export interface Pos {
+  /** UTF-16 code-unit offset of the node's first char (mdast position.start.offset). */
+  start: number;
+  /** UTF-16 code-unit offset just past the node's last char (mdast position.end.offset). */
+  end: number;
+}
+
+// ---------------------------------------------------------------------------
+// Inline nodes
+// ---------------------------------------------------------------------------
+
+export interface PlainNode extends Pos {
+  type: "plain";
+  text: string;
+}
+
+export interface BoldNode extends Pos {
+  type: "bold";
+  children: Inline[];
+}
+
+export interface ItalicNode extends Pos {
+  type: "italic";
+  children: Inline[];
+}
+
+/** Telegram underline (<u>…</u>). In Bot API 10.1 rich markdown the `__…__`
+ *  double-underscore run is UNDERLINE — distinct from `**…**` bold, even though
+ *  GFM/micromark folds both into a single `strong` mdast node. `parse.ts`
+ *  disambiguates the two by looking at the run's source delimiter. */
+export interface UnderlineNode extends Pos {
+  type: "underline";
+  children: Inline[];
+}
+
+export interface StrikeNode extends Pos {
+  type: "strike";
+  children: Inline[];
+}
+
+/** Telegram spoiler (<tg-spoiler>…</tg-spoiler>), markdown `||…||`. GFM has no
+ *  spoiler syntax, so `parse.ts` recognises the `||…||` delimiter in a
+ *  post-parse pass over `plain` text. */
+export interface SpoilerNode extends Pos {
+  type: "spoiler";
+  children: Inline[];
+}
+
+/** Telegram highlight / marked text (<mark>…</mark>), markdown `==…==` (Bot API
+ *  10.1). Like spoiler, recognised by `parse.ts` in a post-parse pass over
+ *  `plain` text (GFM has no highlight syntax). */
+export interface HighlightNode extends Pos {
+  type: "highlight";
+  children: Inline[];
+}
+
+export interface CodeNode extends Pos {
+  type: "code";
+  text: string;
+}
+
+export interface LinkNode extends Pos {
+  type: "link";
+  href: string;
+  children: Inline[];
+}
+
+export type Inline =
+  | PlainNode
+  | BoldNode
+  | ItalicNode
+  | UnderlineNode
+  | StrikeNode
+  | SpoilerNode
+  | HighlightNode
+  | CodeNode
+  | LinkNode;
+
+// ---------------------------------------------------------------------------
+// Block nodes
+// ---------------------------------------------------------------------------
+
+export interface ParagraphNode extends Pos {
+  type: "paragraph";
+  children: Inline[];
+}
+
+export interface HeadingNode extends Pos {
+  type: "heading";
+  /** 1..6 */
+  level: number;
+  children: Inline[];
+}
+
+export interface BlockquoteNode extends Pos {
+  type: "blockquote";
+  children: Block[];
+  /** Telegram <blockquote expandable>. Always false in Increment 1 — see parse.ts. */
+  expandable: boolean;
+}
+
+export interface CodeBlockNode extends Pos {
+  type: "code-block";
+  text: string;
+  language: string | null;
+}
+
+export interface ListNode extends Pos {
+  type: "list";
+  ordered: boolean;
+  // NOTE: the spec names this ordinal `start`, but every node already carries
+  // `start`/`end` UTF-16 offsets (load-bearing for round-trip slicing). To
+  // avoid the collision the ordered-list ordinal is `startNumber` here; its
+  // semantics match the spec's `list.start` exactly (mdast `list.start`).
+  /** First number of an ordered list (mdast `start`); null for unordered. */
+  startNumber: number | null;
+  /** Loose vs tight (mdast `list.spread`). A LOOSE list separates its items
+   *  with a blank line in the source; a TIGHT list keeps them on adjacent
+   *  lines. The renderer preserves this: loose lists join items with a blank
+   *  line, tight lists (including nested sub-lists) stay on single newlines so
+   *  no spurious blank line is injected between a tight item and its sub-list. */
+  spread: boolean;
+  items: ListItem[];
+}
+
+export interface ThematicBreakNode extends Pos {
+  type: "thematic-break";
+}
+
+export interface TableNode extends Pos {
+  type: "table";
+  header: TableRow;
+  rows: TableRow[];
+  /** Per-column alignment, parallel to the cells. */
+  align: ("left" | "center" | "right" | null)[];
+}
+
+export type Block =
+  | ParagraphNode
+  | HeadingNode
+  | BlockquoteNode
+  | CodeBlockNode
+  | ListNode
+  | ThematicBreakNode
+  | TableNode;
+
+// ---------------------------------------------------------------------------
+// Composite / container shapes
+// ---------------------------------------------------------------------------
+
+export interface ListItem extends Pos {
+  children: Block[];
+  /** GFM task-list state: true (checked), false (unchecked), null (not a task item). */
+  checked: boolean | null;
+  /** Loose vs tight at the ITEM level (mdast `listItem.spread`): whether this
+   *  item's own block children are separated by a blank line in the source.
+   *  A tight item (spread=false) — e.g. a paragraph followed by a nested
+   *  sub-list — keeps its children on single newlines, so no blank line is
+   *  injected before the sub-list. */
+  spread: boolean;
+}
+
+export interface TableRow extends Pos {
+  cells: TableCell[];
+}
+
+export interface TableCell extends Pos {
+  children: Inline[];
+}
+
+export interface Document {
+  blocks: Block[];
+}