@try-works/dsh-memory 0.1.19 → 0.1.21

package/src/working.js

@@ -1,288 +1,288 @@
-// Working memory: what the AGENT is doing here - the task in hand, what it recently did, and
-// what comes next.
-//
-// This is deliberately NOT repository state. state.md answers "what is this repository right
-// now" and is owned by the codebase; working.md answers "what am I in the middle of" and is
-// owned by the agent. The same repository can be worked on with entirely different intents, and
-// the same intent can span repositories, so the two must not be merged.
-//
-// It has two kinds of section, because the information has two shapes:
-//
-//   CURRENT  - Task, Next steps, Plan, Blocked by. A newer statement replaces the old one:
-//              there is one current task, one current plan.
-//   ROLLING  - Recent activity. A bounded, newest-first log: what actually happened, kept
-//              short by trimming the oldest entries rather than by overwriting.
-//
-// Working memory decays faster than anything else in the store - a plan from last week is
-// history, not a plan - so it carries its own timestamps and is graded on a scale of hours.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { layerDir } from './store.js'
-
-/** Sections whose content is replaced by a newer statement. */
-export const WORKING_SECTIONS = ['Task', 'Next steps', 'Plan', 'Blocked by']
-/** The rolling log section. */
-export const ACTIVITY_SECTION = 'Recent activity'
-
-/** Working memory goes stale in hours, not days. */
-export const WORKING_FRESH_MS = 8 * 3600_000
-export const WORKING_STALE_MS = 48 * 3600_000
-/** How much activity to keep. Bounded by entries and by total characters. */
-export const ACTIVITY_MAX_ENTRIES = 40
-export const ACTIVITY_MAX_CHARS = 4000
-
-/** Absolute path of a workspace working file. */
-export function workingPath(root, scope, key) { return join(layerDir(root, scope, key), 'working.md') }
-
-/** Canonical display form of a working section name. */
-export function workingTitle(name) {
-  const text = String(name ?? '').trim().replace(/\s+/g, ' ')
-  if (text === '') return ''
-  return text[0].toUpperCase() + text.slice(1)
-}
-/** Matching key, so "next steps" and "Next steps" are one section. */
-export function workingKey(name) { return String(name ?? '').trim().toLowerCase() }
-
-/** True when the name refers to the rolling activity log. */
-export function isActivity(name) { return workingKey(name) === workingKey(ACTIVITY_SECTION) }
-
-/** Escape a line that would otherwise parse as a heading. */
-function escapeHeadings(text) {
-  return String(text ?? '').replace(/\r\n/g, String.fromCharCode(10)).split(String.fromCharCode(10))
-    .map((line) => line.replace(/^(#{1,6}\s)/, '\\$1')).join(String.fromCharCode(10))
-}
-function unescapeHeadings(text) {
-  return String(text ?? '').split(String.fromCharCode(10)).map((line) => line.replace(/^\\(#{1,6}\s)/, '$1')).join(String.fromCharCode(10))
-}
-
-/**
- * Freshness of working memory, graded in hours.
- * @param lastActivity - ISO timestamp of the newest activity entry.
- * @returns {{verdict: 'fresh'|'aging'|'stale'|'empty', ageMs: number|undefined}}
- */
-export function workingVerdict(lastActivity, now = Date.now(), options = {}) {
-  const freshMs = options.freshMs ?? WORKING_FRESH_MS
-  const staleMs = options.staleMs ?? WORKING_STALE_MS
-  const parsed = Date.parse(String(lastActivity ?? ''))
-  if (!Number.isFinite(parsed)) return { verdict: 'empty', ageMs: undefined }
-  const ageMs = Math.max(0, now - parsed)
-  if (ageMs <= freshMs) return { verdict: 'fresh', ageMs }
-  if (ageMs <= staleMs) return { verdict: 'aging', ageMs }
-  return { verdict: 'stale', ageMs }
-}
-
-/** Short age for working memory: 25m, 6h, 3d. */
-export function workingAge(ageMs) {
-  if (!Number.isFinite(ageMs)) return 'unknown'
-  if (ageMs < 60_000) return 'just now'
-  const minutes = Math.round(ageMs / 60_000)
-  if (minutes < 90) return minutes + 'm'
-  const hours = Math.round(ageMs / 3600_000)
-  if (hours < 48) return hours + 'h'
-  return Math.round(ageMs / 86400_000) + 'd'
-}
-
-/** Marker shown wherever working memory appears. */
-export function workingMarker(verdict, ageMs) {
-  if (verdict === 'fresh') return ''
-  if (verdict === 'empty') return ' [NOT STARTED]'
-  return ' [' + verdict.toUpperCase() + ' ' + workingAge(ageMs) + ']'
-}
-
-/**
- * Parse a working file into its sections and its activity log.
- * @returns {{ updated: string|undefined, lastActivity: string|undefined, sections: object[], activity: {at: string, text: string}[] }}
- */
-export function parseWorking(text) {
-  const lines = String(text ?? '').split(String.fromCharCode(10))
-  const sections = []
-  const activity = []
-  let updated
-  let current = null
-  const push = () => { if (current) { current.content = unescapeHeadings(current.content.join(String.fromCharCode(10)).trim()); sections.push(current) } }
-  for (const line of lines) {
-    const stamp = /^Last activity:\s*(.+)$/.exec(line.trim())
-    if (stamp && updated === undefined) { updated = stamp[1].trim(); continue }
-    const heading = /^##\s+(.+)$/.exec(line)
-    if (heading) { push(); current = { name: heading[1].trim(), updated: undefined, content: [] }; continue }
-    if (!current) continue
-    if (isActivity(current.name)) {
-      const bullet = /^-\s*(?:(\S+)\s+)?(.*)$/.exec(line.trim())
-      if (bullet && bullet[2] !== '') activity.push({ at: bullet[1] ?? '', text: bullet[2] })
-      continue
-    }
-    const when = /^\*\*Updated:\*\*\s*(.*)$/.exec(line.trim())
-    if (when) { current.updated = when[1].trim() || undefined; continue }
-    current.content.push(line)
-  }
-  push()
-  const named = sections.filter((s) => !isActivity(s.name))
-  return { updated, lastActivity: activity.length ? activity[activity.length - 1].at : undefined, sections: named, activity }
-}
-
-/** Render a whole working file. */
-/**
- * The preamble every working file carries. Rendered on EVERY write, so the file keeps stating
- * its own purpose and ownership no matter how many times it is rewritten - the agent is
- * expected to read this file directly, not only through the injected card.
- */
-export function workingPreamble() {
-  const NL = String.fromCharCode(10)
-  return [
-    'THIS FILE BELONGS TO THE AGENT. It is not repository state (that is state.md) and not',
-    'durable memory (those are the layered entries). It is your own head for this workspace:',
-    'what you are doing, what you just did, and what comes next.',
-    '',
-    'You own it. Read it, edit it, and keep it honest. Write it with memory_working, or edit',
-    'this file directly. Nothing else writes here, so a stale or empty file means the intent',
-    'was never recorded.',
-    '',
-    '  Task              what you are working on right now   (replaced on write)',
-    '  Next steps        the immediate plan                  (replaced on write)',
-    '  Plan              the shape of the whole effort       (replaced on write)',
-    '  Blocked by        what is stopping progress           (replaced on write)',
-    '  Recent activity   a rolling log of what you did       (newest last, oldest trimmed)',
-    '',
-    'Durable facts belong in the layered entries. When something here stops changing, move it',
-    'to semantic/episodic/procedural and let this file go quiet.',
-  ].join(NL)
-}
-
-/** Render a whole working file. */
-export function renderWorking(title, sections, activity, options = {}) {
-  const NL = String.fromCharCode(10)
-  const lines = [
-    '# ' + title + ' — working memory',
-    '',
-    workingPreamble(),
-    '',
-    'Last activity: ' + (options.lastActivity ?? ''),
-    '',
-  ]
-  for (const section of sections) {
-    lines.push('## ' + section.name, '')
-    if (section.updated) lines.push('**Updated:** ' + section.updated)
-    lines.push('', section.content.trim(), '')
-  }
-  lines.push('## ' + ACTIVITY_SECTION, '')
-  if (activity.length === 0) lines.push('(nothing recorded yet)')
-  else for (const item of activity) lines.push('- ' + (item.at ? item.at + ' ' : '') + item.text)
-  lines.push('')
-  return lines.join(NL).replace(new RegExp(NL + '{3,}', 'g'), NL + NL).trimEnd() + NL
-}
-/** Read a working file, graded. Returns undefined when there is none. */
-export function readWorking(root, scope, key, options = {}) {
-  const path = workingPath(root, scope, key)
-  if (!existsSync(path)) return undefined
-  let text
-  try { text = readFileSync(path, 'utf8') } catch { return undefined }
-  const parsed = parseWorking(text)
-  const now = options.now ?? Date.now()
-  return { path, ...parsed, ...workingVerdict(parsed.lastActivity, now, options) }
-}
-
-/** Load the current state of a file for rewriting, or an empty shell. */
-function loadForWrite(root, scope, key, now) {
-  const existing = readWorking(root, scope, key, { now: Date.parse(now) })
-  if (!existing) return { sections: [], activity: [] }
-  return {
-    sections: existing.sections.map((s) => ({ name: s.name, updated: s.updated, content: s.content })),
-    activity: existing.activity.slice(),
-  }
-}
-
-/** Order sections by the canonical list, keeping unknown ones after it. */
-function orderSections(sections) {
-  return [...sections].sort((a, b) => {
-    const ia = WORKING_SECTIONS.findIndex((s) => workingKey(s) === workingKey(a.name))
-    const ib = WORKING_SECTIONS.findIndex((s) => workingKey(s) === workingKey(b.name))
-    if (ia === -1 && ib === -1) return 0
-    if (ia === -1) return 1
-    if (ib === -1) return -1
-    return ia - ib
-  })
-}
-
-function persist(root, scope, key, sections, activity, now) {
-  mkdirSync(layerDir(root, scope, key), { recursive: true })
-  writeFileSync(workingPath(root, scope, key), renderWorking(scope === 'global' ? 'Global' : key, orderSections(sections), activity, { lastActivity: activity.length ? activity[activity.length - 1].at : '' }), 'utf8')
-}
-
-/**
- * Set a CURRENT section ("what am I doing"), replacing any previous version.
- * @returns {{ section: string, updated: string, created: boolean, sections: string[] }}
- */
-export function writeWorkingSection(root, scope, key, section, content, options = {}) {
-  const name = workingTitle(section)
-  if (name === '' || name.length > 60 || /[\r\n]/.test(name) || name.startsWith('#')) throw new Error('invalid working section name: ' + String(section))
-  if (isActivity(name)) throw new Error('"' + ACTIVITY_SECTION + '" is a rolling log; use appendActivity')
-  const body = escapeHeadings(content).trim()
-  if (body === '') throw new Error('working section content must not be empty')
-  const now = options.now ?? new Date().toISOString()
-  const state = loadForWrite(root, scope, key, now)
-  const wanted = workingKey(name)
-  const prior = state.sections.find((s) => workingKey(s.name) === wanted)
-  const kept = state.sections.filter((s) => workingKey(s.name) !== wanted)
-  const written = { name: prior ? prior.name : name, updated: now, content: body }
-  persist(root, scope, key, [...kept, written], state.activity, now)
-  return { section: written.name, updated: now, created: !prior, sections: orderSections([...kept, written]).map((s) => s.name) }
-}
-
-/**
- * Append to the rolling activity log. Newest last, trimmed oldest-first by entry count and
- * total characters, and identical adjacent notes are not repeated.
- * @param notes - a string or an array of strings.
- */
-export function appendActivity(root, scope, key, notes, options = {}) {
-  const list = (Array.isArray(notes) ? notes : [notes])
-    .map((n) => String(n ?? '').replace(/\s+/g, ' ').trim())
-    .filter(Boolean)
-  if (list.length === 0) return { added: 0, total: 0 }
-  const now = options.now ?? new Date().toISOString()
-  const state = loadForWrite(root, scope, key, now)
-  const maxEntries = options.maxEntries ?? ACTIVITY_MAX_ENTRIES
-  const maxChars = options.maxChars ?? ACTIVITY_MAX_CHARS
-  let added = 0
-  for (const text of list) {
-    const last = state.activity[state.activity.length - 1]
-    if (last && last.text === text) continue
-    state.activity.push({ at: now, text })
-    added += 1
-  }
-  // Trim oldest-first until both bounds hold.
-  while (state.activity.length > maxEntries) state.activity.shift()
-  let chars = state.activity.reduce((n, a) => n + a.text.length + a.at.length + 3, 0)
-  while (chars > maxChars && state.activity.length > 1) {
-    const dropped = state.activity.shift()
-    chars -= dropped.text.length + dropped.at.length + 3
-  }
-  persist(root, scope, key, state.sections, state.activity, now)
-  return { added, total: state.activity.length }
-}
-
-/** Clear the activity log, keeping the current sections. */
-export function clearActivity(root, scope, key, options = {}) {
-  const now = options.now ?? new Date().toISOString()
-  const state = loadForWrite(root, scope, key, now)
-  const removed = state.activity.length
-  persist(root, scope, key, state.sections, [], now)
-  return { removed }
-}
-
-/**
- * A short picture of where the work stands: the task, the next step, and how recent it is.
- * @returns {{ verdict: string, ageMs: number|undefined, task?: string, nextStep?: string, activity: number }}
- */
-export function workingSummary(root, scope, key, options = {}) {
-  const working = readWorking(root, scope, key, options)
-  if (!working) return { verdict: 'empty', ageMs: undefined, activity: 0 }
-  const find = (name) => working.sections.find((s) => workingKey(s.name) === workingKey(name))
-  const next = find('Next steps')
-  return {
-    verdict: working.verdict,
-    ageMs: working.ageMs,
-    task: find('Task') ? find('Task').content.split(String.fromCharCode(10))[0].slice(0, 160) : undefined,
-    nextStep: next ? next.content.split(String.fromCharCode(10)).map((l) => l.trim()).filter(Boolean)[0] : undefined,
-    activity: working.activity.length,
-  }
-}
+// Working memory: what the AGENT is doing here - the task in hand, what it recently did, and
+// what comes next.
+//
+// This is deliberately NOT repository state. state.md answers "what is this repository right
+// now" and is owned by the codebase; working.md answers "what am I in the middle of" and is
+// owned by the agent. The same repository can be worked on with entirely different intents, and
+// the same intent can span repositories, so the two must not be merged.
+//
+// It has two kinds of section, because the information has two shapes:
+//
+//   CURRENT  - Task, Next steps, Plan, Blocked by. A newer statement replaces the old one:
+//              there is one current task, one current plan.
+//   ROLLING  - Recent activity. A bounded, newest-first log: what actually happened, kept
+//              short by trimming the oldest entries rather than by overwriting.
+//
+// Working memory decays faster than anything else in the store - a plan from last week is
+// history, not a plan - so it carries its own timestamps and is graded on a scale of hours.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { layerDir } from './store.js'
+
+/** Sections whose content is replaced by a newer statement. */
+export const WORKING_SECTIONS = ['Task', 'Next steps', 'Plan', 'Blocked by']
+/** The rolling log section. */
+export const ACTIVITY_SECTION = 'Recent activity'
+
+/** Working memory goes stale in hours, not days. */
+export const WORKING_FRESH_MS = 8 * 3600_000
+export const WORKING_STALE_MS = 48 * 3600_000
+/** How much activity to keep. Bounded by entries and by total characters. */
+export const ACTIVITY_MAX_ENTRIES = 40
+export const ACTIVITY_MAX_CHARS = 4000
+
+/** Absolute path of a workspace working file. */
+export function workingPath(root, scope, key) { return join(layerDir(root, scope, key), 'working.md') }
+
+/** Canonical display form of a working section name. */
+export function workingTitle(name) {
+  const text = String(name ?? '').trim().replace(/\s+/g, ' ')
+  if (text === '') return ''
+  return text[0].toUpperCase() + text.slice(1)
+}
+/** Matching key, so "next steps" and "Next steps" are one section. */
+export function workingKey(name) { return String(name ?? '').trim().toLowerCase() }
+
+/** True when the name refers to the rolling activity log. */
+export function isActivity(name) { return workingKey(name) === workingKey(ACTIVITY_SECTION) }
+
+/** Escape a line that would otherwise parse as a heading. */
+function escapeHeadings(text) {
+  return String(text ?? '').replace(/\r\n/g, String.fromCharCode(10)).split(String.fromCharCode(10))
+    .map((line) => line.replace(/^(#{1,6}\s)/, '\\$1')).join(String.fromCharCode(10))
+}
+function unescapeHeadings(text) {
+  return String(text ?? '').split(String.fromCharCode(10)).map((line) => line.replace(/^\\(#{1,6}\s)/, '$1')).join(String.fromCharCode(10))
+}
+
+/**
+ * Freshness of working memory, graded in hours.
+ * @param lastActivity - ISO timestamp of the newest activity entry.
+ * @returns {{verdict: 'fresh'|'aging'|'stale'|'empty', ageMs: number|undefined}}
+ */
+export function workingVerdict(lastActivity, now = Date.now(), options = {}) {
+  const freshMs = options.freshMs ?? WORKING_FRESH_MS
+  const staleMs = options.staleMs ?? WORKING_STALE_MS
+  const parsed = Date.parse(String(lastActivity ?? ''))
+  if (!Number.isFinite(parsed)) return { verdict: 'empty', ageMs: undefined }
+  const ageMs = Math.max(0, now - parsed)
+  if (ageMs <= freshMs) return { verdict: 'fresh', ageMs }
+  if (ageMs <= staleMs) return { verdict: 'aging', ageMs }
+  return { verdict: 'stale', ageMs }
+}
+
+/** Short age for working memory: 25m, 6h, 3d. */
+export function workingAge(ageMs) {
+  if (!Number.isFinite(ageMs)) return 'unknown'
+  if (ageMs < 60_000) return 'just now'
+  const minutes = Math.round(ageMs / 60_000)
+  if (minutes < 90) return minutes + 'm'
+  const hours = Math.round(ageMs / 3600_000)
+  if (hours < 48) return hours + 'h'
+  return Math.round(ageMs / 86400_000) + 'd'
+}
+
+/** Marker shown wherever working memory appears. */
+export function workingMarker(verdict, ageMs) {
+  if (verdict === 'fresh') return ''
+  if (verdict === 'empty') return ' [NOT STARTED]'
+  return ' [' + verdict.toUpperCase() + ' ' + workingAge(ageMs) + ']'
+}
+
+/**
+ * Parse a working file into its sections and its activity log.
+ * @returns {{ updated: string|undefined, lastActivity: string|undefined, sections: object[], activity: {at: string, text: string}[] }}
+ */
+export function parseWorking(text) {
+  const lines = String(text ?? '').split(String.fromCharCode(10))
+  const sections = []
+  const activity = []
+  let updated
+  let current = null
+  const push = () => { if (current) { current.content = unescapeHeadings(current.content.join(String.fromCharCode(10)).trim()); sections.push(current) } }
+  for (const line of lines) {
+    const stamp = /^Last activity:\s*(.+)$/.exec(line.trim())
+    if (stamp && updated === undefined) { updated = stamp[1].trim(); continue }
+    const heading = /^##\s+(.+)$/.exec(line)
+    if (heading) { push(); current = { name: heading[1].trim(), updated: undefined, content: [] }; continue }
+    if (!current) continue
+    if (isActivity(current.name)) {
+      const bullet = /^-\s*(?:(\S+)\s+)?(.*)$/.exec(line.trim())
+      if (bullet && bullet[2] !== '') activity.push({ at: bullet[1] ?? '', text: bullet[2] })
+      continue
+    }
+    const when = /^\*\*Updated:\*\*\s*(.*)$/.exec(line.trim())
+    if (when) { current.updated = when[1].trim() || undefined; continue }
+    current.content.push(line)
+  }
+  push()
+  const named = sections.filter((s) => !isActivity(s.name))
+  return { updated, lastActivity: activity.length ? activity[activity.length - 1].at : undefined, sections: named, activity }
+}
+
+/** Render a whole working file. */
+/**
+ * The preamble every working file carries. Rendered on EVERY write, so the file keeps stating
+ * its own purpose and ownership no matter how many times it is rewritten - the agent is
+ * expected to read this file directly, not only through the injected card.
+ */
+export function workingPreamble() {
+  const NL = String.fromCharCode(10)
+  return [
+    'THIS FILE BELONGS TO THE AGENT. It is not repository state (that is state.md) and not',
+    'durable memory (those are the layered entries). It is your own head for this workspace:',
+    'what you are doing, what you just did, and what comes next.',
+    '',
+    'You own it. Read it, edit it, and keep it honest. Write it with memory_working, or edit',
+    'this file directly. Nothing else writes here, so a stale or empty file means the intent',
+    'was never recorded.',
+    '',
+    '  Task              what you are working on right now   (replaced on write)',
+    '  Next steps        the immediate plan                  (replaced on write)',
+    '  Plan              the shape of the whole effort       (replaced on write)',
+    '  Blocked by        what is stopping progress           (replaced on write)',
+    '  Recent activity   a rolling log of what you did       (newest last, oldest trimmed)',
+    '',
+    'Durable facts belong in the layered entries. When something here stops changing, move it',
+    'to semantic/episodic/procedural and let this file go quiet.',
+  ].join(NL)
+}
+
+/** Render a whole working file. */
+export function renderWorking(title, sections, activity, options = {}) {
+  const NL = String.fromCharCode(10)
+  const lines = [
+    '# ' + title + ' — working memory',
+    '',
+    workingPreamble(),
+    '',
+    'Last activity: ' + (options.lastActivity ?? ''),
+    '',
+  ]
+  for (const section of sections) {
+    lines.push('## ' + section.name, '')
+    if (section.updated) lines.push('**Updated:** ' + section.updated)
+    lines.push('', section.content.trim(), '')
+  }
+  lines.push('## ' + ACTIVITY_SECTION, '')
+  if (activity.length === 0) lines.push('(nothing recorded yet)')
+  else for (const item of activity) lines.push('- ' + (item.at ? item.at + ' ' : '') + item.text)
+  lines.push('')
+  return lines.join(NL).replace(new RegExp(NL + '{3,}', 'g'), NL + NL).trimEnd() + NL
+}
+/** Read a working file, graded. Returns undefined when there is none. */
+export function readWorking(root, scope, key, options = {}) {
+  const path = workingPath(root, scope, key)
+  if (!existsSync(path)) return undefined
+  let text
+  try { text = readFileSync(path, 'utf8') } catch { return undefined }
+  const parsed = parseWorking(text)
+  const now = options.now ?? Date.now()
+  return { path, ...parsed, ...workingVerdict(parsed.lastActivity, now, options) }
+}
+
+/** Load the current state of a file for rewriting, or an empty shell. */
+function loadForWrite(root, scope, key, now) {
+  const existing = readWorking(root, scope, key, { now: Date.parse(now) })
+  if (!existing) return { sections: [], activity: [] }
+  return {
+    sections: existing.sections.map((s) => ({ name: s.name, updated: s.updated, content: s.content })),
+    activity: existing.activity.slice(),
+  }
+}
+
+/** Order sections by the canonical list, keeping unknown ones after it. */
+function orderSections(sections) {
+  return [...sections].sort((a, b) => {
+    const ia = WORKING_SECTIONS.findIndex((s) => workingKey(s) === workingKey(a.name))
+    const ib = WORKING_SECTIONS.findIndex((s) => workingKey(s) === workingKey(b.name))
+    if (ia === -1 && ib === -1) return 0
+    if (ia === -1) return 1
+    if (ib === -1) return -1
+    return ia - ib
+  })
+}
+
+function persist(root, scope, key, sections, activity, now) {
+  mkdirSync(layerDir(root, scope, key), { recursive: true })
+  writeFileSync(workingPath(root, scope, key), renderWorking(scope === 'global' ? 'Global' : key, orderSections(sections), activity, { lastActivity: activity.length ? activity[activity.length - 1].at : '' }), 'utf8')
+}
+
+/**
+ * Set a CURRENT section ("what am I doing"), replacing any previous version.
+ * @returns {{ section: string, updated: string, created: boolean, sections: string[] }}
+ */
+export function writeWorkingSection(root, scope, key, section, content, options = {}) {
+  const name = workingTitle(section)
+  if (name === '' || name.length > 60 || /[\r\n]/.test(name) || name.startsWith('#')) throw new Error('invalid working section name: ' + String(section))
+  if (isActivity(name)) throw new Error('"' + ACTIVITY_SECTION + '" is a rolling log; use appendActivity')
+  const body = escapeHeadings(content).trim()
+  if (body === '') throw new Error('working section content must not be empty')
+  const now = options.now ?? new Date().toISOString()
+  const state = loadForWrite(root, scope, key, now)
+  const wanted = workingKey(name)
+  const prior = state.sections.find((s) => workingKey(s.name) === wanted)
+  const kept = state.sections.filter((s) => workingKey(s.name) !== wanted)
+  const written = { name: prior ? prior.name : name, updated: now, content: body }
+  persist(root, scope, key, [...kept, written], state.activity, now)
+  return { section: written.name, updated: now, created: !prior, sections: orderSections([...kept, written]).map((s) => s.name) }
+}
+
+/**
+ * Append to the rolling activity log. Newest last, trimmed oldest-first by entry count and
+ * total characters, and identical adjacent notes are not repeated.
+ * @param notes - a string or an array of strings.
+ */
+export function appendActivity(root, scope, key, notes, options = {}) {
+  const list = (Array.isArray(notes) ? notes : [notes])
+    .map((n) => String(n ?? '').replace(/\s+/g, ' ').trim())
+    .filter(Boolean)
+  if (list.length === 0) return { added: 0, total: 0 }
+  const now = options.now ?? new Date().toISOString()
+  const state = loadForWrite(root, scope, key, now)
+  const maxEntries = options.maxEntries ?? ACTIVITY_MAX_ENTRIES
+  const maxChars = options.maxChars ?? ACTIVITY_MAX_CHARS
+  let added = 0
+  for (const text of list) {
+    const last = state.activity[state.activity.length - 1]
+    if (last && last.text === text) continue
+    state.activity.push({ at: now, text })
+    added += 1
+  }
+  // Trim oldest-first until both bounds hold.
+  while (state.activity.length > maxEntries) state.activity.shift()
+  let chars = state.activity.reduce((n, a) => n + a.text.length + a.at.length + 3, 0)
+  while (chars > maxChars && state.activity.length > 1) {
+    const dropped = state.activity.shift()
+    chars -= dropped.text.length + dropped.at.length + 3
+  }
+  persist(root, scope, key, state.sections, state.activity, now)
+  return { added, total: state.activity.length }
+}
+
+/** Clear the activity log, keeping the current sections. */
+export function clearActivity(root, scope, key, options = {}) {
+  const now = options.now ?? new Date().toISOString()
+  const state = loadForWrite(root, scope, key, now)
+  const removed = state.activity.length
+  persist(root, scope, key, state.sections, [], now)
+  return { removed }
+}
+
+/**
+ * A short picture of where the work stands: the task, the next step, and how recent it is.
+ * @returns {{ verdict: string, ageMs: number|undefined, task?: string, nextStep?: string, activity: number }}
+ */
+export function workingSummary(root, scope, key, options = {}) {
+  const working = readWorking(root, scope, key, options)
+  if (!working) return { verdict: 'empty', ageMs: undefined, activity: 0 }
+  const find = (name) => working.sections.find((s) => workingKey(s.name) === workingKey(name))
+  const next = find('Next steps')
+  return {
+    verdict: working.verdict,
+    ageMs: working.ageMs,
+    task: find('Task') ? find('Task').content.split(String.fromCharCode(10))[0].slice(0, 160) : undefined,
+    nextStep: next ? next.content.split(String.fromCharCode(10)).map((l) => l.trim()).filter(Boolean)[0] : undefined,
+    activity: working.activity.length,
+  }
+}