dsh-error-atlas 0.0.0-stage → 0.11.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-error-atlas contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# Error Atlas · 错误星图
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把 DSH 自己的运行错误和每个编程任务的复盘，沉淀成一张可以被**人看见**、也可以被**模型读到**的记忆图谱。
+
+![错误星图面板](https://raw.githubusercontent.com/chaos-miku/dsh-error-atlas/main/docs/screenshot.jpg)
+
+*面板实拍：顶部是统计与操作，左侧是颜色图例，中间是 GPU 渲染的错误星系，底部是「记忆」开关、教训有效性榜单与最近事件表。标题旁的 `V33` 是 build 号，用来确认页面跑的是哪一代客户端代码。*
+
+A local-first memory plugin for DeepSeek Harness: it records runtime failures and
+coding-task retrospectives, injects the reusable lessons back into the prompt, and
+renders the whole atlas as an interactive WebGL knowledge graph.
+
+---
+
+## 它解决什么
+
+DSH 报过的错、踩过的坑，默认会随会话结束消失。这个插件做两件事：
+
+**写侧**：把错误和复盘结构化地存下来。
+
+- 运行期错误自动入库：`agent/error`（步/轮失败）、`api-session/error`、`agent-loop/config-start-failed`、`tools/result` 里的工具失败与非零退出码；
+- 同一签名（类型 + 工具 + 消息）自动去重聚合，记次数、首末时间、涉及会话；
+- 每次编程任务收尾由模型调用 `atlas_retro` 写一条复盘：**做了什么 / 根因 / 怎么修 / 教训**；模型没写的，宿主用工具与文件留一条自动骨架（不会抢模型手写的份额）。
+
+**读侧**：让教训在下次真的被用上。
+
+- 一段全局提示词要求「编程任务收尾前写复盘」；
+- 每次请求动态注入简报：**失效教训优先**（写完又复发的），再加几条最近的规则；没有教训时整段不出现，不产生固定开销；
+- 只读工具 `atlas_lessons`，可按 `query` / `program` / `limit` 查询全部教训。
+
+**图谱只是这些数据的一个视图**——它不是装饰，但也不是产品本身：价值在于「教训能被下次会话读到」。
+
+## 使用方式
+
+### 1. 打开面板
+
+左侧栏点击 **错误图谱**（图标是一颗星）。第一次打开是空的——它只记录安装之后发生的事。
+
+### 2. 正常干活
+
+不需要做任何事。之后你在 DSH 里跑命令、改文件、插件加载失败、工具非零退出，都会自动入库并按签名聚合；重复犯同一个错，那颗点会变大变亮，次数 +1。
+
+### 3. 收尾写复盘
+
+一段全局提示词会让模型在每个编程任务收尾前调用 `atlas_retro`，写入四条信息：做了什么、根因、怎么修、教训（那条「下次别再犯」的规则）。如果模型忘了写，宿主会留一条自动骨架，保证「这一轮干过什么」不丢。
+
+面板上紫色的 `RETRO` 节点就是复盘，一条紫色的「教训」线把它连向它要治的那个错误；线上会有光点从错误流向复盘，表示这条教训正在被应用。**同一错误在复盘之后又出现，管线会反过来倒灌并变红**，面板顶部统计格里的「教训失效」计数 +1。
+
+### 4. 让教训回到下一次
+
+- 新会话开始后，宿主会自动把「失效教训 + 最近几条规则」注入上下文，模型不用查就知道；
+- 你也可以让它主动查：模型可以调用 `atlas_lessons`（按程序 / 关键词 / 条数），面板上的「导出」则给人看。
+
+### 5. 维护
+
+- **噪声太多**：卡片上点「忽略」，把这条签名加入前缀规则，永久静音；顶部「过滤 ≥N」按命中次数裁剪视图；
+- **找东西**：搜索框输入标签、程序名、错误文本，命中高亮、其余压暗；点教训有效性榜单里的任意一行，图谱会过滤到那一类；
+- **太久之前**：点「清空」删除运行时错误记录（青色开发错误与紫色复盘是保留的）；点「导出」把整份数据写成 Markdown。
+
+## 面板上都有什么
+
+| 区域 | 说明 |
+|---|---|
+| 顶部统计 | 累计错误 / 去重条目 / 图谱节点 / 会话 / 工具 / 程序 / 开发错误 / 任务复盘 / 教训失效 |
+| 顶部操作 | 刷新、搜索、暂停、自转速度、过滤 ≥N、重排、导出、清空、标题开关 |
+| 左侧图例 | 见下表 |
+| 中央星图 | 拖拽旋转、滚轮缩放、点节点看详情卡、双击带会话的节点跳回该会话 |
+| 底部「记忆」 | 两枚开关：收尾提示 / 注入教训 |
+| 教训有效性 | 按标签与程序统计复盘数、失效数、失效率；可收起；行可点击过滤 |
+| 最近事件 | 最新 400 条事件的表格视图（次数、类型、工具、消息、首次/最近） |
+
+图例与配色：
+
+| 节点 | 颜色 | 含义 |
+|---|---|---|
+| `AGENT` | 亮红 `#ff4453` | 模型自身在某一轮/步失败 |
+| `TOOL` | 橙 `#ffb570` | 工具调用返回了错误 |
+| `EXIT` | 杏黄 `#ffd68f` | 命令非零退出码 |
+| `SESSION` | 粉 `#ff859d` | 会话枢纽（出过错的那个窗口） |
+| `CONFIG` | 紫 `#d89eff` | 会话/插件配置启动失败 |
+| `DEV` | 青 `#7ff3e0` | 插件自己的开发错误（内置 12 条，随版本更新） |
+| `RETRO` | 紫 `#c7a4ff` | 一条任务复盘 |
+| `PROJECT` | 浅蓝 `#7fd4ff` | 程序枢纽：同一项目里的错误额外连向它 |
+| `STALE` | 红 `#ff5b4d` | 教训失效（复盘之后同一错误又出现） |
+
+## 安装
+
+市场安装：在 DSH 插件市场搜索 `error-atlas` / `错误星图`。
+
+本地目录安装（开发用）：
+
+```
+plugin_manager install_bundle target="<本包绝对路径>"
+```
+
+安装后**重启 DSH**（宿主半边要注册路由、工具和提示词段），再刷新页面。
+
+## 两个记忆开关
+
+面板底部有一条「记忆」栏，两枚开关都是即时生效、重启后保留：
+
+| 开关 | 关闭后 |
+|---|---|
+| 收尾提示 | 不再注册「编程任务收尾前写复盘」的提示词段（省掉每轮固定字符） |
+| 注入教训 | 不再每轮注入历史教训简报（图谱与复盘照常记录） |
+
+只想安静记录、不想被提示词影响的人，两个都关掉即可；复盘与图谱不受影响。
+
+## 命令行
+
+包内自带两个 CLI，也可被直接调用：
+
+```
+node bin/atlas-digest.mjs                 # 终端摘要：概览、Top 失败、失效教训、最近复盘
+node bin/atlas-digest.mjs --json          # 机器可读
+node bin/atlas-retro.mjs --list           # 列出复盘
+node bin/atlas-retro.mjs --upgrade <id> --lesson "…"   # 升级/改写某条复盘
+node bin/atlas-retro.mjs --new --title "…" --lesson "…" # 手写一条复盘
+```
+
+`atlas-retro` 优先通过宿主路由写入（`POST /error-atlas/retro`，仅回环可访问）；宿主不在时退化为直接改库文件并给出警告。
+
+## 数据与隐私
+
+- 数据只落在本机：`$DSH_HOME/error-atlas/records.json`（日志、聚合错误、复盘、偏好设置）；
+- 导出的 Markdown 写到 `$DSH_HOME/error-atlas/exports/`；
+- 所有 HTTP 路由（`/error-atlas/data|prefs|retro|clear|export`）都只接受回环地址；
+- 不联网、不上报、不采集对话内容；错误消息里可能含命令与路径，介意的话用面板的「清空」一键删除运行时记录（开发错误、任务复盘是内置/用户自己的数据，不会被清空）。
+
+## 开发与测试
+
+```
+npm test        # 157 项断言：宿主事件/路由/存储 + 客户端渲染（借用本机 DSH 的 React）
+npm run smoke   # 干净 DSH_HOME 下的冷启动冒烟：空库 → 写复盘 → 读回 → CLI 可读
+```
+
+客户端为零依赖手写 bundle（`window.__ModuleLoader__`），宿主为纯 ESM。面板标题旁的 `V30`/`V31`… 是 BUILD 号，用来确认页面加载的是哪一代客户端代码。
+
+## 已知边界
+
+- 只看得见**工具层失败与非零退出**，模型在「成功路径」上的逻辑错误不会自动入库——那部分要靠复盘自己写；
+- 教训注入是全局的（每轮一次），不按工作区精确匹配；
+- 程序枢纽只从复盘的 `files` + `cwd` 推导，错误记录本身不存路径，所以没写过复盘的目录不会出现在图里；
+- 图谱上限 240 个节点，超出时 `stats.truncated` 会如实标记，且被复盘引用的错误不会被裁掉；
+- 需要 Node ≥ 20；客户端需要 WebGL2（不可用时面板退化为提示）。
+
+## 相关链接
+
+- 源码与问题反馈：<https://github.com/chaos-miku/dsh-error-atlas>
+- 作者：<https://github.com/chaos-miku>
+
+## License
+
+MIT

package/bin/atlas-digest.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+// atlas-digest: a small terminal reader for the Error Atlas store.
+// Prints a compact digest of recorded runtime errors and coding retrospectives.
+//
+//   node bin/atlas-digest.mjs [--json] [--store=<path>] [--top=<n>]
+
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const argv = process.argv.slice(2)
+const wantJson = argv.includes('--json')
+
+const opt = (name, fallback) => {
+  const hit = argv.find((a) => a.startsWith('--' + name + '='))
+  return hit ? hit.slice(name.length + 3) : fallback
+}
+
+const stamp = (ms) => {
+  const d = new Date(ms)
+  const p = (n) => String(n).padStart(2, '0')
+  return p(d.getMonth() + 1) + '-' + p(d.getDate()) + ' ' + p(d.getHours()) + ':' + p(d.getMinutes())
+}
+
+// East Asian glyphs take two terminal cells; everything we print is padded by
+// display width, never by String#length.
+const wideCode = (code) =>
+  (code >= 0x1100 && code <= 0x115f) ||
+  (code >= 0x2e80 && code <= 0xa4cf) ||
+  (code >= 0xac00 && code <= 0xd7a3) ||
+  (code >= 0xf900 && code <= 0xfaff) ||
+  (code >= 0xfe30 && code <= 0xfe6f) ||
+  (code >= 0xff00 && code <= 0xff60) ||
+  (code >= 0xffe0 && code <= 0xffe6) ||
+  (code >= 0x1f300 && code <= 0x1f64f) ||
+  (code >= 0x20000 && code <= 0x3fffd)
+
+function displayWidth(text) {
+  let width = 0
+  for (const ch of String(text)) width += wideCode(ch.codePointAt(0)) ? 2 : 1
+  return width
+}
+
+// One-line cell of exactly `width` terminal columns, ellipsised when too long.
+function fit(text, width) {
+  const one = String(text == null ? '' : text).replace(/\s+/g, ' ').trim()
+  const total = displayWidth(one)
+  if (total <= width) return one + ' '.repeat(width - total)
+  let out = ''
+  let used = 0
+  for (const ch of one) {
+    const step = wideCode(ch.codePointAt(0)) ? 2 : 1
+    if (used + step > width - 1) break
+    out += ch
+    used += step
+  }
+  return out + '…' + ' '.repeat(Math.max(0, width - used - 1))
+}
+
+// A terminal cell is not the same thing as a JS character: CJK glyphs occupy two
+// columns, so padding by String#length leaves every Chinese row ragged.
+if (argv.includes('--selftest')) {
+  const cases = [
+    ['DSH', 6],
+    ['中文', 8],
+    ['学习管线：光点沿复盘连线运行', 20],
+    ['a中b', 7],
+    ['中文中文中文中文', 9],
+  ]
+  let bad = 0
+  for (const [text, width] of cases) {
+    const cell = fit(text, width)
+    const got = displayWidth(cell)
+    if (got !== width) {
+      bad += 1
+      console.error('FAIL fit(' + JSON.stringify(text) + ', ' + width + ') → ' + JSON.stringify(cell) + ' width ' + got)
+    } else {
+      console.log('ok   fit(' + JSON.stringify(text) + ', ' + width + ')')
+    }
+  }
+  console.log(bad ? 'SELFTEST FAILED: ' + bad : 'SELFTEST PASSED')
+  process.exit(bad ? 1 : 0)
+}
+
+const storePath =
+  opt('store', null) ||
+  join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'error-atlas', 'records.json')
+const topN = Number(opt('top', '6'))
+
+if (!existsSync(storePath)) {
+  console.error('atlas-digest: no store at ' + storePath)
+  process.exit(2)
+}
+
+// Tolerate a BOM: hand-edited stores written by PowerShell often carry one.
+const store = JSON.parse(readFileSync(storePath, 'utf8').replace(/^\uFEFF/, ''))
+const records = Array.isArray(store.records) ? store.records : []
+const retros = Array.isArray(store.retros) ? store.retros : []
+const log = Array.isArray(store.log) ? store.log : []
+const hits = records.reduce((sum, r) => sum + (Number(r.count) || 0), 0)
+
+// A lesson fails when the error it explains comes back after it was written. The same
+// 90s grace window the graph uses keeps the failure that produced the lesson from
+// counting as its own relapse.
+const GRACE_MS = 90 * 1000
+const byId = new Map(records.map((r) => [r.id, r]))
+const signature = (entry) => entry.kind + '\u0000' + entry.name + '\u0000' + entry.message
+
+function recurrenceOf(retro) {
+  const ids = Array.isArray(retro.errorIds) ? retro.errorIds : []
+  if (ids.length === 0) return null
+  const cutoff = (Number(retro.at) || 0) + GRACE_MS
+  const keys = new Set()
+  let lastAt = 0
+  for (const id of ids) {
+    const entry = byId.get(id)
+    if (!entry) continue
+    keys.add(signature(entry))
+    if ((entry.last || 0) > cutoff) lastAt = Math.max(lastAt, entry.last)
+  }
+  if (keys.size === 0) return null
+  let times = 0
+  for (const event of log) {
+    if (!(event.at > cutoff)) continue
+    if (!keys.has(signature(event))) continue
+    times += 1
+    lastAt = Math.max(lastAt, event.at)
+  }
+  // The log is capped; an aggregate `last` beyond the cutoff still proves a relapse.
+  if (times === 0 && lastAt > 0) times = 1
+  if (times === 0) return null
+  const errors = ids
+    .map((id) => byId.get(id))
+    .filter(Boolean)
+    .map((entry) => ({ kind: entry.kind, name: entry.name, message: entry.message, count: entry.count }))
+  return { times, lastAt, errors }
+}
+
+const failed = []
+for (const retro of retros) {
+  const relapse = recurrenceOf(retro)
+  if (relapse) failed.push({ retro, relapse })
+}
+failed.sort((a, b) => b.relapse.times - a.relapse.times || b.relapse.lastAt - a.relapse.lastAt)
+const staleIds = new Set(failed.map((item) => item.retro.id))
+
+if (wantJson) {
+  console.log(
+    JSON.stringify(
+      {
+        store: storePath,
+        version: store.version,
+        errors: records.length,
+        hits,
+        retros: retros.length,
+        modelRetros: retros.filter((r) => !r.auto).length,
+        autoRetros: retros.filter((r) => r.auto).length,
+        staleLessons: failed.length,
+        stale: failed.map(({ retro, relapse }) => ({
+          at: retro.at,
+          auto: Boolean(retro.auto),
+          title: retro.title,
+          times: relapse.times,
+          lastAt: relapse.lastAt,
+          errors: relapse.errors,
+        })),
+        top: [...records].sort((a, b) => b.count - a.count).slice(0, topN).map((r) => ({
+          count: r.count,
+          kind: r.kind,
+          name: r.name,
+          message: r.message,
+        })),
+        recent: [...retros].sort((a, b) => b.at - a.at).slice(0, topN).map((r) => ({
+          at: r.at,
+          auto: Boolean(r.auto),
+          title: r.title,
+          errors: Array.isArray(r.errorIds) ? r.errorIds.length : (Array.isArray(r.errors) ? r.errors.length : 0),
+        })),
+      },
+      null,
+      2,
+    ),
+  )
+  process.exit(0)
+}
+
+const first = Math.min(...records.map((r) => r.first || r.last || 0))
+const last = Math.max(...records.map((r) => r.last || r.first || 0))
+const autoCount = retros.filter((r) => r.auto).length
+
+console.log('')
+console.log('  ERROR ATLAS · digest')
+console.log('  ' + storePath)
+console.log(
+  '  span  ' + (records.length ? stamp(first) + ' → ' + stamp(last) : '—') +
+    '   ·  ' + records.length + ' distinct errors  ·  ' + hits + ' hits',
+)
+console.log(
+  '  retros  ' + retros.length + ' (' + (retros.length - autoCount) + ' model · ' + autoCount + ' auto)' +
+    '   ·   ' + (failed.length ? failed.length + ' failed lesson' + (failed.length > 1 ? 's' : '') : 'every lesson held'),
+)
+
+// Read this first: a lesson that did not hold is the one thing worth looking at.
+if (failed.length) {
+  console.log('')
+  console.log('  STALE LESSONS  (' + failed.length + ')')
+  for (const { retro, relapse } of failed) {
+    const target = relapse.errors[0] || { kind: '?', name: '?', message: '' }
+    console.log(
+      '  ' + stamp(retro.at) + '  ' + ('×' + relapse.times).padStart(3) + '  ' + fit(retro.title, 46) +
+        '  ' + (retro.auto ? 'auto' : 'model'),
+    )
+    console.log(
+      '                    ' + '最近 ' + stamp(relapse.lastAt) + '  ·  ' +
+        fit(target.kind + '/' + (target.name || '?'), 18) + '  ·  ' + fit(target.message, 46),
+    )
+    if (relapse.errors.length > 1) {
+      console.log('                    ' + '关联错误 ' + relapse.errors.length + ' 条（其余见 JSON）')
+    }
+  }
+}
+
+const ranked = [...records].sort((a, b) => b.count - a.count).slice(0, topN)
+const widest = ranked.reduce((max, r) => Math.max(max, String(r.count).length), 1)
+console.log('')
+console.log('  TOP FAILURES')
+for (const r of ranked) {
+  const bar = '█'.repeat(Math.max(1, Math.round((r.count / ranked[0].count) * 12)))
+  console.log(
+    '  ' + String(r.count).padStart(widest) + '  ' + bar.padEnd(12) +
+      '  ' + fit(r.kind + '/' + (r.name || '?'), 16) + '  ' + fit(r.message, 58),
+  )
+}
+
+const recent = [...retros].sort((a, b) => b.at - a.at).slice(0, topN)
+if (recent.length) {
+  console.log('')
+  console.log('  RECENT RETROSPECTIVES')
+  for (const r of recent) {
+    const linked = Array.isArray(r.errorIds) ? r.errorIds.length : Array.isArray(r.errors) ? r.errors.length : 0
+    console.log(
+      '  ' + stamp(r.at) + '  ' + (r.auto ? 'auto ' : 'model') + '  ' +
+        fit(r.title, 44) + '  ' + (linked ? linked + ' linked' : '—') +
+        (staleIds.has(r.id) ? '  ⚠ 失效' : ''),
+    )
+  }
+}
+console.log('')

package/bin/atlas-retro.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+// atlas-retro — write a retrospective into the error atlas by hand.
+//
+// The atlas_retro tool only exists inside a session that was started after the plugin
+// loaded; this CLI is the same thing from the outside, so a retrospective can be written
+// (or an automatic skeleton upgraded) at any time.
+//
+//   node bin/atlas-retro.mjs --list
+//   node bin/atlas-retro.mjs --upgrade r7 --cause "..." --lesson "..."
+//   node bin/atlas-retro.mjs --new --title "..." --lesson "..." --done "..."
+//   node bin/atlas-retro.mjs --fields retros.json     # one object or an array, UTF-8 safe
+//
+// --fields exists because a Chinese --cause on a Windows shell is mangled long before it
+// reaches node: put the text in a JSON file and the bytes survive.
+//
+// It posts to the running host when possible (the host owns the store, so writing the
+// JSON file underneath it would be lost on the next save) and falls back to the file
+// with a warning when the host is not answering.
+
+import { readFileSync, writeFileSync, renameSync, existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { homedir } from 'node:os'
+
+const HOME = process.env.DSH_HOME || join(homedir(), '.dsh')
+const STORE_DIR = join(HOME, 'error-atlas')
+const STORE = join(STORE_DIR, 'records.json')
+const ENDPOINT = join(STORE_DIR, 'endpoint.json')
+
+const args = process.argv.slice(2)
+const flag = (name) => {
+  const index = args.indexOf('--' + name)
+  if (index < 0) return undefined
+  const next = args[index + 1]
+  return next && !next.startsWith('--') ? next : ''
+}
+const has = (name) => args.includes('--' + name)
+
+function readJson(path) {
+  try {
+    // PowerShell's Set-Content can leave a BOM, and JSON.parse dies on it.
+    return JSON.parse(readFileSync(path, 'utf8').replace(/^\uFEFF/, ''))
+  } catch {
+    return null
+  }
+}
+
+function storeOf() {
+  const data = readJson(STORE)
+  if (!data || !Array.isArray(data.retros)) return null
+  return data
+}
+
+function stamp(ms) {
+  const d = new Date(ms)
+  const p = (n) => String(n).padStart(2, '0')
+  return `${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`
+}
+
+function list() {
+  const data = storeOf()
+  if (!data) {
+    console.log('no store at ' + STORE)
+    return 1
+  }
+  const retros = data.retros
+  console.log(`${retros.length} retrospective(s) · ${STORE}`)
+  for (const retro of retros) {
+    const mode = retro.auto ? 'auto ' : 'model'
+    const linked = Array.isArray(retro.errorIds) && retro.errorIds.length ? ` · ${retro.errorIds.length} linked` : ''
+    const title = (retro.title || '(untitled)').slice(0, 52)
+    console.log(`  ${retro.id.padEnd(4)} ${mode}  ${stamp(retro.at)}  ${title}${linked}`)
+  }
+  return 0
+}
+
+function bodyFrom(args2) {
+  const body = {}
+  for (const key of ['title', 'done', 'cause', 'fix', 'lesson']) {
+    const value = flag(key)
+    if (typeof value === 'string' && value.trim()) body[key] = value
+  }
+  const tags = flag('tags')
+  if (tags) body.tags = tags.split(',').map((s) => s.trim()).filter(Boolean)
+  const ids = flag('ids') ?? flag('errorIds')
+  if (ids) body.errorIds = ids.split(',').map((s) => s.trim()).filter(Boolean)
+  const tools = flag('tools')
+  if (tools) body.tools = tools.split(',').map((s) => s.trim()).filter(Boolean)
+  const files = flag('files')
+  if (files) body.files = files.split(',').map((s) => s.trim()).filter(Boolean)
+  return body
+}
+
+// Merge into one stored record without the host: used only when the host is unavailable.
+function patchFile(id, body) {
+  const data = storeOf()
+  if (!data) return { ok: false, error: 'no store at ' + STORE }
+  const retro = data.retros.find((item) => item.id === id)
+  if (!retro) return { ok: false, error: 'no retrospective ' + id }
+  retro.auto = false
+  for (const key of ['title', 'done', 'cause', 'fix', 'lesson']) {
+    if (typeof body[key] === 'string') retro[key] = body[key].slice(0, 420)
+  }
+  if (Array.isArray(body.tags)) retro.tags = body.tags.slice(0, 8)
+  if (Array.isArray(body.errorIds)) retro.errorIds = body.errorIds.slice(0, 12)
+  if (Array.isArray(body.tools)) retro.tools = body.tools.slice(0, 12)
+  if (Array.isArray(body.files)) retro.files = body.files.slice(0, 12)
+  data.updatedAt = Date.now()
+  const tmp = join(dirname(STORE), 'records.json.tmp')
+  writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8')
+  renameSync(tmp, STORE)
+  return { ok: true, id: retro.id, at: retro.at, via: 'file' }
+}
+
+async function post(body) {
+  const endpoint = readJson(ENDPOINT)
+  const port = Number(flag('port')) || (endpoint && Number(endpoint.port)) || 0
+  if (!port) return { ok: false, error: 'no endpoint.json yet — restart DSH once so the host publishes its port' }
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/error-atlas/retro`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(4000),
+    })
+    const text = await response.text()
+    let parsed = null
+    try {
+      parsed = JSON.parse(text)
+    } catch {
+      parsed = null
+    }
+    if (response.status === 404) {
+      return { ok: false, error: 'the running host has no /error-atlas/retro route yet — restart DSH' }
+    }
+    if (!response.ok || !parsed || parsed.ok !== true) {
+      return { ok: false, error: (parsed && parsed.error) || text.slice(0, 200) || 'HTTP ' + response.status }
+    }
+    return { ok: true, id: parsed.id, at: parsed.at, via: 'host' }
+  } catch (error) {
+    return { ok: false, error: String((error && error.message) || error) }
+  }
+}
+
+const USAGE = `atlas-retro — write a retrospective into the error atlas by hand.
+
+  node bin/atlas-retro.mjs --list
+  node bin/atlas-retro.mjs --upgrade r7 --cause "..." --lesson "..."
+  node bin/atlas-retro.mjs --new --title "..." --lesson "..." [--done ...] [--fix ...]
+                                [--tags a,b] [--ids e1,e2] [--tools edit,pwsh] [--files x.js]
+  node bin/atlas-retro.mjs --port 65203 ...     # override the published host port
+  node bin/atlas-retro.mjs --fields retros.json # one record or an array of records
+
+Fields: title, done, cause, fix, lesson (text); tags (a,b); ids / errorIds (e1,e2).
+A --fields record needs "id" to upgrade an existing one, or title+lesson to create one.`
+
+async function main() {
+  if (has('help') || args.length === 0) {
+    console.log(USAGE)
+    return 0
+  }
+  if (has('list')) return list()
+
+  const fieldsPath = flag('fields')
+  let batch
+  if (fieldsPath) {
+    const parsed = readJson(fieldsPath)
+    if (parsed === null || typeof parsed !== 'object') {
+      console.error('cannot read a JSON object/array from ' + fieldsPath)
+      return 2
+    }
+    batch = Array.isArray(parsed) ? parsed : [parsed]
+    if (batch.length === 0) {
+      console.error('fields file holds no records: ' + fieldsPath)
+      return 2
+    }
+  } else {
+    const upgrade = flag('upgrade')
+    const body = bodyFrom(args)
+    if (upgrade) body.id = upgrade
+    if (!upgrade) {
+      if (!body.title || !body.lesson) {
+        console.error('need --title and --lesson (or --upgrade <id>)')
+        return 2
+      }
+    } else if (Object.keys(body).length === 1) {
+      console.error('--upgrade needs at least one field to write (--cause/--lesson/--done/--fix/--tags)')
+      return 2
+    }
+    batch = [body]
+  }
+
+  let failures = 0
+  for (const body of batch) {
+    const upgrade = typeof body.id === 'string' && body.id ? body.id : ''
+    if (!upgrade && (!body.title || !body.lesson)) {
+      console.error('skipped a record without id or title+lesson: ' + JSON.stringify(body).slice(0, 90))
+      failures++
+      continue
+    }
+    const result = await post(body)
+    if (result.ok) {
+      console.log(`ok  ${result.id}  ${stamp(result.at)}  via ${result.via}`)
+      continue
+    }
+    const reason = result.error || 'host unavailable'
+    if (upgrade) {
+      const patched = patchFile(upgrade, body)
+      if (patched.ok) {
+        console.error(`! host not reachable (${reason}) — wrote the store file directly.`)
+        console.error('! the running host may overwrite that file on its next save: restart DSH to be safe.')
+        console.log(`ok  ${patched.id}  ${stamp(patched.at)}  via ${patched.via}`)
+        continue
+      }
+      console.error(`failed ${upgrade}: ${reason} / ${patched.error}`)
+      failures++
+      continue
+    }
+    console.error('failed: ' + reason)
+    console.error('a brand-new retrospective needs the host: restart DSH so it publishes endpoint.json.')
+    failures++
+  }
+  return failures ? 1 : 0
+}
+
+process.exitCode = await main()