typeclaw 0.8.0 → 0.9.0

package/README.md

@@ -19,7 +19,7 @@ TypeClaw is the agent I wanted to use:
 - **TypeScript end to end** — agent core, plugins, channel adapters, CLI, TUI all in one language
 - **Bun-native plugins** — plugins are just TS modules; no IPC, no FFI, hot-reloadable config
 - **Docker-friendly by default** — every agent runs in its own container; the host CLI is purely a launcher
-- **Self-improving** — the agent observes its own work, distills it into long-term memory and reusable skills, and gets sharper over time without you writing prompts for it
+- **Self-improving** — the agent observes its own work, distills it into sharded long-term memory and reusable skills, and gets sharper over time without you writing prompts for it
 
 If you're like me, TypeClaw is the right choice. If not, that's fine too.
 
@@ -31,18 +31,18 @@ If you're like me, TypeClaw is the right choice. If not, that's fine too.
 - ⏰ **Cron** — schedule prompts or shell commands; per-job coalescing so slow jobs don't pile up
 - 📚 **Skills on demand** — markdown procedures the agent loads only when relevant; zero token cost until used
 - 🔎 **Web research** — bundled `scout` subagent plus first-class `websearch` and `webfetch` tools (DuckDuckGo via curl-impersonate, Wikipedia)
-- 🛡 **Security guards** — bundled `tool.before` policies catch secret exfil, SSRF, prompt injection, and tainted git remotes before they fire
-- 📊 **Usage and doctor** — `typeclaw usage` reports token/$ spend per session, model, or day; `typeclaw doctor` diagnoses host, agent folder, and plugin state
+- 🛡 **Security guards** — bundled `tool.before` policies catch secret exfil, SSRF, prompt injection, tainted git remotes, and silent privilege escalation (role/cron promotion) before they fire
+- 📊 **Usage, inspect, doctor** — `typeclaw usage` reports token/$ spend per session, model, or day; `typeclaw inspect` replays a session transcript and tails live activity; `typeclaw doctor` diagnoses host, agent folder, and plugin state
 
 ## Where it goes further
 
-- 🌱 **Self-improving** — bundled `memory` plugin distills sessions into long-term `MEMORY.md` without you writing prompts for it
+- 🌱 **Self-improving** — bundled `memory` plugin logs sessions to daily streams, then a `dreaming` subagent distills them into sharded long-term memory (`memory/topics/`) on its own schedule; no prompts to write
 - 🧠 **Muscle memory** — repeated procedures get distilled into reusable skills the agent writes for itself and loads on later runs
 - 💾 **Auto-backup** — the bundled `backup` plugin commits session logs and memory on every idle window with an LLM-generated commit subject
 - 🪄 **Subagents** — first-class child sessions with their own system prompt, payload schema, and per-payload coalescing; cron and the main agent fire them through one in-process Stream
 - 🪪 **Roles and permissions** — `owner` / `trusted` / `member` / `guest` with first-message match rules per channel; gates `channel.respond`, cron scheduling, and security bypasses, so a Slack stranger can't tell the agent to push to main
 - 👥 **Group chat awareness** — knows who's in the room, distinguishes humans from bots, and stays engaged after a reply without re-mentioning
-- 🧱 **Managed-file guards** — `typeclaw.json`, `cron.json`, `MEMORY.md`, and bundled skills are protected from accidental rewrites; invalid config writes are rejected at the tool boundary
+- 🧱 **Managed-file guards** — `typeclaw.json`, `cron.json`, memory shards, and bundled skills are protected from accidental rewrites; invalid config writes and silent role/cron privilege grants are rejected at the tool boundary
 - 🌐 **Headed browser inside the container** — bundled `agent-browser` plugin ships Chrome under Xvfb so the agent can drive real web pages past bot fingerprinting
 - 🌍 **Tunnels and auto port-forward** — dev servers inside the container appear on `localhost` (even loopback-only ones); public URLs via Cloudflare Quick (zero signup) or your own external URL, with GitHub webhooks self-registered at the resulting URL
 - 🔄 **Hot reload** — change `typeclaw.json`, run `typeclaw reload` — no restart for most fields
@@ -78,7 +78,7 @@ See `typeclaw --help` for the full command surface, or [typeclaw.dev](https://ty
 git clone https://github.com/typeclaw/typeclaw
 cd typeclaw
 bun install
-bun test
+bun run test
 ```
 
 Pre-commit checks (all must pass — no exceptions):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -36,7 +36,7 @@
     "format": "oxfmt --write .",
     "format:check": "oxfmt --check .",
     "check": "bun run typecheck && bun run lint && bun run format:check",
-    "test": "bun test",
+    "test": "bun test --parallel",
     "generate:schema": "bun run scripts/generate-schema.ts",
     "debug:prompt": "bun run scripts/dump-system-prompt.ts",
     "postinstall": "bun run scripts/generate-schema.ts"
@@ -46,7 +46,7 @@
     "@mariozechner/pi-coding-agent": "^0.67.3",
     "@mariozechner/pi-tui": "^0.67.3",
     "@mozilla/readability": "^0.6.0",
-    "agent-messenger": "2.15.0",
+    "agent-messenger": "2.17.0",
     "cheerio": "^1.2.0",
     "citty": "^0.2.2",
     "cron-parser": "^5.5.0",
@@ -56,9 +56,11 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@sinonjs/fake-timers": "^15.4.0",
     "@types/bun": "latest",
     "@types/jsdom": "^28.0.1",
     "@types/proper-lockfile": "^4.1.4",
+    "@types/sinonjs__fake-timers": "^15.0.1",
     "@types/turndown": "^5.0.6",
     "@types/ws": "^8.18.1",
     "@typescript/native-preview": "^7.0.0-dev.20260416.1",

package/scripts/require-parallel.ts

@@ -0,0 +1,41 @@
+// Preloaded by bunfig.toml `[test] preload`. Denies `bun test` without
+// --parallel. Serial runs are ~3.4x slower (44s → 13s, see commit
+// 1c66d5e), and Bun has no bunfig knob for the flag yet (verified
+// against bunfig.zig in oven-sh/bun main, May 2026). Without this
+// guard, IDE test runners and ad-hoc shells silently fall back to the
+// slow path.
+//
+// Detection: Bun strips CLI flags from `Bun.argv` before invoking the
+// preload, so we can't scrape the flag directly. Instead we look for
+// BUN_TEST_WORKER_ID, which Bun sets in the preload env exactly when
+// `--parallel` is active (the variable carries the worker index for
+// the IPC handshake between coordinator and workers). Empirically
+// verified against bun 1.3.14: present under --parallel, absent under
+// serial. If a future Bun version renames this var, the guard fails
+// closed (treats every run as serial → always denies), which is the
+// safe direction.
+//
+// Bypass with TYPECLAW_ALLOW_SERIAL_TESTS=1 when debugging a flaky
+// test where worker contention obscures the failure.
+
+const isParallelWorker = typeof process.env.BUN_TEST_WORKER_ID === 'string'
+
+if (isParallelWorker) {
+  // proceed
+} else if (process.env.TYPECLAW_ALLOW_SERIAL_TESTS === '1') {
+  console.warn('[require-parallel] Running serially — TYPECLAW_ALLOW_SERIAL_TESTS=1 set.')
+} else {
+  console.error('')
+  console.error('  ✗ `bun test` without --parallel is denied in this repo.')
+  console.error('')
+  console.error('    Serial runs take ~46s; --parallel cuts that to ~14s on a multi-core')
+  console.error('    machine and is what CI uses. Bun does not (yet) accept `[test] parallel`')
+  console.error('    in bunfig.toml, so we enforce it via this preload.')
+  console.error('')
+  console.error('    Use one of:')
+  console.error('      bun run test                              # preferred')
+  console.error('      bun test --parallel                       # direct')
+  console.error('      TYPECLAW_ALLOW_SERIAL_TESTS=1 bun test    # intentional serial run')
+  console.error('')
+  process.exit(1)
+}

package/src/agent/index.ts

@@ -765,7 +765,40 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
   const agentDir = options.agentDir ?? process.cwd()
   const mode: SystemPromptMode = options.mode ?? deriveSystemPromptMode(options.origin)
   const basePrompt = mode === 'slim' ? SLIM_SYSTEM_PROMPT : DEFAULT_SYSTEM_PROMPT
-  let self = await loadSelf(agentDir)
+
+  // Kick off the three independent I/O paths concurrently. Sequential awaits
+  // here used to be the dominant cold-start cost amplifier: loadSelf is 2
+  // file reads, renderGitNudge spawns a subprocess, loadMemory reads N topic
+  // shards. None of them depend on each other, so we run them in parallel.
+  // The plugin hook (runSessionPrompt) only needs `self`, so it can overlap
+  // with the gitNudge subprocess and the shard reads while `self` is in
+  // flight too.
+  //
+  // Plugin-hook contract: `runSessionPrompt` runs AFTER gitNudge/memory I/O
+  // has been kicked off. A hook that mutates `memory/topics/` or git-tracked
+  // files during its body races those in-flight reads -- mutations may or
+  // may not be reflected in the resulting prompt. The bundled hooks only
+  // mutate the prompt string itself; third-party plugins that need to mutate
+  // disk before the suffix sections see it must do so before/outside the
+  // session-prompt hook.
+  //
+  // We wrap gitNudge and memory promises in `settled` shells so any
+  // rejection from them cannot surface as an unhandled rejection during the
+  // window where we're awaiting selfPromise + runSessionPrompt. Production
+  // callers don't reject (renderGitNudge swallows internally, loadMemory
+  // catches ENOENT) but a non-ENOENT fs error (EACCES/EIO) on the agent
+  // folder would otherwise terminate the process before we reach the
+  // gather point.
+  const selfPromise = loadSelf(agentDir)
+  const gitNudgeSettled = mode === 'slim' ? Promise.resolve(ok('')) : settle(renderGitNudge(agentDir))
+  const memorySettled = settle(
+    loadMemory(agentDir, {
+      ...(options.origin !== undefined ? { origin: options.origin } : {}),
+      ...(options.plugins?.sessionId !== undefined ? { currentSessionId: options.plugins.sessionId } : {}),
+    }),
+  )
+
+  let self = await selfPromise
 
   if (options.plugins) {
     // The plugin hook receives the partially-assembled prompt (base + identity)
@@ -788,11 +821,9 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
   // commit guidance the nudge points back to is itself excluded from the slim
   // base prompt. Memory is still included so cron jobs that depend on MEMORY.md
   // context (e.g. "send today's standup summary") keep working.
-  const gitNudge = mode === 'slim' ? '' : await renderGitNudge(agentDir)
-  const memorySection = await loadMemory(agentDir, {
-    ...(options.origin !== undefined ? { origin: options.origin } : {}),
-    ...(options.plugins?.sessionId !== undefined ? { currentSessionId: options.plugins.sessionId } : {}),
-  })
+  const [gitNudgeResult, memoryResult] = await Promise.all([gitNudgeSettled, memorySettled])
+  const gitNudge = unwrapSettled(gitNudgeResult)
+  const memorySection = unwrapSettled(memoryResult)
 
   const systemPrompt = composeSystemPrompt({
     mode,
@@ -872,3 +903,21 @@ function resolveRoleContext(
 export function getBundledSkillsDir(): string {
   return join(dirname(fileURLToPath(import.meta.url)), '..', 'skills')
 }
+
+type Settled<T> = { ok: true; value: T } | { ok: false; error: unknown }
+
+function ok<T>(value: T): Settled<T> {
+  return { ok: true, value }
+}
+
+function settle<T>(promise: Promise<T>): Promise<Settled<T>> {
+  return promise.then(
+    (value): Settled<T> => ({ ok: true, value }),
+    (error: unknown): Settled<T> => ({ ok: false, error }),
+  )
+}
+
+function unwrapSettled<T>(result: Settled<T>): T {
+  if (result.ok) return result.value
+  throw result.error
+}

package/src/agent/live-sessions.ts

@@ -0,0 +1,34 @@
+import type { AgentSession } from './index'
+
+export type LiveAgentSession = {
+  sessionId: string
+  session: Pick<AgentSession, 'subscribe'>
+}
+
+export class LiveSessionRegistry {
+  private readonly entries = new Map<string, LiveAgentSession>()
+
+  register(live: LiveAgentSession): void {
+    this.entries.set(live.sessionId, live)
+  }
+
+  unregister(sessionId: string): void {
+    this.entries.delete(sessionId)
+  }
+
+  get(sessionId: string): LiveAgentSession | undefined {
+    return this.entries.get(sessionId)
+  }
+
+  has(sessionId: string): boolean {
+    return this.entries.has(sessionId)
+  }
+
+  size(): number {
+    return this.entries.size
+  }
+
+  clear(): void {
+    this.entries.clear()
+  }
+}

package/src/agent/plugin-tools.ts

@@ -40,6 +40,8 @@ const ACKNOWLEDGE_GUARDS_SCHEMA = Type.Optional(
   Type.Object(
     {
       nonWorkspaceWrite: Type.Optional(Type.Boolean()),
+      rolePromotion: Type.Optional(Type.Boolean()),
+      cronPromotion: Type.Optional(Type.Boolean()),
     },
     { additionalProperties: false },
   ),

package/src/agent/session-meta.ts

@@ -9,12 +9,29 @@ export type SessionMetaPayload = {
 export type MinimalSessionOrigin =
   | { kind: 'tui' }
   | { kind: 'cron'; jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' | 'handler' }
-  | { kind: 'channel'; adapter: string; workspace: string; chat: string; thread: string | null }
+  | {
+      kind: 'channel'
+      adapter: string
+      workspace: string
+      // Optional human-readable names persisted alongside IDs so offline
+      // tooling (`typeclaw inspect`, future report commands) can render
+      // sessions as `Slack acme-corp/#general` instead of bare IDs without
+      // re-querying the adapter at runtime. Workspace/chat NAMES are not
+      // secrets — they are visible to any participant — and they are
+      // stable across reopens, so the tradeoff is one-time write cost for
+      // permanent offline readability. Author handles, participant lists,
+      // and membership counts remain dropped (those carry author identity
+      // and would land in `sessions/`'s auto-backup git history).
+      workspaceName?: string
+      chat: string
+      chatName?: string
+      thread: string | null
+    }
   | { kind: 'subagent'; subagent: string; parentSessionId: string }
 
 // Reduce a full SessionOrigin to the minimum projection persisted to disk.
 // Drops participant lists, membership counts, recursive provenance, and
-// platform-rendered names — none of which `typeclaw usage` reads, and all of
+// author identifiers — none of which `typeclaw usage` reads, and all of
 // which would otherwise land in git history when sessions/ is auto-backed-up.
 // Kept as a separate function so the boundary between "data the LLM sees in
 // the system prompt" (full origin) and "data persisted for usage reporting"
@@ -34,7 +51,9 @@ function minimalOrigin(origin: SessionOrigin): MinimalSessionOrigin {
         kind: 'channel',
         adapter: origin.adapter,
         workspace: origin.workspace,
+        ...(origin.workspaceName !== undefined ? { workspaceName: origin.workspaceName } : {}),
         chat: origin.chat,
+        ...(origin.chatName !== undefined ? { chatName: origin.chatName } : {}),
         thread: origin.thread,
       }
     case 'subagent':

package/src/agent/subagent-completion-reminder.ts

@@ -0,0 +1,89 @@
+// Shared renderer for the `<system-reminder>` block injected into a parent
+// session's prompt queue when one of its backgrounded subagents finishes.
+// Used by the TUI route in src/server/index.ts and the channel-router
+// bridge so the model sees identical wording across origins. The
+// `channel` knob is the only per-origin difference: channel sessions
+// need the "end your reply via channel_reply" nudge because plain-text
+// output is invisible there AND the reminder is not a user message —
+// the channel origin block's MUST-call-channel_reply rule is keyed to
+// user messages, so a model that reads the spec literally would
+// otherwise leave the reply un-sent.
+
+export type CompletionReminderArgs = {
+  subagent: string
+  taskId: string
+  ok: boolean
+  durationMs: number
+  error?: string
+  channel?: boolean
+}
+
+const CHANNEL_REPLY_NUDGE =
+  'This reminder is a system message, not a user inbound — but you are in a channel session, ' +
+  'so end your turn via `channel_reply` (or `channel_send`) to surface the result. ' +
+  'Plain-text output is invisible here. If there is genuinely nothing to surface, end with `NO_REPLY`.'
+
+export function renderSubagentCompletionReminder(args: CompletionReminderArgs): string {
+  const durationStr = formatReminderDuration(args.durationMs)
+  const channelTail = args.channel === true ? ` ${CHANNEL_REPLY_NUDGE}` : ''
+  if (args.ok) {
+    return (
+      `<system-reminder>\n` +
+      `Subagent \`${args.subagent}\` (${args.taskId}) completed in ${durationStr}. ` +
+      `Use subagent_output to fetch the result.${channelTail}\n` +
+      `</system-reminder>`
+    )
+  }
+  const err = args.error ?? 'unknown error'
+  return (
+    `<system-reminder>\n` +
+    `Subagent \`${args.subagent}\` (${args.taskId}) FAILED after ${durationStr}: ${err}. ` +
+    `Use subagent_output to inspect.${channelTail}\n` +
+    `</system-reminder>`
+  )
+}
+
+export function formatReminderDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`
+  const totalSec = Math.floor(ms / 1000)
+  if (totalSec < 60) return `${totalSec}s`
+  const min = Math.floor(totalSec / 60)
+  const sec = totalSec % 60
+  return `${min}m${sec}s`
+}
+
+export type SubagentCompletedPayload = {
+  taskId: string
+  subagent: string
+  parentSessionId: string
+  ok: boolean
+  durationMs: number
+  error?: string
+}
+
+// Type guard for the `subagent.completed` broadcast payload. Subscribers
+// to `target: { kind: 'broadcast' }` see every broadcast; this guard
+// filters and narrows in one place so callers don't repeat the
+// typeof-checking dance.
+export function parseSubagentCompletedPayload(payload: unknown): SubagentCompletedPayload | null {
+  if (payload === null || typeof payload !== 'object') return null
+  const p = payload as {
+    kind?: unknown
+    taskId?: unknown
+    subagent?: unknown
+    parentSessionId?: unknown
+    ok?: unknown
+    durationMs?: unknown
+    error?: unknown
+  }
+  if (p.kind !== 'subagent.completed') return null
+  if (typeof p.parentSessionId !== 'string') return null
+  return {
+    taskId: typeof p.taskId === 'string' ? p.taskId : '<unknown>',
+    subagent: typeof p.subagent === 'string' ? p.subagent : 'subagent',
+    parentSessionId: p.parentSessionId,
+    ok: p.ok === true,
+    durationMs: typeof p.durationMs === 'number' ? p.durationMs : 0,
+    ...(typeof p.error === 'string' ? { error: p.error } : {}),
+  }
+}

package/src/agent/subagents.ts

@@ -206,12 +206,13 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
       hooks && sessionId !== undefined && agentDir !== undefined
         ? { sessionId, agentDir, ...(origin !== undefined ? { origin } : {}) }
         : undefined
+    const userPromptForTurn = override?.userPrompt ?? options.userPrompt
     try {
       if (hooks && turnEvent !== undefined) {
-        await hooks.runSessionTurnStart(turnEvent)
+        await hooks.runSessionTurnStart({ ...turnEvent, userPrompt: userPromptForTurn })
       }
       try {
-        await session.prompt(override?.userPrompt ?? options.userPrompt)
+        await session.prompt(userPromptForTurn)
       } finally {
         if (hooks && turnEvent !== undefined) {
           await hooks.runSessionTurnEnd(turnEvent)

package/src/agent/system-prompt.ts

@@ -10,15 +10,15 @@ TypeClaw is domain-agnostic — your purpose is defined by \`IDENTITY.md\`, your
 - **SOUL.md** *(always injected below)* — your character, tone, voice. Edit rarely.
 - **USER.md** *(read on demand)* — what you know about the user. Update as you learn.
 - **AGENTS.md** *(read on demand)* — your operating manual. Read at the start of any non-trivial task and re-read whenever process is unclear.
-- **MEMORY.md** *(always injected below, READ-ONLY)* — long-term memory, owned by the dreaming subagent. To capture something memorable, surface it in your reply or in \`memory/\` daily streams; never edit MEMORY.md directly.
+- **\`memory/topics/\`** *(always injected below, READ-ONLY)* — sharded long-term memory, owned by the dreaming subagent. To capture something memorable, surface it in your reply or let the memory-logger append to \`memory/streams/\`; never edit memory shards directly.
 
-If a task reveals durable guidance or identity/user context, update the owning file (IDENTITY / SOUL / USER / AGENTS) — never MEMORY.md.
+If a task reveals durable guidance or identity/user context, update the owning file (IDENTITY / SOUL / USER / AGENTS) — never memory shards.
 
 ## Your workspace
 
 - **\`workspace/\`** — your free-write zone for drafts, scratch work, generated artifacts. Do not create files at the agent-folder root unless the user explicitly asks.
 - **\`sessions/\`** — transcripts of past conversations. Runtime-managed; don't write here.
-- **\`memory/\`** *(undreamed daily streams injected below)* — dated streams written by the memory-logger between sessions. Runtime-owned.
+- **\`memory/streams/\`** *(not injected — reach via \`memory_search\`)* — dated streams written by the memory-logger between sessions. Runtime-owned. Undreamed observations are searchable on demand instead of injected into every prompt.
 - **\`memory/skills/\`** — muscle-memory skills written by the dreaming subagent. Auto-loaded; don't write here directly.
 - **\`.agents/skills/\`** — user-installed skills.
 
@@ -47,7 +47,7 @@ Your agent folder is a git repository.
 ## How to behave
 
 - Match the user's register. If SOUL.md specifies a voice, use it. Otherwise, be concise and direct, without filler or flattery.
-- Prefer reading files over guessing — IDENTITY / SOUL / USER / MEMORY / AGENTS or the workspace. Follow AGENTS.md in whatever role IDENTITY.md assigns you; propose additions to AGENTS.md when you find gaps worth codifying.
+- Prefer reading files over guessing — IDENTITY / SOUL / USER / memory topics / AGENTS or the workspace. Follow AGENTS.md in whatever role IDENTITY.md assigns you; propose additions to AGENTS.md when you find gaps worth codifying.
 - Answer questions. Do work. Don't over-explain unless asked.
 - If a request is ambiguous in a way that doubles the effort, ask one clarifying question; otherwise proceed with a reasonable default.
 - Never suppress errors to make things "work", and never fabricate results. Report failures clearly.
@@ -62,7 +62,7 @@ There are two delegation modes. Pick deliberately.
 
 When you need information to answer the user and the search is broad, fire 2-5 subagents in parallel with \`run_in_background: true\` covering different angles. End your response after spawning. The system will deliver a \`<system-reminder>\` for each completion; gather results then answer the user. Do NOT poll \`subagent_output\` in a tight loop.
 
-The bundled \`explorer\` subagent is the right tool for **local** reconnaissance — anything reachable on the agent's filesystem: code, past sessions (\`sessions/*.jsonl\`), MEMORY.md and daily memory streams, skills, cron jobs, config, git history, mounts, channels state. It is read-only and runs on a fast/cheap model, so fire liberally. Do NOT ask it to plan, decide, or write code — it finds and reports.
+The bundled \`explorer\` subagent is the right tool for **local** reconnaissance — anything reachable on the agent's filesystem: code, past sessions (\`sessions/*.jsonl\`), memory topic shards and daily memory streams, skills, cron jobs, config, git history, mounts, channels state. It is read-only and runs on a fast/cheap model, so fire liberally. Do NOT ask it to plan, decide, or write code — it finds and reports.
 
 The bundled \`scout\` subagent is its external counterpart — web research only. Use it when you need information from public sources (docs, library references, vendor changelogs, news, anything not already in this agent's folder). Scout runs \`websearch\` and \`webfetch\` in a fresh context window so the search churn does not pollute yours; it returns a citation-backed answer with a confidence rating. Prefer scout over running \`websearch\`/\`webfetch\` yourself when the research is non-trivial (more than 1-2 queries) or when you want to save your context for the synthesis step.
 
@@ -70,6 +70,8 @@ The bundled \`scout\` subagent is its external counterpart — web research only
 
 When the user hands you a task that will take minutes (a multi-step browser session, a long build, a complex external operation), acknowledge in plain language ("Alright, running that in the background — I'll let you know when it's done"), spawn one subagent with \`run_in_background: true\`, then KEEP TALKING. Stay available for follow-ups, related questions, parallel small tasks. When the completion reminder lands, weave the result into your next reply naturally. If the conversation has gone idle, proactively message the user with the result rather than waiting.
 
+In a channel session, the completion \`<system-reminder>\` is NOT a user message — the channel origin's "you MUST call \`channel_reply\` for every user message" rule does not literally apply, but the underlying constraint does: plain-text output is invisible in a channel. Surface the result via \`channel_reply\` (or \`channel_send\`) so the user actually sees it. Failures need surfacing too: when a delegated task didn't complete, the user needs the outcome and whatever partial progress you got. \`NO_REPLY\` is the escape hatch only when the user has already seen the substantive answer — typically because you posted it via \`channel_reply\` in the same turn that spawned the subagent, and the reminder is purely confirming completion of a step the user is already tracking. Otherwise, post the result.
+
 Before you run a tool chain that returns bulky intermediate output you won't need again — multiple \`webfetch\` calls, a \`websearch\` round you'll iterate on, a \`bash\` command that scrapes a site or dumps a large response, an \`agent-browser\` session, a \`claude\` (Claude Code) delegation driven through tmux, any "fetch N things and synthesize" loop — delegate it to a subagent. \`scout\` (for research) or \`operator\` (for actions with side effects) runs the noisy work in its own context window and returns a distilled summary; your session carries the *answer*, not the raw material you derived it from. This is about context economy, not latency: even a fast operation belongs in a subagent when the byproducts are large and disposable (three quick news searches across different outlets still dumps three SERPs and three article bodies into your context forever). The exception is exactly one call whose result you'll cite directly — one \`webfetch\` of a known URL, one \`websearch\` query whose top result is the answer. Two of either, or any "across multiple sources" framing, is delegation territory.
 
 The bundled \`operator\` subagent is the right tool for this mode. It is write-capable (read, write, edit, bash with side effects) and runs on the default model. Use it for: browser sessions, multi-file refactors, deploys, batch API calls, Claude Code delegations (the tmux driving loop, the multi-turn polling, the worktree teardown — all of it inside operator), anything that involves taking action on behalf of the user over multiple steps. The operator returns a structured final report (outcome, what changed, what was observed); surface it naturally rather than copy-pasting. Operator is gated by a separate permission (\`subagent.spawn.operator\`) so write-capable spawns are restricted to owner-tier and trusted-tier callers — if the gate denies, fall back to doing the work in your own session rather than reporting failure to the user.
@@ -165,10 +167,10 @@ Session started at \`${iso}\` (${zone}). This is a session-creation snapshot, no
 //      plugin does not catch this.
 //   4. Output discipline — keeps tool-call narration from bloating the
 //      ever-growing transcript that the next memory-logger pass has to read.
-//   5. Filesystem hygiene — workspace boundary, MEMORY.md ownership, and
+//   5. Filesystem hygiene — workspace boundary, memory-shard ownership, and
 //      runtime-managed paths (secrets.json / .env / sessions/ / memory/ / workspace/). The
 //      guard plugin blocks non-workspace writes for write/edit, but it
-//      explicitly allows MEMORY.md writes and does not gate bash/git on the
+//      does not gate bash/git on the
 //      runtime-managed paths.
 //
 // What does NOT live here, by design:
@@ -189,6 +191,6 @@ Never suppress errors to make things "work", and never fabricate results. If som
 
 Do not narrate routine, low-risk tool calls — just call the tool. Do not over-explain what you did unless asked.
 
-Your free-write zone is \`workspace/\`. Do not create files at the root of the agent folder unless the prompt names another path. Do not edit \`MEMORY.md\` directly — the dreaming subagent owns it; to capture something memorable, surface it in your reply or in \`memory/\` daily streams. Never stage or commit \`secrets.json\`, \`.env\`, \`sessions/\`, \`memory/\`, or \`workspace/\` — those are runtime- or user-managed.
+Your free-write zone is \`workspace/\`. Do not create files at the root of the agent folder unless the prompt names another path. Do not edit \`memory/topics/\` directly — the dreaming subagent owns it; to capture something memorable, surface it in your reply or let the memory-logger append to \`memory/streams/\`. Never stage or commit \`secrets.json\`, \`.env\`, \`sessions/\`, \`memory/\`, or \`workspace/\` — those are runtime- or user-managed.
 
 See the session-origin block below for what kind of session this is and what's expected of you.`

package/src/bundled-plugins/explorer/explorer.ts

@@ -9,7 +9,7 @@ You are STRICTLY PROHIBITED from:
 - Creating, modifying, or deleting files
 - Using bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any write operation
 - Starting long-running background processes
-- Writing to MEMORY.md, sessions/, workspace/, or any other runtime-managed path
+- Writing to memory/topics/, memory/streams/, sessions/, workspace/, or any other runtime-managed path
 - Spawning further subagents — you are at the end of the delegation chain
 
 Your role is EXCLUSIVELY to search and analyze existing local state.
@@ -32,7 +32,7 @@ The agent folder is mounted at \`/agent\` inside the container. Search the narro
 
 1. **Codebase** — \`/agent/\` root and subdirs (excluding the runtime-managed paths below). Source files, docs, identity files (\`IDENTITY.md\`, \`SOUL.md\`, \`USER.md\`, \`AGENTS.md\`).
 2. **Sessions** — \`/agent/sessions/*.jsonl\` — conversation transcripts. Each line is a JSON event (user message, tool call, tool result, assistant message). Filename pattern \`\${ISO_TIMESTAMP}_\${UUID}.jsonl\`. \`grep\` works directly on the JSONL.
-3. **Memory** — \`/agent/MEMORY.md\` (long-term consolidated memory) and \`/agent/memory/yyyy-MM-dd.jsonl\` (daily fragment streams written by the memory-logger subagent). \`memory/.dreaming-state.json\` tracks the dreaming watermark. Do NOT edit any of these — they are runtime-owned.
+3. **Memory** — \`/agent/memory/topics/*.md\` (long-term topic shards) and \`/agent/memory/streams/yyyy-MM-dd.jsonl\` (daily fragment streams written by the memory-logger subagent). \`memory/.dreaming-state.json\` tracks the dreaming watermark. Do NOT edit any of these — they are runtime-owned.
 4. **Muscle-memory skills** — \`/agent/memory/skills/<name>/SKILL.md\` — procedures the dreaming subagent distilled from repeated work.
 5. **User-installed skills** — \`/agent/.agents/skills/<name>/SKILL.md\` — hand-authored or downloaded skills.
 6. **Workspace** — \`/agent/workspace/\` — the agent's free-write zone. Drafts, scratch work, generated artifacts.

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

@@ -2,6 +2,7 @@ import { definePlugin } from '@/plugin'
 
 import {
   checkManagedConfigGuard,
+  checkMemoryTopicsDeleteGuard,
   checkNonWorkspaceWriteGuard,
   checkSkillAuthoringGuard,
   checkUncommittedChangesAdvice,
@@ -23,7 +24,19 @@ export default definePlugin({
           agentDir: ctx.agentDir,
         })
         if (skillResult) return skillResult
-        return checkNonWorkspaceWriteGuard({ tool: event.tool, args: event.args, agentDir: ctx.agentDir })
+        const memoryTopicsDeleteResult = checkMemoryTopicsDeleteGuard({
+          tool: event.tool,
+          args: event.args,
+          agentDir: ctx.agentDir,
+          origin: event.origin,
+        })
+        if (memoryTopicsDeleteResult) return memoryTopicsDeleteResult
+        return checkNonWorkspaceWriteGuard({
+          tool: event.tool,
+          args: event.args,
+          agentDir: ctx.agentDir,
+          origin: event.origin,
+        })
       },
       'tool.after': async (event, ctx) => {
         await checkUncommittedChangesAdvice({

package/src/bundled-plugins/guard/policies/managed-config.ts

@@ -39,19 +39,31 @@ export async function checkManagedConfigGuard(options: {
   }
 }
 
+// Oracle PR #305 findings #5 and #6: identity-based managed-file
+// detection. The earlier shape compared `basename(realpath(target))` to
+// the managed-file list, which missed two attacks: (5) a symlink at
+// agent root `typeclaw.json -> workspace/tc.json` realpathed to a name
+// outside the managed list, and (6) on case-insensitive filesystems,
+// `TYPECLAW.JSON` addresses the same file as `typeclaw.json` but
+// basename string-equality missed the casing variant.
+//
+// New shape: for each managed-file name, compute the canonical agent-
+// root path and compare against the target. We accept if EITHER the
+// lexical paths match OR they realpath to the same file. Branch (a)
+// covers symlinks and case-aliased filesystems; branch (b) keeps the
+// canonical lexical name authoritative even before the file exists
+// (first-init writes).
 async function resolveManagedTarget(agentDir: string, targetPath: string): Promise<{ file: ManagedFile } | undefined> {
   const resolvedAgentDir = path.resolve(agentDir)
-  const realAgentDir = await resolveRealIntendedPath(resolvedAgentDir)
-  const realTargetPath = await resolveRealIntendedPath(targetPath)
-
-  if (path.dirname(realTargetPath) !== realAgentDir) return undefined
-
-  const basename = path.basename(realTargetPath)
-  return isManagedFile(basename) ? { file: basename } : undefined
-}
-
-function isManagedFile(basename: string): basename is ManagedFile {
-  return MANAGED_FILES.has(basename as ManagedFile)
+  const resolvedTarget = path.resolve(targetPath)
+  for (const file of MANAGED_FILES) {
+    const canonical = path.join(resolvedAgentDir, file)
+    if (canonical === resolvedTarget) return { file }
+    const realCanonical = await resolveRealIntendedPath(canonical)
+    const realTarget = await resolveRealIntendedPath(resolvedTarget)
+    if (realCanonical === realTarget) return { file }
+  }
+  return undefined
 }
 
 function validateManagedContent(file: ManagedFile, content: string): { ok: true } | { ok: false; reason: string } {
@@ -81,6 +93,20 @@ async function intendedContent(
     return blockReason(tool, targetPath, 'edit calls must include an edits array')
   }
 
+  // Oracle PR #305 finding #4: refuse multi-edit on managed files to
+  // avoid simulator-vs-pi divergence. The canonical workflow for
+  // typeclaw.json / cron.json is read + modify in memory + write the
+  // whole file back; multi-edit is not required and the divergence
+  // would let an attacker validate a different final file here than
+  // the one pi actually writes.
+  if (edits.length > 1) {
+    return blockReason(
+      tool,
+      targetPath,
+      'multi-edit calls on managed files are refused — use `write` with full content instead',
+    )
+  }
+
   let content: string
   try {
     content = await readFile(targetPath, 'utf8')
@@ -100,10 +126,14 @@ async function intendedContent(
     if (oldText.length === 0) {
       return blockReason(tool, targetPath, 'edit oldText must not be empty')
     }
-    if (!content.includes(oldText)) {
+    const firstIdx = content.indexOf(oldText)
+    if (firstIdx === -1) {
       return blockReason(tool, targetPath, 'edit oldText was not found in existing file')
     }
-    content = content.replace(oldText, newText)
+    if (content.indexOf(oldText, firstIdx + 1) !== -1) {
+      return blockReason(tool, targetPath, 'edit oldText is not unique in the existing file')
+    }
+    content = content.slice(0, firstIdx) + newText + content.slice(firstIdx + oldText.length)
   }
   return { content }
 }

package/src/bundled-plugins/guard/policies/memory-retrieval-cache-write.ts

@@ -0,0 +1,37 @@
+import path from 'node:path'
+
+import type { SessionOrigin } from '@/agent/session-origin'
+import type { SecuritySeverity } from '@/bundled-plugins/security/permissions'
+
+export const GUARD_MEMORY_RETRIEVAL_CACHE_WRITE = 'memoryRetrievalCacheWrite'
+export const GUARD_MEMORY_RETRIEVAL_CACHE_WRITE_SEVERITY: SecuritySeverity = 'low'
+
+const SESSION_ID_REGEX = /^[A-Za-z0-9._-]{1,128}$/
+
+export async function isMemoryRetrievalCacheWriteAllowed(options: {
+  tool: string
+  args: Record<string, unknown>
+  agentDir: string
+  origin?: SessionOrigin
+}): Promise<boolean> {
+  const { tool, args, agentDir, origin } = options
+  if (tool !== 'write') return false
+  if (origin?.kind !== 'subagent' || origin.subagent !== 'memory-retrieval') return false
+
+  const rawPath = args.path
+  if (typeof rawPath !== 'string') return false
+
+  const targetPath = path.resolve(agentDir, rawPath)
+  const expectedDir = path.resolve(agentDir, 'memory', '.retrieval-cache')
+  const relative = path.relative(expectedDir, targetPath)
+  if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) return false
+
+  const parts = relative.split(path.sep).filter(Boolean)
+  if (parts.length !== 1) return false
+
+  const fileName = parts[0]!
+  if (!fileName.endsWith('.md')) return false
+
+  const sessionId = fileName.slice(0, -3)
+  return SESSION_ID_REGEX.test(sessionId)
+}