typeclaw 0.23.0 → 0.25.0

package/src/channels/router.ts

@@ -4,9 +4,19 @@ import type { AssistantMessage } from '@mariozechner/pi-ai'
 import { SessionManager } from '@mariozechner/pi-coding-agent'
 
 import { createSession, renderTurnRoleAnchor, renderTurnTimeAnchor, type AgentSession } from '@/agent'
+import { forgetSharedLoopGuardTool } from '@/agent/plugin-tools'
 import { subscribeProviderErrors } from '@/agent/provider-error'
+import type { RestartHandoff } from '@/agent/restart-handoff'
 import type { ChannelParticipant, SessionOrigin } from '@/agent/session-origin'
 import { renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
+import {
+  armRestartKickForOrigin,
+  extractTurnUsage,
+  recordTurnOutcome,
+  recordTurnStart,
+  runIdleContinuation,
+} from '@/agent/todo/continuation-wiring'
+import { SUBAGENT_OUTPUT_TOOL_NAME } from '@/agent/tools/subagent-output'
 import { type Command, type CommandPermission, type CommandResult, createCommandRegistry } from '@/commands'
 import { CORE_PERMISSIONS, type PermissionService } from '@/permissions'
 import type { HookBus } from '@/plugin'
@@ -53,6 +63,7 @@ import type {
   HistoryCallback,
   InboundAttachment,
   InboundMessage,
+  InboundReferenceContext,
   RemoveReactionCallback,
   RemoveReactionRequest,
   OutboundCallback,
@@ -63,6 +74,9 @@ import type {
   ReactionRequest,
   ReactionResult,
   ResolvedChannelNames,
+  ReviewThreadResolveRequest,
+  ReviewThreadResolveResult,
+  ReviewThreadResolver,
   SendErrorCode,
   SendResult,
   TypingCallback,
@@ -117,6 +131,23 @@ export const SESSION_GC_INTERVAL_MS = 60 * 1000
 // recovery paths (`source: 'system'`) bypass.
 export const MAX_CHANNEL_SENDS_PER_TURN = 10
 export const ENGAGE_REACTION_EMOJI = 'eyes'
+
+// Wake nudge pushed into a resumed channel session at boot so drain() has a
+// non-empty batch and fires a turn. The substantive instruction the model acts
+// on is the `typeclaw.restart-self` entry already in the reopened JSONL (pi
+// hydrates it as a user message); this nudge only triggers the turn. Uses the
+// repo's SYSTEM MESSAGE framing (see composeTurnPrompt) so persona-rich models
+// do not reply to it as if a human wrote it.
+export const RESTART_RESUME_WAKE_REMINDER = [
+  '---',
+  '**[SYSTEM MESSAGE — not from a human]**',
+  '',
+  'The container just restarted and this session was resumed. Act on the',
+  'restart instructions already in your context. Do not acknowledge or reply to',
+  'this notice itself.',
+  '',
+  '---',
+].join('\n')
 // Ceiling on tool-source channel sends that a same-turn router policy DENIED
 // without delivering — `skip-locked`, `turn-cap`, or `duplicate`. Such denials
 // return a soft error and do NOT increment `consecutiveSends`, so a model that
@@ -280,6 +311,7 @@ export type ConfigForAdapter = (adapter: ChannelKey['adapter']) => ChannelAdapte
 
 type QueuedInbound = {
   text: string
+  referenceContext?: InboundReferenceContext
   attachments?: readonly InboundAttachment[]
   authorId: string
   authorName: string
@@ -290,6 +322,7 @@ type QueuedInbound = {
   isBotMention: boolean
   replyToBotMessageId: string | null
   isDm: boolean
+  typingThread?: string
   receivedAt: number
   // Original platform timestamp (Slack/Discord), in ms since epoch. Used
   // by composeTurnPrompt to render an ISO 8601 prefix on each line so the
@@ -301,6 +334,7 @@ type QueuedInbound = {
 
 type ObservedInbound = {
   text: string
+  referenceContext?: InboundReferenceContext
   attachments?: readonly InboundAttachment[]
   authorId: string
   authorName: string
@@ -358,6 +392,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
+  // Typing-status anchor of the inbound that triggered THIS turn (last item in
+  // the drained batch, mirroring `currentTurnReactionRef`). Adapter-opaque ts
+  // carried only to the typing path; null when the triggering inbound supplied
+  // none (every non-DM inbound, and reminder-only turns).
+  currentTurnTypingThread: string | 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
@@ -445,9 +484,25 @@ type LiveSession = {
   // with the current `turnSeq`. Read at the top of `validateChannelTurn`:
   // if it matches the just-completed turn, recovery is skipped entirely
   // (no NO_REPLY check, no Kimi leak check, no assistant-text recovery).
-  // The model has explicitly opted out of this turn and we honor that
-  // unconditionally. `null` when no skip has been recorded.
+  // The model has explicitly opted out of this turn and we honor that —
+  // UNLESS the model also tried a tool-source send this turn (see
+  // `skipLockedSendTurn`), in which case the skip was contested and we let
+  // recovery run so the contested reply isn't silently dropped. `null` when
+  // no skip has been recorded.
   skippedTurn: { turnSeq: number; reason: string } | null
+  // Stamped by `send()` with the current `turnSeq` when a tool-source send is
+  // DENIED by the skip lock (the model called `skip_response` first, then
+  // changed its mind and tried `channel_reply`). The send still stays denied —
+  // "commit to silence" is binding for the live send path — but a contested
+  // skip must NOT also suppress the post-turn recovery net: the model produced
+  // user-facing reply text that the skip short-circuit would otherwise drop on
+  // the floor with no retry (the inbound is already drained). When this matches
+  // the just-completed turn, `validateChannelTurn` falls through to the normal
+  // `recoverableAssistantText` path, which posts the reply via `source:'system'`
+  // (subject to the existing NO_REPLY / leak guards). `null` when no skip-locked
+  // send was attempted. Compared by `turnSeq` so a stale value can't leak across
+  // turns.
+  skipLockedSendTurn: number | null
   // Captured by drain() at batch dequeue; read+cleared by send() on the
   // first tool-source send of the turn. The anchor decision (delay
   // threshold + intervening-observed check) is evaluated at SEND time
@@ -474,6 +529,7 @@ type LiveSession = {
   destroyed: boolean
   unsubProviderErrors: (() => void) | null
   unsubTypingActivity: (() => void) | null
+  unsubTodoOutcome: (() => void) | null
 }
 
 // `event` is null for command invocations that originated outside the inbound
@@ -570,6 +626,14 @@ export type ChannelRouter = {
   registerFetchAttachment: (adapter: ChannelKey['adapter'], cb: FetchAttachmentCallback) => void
   unregisterFetchAttachment: (adapter: ChannelKey['adapter'], cb: FetchAttachmentCallback) => void
   fetchAttachment: (adapter: ChannelKey['adapter'], args: FetchAttachmentArgs) => Promise<FetchAttachmentResult>
+  // Review-thread resolution is opt-in per adapter and last-write-wins (one
+  // bot account per adapter, like self-identity). An adapter that never calls
+  // registerReviewThreadResolver makes `resolveReviewThread` answer
+  // `unsupported`. Kept off the outbound path: resolving is a side-effect close-
+  // out, not a message, so it bypasses send()'s flood/cap/dup/sticky guards.
+  registerReviewThreadResolver: (adapter: ChannelKey['adapter'], resolver: ReviewThreadResolver) => void
+  unregisterReviewThreadResolver: (adapter: ChannelKey['adapter'], resolver: ReviewThreadResolver) => void
+  resolveReviewThread: (req: ReviewThreadResolveRequest) => Promise<ReviewThreadResolveResult>
   lookupInboundAttachment: (args: ChannelKey & { id: number }) => InboundAttachment | null
   listInboundAttachmentIds: (args: ChannelKey) => readonly number[]
   // Execute a command by name against an existing live session, bypassing
@@ -607,6 +671,7 @@ export type ChannelRouter = {
     ok: boolean
     durationMs: number
     error?: string
+    channelKey?: { adapter: string; workspace: string; chat: string; thread: string | null }
   }) => { kind: 'delivered'; keyId: string } | { kind: 'no-live-session' }
   // Record that the agent invoked `skip_response` during the current turn
   // for the channel session identified by `parentSessionId`. The reason is
@@ -635,6 +700,17 @@ export type ChannelRouter = {
     | { kind: 'recorded'; keyId: string }
     | { kind: 'recorded-after-send'; keyId: string }
     | { kind: 'no-live-session' }
+  // Two-phase boot restart-resume. Call `reserveRestartHandoff(handoff)` BEFORE
+  // `channelManager.start()` to install a per-key gate so an inbound that races
+  // the adapters coming online coalesces onto the resume instead of competing
+  // with it; then `await reservation.resume()` AFTER start so the reopen + wake
+  // reply have registered adapters. Returns null for non-channel handoffs or an
+  // unconfigured adapter. `resume()` is safe on a stale/missing mapping — it
+  // logs and skips, leaving the todo to resume on the next real inbound.
+  reserveRestartHandoff: (handoff: RestartHandoff) => RestartReservation | null
+  // Reserve + resume in one call (reserve, then immediately resume). For
+  // callers already past adapter startup; prefer the two-phase form at boot.
+  resumeRestartHandoff: (handoff: RestartHandoff) => Promise<void>
   stop: () => Promise<void>
   tearDownAllLive: () => Promise<void>
   liveCount: () => number
@@ -739,7 +815,18 @@ export type CreateChannelRouterOptions = {
   // confirmation string (the container exits shortly after, so the reply is
   // best-effort).
   onReload?: () => Promise<string>
-  onRestart?: () => Promise<string>
+  // `ctx` is present only when the /restart command resolved a live session for
+  // the invoking channel (wantsLiveSession). When present, the handler should
+  // write a channel-origin resume handoff so the originating conversation
+  // resumes on the next boot; when absent (cold channel / native slash with no
+  // session) it should just bounce the container with no handoff.
+  onRestart?: (ctx?: RestartCommandContext) => Promise<string>
+}
+
+export type RestartCommandContext = {
+  originatingSessionId: string
+  originatingSessionFile?: string
+  handoffOrigin: { kind: 'channel'; key: ChannelKey }
 }
 
 export type ClaimHandlerInput = {
@@ -756,6 +843,16 @@ export type ClaimHandlerOutcome =
   | { kind: 'fail'; reply: string }
   | { kind: 'fallthrough' }
 
+// A boot-time restart-resume reservation for one channel key. `resume()` runs
+// the real reopen after adapters are ready; `sawInbound` records whether a real
+// inbound coalesced onto it in the meantime (in which case the synthetic wake
+// is skipped — the inbound already triggers the turn).
+export type RestartReservation = {
+  keyId: string
+  sawInbound: boolean
+  resume: () => Promise<void>
+}
+
 export type ClaimHandler = (input: ClaimHandlerInput) => Promise<ClaimHandlerOutcome>
 
 const GRANT_ALL_PERMISSIONS: PermissionService = {
@@ -780,6 +877,14 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const onRestart = options.onRestart
   const liveSessions = new Map<string, LiveSession>()
   const creating = new Map<string, Promise<LiveSession>>()
+  // Restart-resume reservations, keyed by channelKeyId. Installed by
+  // reserveRestartHandoff BEFORE channel adapters start receiving, so an
+  // inbound that races the boot resume coalesces onto the reservation (via the
+  // `creating` entry it seeds) instead of stale-rolling the mapping or
+  // creating a competing session. `sawInbound` is flipped by route() when an
+  // inbound waited on it, which suppresses the synthetic wake (the real inbound
+  // is the wake). Cleared when the reservation resolves.
+  const restartReservations = new Map<string, RestartReservation>()
   // Bumped by tearDownAllLive() and stop() before they tear sessions down. An
   // in-flight ensureLive() captures the value at creation start and re-checks
   // it right before installing into liveSessions; if it changed, a teardown
@@ -798,6 +903,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const membershipCaches = new Map<ChannelKey['adapter'], MembershipCache>()
   const historyCallbacks = new Map<ChannelKey['adapter'], Set<HistoryCallback>>()
   const fetchAttachmentCallbacks = new Map<ChannelKey['adapter'], Set<FetchAttachmentCallback>>()
+  const reviewThreadResolvers = new Map<ChannelKey['adapter'], ReviewThreadResolver>()
   const stickyLedger = new StickyLedger()
   // The /help handler reads the live registry to enumerate commands, so it
   // forward-references `commands`. Safe at runtime — the handler only runs on
@@ -842,7 +948,22 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       description: 'Restart the typeclaw container.',
       permission: 'session.admin',
       requiresLiveSession: false,
-      handler: async () => ({ reply: await onRestart() }),
+      // Resolve the live session when one exists so the restart can write a
+      // resume handoff for this conversation; still bounces from a cold channel.
+      wantsLiveSession: true,
+      handler: async ({ live }) => ({
+        reply: await onRestart(
+          live !== null
+            ? {
+                originatingSessionId: live.sessionId,
+                ...(live.getTranscriptPath?.() !== undefined
+                  ? { originatingSessionFile: live.getTranscriptPath!()! }
+                  : {}),
+                handoffOrigin: { kind: 'channel', key: live.key },
+              }
+            : undefined,
+        ),
+      }),
     })
   }
   const commands = createCommandRegistry<ChannelCommandContext>(channelCommands)
@@ -997,10 +1118,20 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     key: ChannelKey,
     triggeringMessageId?: string,
     triggeringAuthorId?: string,
+    // Restart-resume only: force rehydration of this exact (sessionId,
+    // sessionFile) and bypass stale-rollover, so the originating session's
+    // `typeclaw.restart-self` entry is reopened rather than rolled into a fresh
+    // session (a restart easily outlasts SESSION_FRESHNESS_TTL_MS). The mapping
+    // is persisted only through the normal success path below — no pre-mutation
+    // — so a reopen failure leaves the durable mapping untouched.
+    resumeTarget?: { sessionId: string; sessionFile: string },
   ): Promise<LiveSession> => {
     const keyId = channelKeyId(key)
     const existing = liveSessions.get(keyId)
     if (existing && !existing.destroyed) {
+      // A resume that finds the key already live is a no-op for reopening: the
+      // session is up, so just hand it back and let the caller enqueue the wake.
+      if (resumeTarget !== undefined) return existing
       const idleMs = now() - existing.lastInboundAt
       // `lastInboundAt` is only bumped on engaged inbounds (see route()),
       // so a session whose drain loop has been compiling a slow reply for
@@ -1055,6 +1186,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       const record = mappings ? findRecord(mappings, key) : undefined
       let resolvedRecord = record
       if (
+        resumeTarget === undefined &&
         record?.sessionId !== undefined &&
         existing === undefined &&
         now() - (record.lastInboundAt ?? 0) > SESSION_FRESHNESS_TTL_MS
@@ -1083,6 +1215,21 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           }
         }
       }
+      if (resumeTarget !== undefined) {
+        // Reopen the exact originating session in-memory only; the success
+        // path below persists it. Carry the prior record's participants when
+        // present so the reopened session keeps its roster.
+        resolvedRecord = {
+          adapter: key.adapter,
+          workspace: key.workspace,
+          chat: key.chat,
+          thread: key.thread,
+          sessionId: resumeTarget.sessionId,
+          sessionFile: resumeTarget.sessionFile,
+          participants: (record?.participants ?? []) as ChannelParticipant[],
+          lastInboundAt: now(),
+        }
+      }
       const phase = resolvedRecord?.sessionId === undefined ? 'cold-start' : 'rehydrate'
       logger.info(`[channels] ${keyId}: ensureLive begin (${phase})`)
       const participants = (resolvedRecord?.participants ?? []) as ChannelParticipant[]
@@ -1181,6 +1328,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         currentTurnAuthorId: null,
         currentTurnAuthorIds: new Set(),
         currentTurnReactionRef: null,
+        currentTurnTypingThread: null,
         currentTurnEngageReactions: [],
         // `lastTurnAuthorId` (string, used for `lastInboundAuthorId` in
         // origin) and `lastTurnAuthorIds` (Set, used by
@@ -1204,6 +1352,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         inFlightToolSends: new Map(),
         policyDeniedToolSendsThisTurn: new Map(),
         skippedTurn: null,
+        skipLockedSendTurn: null,
         pendingQuoteCandidate: null,
         recentEngagedPeerBotTurns: [],
         consecutiveEngagedPeerBotTurns: 0,
@@ -1213,10 +1362,22 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         destroyed: false,
         unsubProviderErrors: null,
         unsubTypingActivity: null,
+        unsubTodoOutcome: null,
       }
       live.unsubProviderErrors = subscribeProviderErrors(created.session, (err) => {
         logger.error(`[channels] ${live.keyId}: LLM call failed: ${err.message}`)
       })
+      live.unsubTodoOutcome = created.session.subscribe((event: unknown) => {
+        const usage = extractTurnUsage(event)
+        if (usage === null) return
+        void recordTurnOutcome({
+          agentDir: options.agentDir,
+          origin: buildLiveOrigin(live),
+          turnId: live.sessionId,
+          stopReason: usage.stopReason,
+          ...(usage.tokens !== undefined ? { tokens: usage.tokens } : {}),
+        }).catch((err) => logger.error(`[channels] ${live.keyId}: todo outcome capture failed: ${describe(err)}`))
+      })
       live.unsubTypingActivity = subscribeTypingActivity(created.session, live)
       installChannelReplyTerminalHook(live)
       installChannelOutputCap(live)
@@ -1308,6 +1469,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       if (item.kind === 'message') {
         observed.push({
           text: item.message.text,
+          ...(item.message.referenceContext !== undefined ? { referenceContext: item.message.referenceContext } : {}),
           authorId: item.message.authorId,
           authorName: item.message.authorName,
           authorIsBot: item.message.isBot,
@@ -1366,6 +1528,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       workspace: live.key.workspace,
       chat: live.key.chat,
       thread: live.key.thread,
+      ...(live.currentTurnTypingThread !== null ? { typingThread: live.currentTurnTypingThread } : {}),
       phase,
     }
     await Promise.all(
@@ -1505,6 +1668,36 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
   }
 
+  const recordTodoTurnStart = async (live: LiveSession, isRealUserTurn: boolean): Promise<void> => {
+    try {
+      await recordTurnStart({ agentDir: options.agentDir, origin: buildLiveOrigin(live), isRealUserTurn })
+    } catch (err) {
+      logger.warn(`[channels] ${live.keyId}: todo turn-start failed: ${describe(err)}`)
+    }
+  }
+
+  // After the drain queue empties, push at most one continuation reminder into
+  // pendingSystemReminders. The enclosing drain `while` re-checks that array,
+  // so the reminder is picked up as a batch-empty (injected, non-user) turn in
+  // the same drain pass. The episode guard bounds how many times this can
+  // re-fire; a reminder-only turn records isRealUserTurn=false so it never
+  // resets the budget.
+  const maybeContinueTodosChannel = async (live: LiveSession): Promise<void> => {
+    if (live.destroyed) return
+    if (live.promptQueue.length > 0 || live.pendingSystemReminders.length > 0) return
+    try {
+      await runIdleContinuation({
+        agentDir: options.agentDir,
+        origin: buildLiveOrigin(live),
+        deliver: (text) => {
+          live.pendingSystemReminders.push(text)
+        },
+      })
+    } catch (err) {
+      logger.warn(`[channels] ${live.keyId}: todo continuation failed: ${describe(err)}`)
+    }
+  }
+
   const fireSessionTurnStart = async (live: LiveSession, userPrompt: string): Promise<void> => {
     if (!live.hooks) return
     try {
@@ -1595,6 +1788,7 @@ 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.currentTurnTypingThread = batch[batch.length - 1]!.typingThread ?? null
           live.currentTurnEngageReactions = batch.flatMap((m) =>
             m.engageReaction !== undefined ? [m.engageReaction] : [],
           )
@@ -1648,7 +1842,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         const engageAddPromises = live.currentTurnEngageReactions
         live.turnSeq++
         live.successfulSendsAtTurnStart = successfulSendsBeforePrompt
+        live.skipLockedSendTurn = null
         live.policyDeniedToolSendsThisTurn.clear()
+        const isRealUserTurn = batch.length > 0
         await fireSessionTurnStart(live, text)
         try {
           await live.session.prompt(text)
@@ -1665,6 +1861,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           await fireSessionTurnEnd(live)
         }
         await fireSessionIdle(live)
+        await recordTodoTurnStart(live, isRealUserTurn)
+        await maybeContinueTodosChannel(live)
         live.lastTurnAuthorIds = new Set(live.currentTurnAuthorIds)
         if (live.currentTurnAuthorId !== null) {
           live.lastTurnAuthorId = live.currentTurnAuthorId
@@ -1677,7 +1875,10 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       live.currentTurnReactionRef = null
       live.currentTurnEngageReactions = []
       live.currentTurnAttachments = []
+      // Reset AFTER stopTypingHeartbeat: its final 'stop' tick reads the anchor
+      // to clear a flat-DM status; clearing it first would strand the indicator.
       await stopTypingHeartbeat(live)
+      live.currentTurnTypingThread = null
     }
   }
 
@@ -1858,6 +2059,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       }
       // Session-less commands (e.g. /help) are informational and run without a
       // live session; their handler reply is posted straight back to the channel.
+      // `wantsLiveSession` commands (/restart) resolve an existing session when
+      // present but do not abort when absent.
       let existingLive: LiveSession | null = null
       if (commandInfo.requiresLiveSession) {
         existingLive = liveSessions.get(keyId) ?? null
@@ -1865,11 +2068,21 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           logger.info(`[channels] ${keyId}: ignoring command /${parsedCommand.name} with no live session`)
           return
         }
+      } else if (commandInfo.wantsLiveSession) {
+        const candidate = liveSessions.get(keyId) ?? null
+        existingLive = candidate !== null && !candidate.destroyed ? candidate : null
       }
       const commandResult = await runChannelCommand(event, existingLive)
       if (commandResult.kind !== 'not-command') return
     }
 
+    // If a boot restart-resume reservation is pending for this key, mark that a
+    // real inbound arrived: ensureLive below will coalesce onto the reservation
+    // (via its `creating` seed), and the reservation's resume() will skip the
+    // synthetic wake since this inbound already triggers the turn.
+    const reservation = restartReservations.get(channelKeyId(key))
+    if (reservation !== undefined) reservation.sawInbound = true
+
     const live = await ensureLive(key, event.externalMessageId, event.authorId)
 
     const isNewAuthor = !live.participants.some((p) => p.authorId === event.authorId)
@@ -2013,6 +2226,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const observe = (live: LiveSession, event: InboundMessage): void => {
     live.contextBuffer.push({
       text: event.text,
+      ...(event.referenceContext !== undefined ? { referenceContext: event.referenceContext } : {}),
       ...(event.attachments !== undefined && event.attachments.length > 0 ? { attachments: event.attachments } : {}),
       authorId: event.authorId,
       authorName: event.authorName,
@@ -2033,6 +2247,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   ): void => {
     live.promptQueue.push({
       text: event.text,
+      ...(event.referenceContext !== undefined ? { referenceContext: event.referenceContext } : {}),
       ...(event.attachments !== undefined && event.attachments.length > 0 ? { attachments: event.attachments } : {}),
       authorId: event.authorId,
       authorName: event.authorName,
@@ -2043,9 +2258,14 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       isBotMention: event.isBotMention,
       replyToBotMessageId: event.replyToBotMessageId,
       isDm: event.isDm,
+      ...(event.typingThread !== undefined ? { typingThread: event.typingThread } : {}),
       receivedAt: now(),
       ts: event.ts,
     })
+    // Make the typing anchor live BEFORE startTypingHeartbeat fires (route()
+    // starts the heartbeat right after enqueue, ahead of drain). drain() later
+    // refreshes it to the last inbound of a coalesced batch.
+    if (event.typingThread !== undefined) live.currentTurnTypingThread = event.typingThread
   }
 
   const registerOutbound = (adapter: ChannelKey['adapter'], cb: OutboundCallback): void => {
@@ -2328,6 +2548,30 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     return lastError
   }
 
+  const registerReviewThreadResolver = (adapter: ChannelKey['adapter'], resolver: ReviewThreadResolver): void => {
+    reviewThreadResolvers.set(adapter, resolver)
+  }
+
+  const unregisterReviewThreadResolver = (adapter: ChannelKey['adapter'], resolver: ReviewThreadResolver): void => {
+    if (reviewThreadResolvers.get(adapter) === resolver) {
+      reviewThreadResolvers.delete(adapter)
+    }
+  }
+
+  const resolveReviewThread = async (req: ReviewThreadResolveRequest): Promise<ReviewThreadResolveResult> => {
+    const resolver = reviewThreadResolvers.get(req.adapter)
+    if (resolver === undefined) {
+      return {
+        ok: false,
+        error: `adapter "${req.adapter}" does not support review-thread resolution`,
+        code: 'unsupported',
+      }
+    }
+    return await resolver(req).catch(
+      (err): ReviewThreadResolveResult => ({ ok: false, error: describe(err), code: 'transient' }),
+    )
+  }
+
   const lookupInboundAttachment = (args: ChannelKey & { id: number }): InboundAttachment | null => {
     const live = liveSessions.get(channelKeyId(args))
     if (live === undefined) return null
@@ -2459,7 +2703,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       // violation: the model already committed to silence. Reject before any
       // state mutation so the model gets a clear error and the channel stays
       // silent. System-source sends (recovery, role-claim) are not affected.
+      // Record the contested skip so `validateChannelTurn` doesn't ALSO drop the
+      // reply text on the floor — the live send stays denied, but the post-turn
+      // recovery net must still surface what the model wanted to say.
       if (live.skippedTurn !== null && live.skippedTurn.turnSeq === live.turnSeq) {
+        live.skipLockedSendTurn = live.turnSeq
         return denyPolicyToolSend(SKIP_RESPONSE_LOCK_ERROR, 'skip-locked')
       }
       const currentCount = live.consecutiveSends.get(sendKey) ?? 0
@@ -2482,6 +2730,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       reserved = true
     }
 
+    // The adapter needs the typing anchor to clear a flat-DM status (msg.thread
+    // is null there, so a thread-keyed clear would no-op). Kept off msg.thread
+    // to leave reply threading untouched.
+    if (live?.currentTurnTypingThread != null && msg.typingThread === undefined) {
+      msg = { ...msg, typingThread: live.currentTurnTypingThread }
+    }
+
     // Snapshot the callbacks before iterating so a callback that mutates the
     // set (e.g. unregisters mid-send) does not cause the iterator to skip
     // siblings or trip into surprising behavior.
@@ -2561,19 +2816,30 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   }
 
   const validateChannelTurn = async (live: LiveSession, successfulSendsBeforePrompt: number): Promise<void> => {
-    // `skip_response` short-circuit. Must run before the `successfulChannelSends`
-    // check so a model that called both `skip_response` and a channel tool in
-    // the same turn still resolves as "skipped" — the rejection inside `send()`
-    // means the channel tool returned an error and never actually delivered.
+    // `skip_response` short-circuit. Honoring it bypasses recovery entirely.
     // Stale-flag protection: only honor when stamped on the just-completed
     // turn. A flag set by a previous turn that crashed before validation
     // would otherwise drop the next legitimate user-facing reply.
-    if (live.skippedTurn !== null && live.skippedTurn.turnSeq === live.turnSeq) {
+    //
+    // Contested-skip carve-out: if the model ALSO attempted a tool-source send
+    // this turn (denied `skip-locked` in `send()`, stamped on `skipLockedSendTurn`),
+    // the skip is no longer a clean opt-out — the model produced reply text it
+    // wanted delivered. The live send stays denied, but we must NOT also suppress
+    // recovery, or the reply is silently dropped with nothing to retry it (the
+    // inbound is already drained). Fall through to the normal recovery path, which
+    // posts it via `source:'system'` under the existing NO_REPLY / leak guards.
+    const skipContested = live.skipLockedSendTurn === live.turnSeq
+    if (live.skippedTurn !== null && live.skippedTurn.turnSeq === live.turnSeq && !skipContested) {
       const { reason } = live.skippedTurn
       live.skippedTurn = null
       logger.info(`[channels] ${live.keyId} skipped_by_tool reason=${JSON.stringify(reason)}`)
       return
     }
+    if (live.skippedTurn !== null && live.skippedTurn.turnSeq === live.turnSeq) {
+      // Clear the now-contested skip so it can't leak into a later turn's check.
+      live.skippedTurn = null
+      logger.info(`[channels] ${live.keyId} skip_contested_by_send recovering reply`)
+    }
     if (live.successfulChannelSends > successfulSendsBeforePrompt) return
 
     const candidate = recoverableAssistantText(live.session)
@@ -2695,6 +2961,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     live.unsubProviderErrors = null
     live.unsubTypingActivity?.()
     live.unsubTypingActivity = null
+    live.unsubTodoOutcome?.()
+    live.unsubTodoOutcome = null
     await stopTypingHeartbeat(live)
     try {
       await live.session.abort()
@@ -2772,6 +3040,127 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
   }
 
+  // Boot-time resume for a restart that originated from a channel session, in
+  // two phases to close the race with adapters that begin receiving inbounds.
+  //
+  // PHASE 1 — reserveRestartHandoff(handoff): called BEFORE the adapters start.
+  // It seeds a per-key entry in `creating` so any inbound that arrives during
+  // boot coalesces onto the (not-yet-run) resume instead of stale-rolling the
+  // mapping or creating a competing session. It does NOT touch resolvers or
+  // outbound callbacks (not registered yet) — it only installs the gate.
+  //
+  // PHASE 2 — reservation.resume(): called AFTER channelManager.start(), when
+  // adapters (and thus resolvers + the outbound callback the wake reply needs)
+  // are ready. It removes its own `creating` seed, reopens the exact session
+  // via ensureLive(resumeTarget) (bypassing stale-rollover, persisting only on
+  // success), and — only if no real inbound coalesced in the meantime — arms
+  // the restart-kick suppressor and enqueues the synthetic wake. If an inbound
+  // did arrive, that inbound is the wake, so the synthetic one is skipped to
+  // avoid a duplicate/spurious "I'm back" turn.
+  //
+  // The `typeclaw.restart-self` entry is already in the reopened JSONL (the
+  // dying container appended it on the restart broadcast), so reopening the
+  // file is what produces the greeting; adapter readiness only matters for
+  // delivering the eventual reply.
+  const reserveRestartHandoff = (handoff: RestartHandoff): RestartReservation | null => {
+    if (handoff.origin.kind !== 'channel') return null
+    const key: ChannelKey = {
+      adapter: handoff.origin.key.adapter,
+      workspace: handoff.origin.key.workspace,
+      chat: handoff.origin.key.chat,
+      thread: handoff.origin.key.thread,
+    }
+    const keyId = channelKeyId(key)
+
+    if (options.configForAdapter(key.adapter) === undefined) {
+      logger.warn(`[channels] ${keyId}: restart-resume skipped — adapter not configured`)
+      return null
+    }
+
+    let resolveGate!: (live: LiveSession) => void
+    let rejectGate!: (err: unknown) => void
+    const gate = new Promise<LiveSession>((res, rej) => {
+      resolveGate = res
+      rejectGate = rej
+    })
+    // Seed `creating` so a racing inbound's ensureLive awaits this gate rather
+    // than starting its own create. Suppress an unhandled-rejection warning on
+    // the skip/failure paths that never get an inbound waiter.
+    creating.set(keyId, gate)
+    gate.catch(() => undefined)
+
+    const reservation: RestartReservation = {
+      keyId,
+      sawInbound: false,
+      resume: async () => {
+        // Drop our own seed BEFORE calling ensureLive, or ensureLive would
+        // await the gate we are about to resolve and deadlock.
+        if (creating.get(keyId) === gate) creating.delete(keyId)
+        restartReservations.delete(keyId)
+
+        await ensureLoaded()
+        const record = mappings ? findRecord(mappings, key) : undefined
+        if (record?.sessionId !== handoff.originatingSessionId) {
+          logger.warn(
+            `[channels] ${keyId}: restart-resume skipped — persisted session ` +
+              `${record?.sessionId ?? '<none>'} no longer matches handoff ${handoff.originatingSessionId}`,
+          )
+          rejectGate(new StaleLiveSessionError(keyId))
+          return
+        }
+
+        let live: LiveSession
+        try {
+          live = await ensureLive(key, undefined, undefined, {
+            sessionId: handoff.originatingSessionId,
+            sessionFile: handoff.originatingSessionFile,
+          })
+        } catch (err) {
+          logger.warn(`[channels] ${keyId}: restart-resume ensureLive failed: ${describe(err)}`)
+          rejectGate(err)
+          return
+        }
+        resolveGate(live)
+
+        if (live.sessionId !== handoff.originatingSessionId) {
+          logger.warn(
+            `[channels] ${keyId}: restart-resume reopened a different session ` +
+              `(${live.sessionId} != ${handoff.originatingSessionId}); skipping wake`,
+          )
+          return
+        }
+
+        // A real inbound coalesced onto the reservation during boot: it is the
+        // wake. Adding the synthetic "I'm back" turn on top would duplicate
+        // work / stack a spurious turn, so skip it and let the inbound drain.
+        if (reservation.sawInbound) {
+          logger.info(`[channels] ${keyId}: restart-resume coalesced with a real inbound; skipping synthetic wake`)
+          return
+        }
+
+        await armRestartKickForOrigin(options.agentDir, buildLiveOrigin(live)).catch((err) =>
+          logger.error(`[channels] ${keyId}: restart-resume arm restart-kick failed: ${describe(err)}`),
+        )
+
+        live.pendingSystemReminders.push(RESTART_RESUME_WAKE_REMINDER)
+        logger.info(`[channels] ${keyId}: restart-resume waking session ${live.sessionId}`)
+        void drain(live)
+      },
+    }
+    restartReservations.set(keyId, reservation)
+    return reservation
+  }
+
+  // Reserve + resume in one call, for callers (and tests) that run after the
+  // adapters are already started and so don't need the pre-start gate. Still
+  // benefits from the reservation's sawInbound suppression for inbounds that
+  // race between reserve and resume.
+  const resumeRestartHandoff = async (handoff: RestartHandoff): Promise<void> => {
+    const reservation = reserveRestartHandoff(handoff)
+    if (reservation === null) return
+    await reservation.resume()
+  }
+
   const executeCommand = async (
     key: ChannelKey,
     name: string,
@@ -2815,6 +3204,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         return { kind: 'ambiguous', matchCount: resolved.count }
       }
       live = resolved.session
+    } else if (commandInfo.wantsLiveSession) {
+      // Best-effort: resolve a session if exactly one matches, but never fail
+      // the command when absent or ambiguous — /restart still bounces.
+      const resolved = resolveLiveSessionForCommand(liveSessions, key)
+      live = resolved.kind === 'found' ? resolved.session : null
     }
     const result = await commands.execute(`/${lowered}`, { live, event: null })
     if (result.kind === 'handled') {
@@ -2828,6 +3222,47 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     return { kind: 'unknown-command', name: lowered }
   }
 
+  const deliverCompletionReminder = (
+    live: LiveSession,
+    args: {
+      parentSessionId: string
+      subagent: string
+      taskId: string
+      ok: boolean
+      durationMs: number
+      error?: string
+    },
+  ): { kind: 'delivered'; keyId: string } => {
+    const text = renderSubagentCompletionReminder({
+      subagent: args.subagent,
+      taskId: args.taskId,
+      ok: args.ok,
+      durationMs: args.durationMs,
+      ...(args.error !== undefined ? { error: args.error } : {}),
+      channel: true,
+    })
+    live.pendingSystemReminders.push(text)
+    // The reminder tells the agent to fetch this result now; clear the
+    // subagent_output window so an earlier premature-polling streak can't
+    // hard-block that legitimate fetch.
+    forgetSharedLoopGuardTool(live.sessionId, SUBAGENT_OUTPUT_TOOL_NAME)
+    logger.info(`[channels] ${live.keyId}: subagent-completion reminder queued task=${args.taskId} ok=${args.ok}`)
+    // Wake the drain loop. If a turn is already in flight, the wakeup is
+    // a no-op because drain() will pick up the reminder on its next
+    // iteration (it now gates on promptQueue OR pendingSystemReminders).
+    // If the session is idle, fire drain() immediately rather than going
+    // through the debounce path — the reminder is not a user inbound,
+    // so the "coalesce nearby inbounds" rationale for debouncing does
+    // not apply. Mirrors the TUI path's `idle ? 'interrupt' : 'queue'`
+    // semantics: the channel router doesn't have a `delivery: interrupt`
+    // mechanism (no in-flight abort during a turn), but firing drain()
+    // immediately is the equivalent for an idle session.
+    if (!live.draining) {
+      void drain(live)
+    }
+    return { kind: 'delivered', keyId: live.keyId }
+  }
+
   const injectSubagentCompletionReminder = (args: {
     parentSessionId: string
     subagent: string
@@ -2835,34 +3270,28 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     ok: boolean
     durationMs: number
     error?: string
+    channelKey?: { adapter: string; workspace: string; chat: string; thread: string | null }
   }): { kind: 'delivered'; keyId: string } | { kind: 'no-live-session' } => {
     for (const live of liveSessions.values()) {
       if (live.destroyed) continue
       if (live.sessionId !== args.parentSessionId) continue
-      const text = renderSubagentCompletionReminder({
-        subagent: args.subagent,
-        taskId: args.taskId,
-        ok: args.ok,
-        durationMs: args.durationMs,
-        ...(args.error !== undefined ? { error: args.error } : {}),
-        channel: true,
-      })
-      live.pendingSystemReminders.push(text)
-      logger.info(`[channels] ${live.keyId}: subagent-completion reminder queued task=${args.taskId} ok=${args.ok}`)
-      // Wake the drain loop. If a turn is already in flight, the wakeup is
-      // a no-op because drain() will pick up the reminder on its next
-      // iteration (it now gates on promptQueue OR pendingSystemReminders).
-      // If the session is idle, fire drain() immediately rather than going
-      // through the debounce path — the reminder is not a user inbound,
-      // so the "coalesce nearby inbounds" rationale for debouncing does
-      // not apply. Mirrors the TUI path's `idle ? 'interrupt' : 'queue'`
-      // semantics: the channel router doesn't have a `delivery: interrupt`
-      // mechanism (no in-flight abort during a turn), but firing drain()
-      // immediately is the equivalent for an idle session.
-      if (!live.draining) {
-        void drain(live)
+      return deliverCompletionReminder(live, args)
+    }
+    // The exact parent session is gone. If the subagent was spawned from a
+    // channel session, the conversation may have rolled over
+    // (SESSION_FRESHNESS_TTL_MS) or been idle-evicted onto a fresh sessionId
+    // for the same channel key while the subagent ran. Fall back to the live
+    // successor for that key so a finished review/result still surfaces
+    // instead of being silently dropped.
+    if (args.channelKey !== undefined) {
+      const targetKeyId = channelKeyId(args.channelKey)
+      const successor = liveSessions.get(targetKeyId)
+      if (successor !== undefined && !successor.destroyed) {
+        logger.info(
+          `[channels] ${targetKeyId}: subagent-completion reminder rerouted to live successor (parent ${args.parentSessionId} gone) task=${args.taskId}`,
+        )
+        return deliverCompletionReminder(successor, args)
       }
-      return { kind: 'delivered', keyId: live.keyId }
     }
     return { kind: 'no-live-session' }
   }
@@ -2922,12 +3351,17 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     registerFetchAttachment,
     unregisterFetchAttachment,
     fetchAttachment,
+    registerReviewThreadResolver,
+    unregisterReviewThreadResolver,
+    resolveReviewThread,
     lookupInboundAttachment,
     listInboundAttachmentIds,
     executeCommand,
     getSelfAliases: computeSelfAliases,
     injectSubagentCompletionReminder,
     markTurnSkipped,
+    reserveRestartHandoff,
+    resumeRestartHandoff,
     stop,
     tearDownAllLive,
     liveCount: () => liveSessions.size,
@@ -3132,7 +3566,7 @@ function composeTurnPrompt(
   if (observed.length > 0) {
     parts.push('## Recent context (not addressed to you, for awareness only)')
     for (const o of observed) {
-      parts.push(formatAuthorLine(o.ts, adapter, o.authorId, o.authorName, o.authorIsBot, o.text))
+      parts.push(formatInboundPromptLines(o, adapter))
     }
     parts.push('')
   }
@@ -3150,7 +3584,7 @@ function composeTurnPrompt(
       )
     }
     for (const b of batch) {
-      parts.push(formatAuthorLine(b.ts, adapter, b.authorId, b.authorName, b.authorIsBot, b.text))
+      parts.push(formatInboundPromptLines(b, adapter))
     }
   }
   return parts.join('\n')
@@ -3169,6 +3603,24 @@ function formatAuthorLine(
   return `${stamp}${formatAuthorReference(adapter, authorId, authorName)} (${authorName})${tag}: ${text}`
 }
 
+function formatInboundPromptLines(
+  inbound: {
+    ts: number
+    authorId: string
+    authorName: string
+    authorIsBot: boolean
+    text: string
+    referenceContext?: InboundReferenceContext
+  },
+  adapter: AdapterId,
+): string {
+  const lines = inbound.referenceContext?.sources.map(renderQuoteAnchor) ?? []
+  lines.push(
+    formatAuthorLine(inbound.ts, adapter, inbound.authorId, inbound.authorName, inbound.authorIsBot, inbound.text),
+  )
+  return lines.join('\n')
+}
+
 export type { QuoteAnchorSource } from './types'
 
 // Picks the right author syntax for the platform so prompts and rendered
@@ -3755,10 +4207,10 @@ export function isLikelyKimiChannelToolLeak(text: string): boolean {
   return KIMI_CHANNEL_TOOL_ID_RE.test(text)
 }
 
-// Detects the *plain-text* shape of a leaked channel-tool invocation — the
-// model serialized the tool call as ordinary prose instead of producing a
-// real tool call. Observed against Kimi-family deployments on KakaoTalk:
-// the entire assistant message body is literally
+// Detects the *plain-text* shape of a leaked tool invocation — the model
+// serialized a tool call as ordinary prose instead of producing a real tool
+// call. Observed against Kimi-family deployments on KakaoTalk: the entire
+// assistant message body is literally
 //
 //   channel_reply({"text":"<the user-facing greeting the bot meant to send>"})
 //
@@ -3768,18 +4220,27 @@ export function isLikelyKimiChannelToolLeak(text: string): boolean {
 // serialization straight to the channel, which is exactly what
 // users see in the reported screenshots.
 //
+// `skip_response` belongs here too, and is the more insidious case: the model
+// means to *decline* the turn but serializes the decision as prose —
+//
+//   skip_response({ reason: "Empty messages, no content to respond to" })
+//
+// Because the recovery path treats this as ordinary assistant text, the bot
+// posts its own "I'm staying silent" plumbing to the channel, the exact
+// opposite of the intended no-op. It is never a legitimate user-facing reply.
+//
 // Structural-only detection (NOT a substring search): the trimmed text must
-// *start* with `channel_reply(` or `channel_send(`, and that opening paren
-// must enclose at least one `"` (the JSON argument). This deliberately
-// matches the leak shape while letting prose that merely *mentions* the
-// tool name (e.g. "I would normally call channel_reply here but...") reach
-// the user — that false-positive class is already locked in by the
-// `still recovers legit prose that happens to mention "channel_reply"` test.
+// *start* with `channel_reply(`, `channel_send(`, or `skip_response(`, and
+// that opening paren must enclose at least one `"` (the serialized argument).
+// This deliberately matches the leak shape while letting prose that merely
+// *mentions* a tool name (e.g. "I would normally call channel_reply here
+// but...") reach the user — that false-positive class is already locked in by
+// the `still recovers prose that mentions channel_reply` test.
 //
 // The trailing close paren is NOT required: the model sometimes truncates
 // mid-serialization, and a half-leaked `channel_reply({"text":"..."` is
 // just as user-hostile as the full shape.
-const PLAIN_TEXT_CHANNEL_TOOL_CALL_RE = /^channel_(?:reply|send)\s*\(\s*[^)]*"/
+const PLAIN_TEXT_CHANNEL_TOOL_CALL_RE = /^(?:channel_(?:reply|send)|skip_response)\s*\(\s*[^)]*"/
 
 export function isLikelyPlainTextChannelToolCall(text: string): boolean {
   return PLAIN_TEXT_CHANNEL_TOOL_CALL_RE.test(text.trim())