typeclaw 0.20.0 → 0.22.0

package/src/cli/ui.ts

@@ -7,6 +7,28 @@ import { type AutoUpgradeOutcome, describeAutoUpgrade } from '@/init/auto-upgrad
 
 export { cancel, intro, isCancel, log, note, outro }
 
+type ClackInput = Pick<NodeJS.ReadStream, 'isTTY' | 'setRawMode' | 'resume'>
+
+// Hand stdin to a clack picker in a state it can own. Over an SSH pseudo-TTY,
+// Bun's readline keypress wiring only transitions stdin into flowing raw mode
+// reliably once the stream has already been resumed; on a never-resumed stdin
+// the picker renders but arrow keys echo as raw `^[[B` and never advance it.
+// Local terminals dodge this because stdin was already flowing. So before every
+// picker: clear any stale raw mode for a clean baseline, then resume the stream.
+// Never pause() here — a previously-paused process.stdin does not reliably
+// re-flow under Bun, which is the same failure this resume() is fixing.
+export function prepareStdinForClack(input: ClackInput = process.stdin): void {
+  if (!input.isTTY) return
+  if (typeof input.setRawMode === 'function') {
+    try {
+      input.setRawMode(false)
+    } catch {
+      /* terminal already torn down */
+    }
+  }
+  input.resume()
+}
+
 function colorize(modifier: Parameters<typeof styleText>[0], s: string): string {
   if (!colorsEnabled()) return s
   return styleText(modifier, s)
@@ -169,6 +191,18 @@ export const SLACK_APP_MANIFEST = {
         url: 'https://example.invalid/typeclaw-uses-socket-mode',
         should_escape: false,
       },
+      {
+        command: '/reload',
+        description: 'Reload typeclaw config and subsystems from disk',
+        url: 'https://example.invalid/typeclaw-uses-socket-mode',
+        should_escape: false,
+      },
+      {
+        command: '/restart',
+        description: 'Restart the typeclaw container',
+        url: 'https://example.invalid/typeclaw-uses-socket-mode',
+        should_escape: false,
+      },
     ],
   },
   oauth_config: {

package/src/commands/index.ts

@@ -13,8 +13,11 @@ export type CommandHandler<Context> = (
 // dispatcher, so a new command declares its own requirements in one place:
 // 'session.control' + requiresLiveSession:true is the control-command default
 // (/stop); 'none' + requiresLiveSession:false is the informational default
-// (/help). Both are optional so plain registries (tests, TUI) need not care.
-export type CommandPermission = 'none' | 'session.control'
+// (/help). 'session.admin' + requiresLiveSession:false is the operate-the-agent
+// tier (/reload, /restart) — owner+trusted only, no live session required since
+// it acts on the container, not a channel turn. Both are optional so plain
+// registries (tests, TUI) need not care.
+export type CommandPermission = 'none' | 'session.control' | 'session.admin'
 
 export type Command<Context> = {
   name: string

package/src/config/config.ts

@@ -8,6 +8,7 @@ import { z } from 'zod'
 import { channelsSchema } from '@/channels/schema'
 import { commitSystemFileSync } from '@/git/system-commit'
 import { rolesConfigSchema } from '@/permissions/schema'
+import { secretFieldSchema } from '@/secrets/resolve'
 
 import {
   DEFAULT_MODEL_REF,
@@ -30,6 +31,30 @@ const DEFAULT_PORT = 8973
 // of files like `mounts/.git` or `mounts/Hello`.
 const MOUNT_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]*$/
 
+// Shell-portable env var identifier: a leading letter or underscore followed by
+// letters, digits, or underscores. MCP `env` keys are passed verbatim to a child
+// process environment, so an invalid identifier (spaces, `=`, leading digit)
+// would be silently dropped or corrupt the spawned server's env.
+const ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+// Upper bound for a per-server MCP request timeout: 10 minutes. Long-running
+// MCP tools (large crawls, builds) can legitimately take minutes, but a ceiling
+// guards against fat-finger values that would re-introduce the unbounded-hang
+// failure mode the explicit timeouts exist to prevent.
+const MCP_MAX_TIMEOUT_MS = 600_000
+
+// URL schemes are case-insensitive (RFC 3986), and the WHATWG parser normalizes
+// `.protocol` to lowercase. Checking the parsed protocol instead of a raw
+// `startsWith` keeps `HTTPS://…` valid, which `z.string().url()` already accepts.
+function isHttpProtocol(value: string): boolean {
+  try {
+    const protocol = new URL(value).protocol
+    return protocol === 'http:' || protocol === 'https:'
+  } catch {
+    return false
+  }
+}
+
 export const mountSchema = z.object({
   name: z.string().regex(MOUNT_NAME_PATTERN, 'mount name must be lowercase alphanumeric with - or _'),
   path: z.string().min(1),
@@ -39,6 +64,66 @@ export const mountSchema = z.object({
 
 export type Mount = z.infer<typeof mountSchema>
 
+// MCP servers are keyed by the same shell/disk-safe namespace as mounts because
+// the name becomes the tool namespace exposed to the agent. The transport is an
+// XOR on purpose: stdio servers are child processes (`command` + `args` + env),
+// while Streamable HTTP servers are remote endpoints (`url`); accepting both
+// would make ownership, lifetime, and credential injection ambiguous at boot.
+export const mcpServerSchema = z
+  .object({
+    name: z
+      .string()
+      .regex(MOUNT_NAME_PATTERN, 'MCP server name must be lowercase alphanumeric with - or _')
+      .refine((name) => !name.includes('__'), {
+        message: "MCP server name must not contain '__' (reserved as the tool-namespace separator)",
+      }),
+    description: z.string().optional(),
+    // Default true so omitting the field keeps the server on; set false to keep config but skip connecting.
+    enabled: z.boolean().default(true),
+    timeoutMs: z.number().int().positive().max(MCP_MAX_TIMEOUT_MS).optional(),
+    command: z.string().trim().min(1).optional(),
+    args: z.array(z.string()).default([]),
+    url: z
+      .string()
+      .url()
+      .refine((u) => isHttpProtocol(u), {
+        message: 'MCP server url must use http:// or https://',
+      })
+      .optional(),
+    env: z
+      .record(z.string().regex(ENV_NAME_PATTERN, 'env var name must be a valid identifier'), secretFieldSchema)
+      .default({}),
+  })
+  .refine((server) => (server.command !== undefined) !== (server.url !== undefined), {
+    message: 'MCP server must be either stdio (command) or http (url), not both or neither',
+  })
+
+export type McpServer = z.infer<typeof mcpServerSchema>
+
+// The name becomes the `<server>__<tool>` namespace at dispatch, so duplicates
+// would make tool lookup ambiguous and silently shadow one server behind
+// another. Reject them with an indexed path so the error points at the
+// offending entry instead of the whole array.
+const mcpServersArraySchema = z
+  .array(mcpServerSchema)
+  .default([])
+  .superRefine((entries, ctx) => {
+    const seen = new Map<string, number>()
+    for (let i = 0; i < entries.length; i++) {
+      const name = entries[i]!.name
+      const prev = seen.get(name)
+      if (prev !== undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [i, 'name'],
+          message: `mcpServers[${i}].name duplicates mcpServers[${prev}].name ('${name}')`,
+        })
+      } else {
+        seen.set(name, i)
+      }
+    }
+  })
+
 const portNumber = z.number().int().min(1).max(65535)
 
 // `allow` is the discriminator between "forward everything" ('*') and a fixed
@@ -391,6 +476,7 @@ export const configSchema = z
     // host paths exposed) without failing the whole config load. `typeclaw
     // init` omits this field so users don't see noise for the empty case.
     mounts: z.array(mountSchema).default([]),
+    mcpServers: mcpServersArraySchema,
     plugins: z.array(z.string().min(1)).default([]),
     // Additional names the agent answers to in channel engagement, on top
     // of `basename(agentDir)` which is always implicit. Each entry is a
@@ -538,6 +624,7 @@ export const FIELD_EFFECTS: Record<string, FieldEffect> = {
   models: 'applied',
   port: 'restart-required',
   mounts: 'restart-required',
+  mcpServers: 'restart-required',
   plugins: 'restart-required',
   alias: 'applied',
   channels: 'applied',
@@ -638,6 +725,8 @@ export function extractPluginConfigs(raw: unknown): Record<string, unknown> {
     'git',
     'roles',
     'permissions',
+    'tunnels',
+    'mcpServers',
   ])
   const result: Record<string, unknown> = {}
   for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {

package/src/dreams/git.ts

@@ -0,0 +1,85 @@
+export type GitResult = { exitCode: number; stdout: string; stderr: string }
+export type SpawnGit = (args: string[], cwd: string) => Promise<GitResult>
+
+export type RawCommit = {
+  sha: string
+  shortSha: string
+  committedAt: string
+  subject: string
+}
+
+export type ResolveRepoResult = { ok: true; root: string } | { ok: false; reason: 'not-a-repo' | 'git-failed' }
+
+const FIELD_SEP = '\x1f'
+const RECORD_SEP = '\x1e'
+
+export async function resolveGitRepo(cwd: string, spawnGit: SpawnGit = defaultSpawnGit): Promise<ResolveRepoResult> {
+  const res = await spawnGit(['rev-parse', '--show-toplevel'], cwd)
+  if (res.exitCode === 0) {
+    const root = res.stdout.trim()
+    if (root.length > 0) return { ok: true, root }
+    return { ok: false, reason: 'git-failed' }
+  }
+  if (/not a git repository/i.test(res.stderr)) return { ok: false, reason: 'not-a-repo' }
+  return { ok: false, reason: 'git-failed' }
+}
+
+const DREAM_SUBJECT_PREFIX = 'dream: '
+
+export async function readDreamCommitLog(
+  root: string,
+  opts: { limit?: number } = {},
+  spawnGit: SpawnGit = defaultSpawnGit,
+): Promise<RawCommit[]> {
+  // --grep is only a cheap pre-filter: it matches ANY line of the commit
+  // message, so a non-dream commit with a `dream: ...` body line slips
+  // through. The subject is the authoritative contract, so the prefix filter
+  // below is what actually decides membership — and the limit is applied
+  // AFTER it so body-matching impostors can't consume a slot and shrink the
+  // result below the requested count.
+  const args = ['log', '--grep=^dream: ', `--format=%H${FIELD_SEP}%h${FIELD_SEP}%cI${FIELD_SEP}%s${RECORD_SEP}`]
+
+  const res = await spawnGit(args, root)
+  if (res.exitCode !== 0) return []
+  const dreams = parseLogOutput(res.stdout).filter((c) => c.subject.startsWith(DREAM_SUBJECT_PREFIX))
+  if (opts.limit !== undefined && opts.limit > 0) return dreams.slice(0, opts.limit)
+  return dreams
+}
+
+export function parseLogOutput(stdout: string): RawCommit[] {
+  const commits: RawCommit[] = []
+  for (const record of stdout.split(RECORD_SEP)) {
+    const trimmed = record.replace(/^\n+/, '')
+    if (trimmed.length === 0) continue
+    const [sha, shortSha, committedAt, subject] = trimmed.split(FIELD_SEP)
+    if (sha === undefined || shortSha === undefined || committedAt === undefined || subject === undefined) continue
+    commits.push({ sha, shortSha, committedAt, subject })
+  }
+  return commits
+}
+
+export async function readDreamCommitShow(
+  root: string,
+  sha: string,
+  spawnGit: SpawnGit = defaultSpawnGit,
+): Promise<{ nameStatus: string; patch: string } | null> {
+  const nameStatus = await spawnGit(['show', '--no-color', '--find-renames', '--format=', '--name-status', sha], root)
+  if (nameStatus.exitCode !== 0) return null
+  const patch = await spawnGit(['show', '--no-color', '--format=', '--unified=0', sha], root)
+  if (patch.exitCode !== 0) return null
+  return { nameStatus: nameStatus.stdout, patch: patch.stdout }
+}
+
+const defaultSpawnGit: SpawnGit = async (args, cwd) => {
+  const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
+  if (!bun) return { exitCode: -1, stdout: '', stderr: 'bun runtime not available' }
+  try {
+    const proc = bun.spawn({ cmd: ['git', ...args], cwd, stdout: 'pipe', stderr: 'pipe' })
+    const exitCode = await proc.exited
+    const stdout = await new Response(proc.stdout).text()
+    const stderr = await new Response(proc.stderr).text()
+    return { exitCode, stdout, stderr }
+  } catch (err) {
+    return { exitCode: -1, stdout: '', stderr: err instanceof Error ? err.message : String(err) }
+  }
+}

package/src/dreams/index.ts

@@ -0,0 +1,134 @@
+import { readDreamCommitLog, readDreamCommitShow, resolveGitRepo, type SpawnGit } from './git'
+import { parseDreamDetail, parseDreamSubject } from './parse'
+import { renderDetail, renderListRow, type RenderOptions, toJsonShape } from './render'
+import type { DreamEntry } from './types'
+
+export type { SpawnGit } from './git'
+export type { DreamEntry } from './types'
+export { renderDetail, renderListRow, toJsonShape } from './render'
+export { parseDreamDetail, parseDreamSubject } from './parse'
+
+export type SelectDreamOptions = {
+  initialSha?: string
+}
+
+export type SelectDream = (entries: DreamEntry[], opts?: SelectDreamOptions) => Promise<DreamEntry | null>
+
+// 'back' re-opens the picker with the just-viewed dream pre-selected.
+export type ViewAction = 'back' | 'exit'
+export type ViewDream = () => Promise<ViewAction>
+
+export type RunDreamsOptions = {
+  agentDir: string
+  json: boolean
+  details: boolean
+  color: boolean
+  limit?: number
+  selectDream: SelectDream
+  viewDream?: ViewDream
+  stdout: (line: string) => void
+  spawnGit?: SpawnGit
+}
+
+export type RunDreamsResult = { ok: true; exitCode: 0 } | { ok: false; exitCode: number; reason: string }
+
+export async function listDreams(
+  agentDir: string,
+  opts: { limit?: number } = {},
+  spawnGit?: SpawnGit,
+): Promise<DreamEntry[]> {
+  const repo = await resolveGitRepo(agentDir, spawnGit)
+  if (!repo.ok) return []
+  const commits = await readDreamCommitLog(repo.root, opts.limit !== undefined ? { limit: opts.limit } : {}, spawnGit)
+  return commits.map((commit) => {
+    const subject = parseDreamSubject(commit.subject)
+    return {
+      sha: commit.sha,
+      shortSha: commit.shortSha,
+      subject: commit.subject,
+      committedAt: commit.committedAt,
+      isDreamCommit: subject.isDreamCommit,
+      summary: subject.summary,
+      emoji: subject.emoji,
+      categories: subject.categories,
+    }
+  })
+}
+
+export async function hydrateDream(agentDir: string, entry: DreamEntry, spawnGit?: SpawnGit): Promise<DreamEntry> {
+  const repo = await resolveGitRepo(agentDir, spawnGit)
+  if (!repo.ok) return entry
+  const show = await readDreamCommitShow(repo.root, entry.sha, spawnGit)
+  if (show === null) return entry
+  return { ...entry, detail: parseDreamDetail(show.nameStatus, show.patch) }
+}
+
+export async function runDreams(opts: RunDreamsOptions): Promise<RunDreamsResult> {
+  const repo = await resolveGitRepo(opts.agentDir, opts.spawnGit)
+  if (!repo.ok) {
+    if (repo.reason === 'not-a-repo') {
+      return {
+        ok: false,
+        exitCode: 1,
+        reason:
+          "Not a git repository. Dreams live in the agent folder's git history — run this from your agent folder.",
+      }
+    }
+    return { ok: false, exitCode: 1, reason: 'git failed while resolving the repository root.' }
+  }
+
+  const entries = await listDreams(opts.agentDir, opts.limit !== undefined ? { limit: opts.limit } : {}, opts.spawnGit)
+  const renderOpts: RenderOptions = { color: opts.color }
+
+  if (opts.json) return runJson(opts, repo.root, entries)
+
+  if (entries.length === 0) {
+    opts.stdout('No dreams yet. The dreaming subagent commits here after it consolidates memory.')
+    return { ok: true, exitCode: 0 }
+  }
+
+  if (!isInteractive()) {
+    for (const entry of entries) opts.stdout(renderListRow(entry, renderOpts))
+    return { ok: true, exitCode: 0 }
+  }
+
+  return runInteractiveLoop(opts, entries, renderOpts)
+}
+
+async function runInteractiveLoop(
+  opts: RunDreamsOptions,
+  entries: DreamEntry[],
+  renderOpts: RenderOptions,
+): Promise<RunDreamsResult> {
+  let initialSha: string | undefined
+  while (true) {
+    const picked = await opts.selectDream(entries, initialSha !== undefined ? { initialSha } : {})
+    if (picked === null) return { ok: true, exitCode: 0 }
+    initialSha = picked.sha
+
+    const hydrated = await hydrateDream(opts.agentDir, picked, opts.spawnGit)
+    opts.stdout(renderDetail(hydrated, renderOpts))
+
+    if (opts.viewDream === undefined) return { ok: true, exitCode: 0 }
+    const action = await opts.viewDream()
+    if (action === 'exit') return { ok: true, exitCode: 0 }
+  }
+}
+
+async function runJson(opts: RunDreamsOptions, root: string, entries: DreamEntry[]): Promise<RunDreamsResult> {
+  for (const entry of entries) {
+    const final = opts.details ? await hydrateEntryFromRoot(root, entry, opts.spawnGit) : entry
+    opts.stdout(JSON.stringify(toJsonShape(final)))
+  }
+  return { ok: true, exitCode: 0 }
+}
+
+async function hydrateEntryFromRoot(root: string, entry: DreamEntry, spawnGit?: SpawnGit): Promise<DreamEntry> {
+  const show = await readDreamCommitShow(root, entry.sha, spawnGit)
+  if (show === null) return entry
+  return { ...entry, detail: parseDreamDetail(show.nameStatus, show.patch) }
+}
+
+function isInteractive(): boolean {
+  return Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY)
+}

package/src/dreams/parse.ts

@@ -0,0 +1,224 @@
+import {
+  type DreamCategory,
+  type DreamEmoji,
+  DREAM_EMOJI_POOL,
+  type DreamEntryDetail,
+  type FragmentEventSummary,
+  type ShardChangeStatus,
+  type SkillCreation,
+  type TopicShardChange,
+} from './types'
+
+const BODY_PREVIEW_MAX = 80
+const EMOJI_SET = new Set<string>(DREAM_EMOJI_POOL)
+const STREAM_PATH = /^memory\/(?:streams\/)?(\d{4}-\d{2}-\d{2})\.jsonl$/
+const TOPIC_PATH = /^memory\/topics\/(.+)\.md$/
+const SKILL_PATH = /^memory\/skills\/([^/]+)\/SKILL\.md$/
+const STATE_PATH = 'memory/.dreaming-state.json'
+
+export type DreamSubject = {
+  isDreamCommit: boolean
+  summary: string | null
+  emoji: DreamEmoji | null
+  categories: DreamCategory[]
+}
+
+export function parseDreamSubject(subject: string): DreamSubject {
+  const match = /^dream:\s+(.*)$/.exec(subject)
+  if (match === null) {
+    return { isDreamCommit: false, summary: null, emoji: null, categories: [] }
+  }
+
+  const rest = (match[1] ?? '').trim()
+  const { summary, emoji } = splitTrailingEmoji(rest)
+  return {
+    isDreamCommit: true,
+    summary: summary.length > 0 ? summary : null,
+    emoji,
+    categories: classifySummary(summary),
+  }
+}
+
+function splitTrailingEmoji(rest: string): { summary: string; emoji: DreamEmoji | null } {
+  const chars = [...rest]
+  const last = chars.at(-1)
+  if (last !== undefined && EMOJI_SET.has(last)) {
+    return { summary: chars.slice(0, -1).join('').trim(), emoji: last as DreamEmoji }
+  }
+  return { summary: rest, emoji: null }
+}
+
+function classifySummary(summary: string): DreamCategory[] {
+  const categories: DreamCategory[] = []
+  if (/\bfragments?\b/.test(summary)) categories.push('fragments')
+  if (/\bskills?\b/.test(summary)) categories.push('skills')
+  if (/watermarks only/.test(summary)) categories.push('watermarks-only')
+  if (/^snapshot$/.test(summary)) categories.push('snapshot')
+  if (categories.length === 0) categories.push('other')
+  return categories
+}
+
+export function parseDreamDetail(nameStatus: string, patch: string): DreamEntryDetail {
+  const warnings: string[] = []
+  const changedTopics: TopicShardChange[] = []
+  const createdSkills: SkillCreation[] = []
+  let stateChanged = false
+
+  for (const { status, path, oldPath } of parseNameStatus(nameStatus)) {
+    if (path === STATE_PATH || oldPath === STATE_PATH) {
+      stateChanged = true
+      continue
+    }
+    const topic = TOPIC_PATH.exec(path)
+    if (topic !== null) {
+      changedTopics.push({ path, slug: topic[1] ?? path, status, additions: null, deletions: null })
+      continue
+    }
+    if (status === 'added') {
+      const skill = SKILL_PATH.exec(path)
+      if (skill !== null) createdSkills.push({ name: skill[1] ?? '', path })
+    }
+  }
+
+  applyTopicLineCounts(changedTopics, patch, warnings)
+  const addedFragments = extractAddedFragments(patch, warnings)
+
+  return { addedFragments, changedTopics, createdSkills, stateChanged, parseWarnings: warnings }
+}
+
+type NameStatusRow = { status: ShardChangeStatus; path: string; oldPath: string | null }
+
+function parseNameStatus(nameStatus: string): NameStatusRow[] {
+  const rows: NameStatusRow[] = []
+  for (const line of nameStatus.split('\n')) {
+    if (line.trim().length === 0) continue
+    const cols = line.split('\t')
+    const code = cols[0] ?? ''
+    if (code.startsWith('R')) {
+      const oldPath = cols[1] ?? ''
+      const newPath = cols[2] ?? ''
+      if (newPath.length > 0) rows.push({ status: 'renamed', path: newPath, oldPath })
+      continue
+    }
+    const path = cols[1] ?? ''
+    if (path.length === 0) continue
+    rows.push({ status: mapStatusCode(code), path, oldPath: null })
+  }
+  return rows
+}
+
+function mapStatusCode(code: string): ShardChangeStatus {
+  const c = code.charAt(0)
+  if (c === 'A') return 'added'
+  if (c === 'M') return 'modified'
+  if (c === 'D') return 'deleted'
+  if (c === 'R') return 'renamed'
+  return 'unknown'
+}
+
+type ParsedHunk = { path: string; addedLines: string[] }
+
+function* iterateHunks(patch: string): Generator<ParsedHunk> {
+  let currentPath: string | null = null
+  let added: string[] = []
+  const flush = function* (): Generator<ParsedHunk> {
+    if (currentPath !== null) yield { path: currentPath, addedLines: added }
+  }
+
+  for (const line of patch.split('\n')) {
+    if (line.startsWith('diff --git ')) {
+      yield* flush()
+      currentPath = null
+      added = []
+      continue
+    }
+    if (line.startsWith('+++ ')) {
+      currentPath = stripDiffPathPrefix(line.slice(4))
+      continue
+    }
+    if (line.startsWith('+') && !line.startsWith('+++')) {
+      added.push(line.slice(1))
+    }
+  }
+  yield* flush()
+}
+
+function stripDiffPathPrefix(raw: string): string {
+  const trimmed = raw.trim()
+  if (trimmed === '/dev/null') return trimmed
+  return trimmed.replace(/^b\//, '')
+}
+
+function extractAddedFragments(patch: string, warnings: string[]): FragmentEventSummary[] {
+  const out: FragmentEventSummary[] = []
+  for (const hunk of iterateHunks(patch)) {
+    const streamMatch = STREAM_PATH.exec(hunk.path)
+    if (streamMatch === null) continue
+    const streamDate = streamMatch[1] ?? null
+    for (const line of hunk.addedLines) {
+      if (line.trim().length === 0) continue
+      const fragment = parseFragmentLine(line, streamDate)
+      if (fragment === null) {
+        warnings.push(`unparseable stream line in ${hunk.path}`)
+        continue
+      }
+      if (fragment !== 'skip') out.push(fragment)
+    }
+  }
+  return out
+}
+
+function parseFragmentLine(line: string, streamDate: string | null): FragmentEventSummary | 'skip' | null {
+  let raw: unknown
+  try {
+    raw = JSON.parse(line)
+  } catch {
+    return null
+  }
+  if (typeof raw !== 'object' || raw === null) return null
+  const obj = raw as Record<string, unknown>
+  if (obj.type !== 'fragment') return 'skip'
+  if (typeof obj.id !== 'string' || obj.id.length === 0) return null
+  return {
+    id: obj.id,
+    streamDate,
+    topic: typeof obj.topic === 'string' ? obj.topic : null,
+    bodyPreview: typeof obj.body === 'string' ? preview(obj.body) : null,
+  }
+}
+
+function applyTopicLineCounts(topics: TopicShardChange[], patch: string, warnings: string[]): void {
+  if (topics.length === 0) return
+  const counts = new Map<string, { additions: number; deletions: number }>()
+  let currentPath: string | null = null
+
+  for (const line of patch.split('\n')) {
+    if (line.startsWith('+++ ')) {
+      currentPath = stripDiffPathPrefix(line.slice(4))
+      if (currentPath !== null && !counts.has(currentPath)) counts.set(currentPath, { additions: 0, deletions: 0 })
+      continue
+    }
+    if (currentPath === null) continue
+    const bucket = counts.get(currentPath)
+    if (bucket === undefined) continue
+    if (line.startsWith('+') && !line.startsWith('+++')) bucket.additions++
+    else if (line.startsWith('-') && !line.startsWith('---')) bucket.deletions++
+  }
+
+  for (const topic of topics) {
+    if (topic.status === 'deleted') continue
+    const bucket = counts.get(topic.path)
+    if (bucket === undefined) {
+      if (topic.status === 'modified') warnings.push(`no diff hunk for modified topic ${topic.path}`)
+      continue
+    }
+    topic.additions = bucket.additions
+    topic.deletions = bucket.deletions
+  }
+}
+
+function preview(body: string): string {
+  const oneline = body.replace(/\s+/g, ' ').trim()
+  if (oneline.length <= BODY_PREVIEW_MAX) return oneline
+  return `${oneline.slice(0, BODY_PREVIEW_MAX)}…`
+}