typeclaw 0.20.0 → 0.21.0

package/src/channels/router.ts

@@ -51,6 +51,8 @@ import type {
   HistoryCallback,
   InboundAttachment,
   InboundMessage,
+  RemoveReactionCallback,
+  RemoveReactionRequest,
   OutboundCallback,
   OutboundMessage,
   QuoteAnchorSource,
@@ -282,6 +284,7 @@ type QueuedInbound = {
   authorIsBot: boolean
   externalMessageId: string
   reactionRef?: ReactionRef
+  engageReaction?: Promise<ReactionRef | null>
   isBotMention: boolean
   replyToBotMessageId: string | null
   isDm: boolean
@@ -353,6 +356,11 @@ type LiveSession = {
   // origin so `channel_react` reacts to the triggering message, not whichever
   // inbound happens to be latest in the queue. Null on reminder-only turns.
   currentTurnReactionRef: ReactionRef | null
+  // One engage-:eyes:-add promise per inbound coalesced into THIS turn, each
+  // resolving to its removable per-instance ref (or null). A debounced turn can
+  // batch several inbounds that each got their own :eyes:, so every entry is
+  // removed after the reply. Empty on turns with no reactable inbound.
+  currentTurnEngageReactions: Array<Promise<ReactionRef | null>>
   lastTurnAuthorIds: Set<string>
   // Mirror of currentTurnAuthorId at end-of-turn (the LAST speaker of the
   // prior batch), preserved across the drain finally-block which resets
@@ -538,6 +546,9 @@ export type ChannelRouter = {
   registerReaction: (adapter: ChannelKey['adapter'], cb: ReactionCallback) => void
   unregisterReaction: (adapter: ChannelKey['adapter'], cb: ReactionCallback) => void
   react: (req: ReactionRequest) => Promise<ReactionResult>
+  registerRemoveReaction: (adapter: ChannelKey['adapter'], cb: RemoveReactionCallback) => void
+  unregisterRemoveReaction: (adapter: ChannelKey['adapter'], cb: RemoveReactionCallback) => void
+  removeReaction: (req: RemoveReactionRequest) => Promise<ReactionResult>
   registerTyping: (adapter: ChannelKey['adapter'], cb: TypingCallback) => void
   unregisterTyping: (adapter: ChannelKey['adapter'], cb: TypingCallback) => void
   registerChannelNameResolver: (adapter: ChannelKey['adapter'], resolver: ChannelNameResolver) => void
@@ -757,6 +768,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   let liveGeneration = 0
   const outboundCallbacks = new Map<ChannelKey['adapter'], Set<OutboundCallback>>()
   const reactionCallbacks = new Map<ChannelKey['adapter'], Set<ReactionCallback>>()
+  const removeReactionCallbacks = new Map<ChannelKey['adapter'], Set<RemoveReactionCallback>>()
   const typingCallbacks = new Map<ChannelKey['adapter'], Set<TypingCallback>>()
   const channelNameResolvers = new Map<ChannelKey['adapter'], Set<ChannelNameResolver>>()
   const membershipResolvers = new Map<ChannelKey['adapter'], Set<MembershipResolver>>()
@@ -1122,6 +1134,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         currentTurnAuthorId: null,
         currentTurnAuthorIds: new Set(),
         currentTurnReactionRef: null,
+        currentTurnEngageReactions: [],
         // `lastTurnAuthorId` (string, used for `lastInboundAuthorId` in
         // origin) and `lastTurnAuthorIds` (Set, used by
         // `grantStickyForReplyTargets` as the fallback when
@@ -1254,6 +1267,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           receivedAt: now(),
           ts: item.message.ts,
           source: 'prefetch',
+          ...(item.message.attachments !== undefined ? { attachments: item.message.attachments } : {}),
         })
       } else {
         observed.push({
@@ -1532,10 +1546,14 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           live.currentTurnAuthorId = batch[batch.length - 1]!.authorId
           live.currentTurnAuthorIds = new Set(batch.map((m) => m.authorId))
           live.currentTurnReactionRef = batch[batch.length - 1]!.reactionRef ?? null
+          live.currentTurnEngageReactions = batch.flatMap((m) =>
+            m.engageReaction !== undefined ? [m.engageReaction] : [],
+          )
           live.consecutiveSends.clear()
           live.lastSentText.clear()
           live.pendingQuoteCandidate = captureQuoteCandidate(live.key.adapter, batch, observed)
         } else if (live.lastTurnAuthorId !== null) {
+          live.currentTurnEngageReactions = []
           // Reminder-only turn (batch.length === 0, reminders.length > 0):
           // restore the author identity from the prior turn so author-
           // scoped role resolution still works on this turn. The drain
@@ -1550,6 +1568,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           // author prior turn like alice→bob restores `bob`, not alice.
           live.currentTurnAuthorId = live.lastTurnAuthorId
           live.currentTurnAuthorIds = new Set(live.lastTurnAuthorIds)
+        } else {
+          live.currentTurnEngageReactions = []
         }
 
         // Update the live origin holder so this turn's tool.before events
@@ -1576,6 +1596,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         logger.info(`[channels] ${live.keyId} prompting batch=${batch.length} text_len=${text.length}`)
         const promptStart = now()
         const successfulSendsBeforePrompt = live.successfulChannelSends
+        const engageAddPromises = live.currentTurnEngageReactions
         live.turnSeq++
         live.successfulSendsAtTurnStart = successfulSendsBeforePrompt
         live.policyDeniedToolSendsThisTurn.clear()
@@ -1590,6 +1611,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           live.consecutiveSends.clear()
           live.lastSentText.clear()
         } finally {
+          const sentReplyThisTurn = live.successfulChannelSends > successfulSendsBeforePrompt
+          if (sentReplyThisTurn) dropEngageReactionsAfterReply(live, engageAddPromises)
           await fireSessionTurnEnd(live)
         }
         await fireSessionIdle(live)
@@ -1603,6 +1626,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       live.currentTurnAuthorId = null
       live.currentTurnAuthorIds = new Set()
       live.currentTurnReactionRef = null
+      live.currentTurnEngageReactions = []
       live.currentTurnAttachments = []
       await stopTypingHeartbeat(live)
     }
@@ -1852,11 +1876,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
     publishInbound(event, 'engage', live.sessionId)
 
-    autoReactOnEngage(event)
+    const engageReaction = autoReactOnEngage(event)
 
     updateLoopGuard(live, event)
 
-    enqueue(live, event)
+    enqueue(live, event, engageReaction)
 
     // Start showing "typing..." the moment we know we're going to engage,
     // so users see the indicator during the debounce window — not just
@@ -1938,7 +1962,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
   }
 
-  const enqueue = (live: LiveSession, event: InboundMessage): void => {
+  const enqueue = (
+    live: LiveSession,
+    event: InboundMessage,
+    engageReaction: Promise<ReactionRef | null> | null,
+  ): void => {
     live.promptQueue.push({
       text: event.text,
       ...(event.attachments !== undefined && event.attachments.length > 0 ? { attachments: event.attachments } : {}),
@@ -1947,6 +1975,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       authorIsBot: event.authorIsBot,
       externalMessageId: event.externalMessageId,
       ...(event.reactionRef !== undefined ? { reactionRef: event.reactionRef } : {}),
+      ...(engageReaction !== null ? { engageReaction } : {}),
       isBotMention: event.isBotMention,
       replyToBotMessageId: event.replyToBotMessageId,
       isDm: event.isDm,
@@ -1977,6 +2006,19 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     reactionCallbacks.get(adapter)?.delete(cb)
   }
 
+  const registerRemoveReaction = (adapter: ChannelKey['adapter'], cb: RemoveReactionCallback): void => {
+    let set = removeReactionCallbacks.get(adapter)
+    if (!set) {
+      set = new Set()
+      removeReactionCallbacks.set(adapter, set)
+    }
+    set.add(cb)
+  }
+
+  const unregisterRemoveReaction = (adapter: ChannelKey['adapter'], cb: RemoveReactionCallback): void => {
+    removeReactionCallbacks.get(adapter)?.delete(cb)
+  }
+
   const react = async (req: ReactionRequest): Promise<ReactionResult> => {
     if (req.reactionRef.adapter !== req.adapter) {
       return { ok: false, error: 'reaction ref adapter mismatch', code: 'unsupported' }
@@ -2001,15 +2043,34 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     return lastError ?? { ok: false, error: 'no reaction callback handled request', code: 'unsupported' }
   }
 
+  const removeReaction = async (req: RemoveReactionRequest): Promise<ReactionResult> => {
+    if (req.reactionRef.adapter !== req.adapter) {
+      return { ok: false, error: 'reaction ref adapter mismatch', code: 'unsupported' }
+    }
+    const callbacks = removeReactionCallbacks.get(req.adapter)
+    if (!callbacks || callbacks.size === 0) {
+      return { ok: false, error: `adapter "${req.adapter}" does not support reaction removal`, code: 'unsupported' }
+    }
+    let lastError: ReactionResult | undefined
+    for (const cb of Array.from(callbacks)) {
+      const result = await cb(req).catch(
+        (err): ReactionResult => ({ ok: false, error: describe(err), code: 'transient' }),
+      )
+      if (result.ok) return result
+      lastError = result
+    }
+    return lastError ?? { ok: false, error: 'no reaction removal callback handled request', code: 'unsupported' }
+  }
+
   // Best-effort acknowledgment: drop an :eyes: on the triggering inbound the
   // moment we decide to engage, replacing the old "On it" ack comment on
   // GitHub. Fire-and-forget so a reaction failure (missing permission, the
   // adapter not supporting reactions, a transient API error) can NEVER block
   // engagement, enqueueing, or the agent's actual reply. No reactionRef =
   // nothing reactable (synthetic inbounds, reaction-less adapters) = silent skip.
-  const autoReactOnEngage = (event: InboundMessage): void => {
-    if (event.reactionRef === undefined) return
-    void react({
+  const autoReactOnEngage = (event: InboundMessage): Promise<ReactionRef | null> | null => {
+    if (event.reactionRef === undefined) return null
+    const addResult = react({
       adapter: event.adapter,
       workspace: event.workspace,
       chat: event.chat,
@@ -2017,6 +2078,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       reactionRef: event.reactionRef,
       emoji: ENGAGE_REACTION_EMOJI,
     })
+    const addReactionRef = addResult.then((r) => (r.ok ? (r.reactionRef ?? null) : null)).catch(() => null)
+    void addResult
       .then((result) => {
         if (!result.ok && result.code !== 'unsupported') {
           logger.info(`[channels] engage-react failed adapter=${event.adapter} chat=${event.chat}: ${result.error}`)
@@ -2025,6 +2088,37 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       .catch((err) => {
         logger.info(`[channels] engage-react threw adapter=${event.adapter} chat=${event.chat}: ${describe(err)}`)
       })
+    return addReactionRef
+  }
+
+  const dropEngageReactionsAfterReply = (live: LiveSession, addPromises: Array<Promise<ReactionRef | null>>): void => {
+    for (const addPromise of addPromises) dropOneEngageReactionAfterReply(live, addPromise)
+  }
+
+  const dropOneEngageReactionAfterReply = (live: LiveSession, addPromise: Promise<ReactionRef | null>): void => {
+    void addPromise
+      .then((reactionRef) => {
+        if (reactionRef === null) return undefined
+        return removeReaction({
+          adapter: live.key.adapter,
+          workspace: live.key.workspace,
+          chat: live.key.chat,
+          thread: live.key.thread,
+          reactionRef,
+        })
+      })
+      .then((result) => {
+        if (result && !result.ok && result.code !== 'unsupported' && result.code !== 'not-found') {
+          logger.info(
+            `[channels] engage-unreact failed adapter=${live.key.adapter} chat=${live.key.chat}: ${result.error}`,
+          )
+        }
+      })
+      .catch((err) => {
+        logger.info(
+          `[channels] engage-unreact threw adapter=${live.key.adapter} chat=${live.key.chat}: ${describe(err)}`,
+        )
+      })
   }
 
   const unregisterOutbound = (adapter: ChannelKey['adapter'], cb: OutboundCallback): void => {
@@ -2728,6 +2822,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     registerReaction,
     unregisterReaction,
     react,
+    registerRemoveReaction,
+    unregisterRemoveReaction,
+    removeReaction,
     registerTyping,
     unregisterTyping,
     registerChannelNameResolver,
@@ -2929,14 +3026,19 @@ function composeTurnPrompt(
       '**Do not acknowledge or reply to this notice.**',
       '',
       'You are woken on every message from someone you recently talked with, so',
-      'most turns you should stay quiet. Reply ONLY when:',
+      'most turns you should stay quiet. In a group the target shifts every',
+      'message: before replying, identify who THIS latest message is aimed at.',
+      'Reply ONLY when:',
       '- the current message is addressed to you (by name, @-mention, or reply), or',
       '- it directly continues your own last exchange and clearly wants an answer',
       '  (e.g. a follow-up question about what you just said).',
       '',
-      'Otherwise — chatter between others, side-conversation, banter, or anything',
-      'not actually waiting on you — reply with `NO_REPLY` (or call `skip_response`)',
-      'to stay silent and keep watching. When unsure, prefer silence.',
+      'If it is aimed at someone else — another person by name or @-mention, a',
+      'reply to their message, or another bot — it is not your turn, even if you',
+      'were just talking with its author. Otherwise too — chatter, side-',
+      'conversation, banter, or anything not actually waiting on you — reply with',
+      '`NO_REPLY` (or call `skip_response`) to stay silent and keep watching.',
+      'When unsure, prefer silence.',
       '',
       '---',
       '',

package/src/channels/types.ts

@@ -132,12 +132,27 @@ export type ReactionRequest = {
   emoji: string
 }
 
+export type RemoveReactionRequest = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread?: string | null
+  // Per-reaction-instance ref returned by ReactionResult.reactionRef from the
+  // add request, not the inbound message target ref used by ReactionRequest.
+  reactionRef: ReactionRef
+}
+
 export type ReactionErrorCode = 'permission-denied' | 'not-found' | 'unsupported' | 'rate-limited' | 'transient'
 
-export type ReactionResult = { ok: true } | { ok: false; error: string; code?: ReactionErrorCode }
+export type ReactionResult =
+  // Optional success ref identifies THIS created reaction instance for later
+  // removal, not the original message target. Adapters that cannot remove omit it.
+  { ok: true; reactionRef?: ReactionRef } | { ok: false; error: string; code?: ReactionErrorCode }
 
 export type ReactionCallback = (req: ReactionRequest) => Promise<ReactionResult>
 
+export type RemoveReactionCallback = (req: RemoveReactionRequest) => Promise<ReactionResult>
+
 // File on disk that the agent wants to attach to an outbound message. The
 // agent runs inside a container with /agent bind-mounted from the host;
 // `path` should be an absolute path the container can `readFile`. The

package/src/cli/builtins.ts

@@ -13,6 +13,7 @@ export const BUILTIN_COMMAND_NAMES = [
   'reload',
   'logs',
   'inspect',
+  'dreams',
   'shell',
   'compose',
   'channel',

package/src/cli/dreams.ts

@@ -0,0 +1,147 @@
+import { defineCommand } from 'citty'
+
+import { type DreamEntry, renderListRow, runDreams, type ViewAction } from '@/dreams'
+import { findAgentDir } from '@/init'
+
+import { createEscController } from './inspect-controller'
+import { c, cancel, errorLine, isCancel } from './ui'
+
+const ESC_DEBOUNCE_MS = 50
+const QUIT_KEY = 0x71
+
+export const dreamsCommand = defineCommand({
+  meta: {
+    name: 'dreams',
+    description: "browse the dreaming subagent's memory-consolidation journal from git history (host stage)",
+  },
+  args: {
+    limit: {
+      type: 'string',
+      description: 'show at most N most-recent dreams',
+    },
+    json: {
+      type: 'boolean',
+      description: 'emit one JSON object per dream (subject-level)',
+      default: false,
+    },
+    details: {
+      type: 'boolean',
+      description: 'with --json, hydrate each dream with its consolidated fragments/shards/skills',
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const color = useColor()
+    const limit = parseLimit(args.limit)
+    const interactive = isInteractive() && args.json !== true
+
+    const result = await runDreams({
+      agentDir: cwd,
+      json: args.json === true,
+      details: args.details === true,
+      color,
+      ...(limit !== undefined ? { limit } : {}),
+      selectDream: (entries, selectOpts) => clackSelect(entries, color, selectOpts?.initialSha),
+      ...(interactive ? { viewDream: () => waitForViewerKey(color) } : {}),
+      stdout: (line) => process.stdout.write(`${line}\n`),
+    })
+
+    if (!result.ok) {
+      process.stderr.write(`${errorLine(result.reason)}\n`)
+      process.exit(result.exitCode)
+    }
+    process.exit(result.exitCode)
+  },
+})
+
+function isInteractive(): boolean {
+  return Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY)
+}
+
+type RawInput = Pick<NodeJS.ReadStream, 'isTTY' | 'setRawMode' | 'resume' | 'pause' | 'on' | 'off'>
+
+// Esc routes through createEscController so a standalone Esc returns 'back'
+// while a multi-byte CSI sequence (↑/↓ arrows) does not. Teardown restores
+// raw mode but deliberately does NOT pause stdin: clack cannot re-flow a
+// paused process.stdin under Bun, so the next picker would freeze — the same
+// reason cli/inspect.ts leaves the stream flowing on its return path.
+export async function waitForViewerKey(color: boolean, input: RawInput = process.stdin): Promise<ViewAction> {
+  const stdin = input
+  if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') return 'exit'
+
+  process.stdout.write(`${viewerHintLine(color)}\n`)
+
+  const ctrl = createEscController({ debounceMs: ESC_DEBOUNCE_MS })
+  const escSignal = ctrl.armForStream()
+
+  return new Promise<ViewAction>((resolve) => {
+    let settled = false
+    const finish = (action: ViewAction): void => {
+      if (settled) return
+      settled = true
+      escSignal.removeEventListener('abort', onEscAbort)
+      stdin.off('data', onData)
+      ctrl.dispose()
+      try {
+        stdin.setRawMode(false)
+      } catch {
+        /* terminal already torn down */
+      }
+      resolve(action)
+    }
+    const onEscAbort = (): void => finish('back')
+    const onData = (chunk: Buffer): void => {
+      if (chunk[0] === QUIT_KEY) {
+        finish('exit')
+        return
+      }
+      const { sigint } = ctrl.onChunk(chunk)
+      if (sigint) finish('exit')
+    }
+    escSignal.addEventListener('abort', onEscAbort, { once: true })
+    stdin.setRawMode(true)
+    stdin.resume()
+    stdin.on('data', onData)
+  })
+}
+
+function viewerHintLine(color: boolean): string {
+  const text = '(esc to go back to the list · q to quit)'
+  return color ? c.dim(text) : text
+}
+
+function parseLimit(raw: unknown): number | undefined {
+  if (typeof raw !== 'string') return undefined
+  const n = Number.parseInt(raw, 10)
+  return Number.isFinite(n) && n > 0 ? n : undefined
+}
+
+async function clackSelect(
+  entries: DreamEntry[],
+  color: boolean,
+  initialSha: string | undefined,
+): Promise<DreamEntry | null> {
+  const { select } = await import('@clack/prompts')
+  const preferred = initialSha !== undefined && entries.some((e) => e.sha === initialSha) ? initialSha : entries[0]?.sha
+  const picked = await select<string>({
+    message: `Pick a dream to open (${entries.length} total)`,
+    options: entries.map((entry) => ({
+      value: entry.sha,
+      label: renderListRow(entry, { color }),
+    })),
+    initialValue: preferred,
+  })
+  if (isCancel(picked)) {
+    cancel('Cancelled.')
+    return null
+  }
+  return entries.find((entry) => entry.sha === picked) ?? null
+}
+
+function useColor(): boolean {
+  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '') return false
+  if (process.env.FORCE_COLOR === '0') return false
+  if (process.env.FORCE_COLOR) return true
+  return Boolean(process.stdout.isTTY)
+}

package/src/cli/index.ts

@@ -23,6 +23,7 @@ const main = defineCommand({
     reload: () => import('./reload').then((m) => m.reload),
     logs: () => import('./logs').then((m) => m.logsCommand),
     inspect: () => import('./inspect').then((m) => m.inspectCommand),
+    dreams: () => import('./dreams').then((m) => m.dreamsCommand),
     shell: () => import('./shell').then((m) => m.shellCommand),
     compose: () => import('./compose').then((m) => m.composeCommand),
     channel: () => import('./channel').then((m) => m.channelCommand),

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) }
+  }
+}