typeclaw 0.1.0

package/src/bundled-plugins/guard/policies/non-workspace-write.ts

@@ -0,0 +1,98 @@
+import { realpath } from 'node:fs/promises'
+import path from 'node:path'
+
+import { ACKNOWLEDGE_GUARDS, type GuardBlock, isGuardAcknowledged } from '../policy'
+import { isSkillAuthoringAllowed } from './skill-authoring'
+
+export const GUARD_NON_WORKSPACE_WRITE = 'nonWorkspaceWrite'
+
+const AGENT_ROOT_WRITE_ALLOWLIST = new Set([
+  'AGENTS.md',
+  'IDENTITY.md',
+  'MEMORY.md',
+  'SOUL.md',
+  'USER.md',
+  'cron.json',
+  'package.json',
+  'typeclaw.json',
+])
+
+// `packages/` is a bun workspace root scaffolded at init (see
+// src/init/index.ts#DIRECTORIES). Reusable systems and custom typeclaw
+// plugins live there as standalone packages, so the agent must be able to
+// write into `packages/<name>/...` without acknowledging the guard — same
+// as `workspace/`, but for code intended to be reused rather than discarded.
+const AGENT_ROOT_DIRECTORY_ALLOWLIST = new Set(['mounts', 'packages'])
+
+export async function checkNonWorkspaceWriteGuard(options: {
+  tool: string
+  args: Record<string, unknown>
+  agentDir: string
+}): Promise<GuardBlock | undefined> {
+  const { tool, args, agentDir } = options
+  if (tool !== 'write' && tool !== 'edit') return undefined
+
+  const rawPath = args.path
+  if (typeof rawPath !== 'string') return undefined
+
+  const targetPath = path.resolve(agentDir, rawPath)
+  const workspacePath = path.resolve(agentDir, 'workspace')
+  const [realTargetPath, realWorkspacePath] = await Promise.all([
+    resolveRealIntendedPath(targetPath),
+    resolveRealIntendedPath(workspacePath),
+  ])
+  if (await isSkillAuthoringAllowed({ tool, args, agentDir })) return undefined
+  if (await isAllowedAgentRootWrite(agentDir, targetPath, realTargetPath)) return undefined
+  if (isInside(realWorkspacePath, realTargetPath)) return undefined
+  if (isGuardAcknowledged(args, GUARD_NON_WORKSPACE_WRITE)) return undefined
+
+  return {
+    block: true,
+    reason: [
+      `Guard \`${GUARD_NON_WORKSPACE_WRITE}\` blocked ${tool} outside the workspace: ${targetPath}.`,
+      `The free-write zone is ${workspacePath}.`,
+      `Retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_NON_WORKSPACE_WRITE}: true\` only if this write is intentional.`,
+    ].join(' '),
+  }
+}
+
+async function isAllowedAgentRootWrite(agentDir: string, targetPath: string, realTargetPath: string): Promise<boolean> {
+  const resolvedAgentDir = path.resolve(agentDir)
+  if (path.dirname(targetPath) === resolvedAgentDir && AGENT_ROOT_WRITE_ALLOWLIST.has(path.basename(targetPath))) {
+    return true
+  }
+
+  for (const dir of AGENT_ROOT_DIRECTORY_ALLOWLIST) {
+    const rootDir = path.join(resolvedAgentDir, dir)
+    if (isInside(await resolveRealIntendedPath(rootDir), realTargetPath)) return true
+  }
+  return false
+}
+
+function isInside(parent: string, child: string): boolean {
+  const relative = path.relative(parent, child)
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))
+}
+
+async function resolveRealIntendedPath(absolutePath: string): Promise<string> {
+  const pending: string[] = []
+  let current = absolutePath
+
+  while (true) {
+    try {
+      const realCurrent = await realpath(current)
+      return path.join(realCurrent, ...pending.reverse())
+    } catch (err) {
+      if (!isNotFoundError(err)) throw err
+    }
+
+    const parent = path.dirname(current)
+    if (parent === current) throw new Error(`could not resolve existing parent for ${absolutePath}`)
+    pending.push(path.basename(current))
+    current = parent
+  }
+}
+
+function isNotFoundError(err: unknown): boolean {
+  return err instanceof Error && 'code' in err && err.code === 'ENOENT'
+}

package/src/bundled-plugins/guard/policies/skill-authoring.ts

@@ -0,0 +1,185 @@
+import { readFile, realpath } from 'node:fs/promises'
+import path from 'node:path'
+
+import type { GuardBlock } from '../policy'
+
+export const GUARD_SKILL_AUTHORING = 'skillAuthoring'
+
+export type SkillAuthoringDecision = GuardBlock | { allow: true } | undefined
+
+const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/
+
+type SkillRoot = {
+  path: string
+}
+
+export async function checkSkillAuthoringGuard(options: {
+  tool: string
+  args: Record<string, unknown>
+  agentDir: string
+}): Promise<GuardBlock | undefined> {
+  const decision = await checkSkillAuthoringDecision(options)
+  return decision && 'block' in decision ? decision : undefined
+}
+
+export async function checkSkillAuthoringDecision(options: {
+  tool: string
+  args: Record<string, unknown>
+  agentDir: string
+}): Promise<SkillAuthoringDecision> {
+  const { tool, args, agentDir } = options
+  if (tool !== 'write' && tool !== 'edit') return undefined
+
+  const rawPath = args.path
+  if (typeof rawPath !== 'string') return undefined
+
+  const targetPath = path.resolve(agentDir, rawPath)
+  const target = await resolveSkillTarget(agentDir, targetPath)
+  if (!target) return undefined
+
+  if (target.rest.length !== 2 || target.rest[1] !== 'SKILL.md') {
+    return block(tool, targetPath, 'skill writes must target exactly <skill-name>/SKILL.md')
+  }
+
+  const skillName = target.rest[0]
+  if (!skillName || !SKILL_NAME_PATTERN.test(skillName)) {
+    return block(tool, targetPath, `skill name must match ${SKILL_NAME_PATTERN}`)
+  }
+  if (skillName.startsWith('typeclaw-')) {
+    return block(tool, targetPath, 'the typeclaw- skill namespace is reserved for bundled skills')
+  }
+
+  const contentResult = await intendedContent(tool, args, targetPath)
+  if ('block' in contentResult) return contentResult
+
+  const frontmatter = parseFrontmatter(contentResult.content)
+  if (!frontmatter) {
+    return block(tool, targetPath, 'SKILL.md must start with YAML frontmatter')
+  }
+  if (frontmatter.name !== skillName) {
+    return block(tool, targetPath, `frontmatter name must match path segment ${skillName}`)
+  }
+  if (!frontmatter.description || frontmatter.description.trim().length === 0) {
+    return block(tool, targetPath, 'frontmatter description is required')
+  }
+
+  return { allow: true }
+}
+
+export async function isSkillAuthoringAllowed(options: {
+  tool: string
+  args: Record<string, unknown>
+  agentDir: string
+}): Promise<boolean> {
+  const decision = await checkSkillAuthoringDecision(options)
+  return decision !== undefined && 'allow' in decision
+}
+
+async function resolveSkillTarget(agentDir: string, targetPath: string): Promise<{ rest: string[] } | undefined> {
+  const roots: SkillRoot[] = [
+    { path: path.join(agentDir, 'memory', 'skills') },
+    { path: path.join(agentDir, '.agents', 'skills') },
+  ]
+  const realTargetPath = await resolveRealIntendedPath(targetPath)
+
+  for (const root of roots) {
+    const realRootPath = await resolveRealIntendedPath(root.path)
+    if (!isInside(realRootPath, realTargetPath)) continue
+    return { rest: path.relative(realRootPath, realTargetPath).split(path.sep).filter(Boolean) }
+  }
+  return undefined
+}
+
+async function intendedContent(
+  tool: string,
+  args: Record<string, unknown>,
+  targetPath: string,
+): Promise<{ content: string } | GuardBlock> {
+  if (tool === 'write') {
+    const content = args.content
+    if (typeof content !== 'string') return block(tool, targetPath, 'write content must be a string')
+    return { content }
+  }
+
+  const edits = args.edits
+  if (!Array.isArray(edits)) return block(tool, targetPath, 'edit calls must include an edits array')
+
+  let content: string
+  try {
+    content = await readFile(targetPath, 'utf8')
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return block(tool, targetPath, `could not read existing skill before edit: ${message}`)
+  }
+
+  for (const edit of edits) {
+    if (!edit || typeof edit !== 'object') return block(tool, targetPath, 'each edit must be an object')
+    const { oldText, newText } = edit as Record<string, unknown>
+    if (typeof oldText !== 'string' || typeof newText !== 'string') {
+      return block(tool, targetPath, 'each edit must include string oldText and newText')
+    }
+    if (oldText.length === 0) return block(tool, targetPath, 'edit oldText must not be empty')
+    if (!content.includes(oldText)) return block(tool, targetPath, 'edit oldText was not found in existing skill')
+    content = content.replace(oldText, newText)
+  }
+  return { content }
+}
+
+function parseFrontmatter(content: string): { name?: string; description?: string } | undefined {
+  const normalized = content.replaceAll('\r\n', '\n')
+  if (!normalized.startsWith('---\n')) return undefined
+  const close = normalized.indexOf('\n---', 4)
+  if (close === -1) return undefined
+
+  const values: { name?: string; description?: string } = {}
+  for (const line of normalized.slice(4, close).split('\n')) {
+    const separator = line.indexOf(':')
+    if (separator === -1) continue
+    const key = line.slice(0, separator).trim()
+    if (key !== 'name' && key !== 'description') continue
+    values[key] = parseScalar(line.slice(separator + 1).trim())
+  }
+  return values
+}
+
+function parseScalar(value: string): string {
+  if (value.length === 0) return ''
+  const quote = value[0]
+  if ((quote === '"' || quote === "'") && value.endsWith(quote)) return value.slice(1, -1)
+  return value
+}
+
+function block(tool: string, targetPath: string, reason: string): GuardBlock {
+  return {
+    block: true,
+    reason: `Guard \`${GUARD_SKILL_AUTHORING}\` blocked ${tool} for ${targetPath}: ${reason}.`,
+  }
+}
+
+function isInside(parent: string, child: string): boolean {
+  const relative = path.relative(parent, child)
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))
+}
+
+async function resolveRealIntendedPath(absolutePath: string): Promise<string> {
+  const pending: string[] = []
+  let current = absolutePath
+
+  while (true) {
+    try {
+      const realCurrent = await realpath(current)
+      return path.join(realCurrent, ...pending.reverse())
+    } catch (err) {
+      if (!isNotFoundError(err)) throw err
+    }
+
+    const parent = path.dirname(current)
+    if (parent === current) throw new Error(`could not resolve existing parent for ${absolutePath}`)
+    pending.push(path.basename(current))
+    current = parent
+  }
+}
+
+function isNotFoundError(err: unknown): boolean {
+  return err instanceof Error && 'code' in err && err.code === 'ENOENT'
+}

package/src/bundled-plugins/guard/policies/uncommitted-changes.ts

@@ -0,0 +1,85 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { ContentPart, ToolResult } from '@/plugin'
+
+export const GUARD_UNCOMMITTED_CHANGES = 'uncommittedChanges'
+
+const FILE_TOUCHING_TOOLS = new Set(['write', 'edit', 'bash'])
+
+const RUNTIME_OWNED_PREFIXES = ['sessions/', 'memory/']
+
+const WARNING_TEXT =
+  '\n\n[guard:uncommittedChanges] The worktree has uncommitted changes. Commit (or stash) them when this task is done — leaving stale changes around between turns risks losing work and confusing future commits.'
+
+export type UncommittedChangesDeps = {
+  readStatus: (agentDir: string) => Promise<readonly string[] | null>
+}
+
+export async function checkUncommittedChangesAdvice(options: {
+  tool: string
+  agentDir: string
+  result: ToolResult
+  deps?: UncommittedChangesDeps
+}): Promise<void> {
+  const { tool, agentDir, result } = options
+  if (!FILE_TOUCHING_TOOLS.has(tool)) return
+  if (!existsSync(join(agentDir, '.git'))) return
+
+  const deps = options.deps ?? defaultDeps
+  const status = await deps.readStatus(agentDir)
+  if (status === null) return
+
+  const dirty = status.filter((p) => !RUNTIME_OWNED_PREFIXES.some((prefix) => p.startsWith(prefix)))
+  if (dirty.length === 0) return
+
+  appendAdviceToContent(result.content, WARNING_TEXT)
+}
+
+export function parsePorcelain(stdout: string): string[] {
+  const out: string[] = []
+  for (const raw of stdout.split('\n')) {
+    if (raw.length < 4) continue
+    const rest = raw.slice(3)
+    const arrowIdx = rest.indexOf(' -> ')
+    out.push(arrowIdx === -1 ? rest : rest.slice(arrowIdx + 4))
+  }
+  return out
+}
+
+function appendAdviceToContent(content: ContentPart[], advice: string): void {
+  for (let i = content.length - 1; i >= 0; i--) {
+    const part = content[i]
+    if (part && part.type === 'text') {
+      content[i] = { ...part, text: `${part.text}${advice}` }
+      return
+    }
+  }
+  content.push({ type: 'text', text: advice.trimStart() })
+}
+
+const defaultDeps: UncommittedChangesDeps = {
+  async readStatus(agentDir) {
+    const bun = getBun()
+    if (!bun) return null
+    try {
+      const proc = bun.spawn({
+        cmd: ['git', 'status', '--porcelain=v1'],
+        cwd: agentDir,
+        stdout: 'pipe',
+        stderr: 'pipe',
+      })
+      const exit = await proc.exited
+      if (exit !== 0) return null
+      const text = await new Response(proc.stdout).text()
+      return parsePorcelain(text)
+    } catch {
+      return null
+    }
+  },
+}
+
+function getBun(): typeof Bun | null {
+  const g = globalThis as { Bun?: typeof Bun }
+  return g.Bun ?? null
+}

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

@@ -0,0 +1,18 @@
+export const ACKNOWLEDGE_GUARDS = 'acknowledgeGuards'
+
+export type GuardBlock = { block: true; reason: string }
+
+export function isGuardAcknowledged(args: Record<string, unknown>, guard: string): boolean {
+  const acknowledgements = args[ACKNOWLEDGE_GUARDS]
+  if (!acknowledgements || typeof acknowledgements !== 'object') return false
+  return (acknowledgements as Record<string, unknown>)[guard] === true
+}
+
+export { GUARD_NON_WORKSPACE_WRITE, checkNonWorkspaceWriteGuard } from './policies/non-workspace-write'
+export {
+  GUARD_SKILL_AUTHORING,
+  checkSkillAuthoringDecision,
+  checkSkillAuthoringGuard,
+  isSkillAuthoringAllowed,
+} from './policies/skill-authoring'
+export { GUARD_UNCOMMITTED_CHANGES, checkUncommittedChangesAdvice } from './policies/uncommitted-changes'

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

@@ -0,0 +1,71 @@
+# typeclaw-plugin-memory
+
+The bundled memory plugin. Owns `MEMORY.md` (long-term memory) and `memory/yyyy-MM-dd.md` (daily streams) plus the two subagents that write them: `memory-logger` and `dreaming`.
+
+This plugin is **auto-loaded** by every TypeClaw agent. There is no `plugins[]` entry to add and no opt-out. To configure it, add a `memory` block to `typeclaw.json`.
+
+## Config
+
+```json
+{
+  "memory": {
+    "idleMs": 10000,
+    "bufferBytes": 100000,
+    "dreaming": { "schedule": "*/30 * * * *" }
+  }
+}
+```
+
+| Field                      | Default            | Effect                                                                                                                                                                                                                                                                                                                                                             |
+| -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `memory.idleMs`            | `10000`            | Debounce window before `memory-logger` spawns after a prompt completes. Minimum `1000`.                                                                                                                                                                                                                                                                            |
+| `memory.bufferBytes`       | `100000`           | Size-based ceiling: spawns `memory-logger` when the transcript grows by this many bytes since the last run, even during continuous activity. `0` disables. Minimum `10000` when non-zero.                                                                                                                                                                          |
+| `memory.dreaming`          | `{}` (cron job on) | Dreaming cron job is always registered. Override `schedule` to change when it fires.                                                                                                                                                                                                                                                                               |
+| `memory.dreaming.schedule` | `"*/30 * * * *"`   | Five-field cron expression. Defaults to every 30 minutes; fires short-circuit with zero LLM cost when nothing sits past the watermark, so frequent no-op fires are cheap and let sporadic agents still consolidate while alive (`src/cron/scheduler.ts` has no catchup for missed fires). Second-level schedules are rejected to avoid noisy no-op dreaming loops. |
+
+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/<today>.md`. Coalesced per `agentDir`; the plugin chains spawn calls onto a per-agent Promise so two concurrent channel sessions never race on the same daily stream file.                            |
+| Subagent | `dreaming`                 | Reads `MEMORY.md` plus undreamed daily-stream tails, rewrites `MEMORY.md`, optionally writes muscle-memory skills under `memory/skills/<name>/SKILL.md`, advances the per-day watermark, and `git commit -m Dream` the result. Coalesced per `agentDir`.                          |
+| Cron job | `__plugin_memory_dreaming` | `kind: 'prompt'`, `subagent: 'dreaming'`, scheduled per `memory.dreaming.schedule`.                                                                                                                                                                                               |
+| Hook     | `session.prompt`           | Appends the rendered memory section (`# Memory`, `MEMORY.md`, undreamed stream tails) to `event.prompt`.                                                                                                                                                                          |
+| Hook     | `session.idle`             | Per-session debouncer with size-based ceiling. Resets a `setTimeout(idleMs)` on every event; on fire, calls `ctx.spawnSubagent('memory-logger', ...)`. Also `fs.stat`s the transcript on every event and spawns immediately when growth since the last run reaches `bufferBytes`. |
+| Hook     | `session.end`              | Cancels the debounce timer and immediately spawns `memory-logger` (so the final transcript is captured even when the user disconnects right away).                                                                                                                                |
+
+## Files on disk
+
+- **`MEMORY.md`** — long-term memory. Created by the dreaming subagent on first run if absent. Force-committed by the runtime; `skip-worktree` flag is set so the human's `git status` stays clean.
+- **`memory/yyyy-MM-dd.md`** — daily fragment streams. Appended to by `memory-logger`. Created on demand. Gitignored at the agent's level but force-committed alongside `MEMORY.md` after each dreaming run.
+- **`memory/skills/<name>/SKILL.md`** — _muscle memory_. Skills the dreaming subagent distills from repeated procedures it sees in daily streams. Auto-discovered as first-class skills by `createResourceLoader`, and force-committed under the same `memory/` snapshot path as the daily streams. Written or refined with the standard `write` / `edit` tools; the bundled guard plugin enforces the exact `memory/skills/<name>/SKILL.md` path shape, single-segment kebab/snake-case names, matching frontmatter, and symlink/path-traversal safety. There is no runtime skill-delete tool; outright deletion of muscle-memory skills remains a user decision.
+- **`memory/.dreaming-state.json`** — per-day watermarks (line counts already consolidated into `MEMORY.md`). Plain JSON; on malformed input the plugin fails open with empty state.
+
+`typeclaw init` does **not** scaffold these files. They appear when needed.
+
+## How `session.idle` works
+
+Core fires `session.idle` immediately after every `session.prompt()` completion (success or error). The plugin owns the debounce: it keeps a `Map<sessionId, Timeout>` and resets the timer on every event. When the timer fires, the plugin spawns `memory-logger` for that session.
+
+If the user starts a new prompt before the timer fires, the next `session.idle` event resets the timer. If the user disconnects, `session.end` cancels the timer and fires `memory-logger` immediately so the final transcript is captured.
+
+In channel sessions, the agent rarely goes idle long enough to trip the timer because new participant messages keep arriving. The size-based ceiling handles this: on every `session.idle` the plugin `fs.stat`s the transcript and compares against the size at the last memory-logger run. Once growth reaches `memory.bufferBytes`, the timer is cancelled and `memory-logger` spawns immediately. The watermark on the output side absorbs any over-firing — if a buffer-trip arrives on a transcript chunk that's all tool noise, `memory-logger` reads it, decides nothing is worth logging, advances the watermark, and exits.
+
+## Migration notes (from before the plugin existed)
+
+- `memory.idleMs` and `memory.dreaming.schedule` already existed in core's `typeclaw.json` schema. They moved into this plugin's `configSchema` verbatim. Existing agents continue to work with no config change.
+- `memory.dreaming.schedule` was previously live-reloadable. It is now **restart-required** because plugin config is read once at boot. To change the schedule, edit `typeclaw.json` and run `typeclaw restart`.
+- The cron job ID changed from `__internal_dreaming` to `__plugin_memory_dreaming`. Anything that referenced the old ID (custom dashboards, scripts) needs updating.
+
+## Tests
+
+- `index.test.ts` — composition tests (config schema, hook wiring, debounce semantics, MEMORY.md auto-create).
+- `memory-logger.test.ts` — system prompt invariants, watermark handling.
+- `dreaming.test.ts` — orchestration, watermark advancement, git snapshot (including muscle-memory skill files), system prompt + tool-surface invariants.
+- `dreaming-state.test.ts` — fail-open semantics on malformed state.
+- `watermark.test.ts` — marker parsing.
+- `append-tool.test.ts` — append-only semantics.
+- `src/bundled-plugins/guard/policies/skill-authoring.test.ts` — runtime skill authoring guard: path sandboxing, name validation, YAML frontmatter, and write/edit final-content validation.
+- `load-memory.test.ts` — memory section rendering, undreamed-tail filtering, watermark stripping.

package/src/bundled-plugins/memory/append-tool.ts

@@ -0,0 +1,84 @@
+import { appendFile, mkdir, open, readFile, stat } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+import { z } from 'zod'
+
+import { defineTool } from '@/plugin'
+
+import { fragmentContentHash, parseFragments } from './fragment-parser'
+import { detectSecrets } from './secret-detector'
+
+const NEWLINE_BYTE = 0x0a
+
+export const appendTool = defineTool({
+  description:
+    'Append content to a file. Creates the file (and any missing parent directories) if needed. Never truncates or overwrites existing content. If the file is non-empty and does not already end in a newline, a single newline is inserted before the appended content so consecutive appends do not run together. Refuses to write content that contains recognizable credential patterns (API keys, tokens, private keys); record the variable name and how it was discovered, never the value. Refuses to append a fragment whose topic+body already exists in the file (case-by-case; topics legitimately repeat across days, but byte-equivalent fragments within the same daily stream are duplicates by design).',
+  parameters: z.object({
+    path: z.string().describe('Path to the file to append to (relative or absolute).'),
+    content: z.string().describe('Content to append, exactly as given.'),
+  }),
+  async execute({ path, content }) {
+    const secrets = detectSecrets(content)
+    if (secrets.length > 0) {
+      const ruleNames = [...new Set(secrets.map((s) => s.rule))].join(', ')
+      throw new Error(
+        `Refusing to append: content contains a recognized credential pattern (${ruleNames}). ` +
+          `Memory fragments must never quote secret values verbatim. Record the env var name and how it ` +
+          `was discovered, not the value itself.`,
+      )
+    }
+    const incomingFragments = parseFragments(content)
+    if (incomingFragments.length > 0) {
+      const existingHashes = await readExistingFragmentHashes(path)
+      const duplicates = incomingFragments.filter((f) => existingHashes.has(fragmentContentHash(f)))
+      if (duplicates.length > 0) {
+        const topics = duplicates.map((d) => `"${d.topic}"`).join(', ')
+        throw new Error(
+          `Refusing to append: ${duplicates.length} fragment${duplicates.length === 1 ? '' : 's'} (${topics}) ` +
+            `already exist in ${path} with byte-equivalent content. The dreaming subagent will see the existing ` +
+            `fragment; do not write it again. If the new occurrence is genuinely informative (e.g. a recurrence ` +
+            `that establishes a pattern), write a fragment that says so explicitly rather than restating the ` +
+            `original.`,
+        )
+      }
+    }
+    await mkdir(dirname(path), { recursive: true })
+    const prefix = (await needsLeadingNewline(path)) ? '\n' : ''
+    await appendFile(path, prefix + content, 'utf-8')
+    const bytesAppended = prefix.length + content.length
+    return {
+      content: [{ type: 'text' as const, text: `Appended ${bytesAppended} bytes to ${path}` }],
+      details: { path, bytesAppended, leadingNewlineInserted: prefix.length > 0 },
+    }
+  },
+})
+
+async function readExistingFragmentHashes(path: string): Promise<Set<string>> {
+  let content: string
+  try {
+    content = await readFile(path, 'utf8')
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return new Set()
+    throw err
+  }
+  return new Set(parseFragments(content).map((f) => fragmentContentHash(f)))
+}
+
+async function needsLeadingNewline(path: string): Promise<boolean> {
+  let info: Awaited<ReturnType<typeof stat>>
+  try {
+    info = await stat(path)
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return false
+    throw err
+  }
+  if (info.size === 0) return false
+  const fh = await open(path, 'r')
+  try {
+    const buf = Buffer.alloc(1)
+    await fh.read(buf, 0, 1, info.size - 1)
+    return buf[0] !== NEWLINE_BYTE
+  } finally {
+    await fh.close()
+  }
+}

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

@@ -0,0 +1,86 @@
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+export const DREAMING_STATE_FILE = 'memory/.dreaming-state.json'
+
+const VERSION = 1
+
+// Per-day watermark: the number of lines of `memory/yyyy-MM-dd.md` that have
+// been consolidated into MEMORY.md. The next dreaming run reads only the tail
+// past this point. The next system-prompt injection (loadMemory) shows only
+// the tail too, so already-consolidated content does not appear twice.
+//
+// We deliberately track lines (not bytes) because line-based slicing is
+// human-inspectable and the `fragments:` citations in MEMORY.md already use
+// `memory/yyyy-MM-dd:<line>-<line>` notation.
+export type DreamingState = {
+  version: number
+  dreamedThrough: Record<string, DreamedDay>
+}
+
+export type DreamedDay = {
+  lines: number
+  ts: string
+}
+
+export function emptyState(): DreamingState {
+  return { version: VERSION, dreamedThrough: {} }
+}
+
+// Missing or unreadable file → empty state. Malformed JSON or wrong shape is
+// also treated as empty: the cost is one redundant re-consolidation, which is
+// strictly safer than crashing the dreaming pipeline because of a bad state
+// file.
+export async function loadDreamingState(agentDir: string): Promise<DreamingState> {
+  const path = join(agentDir, DREAMING_STATE_FILE)
+  if (!existsSync(path)) return emptyState()
+
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch {
+    return emptyState()
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return emptyState()
+  }
+
+  if (!isDreamingState(parsed)) return emptyState()
+  return parsed
+}
+
+export async function saveDreamingState(agentDir: string, state: DreamingState): Promise<void> {
+  const path = join(agentDir, DREAMING_STATE_FILE)
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
+}
+
+export function getDreamedLines(state: DreamingState, date: string): number {
+  return state.dreamedThrough[date]?.lines ?? 0
+}
+
+export function setDreamedLines(state: DreamingState, date: string, lines: number, ts: string): DreamingState {
+  return {
+    version: state.version,
+    dreamedThrough: { ...state.dreamedThrough, [date]: { lines, ts } },
+  }
+}
+
+function isDreamingState(value: unknown): value is DreamingState {
+  if (typeof value !== 'object' || value === null) return false
+  const v = value as Record<string, unknown>
+  if (v.version !== VERSION) return false
+  if (typeof v.dreamedThrough !== 'object' || v.dreamedThrough === null) return false
+  for (const [, entry] of Object.entries(v.dreamedThrough as Record<string, unknown>)) {
+    if (typeof entry !== 'object' || entry === null) return false
+    const e = entry as Record<string, unknown>
+    if (typeof e.lines !== 'number' || e.lines < 0) return false
+    if (typeof e.ts !== 'string') return false
+  }
+  return true
+}