typeclaw 0.7.0 → 0.9.0

package/src/inspect/replay.ts

@@ -0,0 +1,265 @@
+import { SESSION_META_CUSTOM_TYPE } from '@/agent/session-meta'
+import type { MinimalSessionOrigin } from '@/agent/session-meta'
+
+import type { InspectEvent } from './types'
+
+export type ReplayOptions = {
+  onWarn?: (msg: string) => void
+}
+
+export async function* replayJsonl(filePath: string, opts: ReplayOptions = {}): AsyncGenerator<InspectEvent> {
+  const file = Bun.file(filePath)
+  if (!(await file.exists())) {
+    opts.onWarn?.(`could not open ${filePath}: file does not exist`)
+    return
+  }
+  let stream: ReadableStream<Uint8Array>
+  try {
+    stream = file.stream()
+  } catch (err) {
+    opts.onWarn?.(`could not open ${filePath}: ${describeErr(err)}`)
+    return
+  }
+  yield* replayLines(safeStreamLines(stream, filePath, opts), opts)
+}
+
+async function* safeStreamLines(
+  stream: ReadableStream<Uint8Array>,
+  filePath: string,
+  opts: ReplayOptions,
+): AsyncGenerator<string> {
+  try {
+    yield* streamLines(stream)
+  } catch (err) {
+    opts.onWarn?.(`error reading ${filePath}: ${describeErr(err)}`)
+  }
+}
+
+export async function* replayLines(
+  lines: AsyncIterable<string>,
+  opts: ReplayOptions = {},
+): AsyncGenerator<InspectEvent> {
+  const pending = new Map<string, { name: string; startTs: number }>()
+  for await (const line of lines) {
+    const trimmed = line.trim()
+    if (trimmed === '') continue
+    let entry: unknown
+    try {
+      entry = JSON.parse(trimmed)
+    } catch {
+      opts.onWarn?.('skipping malformed JSONL line')
+      continue
+    }
+    yield* eventsFromEntry(entry, pending)
+  }
+}
+
+function* eventsFromEntry(
+  entry: unknown,
+  pending: Map<string, { name: string; startTs: number }>,
+): Iterable<InspectEvent> {
+  const meta = readSessionMeta(entry)
+  if (meta !== null) {
+    yield { cat: 'meta', ts: numberOr(readField(entry, 'timestamp'), 0), origin: meta }
+    return
+  }
+  if (!isMessageEntry(entry)) return
+  const message = entry.message
+  const role = message.role
+  const ts = numberOr(readField(message, 'timestamp'), 0)
+  if (role === 'user') {
+    const text = readTextContent(message.content)
+    if (text !== null) yield { cat: 'user', ts, text }
+    return
+  }
+  if (role === 'assistant') {
+    yield* assistantEvents(message as AssistantMessage, ts, pending)
+    return
+  }
+}
+
+function* assistantEvents(
+  message: AssistantMessage,
+  ts: number,
+  pending: Map<string, { name: string; startTs: number }>,
+): Iterable<InspectEvent> {
+  const text = readTextContent(message.content)
+  if (text !== null && text !== '') {
+    const ev: InspectEvent = {
+      cat: 'assistant',
+      ts,
+      text,
+      ...(typeof message.provider === 'string' ? { provider: message.provider } : {}),
+      ...(typeof message.model === 'string' ? { model: message.model } : {}),
+    }
+    yield ev
+  }
+  if (Array.isArray(message.content)) {
+    for (const block of message.content) {
+      const callEvents = readToolCall(block, ts)
+      for (const ev of callEvents) {
+        if (ev.cat === 'tool' && ev.phase === 'start') pending.set(ev.toolCallId, { name: ev.name, startTs: ev.ts })
+        yield ev
+      }
+      const resultEvents = readToolResult(block, ts, pending)
+      yield* resultEvents
+    }
+  }
+  if (typeof message.errorMessage === 'string' && message.errorMessage !== '') {
+    yield { cat: 'error', ts, message: message.errorMessage }
+  }
+  const usage = readUsage(message.usage)
+  if (usage !== null && (usage.totalTokens > 0 || typeof message.stopReason === 'string')) {
+    yield {
+      cat: 'done',
+      ts,
+      ...(typeof message.stopReason === 'string' ? { stopReason: message.stopReason } : {}),
+      ...usage,
+    }
+  }
+}
+
+function readToolCall(block: unknown, ts: number): InspectEvent[] {
+  if (typeof block !== 'object' || block === null) return []
+  const b = block as Record<string, unknown>
+  if (b.type !== 'toolCall') return []
+  const toolCallId = typeof b.id === 'string' ? b.id : null
+  const name = typeof b.name === 'string' ? b.name : null
+  if (toolCallId === null || name === null) return []
+  return [
+    {
+      cat: 'tool',
+      ts,
+      phase: 'start',
+      toolCallId,
+      name,
+      ...(b.arguments !== undefined ? { args: b.arguments } : {}),
+    },
+  ]
+}
+
+function readToolResult(
+  block: unknown,
+  ts: number,
+  pending: Map<string, { name: string; startTs: number }>,
+): InspectEvent[] {
+  if (typeof block !== 'object' || block === null) return []
+  const b = block as Record<string, unknown>
+  if (b.type !== 'toolResult') return []
+  const toolCallId = typeof b.toolCallId === 'string' ? b.toolCallId : null
+  if (toolCallId === null) return []
+  const entry = pending.get(toolCallId)
+  pending.delete(toolCallId)
+  const name = entry?.name ?? (typeof b.name === 'string' ? b.name : 'unknown')
+  const durationMs = entry !== undefined ? Math.max(0, ts - entry.startTs) : 0
+  const isError = b.isError === true
+  return [
+    {
+      cat: 'tool',
+      ts,
+      phase: 'end',
+      toolCallId,
+      name,
+      ...(b.output !== undefined ? { result: b.output } : {}),
+      isError,
+      durationMs,
+    },
+  ]
+}
+
+function readUsage(value: unknown): {
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+  totalTokens: number
+  cost: number
+} | null {
+  if (typeof value !== 'object' || value === null) return null
+  const u = value as Record<string, unknown>
+  const cost = u.cost as Record<string, unknown> | undefined
+  return {
+    input: numberOr(u.input, 0),
+    output: numberOr(u.output, 0),
+    cacheRead: numberOr(u.cacheRead, 0),
+    cacheWrite: numberOr(u.cacheWrite, 0),
+    totalTokens: numberOr(u.totalTokens, 0),
+    cost: numberOr(cost?.total, 0),
+  }
+}
+
+function readTextContent(content: unknown): string | null {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return null
+  const parts: string[] = []
+  for (const block of content) {
+    if (typeof block !== 'object' || block === null) continue
+    const b = block as Record<string, unknown>
+    if (b.type === 'text' && typeof b.text === 'string') parts.push(b.text)
+  }
+  if (parts.length === 0) return null
+  return parts.join('')
+}
+
+type AssistantMessage = {
+  role: 'assistant'
+  content?: unknown
+  provider?: unknown
+  model?: unknown
+  usage?: unknown
+  errorMessage?: unknown
+  stopReason?: unknown
+}
+
+function isMessageEntry(value: unknown): value is { type: 'message'; message: { role: string; [k: string]: unknown } } {
+  if (typeof value !== 'object' || value === null) return false
+  const v = value as Record<string, unknown>
+  if (v.type !== 'message') return false
+  if (typeof v.message !== 'object' || v.message === null) return false
+  const m = v.message as Record<string, unknown>
+  return typeof m.role === 'string'
+}
+
+function readSessionMeta(value: unknown): MinimalSessionOrigin | null {
+  if (typeof value !== 'object' || value === null) return null
+  const v = value as Record<string, unknown>
+  if (v.type !== 'custom') return null
+  if (v.customType !== SESSION_META_CUSTOM_TYPE) return null
+  if (typeof v.data !== 'object' || v.data === null) return null
+  const d = v.data as Record<string, unknown>
+  if (typeof d.origin !== 'object' || d.origin === null) return null
+  const o = d.origin as Record<string, unknown>
+  if (typeof o.kind !== 'string') return null
+  return d.origin as MinimalSessionOrigin
+}
+
+function readField(value: unknown, key: string): unknown {
+  if (typeof value !== 'object' || value === null) return undefined
+  return (value as Record<string, unknown>)[key]
+}
+
+function numberOr(value: unknown, fallback: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback
+  return value
+}
+
+function describeErr(err: unknown): string {
+  if (err instanceof Error) return err.message
+  return String(err)
+}
+
+async function* streamLines(stream: ReadableStream<Uint8Array>): AsyncGenerator<string> {
+  const decoder = new TextDecoder()
+  let buf = ''
+  for await (const chunk of stream) {
+    buf += decoder.decode(chunk, { stream: true })
+    let nl = buf.indexOf('\n')
+    while (nl !== -1) {
+      const line = buf.slice(0, nl)
+      buf = buf.slice(nl + 1)
+      yield line
+      nl = buf.indexOf('\n')
+    }
+  }
+  if (buf.length > 0) yield buf
+}

package/src/inspect/session-list.ts

@@ -0,0 +1,160 @@
+import { readdir, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import type { MinimalSessionOrigin } from '@/agent/session-meta'
+
+import { replayJsonl } from './replay'
+
+export type SessionSummary = {
+  sessionId: string
+  sessionFile: string
+  basename: string
+  mtimeMs: number
+  origin: MinimalSessionOrigin | null
+  firstPrompt: string | null
+}
+
+export type ListSessionsOptions = {
+  sessionsDir: string
+  limit?: number
+  sinceMs?: number
+  onWarn?: (msg: string) => void
+}
+
+// pi-coding-agent writes session files as `${ISO_TIMESTAMP}_${SESSION_ID}.jsonl`,
+// where SESSION_ID is a UUIDv7 by default. Older typeclaw versions (pre-May
+// 2026, before the channel session-file basename was persisted) also produced
+// bare `${SESSION_ID}.jsonl` files; legacy agent folders still carry those
+// alongside the canonical form, and skipping them hides real history from
+// `typeclaw inspect`. Accept both shapes: take whatever follows the last `_`
+// as the id, or the whole stem when no `_` is present. The id must be
+// filesystem-safe (no `/`, `\`, or whitespace) and must start with a non-`_`
+// character so empty-id filenames like `_.jsonl` don't slip through.
+const FILENAME_PATTERN = /^(?:.*_)?([^_/\\\s][^/\\\s]*)\.jsonl$/
+
+export async function listSessions(opts: ListSessionsOptions): Promise<SessionSummary[]> {
+  const entries = await readSessionFiles(opts.sessionsDir, opts.onWarn)
+  const withStats = await Promise.all(
+    entries.map(async (entry) => {
+      const s = await safeStat(entry.path)
+      if (s === null) return null
+      const mtimeMs = s.mtimeMs
+      if (opts.sinceMs !== undefined && mtimeMs < opts.sinceMs) return null
+      return { ...entry, mtimeMs }
+    }),
+  )
+  const valid = withStats.filter(
+    (v): v is { path: string; basename: string; sessionId: string; mtimeMs: number } => v !== null,
+  )
+  valid.sort((a, b) => b.mtimeMs - a.mtimeMs)
+  const limited = opts.limit !== undefined ? valid.slice(0, opts.limit) : valid
+
+  return Promise.all(
+    limited.map(async ({ path, basename, sessionId, mtimeMs }) => {
+      const peek = await peekSession(path, opts.onWarn)
+      return {
+        sessionId,
+        sessionFile: path,
+        basename,
+        mtimeMs,
+        origin: peek.origin,
+        firstPrompt: peek.firstPrompt,
+      }
+    }),
+  )
+}
+
+export type ResolveResult =
+  | { ok: true; summary: SessionSummary }
+  | { ok: false; reason: 'not-found' | 'ambiguous'; matches: SessionSummary[] }
+
+const MIN_PREFIX_LENGTH = 4
+
+export async function resolveSession(
+  sessionsDir: string,
+  sessionIdOrPrefix: string,
+  onWarn?: (msg: string) => void,
+): Promise<ResolveResult> {
+  const all = await listSessions({ sessionsDir, ...(onWarn !== undefined ? { onWarn } : {}) })
+  const exact = all.find((s) => s.sessionId === sessionIdOrPrefix)
+  if (exact !== undefined) return { ok: true, summary: exact }
+
+  if (sessionIdOrPrefix.length < MIN_PREFIX_LENGTH || !isSessionIdShape(sessionIdOrPrefix)) {
+    return { ok: false, reason: 'not-found', matches: [] }
+  }
+  const prefixMatches = all.filter((s) => s.sessionId.startsWith(sessionIdOrPrefix))
+  if (prefixMatches.length === 0) return { ok: false, reason: 'not-found', matches: [] }
+  if (prefixMatches.length === 1) return { ok: true, summary: prefixMatches[0]! }
+  return { ok: false, reason: 'ambiguous', matches: prefixMatches }
+}
+
+const SESSION_ID_SHAPE = /^[^_/\\\s][^/\\\s]*$/
+
+export function isSessionIdShape(value: string): boolean {
+  return SESSION_ID_SHAPE.test(value)
+}
+
+async function readSessionFiles(
+  dir: string,
+  onWarn?: (msg: string) => void,
+): Promise<{ path: string; basename: string; sessionId: string }[]> {
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true, encoding: 'utf8' })
+  } catch (err) {
+    if (isNoEnt(err)) return []
+    throw err
+  }
+  const out: { path: string; basename: string; sessionId: string }[] = []
+  for (const entry of entries) {
+    const name = entry.name
+    if (!name.endsWith('.jsonl')) continue
+    if (!entry.isFile() && !entry.isSymbolicLink()) {
+      onWarn?.(`skipping non-file in sessions/: ${name}`)
+      continue
+    }
+    const match = FILENAME_PATTERN.exec(name)
+    if (!match) {
+      onWarn?.(`skipping session file with unexpected name: ${name}`)
+      continue
+    }
+    out.push({ path: join(dir, name), basename: name, sessionId: match[1]! })
+  }
+  return out
+}
+
+async function safeStat(path: string): Promise<{ mtimeMs: number } | null> {
+  try {
+    const s = await stat(path)
+    return { mtimeMs: s.mtimeMs }
+  } catch {
+    return null
+  }
+}
+
+const PREVIEW_MAX_BYTES = 64 * 1024
+
+async function peekSession(
+  path: string,
+  onWarn?: (msg: string) => void,
+): Promise<{ origin: MinimalSessionOrigin | null; firstPrompt: string | null }> {
+  let origin: MinimalSessionOrigin | null = null
+  let firstPrompt: string | null = null
+  let bytesRead = 0
+  for await (const event of replayJsonl(path, onWarn !== undefined ? { onWarn } : {})) {
+    if (event.cat === 'meta' && origin === null) origin = event.origin
+    if (event.cat === 'user' && firstPrompt === null) firstPrompt = event.text
+    if (origin !== null && firstPrompt !== null) break
+    bytesRead += approximateSize(event)
+    if (bytesRead > PREVIEW_MAX_BYTES) break
+  }
+  return { origin, firstPrompt }
+}
+
+function approximateSize(event: { ts: number }): number {
+  return JSON.stringify(event).length
+}
+
+function isNoEnt(err: unknown): boolean {
+  return typeof err === 'object' && err !== null && (err as { code?: unknown }).code === 'ENOENT'
+}

package/src/inspect/types.ts

@@ -0,0 +1,110 @@
+import type { MinimalSessionOrigin } from '@/agent/session-meta'
+
+export const INSPECT_CATEGORIES = [
+  'meta',
+  'user',
+  'assistant',
+  'tool',
+  'error',
+  'done',
+  'broadcast',
+  'cron-fire',
+] as const
+export type InspectCategory = (typeof INSPECT_CATEGORIES)[number]
+
+export type InspectEvent =
+  | { cat: 'meta'; ts: number; origin: MinimalSessionOrigin }
+  | { cat: 'user'; ts: number; text: string }
+  | { cat: 'assistant'; ts: number; text: string; provider?: string; model?: string }
+  | {
+      cat: 'tool'
+      ts: number
+      phase: 'start' | 'end'
+      toolCallId: string
+      name: string
+      args?: unknown
+      result?: unknown
+      isError?: boolean
+      durationMs?: number
+    }
+  | { cat: 'error'; ts: number; message: string }
+  | {
+      cat: 'done'
+      ts: number
+      stopReason?: string
+      input: number
+      output: number
+      cacheRead: number
+      cacheWrite: number
+      totalTokens: number
+      cost: number
+    }
+  | { cat: 'broadcast'; ts: number; payload: unknown; meta?: Record<string, string> }
+  | { cat: 'cron-fire'; ts: number; jobId: string; payload: unknown }
+
+export type InspectFilter = {
+  include?: ReadonlySet<InspectCategory>
+  exclude?: ReadonlySet<InspectCategory>
+}
+
+export type ParsedFilterResult = { ok: true; filter: InspectFilter } | { ok: false; reason: string }
+
+export function parseFilter(spec: string | undefined): ParsedFilterResult {
+  if (spec === undefined || spec.trim() === '') return { ok: true, filter: {} }
+  const include = new Set<InspectCategory>()
+  const exclude = new Set<InspectCategory>()
+  for (const raw of spec.split(',')) {
+    const token = raw.trim()
+    if (token === '') continue
+    const negated = token.startsWith('!')
+    const name = (negated ? token.slice(1) : token).toLowerCase()
+    if (!isInspectCategory(name)) {
+      return { ok: false, reason: `unknown filter category "${name}" (valid: ${INSPECT_CATEGORIES.join(', ')})` }
+    }
+    if (negated) exclude.add(name)
+    else include.add(name)
+  }
+  const filter: InspectFilter = {}
+  if (include.size > 0) filter.include = include
+  if (exclude.size > 0) filter.exclude = exclude
+  return { ok: true, filter }
+}
+
+export function matchesFilter(event: InspectEvent, filter: InspectFilter): boolean {
+  if (filter.exclude?.has(event.cat)) return false
+  if (filter.include !== undefined && !filter.include.has(event.cat)) return false
+  return true
+}
+
+function isInspectCategory(value: string): value is InspectCategory {
+  return (INSPECT_CATEGORIES as readonly string[]).includes(value)
+}
+
+const DURATION_PATTERN = /^(\d+)(s|m|h|d)$/
+
+export type ParsedDurationResult = { ok: true; ms: number } | { ok: false; reason: string }
+
+export function parseDuration(spec: string): ParsedDurationResult {
+  const match = DURATION_PATTERN.exec(spec.trim())
+  if (!match) return { ok: false, reason: `invalid duration "${spec}" (expected forms: 30s, 5m, 1h, 7d)` }
+  const value = Number(match[1])
+  const unit = match[2]
+  let mult: number
+  switch (unit) {
+    case 's':
+      mult = 1000
+      break
+    case 'm':
+      mult = 60_000
+      break
+    case 'h':
+      mult = 3_600_000
+      break
+    case 'd':
+      mult = 86_400_000
+      break
+    default:
+      return { ok: false, reason: `invalid duration unit "${unit}"` }
+  }
+  return { ok: true, ms: value * mult }
+}

package/src/plugin/hooks.ts

@@ -31,6 +31,21 @@ export const IDLE_HANDLER_TIMEOUT_MS = 25_000
 // legitimate transcript flush while still bounding the failure mode.
 export const END_HANDLER_TIMEOUT_MS = 60_000
 
+// Per-handler ceiling for session.prompt. session.prompt fires
+// synchronously inside createResourceLoader (src/agent/index.ts), which on
+// channel-origin cold start is itself inside ensureLive's 30s watchdog
+// (src/channels/router.ts). An unbounded hook there silently consumes the
+// outer budget and times out without naming the offending plugin in the
+// logs. 20s leaves ~10s of headroom for the rest of the cold-start chain
+// (loadSelf, loadMemory shard reads, prefetchChannelContext) before
+// ensureLive fires.
+//
+// The bundled memory plugin's session.prompt fires memory-retrieval
+// detached, so it returns in <1ms in steady state; this ceiling guards
+// third-party hooks that legitimately need to do work inline, AND a
+// regression in the memory plugin that re-introduces an inline await.
+export const PROMPT_HANDLER_TIMEOUT_MS = 20_000
+
 export type RegisteredHook<K extends keyof Hooks> = {
   pluginName: string
   agentDir: string
@@ -59,6 +74,8 @@ export type CreateHookBusOptions = {
   idleHandlerTimeoutMs?: number
   // Test seam: per-handler ceiling for session.end invocations.
   endHandlerTimeoutMs?: number
+  // Test seam: per-handler ceiling for session.prompt invocations.
+  promptHandlerTimeoutMs?: number
 }
 
 type Registries = {
@@ -75,6 +92,7 @@ type Registries = {
 export function createHookBus(options: CreateHookBusOptions = {}): HookBus {
   const idleHandlerTimeoutMs = options.idleHandlerTimeoutMs ?? IDLE_HANDLER_TIMEOUT_MS
   const endHandlerTimeoutMs = options.endHandlerTimeoutMs ?? END_HANDLER_TIMEOUT_MS
+  const promptHandlerTimeoutMs = options.promptHandlerTimeoutMs ?? PROMPT_HANDLER_TIMEOUT_MS
   const r: Registries = {
     'session.start': [],
     'session.end': [],
@@ -155,7 +173,11 @@ export function createHookBus(options: CreateHookBusOptions = {}): HookBus {
     async runSessionPrompt(event) {
       for (const reg of r['session.prompt']) {
         try {
-          await reg.handler(event, ctx(reg))
+          await raceWithTimeout(
+            Promise.resolve(reg.handler(event, ctx(reg))),
+            promptHandlerTimeoutMs,
+            `plugin ${reg.pluginName} session.prompt`,
+          )
         } catch (err) {
           reportHookError(reg, 'session.prompt', err)
         }

package/src/plugin/index.ts

@@ -50,6 +50,8 @@ export type {
   SessionIdleEvent,
   SessionPromptEvent,
   SessionStartEvent,
+  SessionTurnEndEvent,
+  SessionTurnStartEvent,
   SpawnSubagentOptions,
   Subagent,
   SubagentContext,

package/src/plugin/manager.ts

@@ -101,7 +101,7 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
       config: validatedConfig as never,
       logger,
       permissions,
-      spawnSubagent: (name, payload) => spawnSubagentImpl(name, payload),
+      spawnSubagent: (name, payload, options) => spawnSubagentImpl(name, payload, options),
       isBooted: () => booted,
     })
 

package/src/plugin/registry.ts

@@ -224,7 +224,7 @@ function toCronJob(globalId: string, spec: PluginCronJob): CronJob {
   // Plugin-contributed jobs default to `owner` because they are part of the
   // agent's bundled (or operator-installed) runtime, not user-channel
   // schedules. Without this default they would resolve to `guest` and the
-  // bundled memory dreaming cron (which writes MEMORY.md, runs git, etc.)
+  // bundled memory dreaming cron (which writes memory/topics/, runs git, etc.)
   // would lose every security bypass. Hand-authored cron.json entries take
   // a different path and must declare scheduledByRole explicitly.
   const scheduledByRole: PromptJob['scheduledByRole'] = 'owner'

package/src/plugin/types.ts

@@ -167,9 +167,19 @@ export type SessionIdleEvent = {
 // don't wedge a turn-counter forever. `origin` carries the session's origin
 // so observers can exclude their own induced turns when counting (e.g. the
 // backup plugin excludes `subagent: 'backup'` to avoid self-gating).
+//
+// `userPrompt` is the EXACT text being passed to `session.prompt(text)` —
+// the user's message for TUI/channel turns, the cron job's prompt for cron
+// turns, or the rendered initial prompt for subagent turns. Distinct from
+// `SessionPromptEvent.prompt` (the assembling system prompt for cache-safe
+// suffix mutation at session creation time). Channel adapters that prefix
+// inbound text with attribution headers (`[Alice in #general]:`) pass the
+// prefixed string here, matching what `session.prompt(text)` receives;
+// observers that need the unattributed text would need a separate hook.
 export type SessionTurnStartEvent = {
   sessionId: string
   agentDir: string
+  userPrompt: string
   origin?: SessionOrigin
 }
 

package/src/run/channel-session-factory.ts

@@ -1,6 +1,7 @@
 import { SessionManager } from '@mariozechner/pi-coding-agent'
 
 import { createSession as defaultCreateSession } from '@/agent'
+import type { LiveSessionRegistry } from '@/agent/live-sessions'
 import type { LiveSubagentRegistry } from '@/agent/live-subagents'
 import type { CreateSessionForSubagent, SubagentRegistry } from '@/agent/subagents'
 import { capJsonlFileInPlace } from '@/bundled-plugins/tool-result-cap/cap-jsonl'
@@ -62,6 +63,7 @@ export type BuildChannelSessionFactoryDeps = {
   liveSubagentRegistry?: LiveSubagentRegistry
   subagentRegistry?: SubagentRegistry
   getCreateSessionForSubagent?: () => CreateSessionForSubagent
+  liveSessionRegistry?: LiveSessionRegistry
 }
 
 // Tight basename validation so a tampered or corrupt channels/sessions.json
@@ -129,10 +131,14 @@ export function buildChannelSessionFactory(deps: BuildChannelSessionFactoryDeps)
         : {}),
     })
 
+    const sessionId = sessionManager.getSessionId()
+    deps.liveSessionRegistry?.register({ sessionId, session })
+
     return {
       session,
-      sessionId: sessionManager.getSessionId(),
+      sessionId,
       dispose: async () => {
+        deps.liveSessionRegistry?.unregister(sessionId)
         session.dispose()
       },
       ...(snap.hasAnyPluginContent ? { hooks: snap.hooks } : {}),