typeclaw 0.9.0 → 0.9.2

package/src/bundled-plugins/memory/README.md

@@ -28,17 +28,17 @@ All fields are **restart-required** — the plugin reads them once at boot.
 
 ## What it contributes
 
-| Kind     | Name                       | Notes                                                                                                                                                                                                                                                                                             |
-| -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Subagent | `memory-logger`            | Reads a parent transcript past a watermark and appends fragments to `memory/streams/<today>.jsonl`. Coalesced per `agentDir`.                                                                                                                                                                     |
-| Subagent | `dreaming`                 | Reads shards under `memory/topics/` plus undreamed daily-stream events and rebalances the topic shards. Coalesced per `agentDir`. Citation-superset invariant enforced on every run.                                                                                                              |
-| Subagent | `memory-retrieval`         | On `session.turn.start` when injection plan is `index` mode, reads the user's actual prompt for this turn + shard listing, writes a focused summary to `memory/.retrieval-cache/<sessionId>.md`. Coalesced per `parentSessionId`.                                                                 |
-| Tool     | `memory_search`            | Main-agent tool. Substring/regex search across BOTH topic shards (slugs, frontmatter, bodies) and undreamed daily-stream events (fragment topic/body, legacy prose). Results are discriminated by `source: "topic" \| "stream"`; topics come first, then streams newest-first.                    |
-| Tool     | `delete_topic_shard`       | Subagent-only (dreaming). Deletes a topic shard at `memory/topics/<slug>.md`. Path-guarded.                                                                                                                                                                                                       |
-| Cron     | `__plugin_memory_dreaming` | `kind: 'prompt'`, `subagent: 'dreaming'`, scheduled per `memory.dreaming.schedule`.                                                                                                                                                                                                               |
-| Hook     | `session.idle`             | Per-session debouncer with size-based ceiling. Spawns `memory-logger` on idle or buffer-trip.                                                                                                                                                                                                     |
-| Hook     | `session.end`              | Spawns `memory-logger` immediately; also unlinks the retrieval-cache file for this session.                                                                                                                                                                                                       |
-| Hook     | `session.turn.start`       | When `buildInjectionPlan` returns `mode: 'index'` and origin is not a subagent, spawns `memory-retrieval` (detached) with the turn's `userPrompt` so the cache reflects the user's current question, not the assembling system prompt. Fire-and-forget; failures route through the plugin logger. |
+| Kind     | Name                       | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| -------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Subagent | `memory-logger`            | Reads a parent transcript past a watermark and appends fragments to `memory/streams/<today>.jsonl`. Coalesced per `agentDir`.                                                                                                                                                                                                                                                                                                                                              |
+| Subagent | `dreaming`                 | Reads shards under `memory/topics/` plus undreamed daily-stream events and rebalances the topic shards. Coalesced per `agentDir`. Citation-superset invariant enforced on every run.                                                                                                                                                                                                                                                                                       |
+| Subagent | `memory-retrieval`         | On `session.turn.start` when injection plan is `index` mode, reads the user's actual prompt for this turn + shard listing, writes a focused summary to `memory/.retrieval-cache/<sessionId>.md`. Coalesced per `parentSessionId`. Declares `profile: 'fast'` (retrieval is "≤3 keyword searches + 1 write", no reasoning required) and `timeoutMs: 30_000` so a wedged provider call releases the coalescing key instead of poisoning the cache for every subsequent turn. |
+| Tool     | `memory_search`            | Main-agent tool. Substring/regex search across BOTH topic shards (slugs, frontmatter, bodies) and undreamed daily-stream events (fragment topic/body, legacy prose). Results are discriminated by `source: "topic" \| "stream"`; topics come first, then streams newest-first.                                                                                                                                                                                             |
+| Tool     | `delete_topic_shard`       | Subagent-only (dreaming). Deletes a topic shard at `memory/topics/<slug>.md`. Path-guarded.                                                                                                                                                                                                                                                                                                                                                                                |
+| Cron     | `__plugin_memory_dreaming` | `kind: 'prompt'`, `subagent: 'dreaming'`, scheduled per `memory.dreaming.schedule`.                                                                                                                                                                                                                                                                                                                                                                                        |
+| Hook     | `session.idle`             | Per-session debouncer with size-based ceiling. Spawns `memory-logger` on idle or buffer-trip.                                                                                                                                                                                                                                                                                                                                                                              |
+| Hook     | `session.end`              | Spawns `memory-logger` immediately; also unlinks the retrieval-cache file for this session.                                                                                                                                                                                                                                                                                                                                                                                |
+| Hook     | `session.turn.start`       | When `buildInjectionPlan` returns `mode: 'index'` and origin is not a subagent, spawns `memory-retrieval` (detached) with the turn's `userPrompt` so the cache reflects the user's current question, not the assembling system prompt. Fire-and-forget; failures route through the plugin logger.                                                                                                                                                                          |
 
 ## Memory injection (two-tier, topic shards only)
 

package/src/bundled-plugins/memory/dreaming-state.ts

@@ -1,11 +1,29 @@
 import { existsSync } from 'node:fs'
-import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 
 export const DREAMING_STATE_FILE = 'memory/.dreaming-state.json'
 
 const VERSION = 2
 
+// Stat-keyed cache for `.dreaming-state.json`. The file is read once at
+// the start of every dreaming run AND once per `readAllStreamDays` call
+// (which fires inside every `memory_search` invocation). For a retrieval
+// subagent that issues 3 parallel searches, this cache turns 3 reads +
+// 3 JSON.parses into 3 stats + 1 parse — small per-call savings, but the
+// file is tiny so the win is mostly avoiding GC pressure on busy
+// channel sessions. Invalidation key matches the stream-file cache
+// (`load-shards.ts` and `stream-io.ts` use the same `(mtimeMs, ctimeMs,
+// size)` shape); `saveDreamingState` uses `writeFile` which bumps both
+// mtime and ctime.
+type DreamingStateCacheEntry = {
+  mtimeMs: number
+  ctimeMs: number
+  size: number
+  state: DreamingState
+}
+const dreamingStateCache = new Map<string, DreamingStateCacheEntry>()
+
 // Per-day "dreamed" set: the set of stream-event ids dreaming has already
 // reasoned over for a given day. Anything in this set is either cited from
 // memory/topics/ (must survive compaction) or was consciously discarded by a
@@ -32,8 +50,35 @@ export function emptyState(): DreamingState {
 
 export async function loadDreamingState(agentDir: string): Promise<DreamingState> {
   const path = join(agentDir, DREAMING_STATE_FILE)
-  if (!existsSync(path)) return emptyState()
+  if (!existsSync(path)) {
+    dreamingStateCache.delete(path)
+    return emptyState()
+  }
 
+  let fileStat: { mtimeMs: number; ctimeMs: number; size: number }
+  try {
+    const s = await stat(path)
+    fileStat = { mtimeMs: s.mtimeMs, ctimeMs: s.ctimeMs, size: s.size }
+  } catch {
+    return emptyState()
+  }
+
+  const cached = dreamingStateCache.get(path)
+  if (
+    cached !== undefined &&
+    cached.mtimeMs === fileStat.mtimeMs &&
+    cached.ctimeMs === fileStat.ctimeMs &&
+    cached.size === fileStat.size
+  ) {
+    return cached.state
+  }
+
+  const state = await loadDreamingStateFromDisk(path)
+  dreamingStateCache.set(path, { ...fileStat, state })
+  return state
+}
+
+async function loadDreamingStateFromDisk(path: string): Promise<DreamingState> {
   let raw: string
   try {
     raw = await readFile(path, 'utf8')
@@ -58,6 +103,10 @@ export async function saveDreamingState(agentDir: string, state: DreamingState):
   await writeFile(path, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
 }
 
+export function __resetDreamingStateCacheForTests(): void {
+  dreamingStateCache.clear()
+}
+
 export function getDreamedIds(state: DreamingState, date: string): ReadonlySet<string> {
   const ids = state.dreamedThrough[date]?.dreamedIds
   return ids === undefined ? EMPTY_SET : new Set(ids)

package/src/bundled-plugins/memory/index.ts

@@ -27,6 +27,17 @@ const MIN_BUFFER_BYTES = 10_000
 // sporadic agents entirely. Operators can override via `memory.dreaming.schedule`.
 const DEFAULT_DREAMING_SCHEDULE = '*/30 * * * *'
 
+// memory-retrieval's ceiling, enforced by the orchestration layer (see
+// `awaitWithSubagentTimeout` in @/agent/subagents). 30s is sized for the
+// declared workload — up to 3 `memory_search` calls + 1 `write` against a
+// `fast`-profile model. The 5+ minute outliers observed in the wild
+// (reasoning-model cold-start on the default profile) require either a
+// genuinely wedged provider, a misconfigured profile that routes retrieval
+// to a reasoning model anyway, or both. In all three cases, releasing the
+// coalescing key after 30s lets the next channel turn spawn a fresh
+// retrieval instead of staying skip-coalesced behind the stuck one.
+const RETRIEVAL_SPAWN_TIMEOUT_MS = 30_000
+
 // Hard ceiling on a single memory-logger spawn. The chain serializes spawns
 // per agent, so a non-settling spawn would otherwise wedge every subsequent
 // fire — including the session.end hook path that gates cron consumer's
@@ -86,6 +97,11 @@ const memoryConfigSchema = z
     // the timeout in milliseconds instead of the production 50s. Kept
     // undocumented for users.
     spawnTimeoutMs: z.number().int().min(1).default(SPAWN_TIMEOUT_MS),
+    // Test seam: per-spawn ceiling for memory-retrieval. Same rationale as
+    // `spawnTimeoutMs` — operators have no reason to tune this; it exists
+    // so the wedge-recovery test for memory-retrieval can fire the timeout
+    // in milliseconds instead of the production 30s.
+    retrievalSpawnTimeoutMs: z.number().int().min(1).default(RETRIEVAL_SPAWN_TIMEOUT_MS),
     dreaming: dreamingConfigSchema.optional(),
   })
   .default({
@@ -93,6 +109,7 @@ const memoryConfigSchema = z
     bufferBytes: DEFAULT_BUFFER_BYTES,
     injectionBudgetBytes: DEFAULT_INJECTION_BUDGET_BYTES,
     spawnTimeoutMs: SPAWN_TIMEOUT_MS,
+    retrievalSpawnTimeoutMs: RETRIEVAL_SPAWN_TIMEOUT_MS,
   })
 
 export default definePlugin({
@@ -101,6 +118,7 @@ export default definePlugin({
     const idleMs = ctx.config.idleMs
     const bufferBytes = ctx.config.bufferBytes
     const spawnTimeoutMs = ctx.config.spawnTimeoutMs
+    const retrievalSpawnTimeoutMs = ctx.config.retrievalSpawnTimeoutMs
     const dreamingSchedule = ctx.config.dreaming?.schedule ?? DEFAULT_DREAMING_SCHEDULE
 
     const migrationResult = await runMigration({
@@ -127,39 +145,46 @@ export default definePlugin({
     const lastIdleEvent = new Map<string, { parentTranscriptPath: string | undefined; origin?: SessionOrigin }>()
     const bytesAtLastRun = new Map<string, number>()
 
-    // memory-logger is now coalesced per agentDir (not per parentSessionId) so that
+    // memory-logger is coalesced per agentDir (not per parentSessionId) so that
     // two concurrent channel sessions for the same agent never write to the same
     // daily stream file at the same time. The subagent consumer would silently drop
     // a colliding fire, so we serialize spawn calls *here* (chaining each onto the
     // previous one's settlement) instead of letting the consumer choose between
     // dropping or queueing. The chain holds at most one in-flight promise plus one
-    // queued; older queued fires for the same session are superseded by newer ones
-    // through the lastIdleEvent map (each fire reads the latest snapshot).
+    // queued.
+    //
+    // The `lastIdleEvent` lookup happens SYNCHRONOUSLY at call time and the
+    // snapshot is captured in `payload` before any await. This is load-bearing
+    // for `session.end`'s fire-and-forget path (see hook below): the hook
+    // synchronously cleans up `lastIdleEvent.delete(sessionId)` immediately
+    // after calling fireMemoryLogger, so if the snapshot were read lazily
+    // inside the chained `.then`, it would race with cleanup and the spawn
+    // would silently no-op. Capturing the payload up front decouples the
+    // session-end snapshot from the cleanup that follows.
     let spawnChain: Promise<void> = Promise.resolve()
 
     const fireMemoryLogger = (sessionId: string, reason: 'idle' | 'buffer-trip' | 'session-end'): Promise<void> => {
+      const last = lastIdleEvent.get(sessionId)
+      if (!last || last.parentTranscriptPath === undefined) return Promise.resolve()
+      const parentTranscriptPath = last.parentTranscriptPath
+      const payload: MemoryLoggerPayload = {
+        parentSessionId: sessionId,
+        parentTranscriptPath,
+        agentDir: ctx.agentDir,
+        ...(last.origin !== undefined ? { origin: last.origin } : {}),
+      }
+      const spawnOptions = {
+        parentSessionId: sessionId,
+        ...(last.origin !== undefined ? { spawnedByOrigin: last.origin } : {}),
+      }
       const next = spawnChain
         .catch(() => undefined)
         .then(async () => {
-          const last = lastIdleEvent.get(sessionId)
-          if (!last || last.parentTranscriptPath === undefined) return
-          const payload: MemoryLoggerPayload = {
-            parentSessionId: sessionId,
-            parentTranscriptPath: last.parentTranscriptPath,
-            agentDir: ctx.agentDir,
-            ...(last.origin !== undefined ? { origin: last.origin } : {}),
-          }
-          const currentSize = await readSize(last.parentTranscriptPath)
+          const currentSize = await readSize(parentTranscriptPath)
           bytesAtLastRun.set(sessionId, currentSize)
           ctx.logger.info(`memory-logger spawn ${sessionId} reason=${reason} transcript_bytes=${currentSize}`)
           try {
-            await raceSpawn(
-              ctx.spawnSubagent('memory-logger', payload, {
-                parentSessionId: sessionId,
-                ...(last.origin !== undefined ? { spawnedByOrigin: last.origin } : {}),
-              }),
-              spawnTimeoutMs,
-            )
+            await raceSpawn(ctx.spawnSubagent('memory-logger', payload, spawnOptions), spawnTimeoutMs)
           } catch (err) {
             ctx.logger.error(`memory-logger spawn failed: ${err instanceof Error ? err.message : String(err)}`)
           }
@@ -224,7 +249,10 @@ export default definePlugin({
     return {
       subagents: {
         'memory-logger': createMemoryLoggerSubagent({ logger: subagentLogger }),
-        'memory-retrieval': createMemoryRetrievalSubagent({ logger: subagentLogger }),
+        'memory-retrieval': createMemoryRetrievalSubagent({
+          logger: subagentLogger,
+          timeoutMs: retrievalSpawnTimeoutMs,
+        }),
         dreaming: createDreamingSubagent({ logger: subagentLogger }),
       },
       tools: {
@@ -334,16 +362,39 @@ export default definePlugin({
             ctx.logger.error(`memory-retrieval spawn failed: ${err instanceof Error ? err.message : String(err)}`)
           })
         },
-        'session.end': async (event) => {
+        // The memory-logger spawn is intentionally detached (`void`) instead
+        // of awaited. The channel router calls `tearDownLive` synchronously
+        // inside `ensureLive`'s stale-rollover path (router.ts:718), and
+        // `tearDownLive` awaits `fireSessionEnd` which awaits this hook. An
+        // awaited memory-logger spawn here would block new-session creation
+        // for the full subagent runtime — observed as 22+ seconds of channel
+        // silence on a 22 KB transcript before the new session even starts
+        // its cold-start chain.
+        //
+        // Safety: `fireMemoryLogger` captures the payload synchronously from
+        // `lastIdleEvent` (see comment above), so the `delete` calls below
+        // cannot race with the chained spawn. `spawnChain` still serializes
+        // memory-logger fires per agentDir — the detached promise is queued
+        // onto the chain before this hook returns, so a subsequent fire from
+        // the new session (idle, buffer-trip, or session-end) waits for the
+        // session-end spawn to settle before running.
+        //
+        // The only durability tradeoff: if the agent process dies between
+        // this hook returning and `spawnChain` settling, the session-end
+        // memory-logger fire is lost (its transcript fragments don't make
+        // it into today's daily stream). This is already true for the idle
+        // and buffer-trip paths, which are timer-driven and fire-and-forget
+        // by design. Session JSONLs are force-committed elsewhere, so no
+        // user-visible transcript is lost — only the LLM-distilled stream
+        // fragments for the final batch.
+        'session.end': (event) => {
           if (event.origin?.kind === 'subagent') return
           cancelTimer(event.sessionId)
-          await fireMemoryLogger(event.sessionId, 'session-end')
+          void fireMemoryLogger(event.sessionId, 'session-end')
           const cacheFilePath = join(ctx.agentDir, 'memory', '.retrieval-cache', `${event.sessionId}.md`)
-          try {
-            await unlink(cacheFilePath)
-          } catch (err) {
+          unlink(cacheFilePath).catch((err) => {
             if (!isEnoent(err)) ctx.logger.warn(`[memory] failed to clean retrieval cache: ${err}`)
-          }
+          })
           lastIdleEvent.delete(event.sessionId)
           bytesAtLastRun.delete(event.sessionId)
         },

package/src/bundled-plugins/memory/memory-retrieval.ts

@@ -26,11 +26,12 @@ export type MemoryRetrievalLogger = {
 
 export type CreateMemoryRetrievalSubagentOptions = {
   logger?: MemoryRetrievalLogger
+  timeoutMs?: number
 }
 
 export const MEMORY_RETRIEVAL_SYSTEM_PROMPT = `You are the memory-retrieval subagent. Read the user's most recent prompt and decide what's relevant from BOTH topic shards in \`memory/topics/\` (consolidated long-term memory) AND undreamed daily-stream events under \`memory/streams/\` (recent fragments not yet folded into shards). Use \`memory_search\` to query both surfaces; use \`read\`/\`ls\` to pull full shard bodies when needed. Synthesize a focused ≤8 KB summary of the relevant memory. Save by \`write\`ing it to the exact path provided in your payload as \`cacheFilePath\`. Be ruthlessly concise. Do NOT write anywhere else. Do NOT delete files.
 
-Search discipline: make AT MOST 3 \`memory_search\` calls before writing the cache. Pick queries that match the user's literal phrasing — not framing vocabulary, not metadata (session ids, dates), not words from your own system prompt. If 3 well-chosen searches turn up nothing relevant, write the empty-context note and stop.`
+Search discipline: issue ALL your \`memory_search\` queries in a SINGLE response as parallel tool calls (up to 3 at once), then wait for every result before deciding what to do next. Different angles in parallel, NEVER one search per turn — sequential searches waste a full LLM round-trip per query (~3s each) on file I/O that takes milliseconds. Pick queries that match the user's literal phrasing — not framing vocabulary, not metadata (session ids, dates), not words from your own system prompt. If the parallel batch turns up nothing relevant, write the empty-context note and stop.`
 
 export function memoryRetrievalExhaustedMessage(used: number, max: number): string {
   const usedKb = Math.round(used / 1024)
@@ -56,10 +57,15 @@ export function createMemoryRetrievalSubagent(
   const logger = options.logger ?? consoleLogger
   return {
     systemPrompt: MEMORY_RETRIEVAL_SYSTEM_PROMPT,
+    // Retrieval is "4 keyword searches + 1 write" — no reasoning required.
+    // `fast` falls back to `default` (with a one-time warning) when the
+    // operator hasn't configured it, so this is safe by construction.
+    profile: 'fast',
     tools: [readTool, writeTool, lsTool],
     customTools: [memorySearchTool],
     payloadSchema: memoryRetrievalPayloadSchema,
     inFlightKey: (payload) => payload.parentSessionId,
+    ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
     // 256 KB read + memory_search budget. Sized for one retrieval pass:
     // ~16 KB of memory_search hits (3 queries × ~5 KB excerpts) plus a few
     // shard reads (~5 KB each). A smaller budget would systematically

package/src/bundled-plugins/memory/migration.ts

@@ -77,7 +77,7 @@ export async function runShardingMigration(options: RunShardingMigrationOptions)
     ...extra,
   })
 
-  await recoverShardingOrphans(options.agentDir, options.logger)
+  await recoverShardingOrphans(options.agentDir, options.logger, options.git)
 
   if (existsSync(topicsDir(options.agentDir)) || !existsSync(rootMemoryPath(options.agentDir))) {
     return empty()
@@ -241,25 +241,38 @@ async function recoverShardingMigration(agentDir: string, logger: MigrationLogge
   )
 }
 
-async function recoverShardingOrphans(agentDir: string, logger: MigrationLogger): Promise<void> {
-  if (!existsSync(topicsDir(agentDir))) return
+async function recoverShardingOrphans(
+  agentDir: string,
+  logger: MigrationLogger,
+  git: MigrationGit | undefined,
+): Promise<void> {
+  if (existsSync(topicsDir(agentDir))) {
+    let cleaned = false
+    const memoryPath = rootMemoryPath(agentDir)
+    if (existsSync(memoryPath)) {
+      await unlink(memoryPath)
+      cleaned = true
+    }
 
-  let cleaned = false
-  const memoryPath = rootMemoryPath(agentDir)
-  if (existsSync(memoryPath)) {
-    await unlink(memoryPath)
-    cleaned = true
-  }
+    const memoryDir = join(agentDir, 'memory')
+    const dates = await collectFlatJsonlDates(memoryDir)
+    for (const date of dates) {
+      if (!existsSync(streamFilePath(agentDir, date))) continue
+      await unlink(join(memoryDir, `${date}.jsonl`))
+      cleaned = true
+    }
 
-  const memoryDir = join(agentDir, 'memory')
-  const dates = await collectFlatJsonlDates(memoryDir)
-  for (const date of dates) {
-    if (!existsSync(streamFilePath(agentDir, date))) continue
-    await unlink(join(memoryDir, `${date}.jsonl`))
-    cleaned = true
+    if (cleaned) logger.info('[memory:migration] cleaned orphaned pre-shard memory files')
   }
 
-  if (cleaned) logger.info('[memory:migration] cleaned orphaned pre-shard memory files')
+  // Always called, even when nothing was cleaned this boot AND even when the
+  // sharded layout never landed on this agent: pre-#315 migrations and
+  // earlier runs of this function unlinked without committing, leaving
+  // staged deletions that survive across reboots until cleared explicitly.
+  // The earlier guard (`return` when topicsDir is absent) stranded any agent
+  // whose pre-shard files were deleted but whose sharding never completed —
+  // their staged deletions sat in the index forever.
+  await commitPendingLegacyDeletions(agentDir, logger, git)
 }
 
 async function collectFlatJsonlDates(memoryDir: string): Promise<string[]> {
@@ -540,6 +553,68 @@ async function commitShardingMigration(
   }
 }
 
+async function commitPendingLegacyDeletions(
+  agentDir: string,
+  logger: MigrationLogger,
+  git: MigrationGit | undefined,
+): Promise<void> {
+  const spawn = git?.spawn ?? spawnGit
+  const inside = await spawn(['rev-parse', '--is-inside-work-tree'], { cwd: agentDir })
+  if (inside.exitCode !== 0) return
+
+  const pending = await collectLegacyDeletions(agentDir, spawn)
+  if (pending.all.length === 0) return
+
+  // `git add -u` errors with "pathspec did not match" on paths whose deletion
+  // is already in the index, so stage only the working-tree-only deletions.
+  // The already-staged set is picked up by the commit directly.
+  if (pending.workingTreeOnly.length > 0) {
+    const addDeletions = await spawn(['add', '-u', '--', ...pending.workingTreeOnly], { cwd: agentDir })
+    if (addDeletions.exitCode !== 0) {
+      logger.warn(`[memory:migration] git add failed: ${addDeletions.stderr || addDeletions.stdout}`.trim())
+      return
+    }
+  }
+
+  const commit = await spawn(
+    [
+      'commit',
+      '-m',
+      `memory: clean up ${pending.all.length} pre-shard file(s) orphaned by earlier migration`,
+      '--no-edit',
+    ],
+    { cwd: agentDir },
+  )
+  if (commit.exitCode !== 0) {
+    logger.warn(`[memory:migration] git commit failed: ${commit.stderr || commit.stdout}`.trim())
+  }
+}
+
+async function collectLegacyDeletions(
+  agentDir: string,
+  spawn: NonNullable<MigrationGit['spawn']>,
+): Promise<{ all: string[]; workingTreeOnly: string[] }> {
+  const isLegacy = (line: string): boolean => line === 'MEMORY.md' || /^memory\/\d{4}-\d{2}-\d{2}\.jsonl$/.test(line)
+  const parse = (out: string): string[] =>
+    out
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(isLegacy)
+
+  const allDiff = await spawn(['diff', 'HEAD', '--name-only', '--diff-filter=D', '--', 'memory/', 'MEMORY.md'], {
+    cwd: agentDir,
+  })
+  if (allDiff.exitCode !== 0) return { all: [], workingTreeOnly: [] }
+  const all = parse(allDiff.stdout)
+  if (all.length === 0) return { all: [], workingTreeOnly: [] }
+
+  const wtDiff = await spawn(['diff', '--name-only', '--diff-filter=D', '--', 'memory/', 'MEMORY.md'], {
+    cwd: agentDir,
+  })
+  const workingTreeOnly = wtDiff.exitCode === 0 ? parse(wtDiff.stdout) : []
+  return { all, workingTreeOnly }
+}
+
 async function spawnGit(
   args: string[],
   options: { cwd: string },

package/src/bundled-plugins/memory/stream-io.ts

@@ -1,4 +1,4 @@
-import { readFile, appendFile, readdir, writeFile, rename } from 'node:fs/promises'
+import { readFile, appendFile, readdir, stat, writeFile, rename } from 'node:fs/promises'
 import { join } from 'node:path'
 
 import { getDreamedIds, loadDreamingState } from './dreaming-state'
@@ -8,7 +8,59 @@ import { parseEventLine, type StreamEvent } from './stream-events'
 const STREAM_FILE_PATTERN = /^\d{4}-\d{2}-\d{2}\.jsonl$/
 const STREAM_DATE_FROM_FILENAME = /^(\d{4}-\d{2}-\d{2})\.jsonl$/
 
+// Per-file event cache. `(mtimeMs, ctimeMs, size)` is the invalidation key,
+// mirroring `load-shards.ts`'s shard cache. The three writers in this module
+// — `appendEvents` (memory-logger appends), `writeEventsAtomic` (dreaming
+// compaction + migration), and any external `writeFile` — all bump mtime
+// and/or ctime, so stat-based invalidation is sufficient without explicit
+// hooks. ctimeMs guards metadata-preserving external edits (rsync -t,
+// `touch -r`, restored backups, `git checkout` with timestamps): the kernel
+// always bumps ctime on inode content changes and ctime cannot be backdated
+// via utimes.
+//
+// Module-level keyed by absolute file path. One Bun process owns one agent
+// dir in production (the container stage), so cardinality is small. Multi-
+// path support exists because dreaming compacts multiple files per run and
+// memory_search reads every dated stream.
+type StreamFileCacheEntry = {
+  mtimeMs: number
+  ctimeMs: number
+  size: number
+  events: StreamEvent[]
+}
+const streamFileCache = new Map<string, StreamFileCacheEntry>()
+
 export async function readEvents(path: string): Promise<StreamEvent[]> {
+  const fileStat = await statFile(path)
+  if (fileStat === null) {
+    // File disappeared since last cache populate (e.g. dreaming dropped a
+    // fully-GC'd day). Drop the entry so a future recreate gets fresh
+    // content.
+    streamFileCache.delete(path)
+    return []
+  }
+
+  const cached = streamFileCache.get(path)
+  if (
+    cached !== undefined &&
+    cached.mtimeMs === fileStat.mtimeMs &&
+    cached.ctimeMs === fileStat.ctimeMs &&
+    cached.size === fileStat.size
+  ) {
+    return cached.events
+  }
+
+  const events = await readEventsFromDisk(path)
+  streamFileCache.set(path, {
+    mtimeMs: fileStat.mtimeMs,
+    ctimeMs: fileStat.ctimeMs,
+    size: fileStat.size,
+    events,
+  })
+  return events
+}
+
+async function readEventsFromDisk(path: string): Promise<StreamEvent[]> {
   let raw: string
   try {
     raw = await readFile(path, 'utf-8')
@@ -34,6 +86,24 @@ export async function readEvents(path: string): Promise<StreamEvent[]> {
   return events
 }
 
+async function statFile(path: string): Promise<{ mtimeMs: number; ctimeMs: number; size: number } | null> {
+  try {
+    const s = await stat(path)
+    return { mtimeMs: s.mtimeMs, ctimeMs: s.ctimeMs, size: s.size }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null
+    throw err
+  }
+}
+
+// Test-only helper. Clears the in-memory stream-file cache so tests that
+// exercise the cache invalidation path can simulate a cold start without
+// spinning up a fresh process. Mirrors `__resetShardCacheForTests` in
+// `load-shards.ts`.
+export function __resetStreamFileCacheForTests(): void {
+  streamFileCache.clear()
+}
+
 export async function appendEvents(path: string, events: readonly StreamEvent[]): Promise<void> {
   if (events.length === 0) return
   const joined = events.map((e) => `${JSON.stringify(e)}\n`).join('')

package/src/channels/adapters/kakaotalk-classify.ts

@@ -67,7 +67,10 @@ export function classifyInbound(
       mentionsOthers: false,
       replyToOtherMessageId: null,
       isDm: chatInfo.isDm,
-      ts: event.sent_at,
+      // SDK delivers `sent_at` in Unix seconds (LOCO `sendAt`); contract
+      // wants ms (see `src/channels/types.ts`). Without `* 1000`, ms-based
+      // renderers (inspect -f, etc.) produce 1970-01-21-shaped dates.
+      ts: event.sent_at * 1000,
     },
   }
 }

package/src/channels/adapters/kakaotalk.ts

@@ -257,7 +257,7 @@ export function createKakaoHistoryCallback(deps: {
             authorId,
             authorName,
             text: formatHistoryText(m),
-            ts: m.sent_at,
+            ts: m.sent_at * 1000,
             isBot: selfId !== null && authorId === selfId,
             replyToBotMessageId: null,
           }

package/src/channels/manager.ts

@@ -5,6 +5,7 @@ import type { PermissionService } from '@/permissions'
 import type { GithubSecretsBlock } from '@/secrets'
 import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
 import { SecretsBackend } from '@/secrets/storage'
+import type { Stream } from '@/stream'
 
 import { createDiscordBotAdapter, type DiscordBotAdapter } from './adapters/discord-bot'
 import { createGithubAdapter, type GithubAdapter } from './adapters/github'
@@ -78,6 +79,11 @@ export type ChannelManagerOptions = {
   // a URL" so error logs can be precise. Same shape as
   // `tunnelUrlForChannel` for consistency. Optional for tests.
   tunnelConfiguredForChannel?: (channelName: string) => boolean
+  // Forwarded to the router as `stream`. When set, every inbound the
+  // router sees is published as a tagged broadcast for inspect surfacing.
+  // Production wiring (`src/run/index.ts`) always passes the agent's
+  // Stream; tests typically omit it.
+  stream?: Stream
 }
 
 export type ChannelManager = {
@@ -113,6 +119,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
     ...(options.createSessionForChannel ? { createSessionForChannel: options.createSessionForChannel } : {}),
     ...(options.permissions ? { permissions: options.permissions } : {}),
     ...(options.claimHandler ? { claimHandler: options.claimHandler } : {}),
+    ...(options.stream ? { stream: options.stream } : {}),
   })
   const createDiscordAdapter = options.createDiscordAdapter ?? createDiscordBotAdapter
   const createGithub = options.createGithubAdapter ?? createGithubAdapter