typeclaw 0.20.0 → 0.22.0

package/src/channels/router.ts

@@ -7,7 +7,7 @@ import { createSession, renderTurnRoleAnchor, renderTurnTimeAnchor, type AgentSe
 import { subscribeProviderErrors } from '@/agent/provider-error'
 import type { ChannelParticipant, SessionOrigin } from '@/agent/session-origin'
 import { renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
-import { type Command, type CommandResult, createCommandRegistry } from '@/commands'
+import { type Command, type CommandPermission, type CommandResult, createCommandRegistry } from '@/commands'
 import { CORE_PERMISSIONS, type PermissionService } from '@/permissions'
 import type { HookBus } from '@/plugin'
 import { extractClaimCode } from '@/role-claim'
@@ -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
@@ -709,6 +720,17 @@ export type CreateChannelRouterOptions = {
   // can diagnose silent drops from `typeclaw inspect` alone. Omitted in
   // tests that don't care about inspect surfacing.
   stream?: Stream
+  // Operate-the-agent command handlers. When set, the router registers the
+  // matching channel command (/reload, /restart) gated on session.admin
+  // (owner+trusted). Omitted means the command is not registered at all — it
+  // won't appear in /help and a text-prefix or native-slash invocation is
+  // treated as unknown. Production wiring (src/run/index.ts via the channel
+  // manager) supplies both; tests opt in per-case. `onReload` returns a short
+  // human-readable summary posted back to the channel; `onRestart` returns a
+  // confirmation string (the container exits shortly after, so the reply is
+  // best-effort).
+  onReload?: () => Promise<string>
+  onRestart?: () => Promise<string>
 }
 
 export type ClaimHandlerInput = {
@@ -745,6 +767,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const permissions = options.permissions ?? GRANT_ALL_PERMISSIONS
   const claimHandler = options.claimHandler
   const stream = options.stream
+  const onReload = options.onReload
+  const onRestart = options.onRestart
   const liveSessions = new Map<string, LiveSession>()
   const creating = new Map<string, Promise<LiveSession>>()
   // Bumped by tearDownAllLive() and stop() before they tear sessions down. An
@@ -757,6 +781,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>>()
@@ -767,7 +792,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   // The /help handler reads the live registry to enumerate commands, so it
   // forward-references `commands`. Safe at runtime — the handler only runs on
   // invocation, long after the assignment below completes.
-  const channelCommands: readonly Command<ChannelCommandContext>[] = [
+  const channelCommands: Command<ChannelCommandContext>[] = [
     {
       name: 'help',
       description: 'List available commands.',
@@ -788,6 +813,28 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       },
     },
   ]
+  // /reload and /restart are registered only when the operate-the-agent
+  // callbacks are wired (production via the channel manager). Without them the
+  // capability doesn't exist for this router, so the commands stay absent from
+  // /help and resolve as unknown — never a silent no-op.
+  if (onReload !== undefined) {
+    channelCommands.push({
+      name: 'reload',
+      description: 'Reload typeclaw config and subsystems from disk.',
+      permission: 'session.admin',
+      requiresLiveSession: false,
+      handler: async () => ({ reply: await onReload() }),
+    })
+  }
+  if (onRestart !== undefined) {
+    channelCommands.push({
+      name: 'restart',
+      description: 'Restart the typeclaw container.',
+      permission: 'session.admin',
+      requiresLiveSession: false,
+      handler: async () => ({ reply: await onRestart() }),
+    })
+  }
   const commands = createCommandRegistry<ChannelCommandContext>(channelCommands)
 
   // Implicit dir-name alias: agent folder basename matches Docker
@@ -1122,6 +1169,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 +1302,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 +1581,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 +1603,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 +1631,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 +1646,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 +1661,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       live.currentTurnAuthorId = null
       live.currentTurnAuthorIds = new Set()
       live.currentTurnReactionRef = null
+      live.currentTurnEngageReactions = []
       live.currentTurnAttachments = []
       await stopTypingHeartbeat(live)
     }
@@ -1776,9 +1835,10 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         logger.info(`[channels] ${keyId}: ignoring unknown command /${parsedCommand.name}`)
         return
       }
-      if (commandInfo.permission === 'session.control' && isSessionControlDenied(event)) {
+      const requiredPermission = commandPermissionString(commandInfo.permission)
+      if (requiredPermission !== null && !permissions.has(inboundAuthorOrigin(event), requiredPermission)) {
         logger.info(
-          `[channels] ${keyId}: denied command /${parsedCommand.name} by permissions (session.control) author=${event.authorId}`,
+          `[channels] ${keyId}: denied command /${parsedCommand.name} by permissions (${requiredPermission}) author=${event.authorId}`,
         )
         return
       }
@@ -1852,11 +1912,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
@@ -1889,8 +1949,22 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   // operator can grant guest channelRespond for masked stranger turns)
   // cannot /stop another speaker's in-flight turn. session.control is
   // member-and-up by default.
-  const isSessionControlDenied = (event: InboundMessage): boolean =>
-    !permissions.has(inboundAuthorOrigin(event), CORE_PERMISSIONS.sessionControl)
+  // Maps a command's declared permission tier to the concrete permission
+  // string gated on both the text-prefix path (route) and the native-slash
+  // path (executeCommand). 'none' is never gated. session.admin (owner+trusted,
+  // not member) covers /reload and /restart, which mutate global agent state
+  // and drop every in-flight session. Centralized so a new tier can't be
+  // honored on one path and silently skipped on the other.
+  const commandPermissionString = (permission: CommandPermission): string | null => {
+    switch (permission) {
+      case 'none':
+        return null
+      case 'session.control':
+        return CORE_PERMISSIONS.sessionControl
+      case 'session.admin':
+        return CORE_PERMISSIONS.sessionAdmin
+    }
+  }
 
   const updateLoopGuard = (live: LiveSession, event: InboundMessage): void => {
     if (!event.authorIsBot) {
@@ -1938,7 +2012,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 +2025,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 +2056,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 +2093,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 +2128,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 +2138,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 => {
@@ -2608,14 +2752,17 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     if (commandInfo === undefined) {
       return { kind: 'unknown-command', name: lowered }
     }
-    // Gates on session.control (not channel.respond) so a respond-capable
-    // guest cannot abort another speaker's turn. Runs BEFORE the live-session
-    // lookup so an unauthorized invoker gets 'permission-denied' regardless of
-    // session state, rather than leaking session presence via the
-    // 'no-live-session' vs 'permission-denied' distinction. Session-less
-    // informational commands (e.g. /help) declare permission:'none' and skip
-    // both the gate and the lookup so they work in channels with no live turn.
-    if (commandInfo.permission === 'session.control') {
+    // Gates on the command's declared tier (session.control for /stop,
+    // session.admin for /reload and /restart) — never channel.respond — so a
+    // respond-capable guest cannot abort another speaker's turn or bounce the
+    // container. Runs BEFORE the live-session lookup so an unauthorized invoker
+    // gets 'permission-denied' regardless of session state, rather than leaking
+    // session presence via the 'no-live-session' vs 'permission-denied'
+    // distinction. Session-less informational commands (e.g. /help) declare
+    // permission:'none' and skip both the gate and the lookup so they work in
+    // channels with no live turn.
+    const requiredPermission = commandPermissionString(commandInfo.permission)
+    if (requiredPermission !== null) {
       const partial: SessionOrigin = {
         kind: 'channel',
         adapter: key.adapter,
@@ -2624,7 +2771,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         thread: key.thread,
         lastInboundAuthorId: options.invokerId,
       }
-      if (!permissions.has(partial, CORE_PERMISSIONS.sessionControl)) {
+      if (!permissions.has(partial, requiredPermission)) {
         return { kind: 'permission-denied' }
       }
     }
@@ -2728,6 +2875,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     registerReaction,
     unregisterReaction,
     react,
+    registerRemoveReaction,
+    unregisterRemoveReaction,
+    removeReaction,
     registerTyping,
     unregisterTyping,
     registerChannelNameResolver,
@@ -2929,14 +3079,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/schema.ts

@@ -131,6 +131,23 @@ export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
   'pull_request_review.submitted',
 ] as const
 
+// PR-review policy knobs. Grouped under `review` so future toggles
+// (`requestChanges`, auto-review-on-request, severity thresholds) cluster
+// here instead of flattening onto the channel root.
+//
+// `approve` gates whether the agent may submit a formal review with
+// `event: APPROVE`. When `false`, the adapter appends an operator-policy note
+// to inbounds and the `typeclaw-channel-github` skill downgrades an `approve`
+// verdict to a `COMMENT` review (findings still posted, no formal approval).
+// Enforced in the inbound text rather than at the bash layer because the
+// review posts via `gh api --input <file>`, so the `event` value lives in a
+// temp file the command interceptor never sees.
+const githubReviewSchema = z
+  .object({
+    approve: z.boolean().default(true),
+  })
+  .default({ approve: true })
+
 const githubChannelSchema = adapterSchema.extend({
   // Optional now (PR 2): when omitted and a `tunnels[]` entry with
   // `for: { kind: 'channel', name: 'github' }` exists, the runtime resolves
@@ -146,6 +163,7 @@ const githubChannelSchema = adapterSchema.extend({
   // this session is deleted so a restart with a different webhookUrl (e.g.
   // a tunnel reassigning a URL) doesn't leave orphaned hooks on GitHub.
   repos: z.array(z.string()).default([]),
+  review: githubReviewSchema,
 })
 
 // KakaoTalk uses the same shape as every other adapter. There used to be an

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,148 @@
+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, prepareStdinForClack } 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')
+  prepareStdinForClack()
+  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/cli/inspect.ts

@@ -6,7 +6,7 @@ import { runInspectLoop, streamLive, type LiveSourceFactory, type SessionSummary
 import { originLabel, shortSessionId } from '@/inspect/label'
 
 import { createEscController } from './inspect-controller'
-import { cancel, c, errorLine, isCancel } from './ui'
+import { cancel, c, errorLine, isCancel, prepareStdinForClack } from './ui'
 
 const ESC_LISTEN_DELAY_MS = 50
 
@@ -212,6 +212,7 @@ async function clackSelect(
   initialSessionId: string | undefined,
 ): Promise<SessionSummary | null> {
   const { select } = await import('@clack/prompts')
+  prepareStdinForClack()
   const preferred =
     initialSessionId !== undefined && sessions.some((s) => s.sessionId === initialSessionId)
       ? initialSessionId