dsh-hypatia-auto-memory 0.5.0 → 1.1.0

package/README.md

@@ -33,6 +33,17 @@ additions are used when the binary has them and skipped when it does not:
 The first call logs which the binary offers
 (`hypatia over mcp: no-embed yes, similar filters yes`).
 
+The plugin also needs **dsh ≥ 0.1.7**, and dsh enforces that itself rather than
+this README: the package declares
+`peerDependencies["@deepseek-ai/dsh"]: ">=0.1.7-rc.1"` (the same range also
+sits under `dsh.engines.dsh` for display), and dsh checks every
+`@deepseek-ai/dsh*` peer against the running version when a bundle is installed
+and again at startup — an older runtime refuses the install instead of loading a
+plugin built for API it does not have, and `dsh plugin allow-version` grants an
+exact-version exemption when the risk is accepted deliberately. The peer is
+marked optional in `peerDependenciesMeta` so that neither npm nor a profile
+installation pulls the runtime in as a dependency: the launcher supplies it.
+
 ```bash
 # from a local checkout (development)
 dsh plugin --profile web add link:/path/to/dsh-hypatia-auto-memory
@@ -85,8 +96,11 @@ session/event (emit)
   │                 └─ cascade      ──▶ $not-summaried ──▶ sum<N>-* (summary N)
   └─ session/title | compaction/summary ──▶ session-node ──▶ session-<sid> + belongTo
 session/disposed ──▶ final flush + consolidation, thresholds waived (a session
-                     closed while DSH keeps running; a restart is covered by the
-                     startup consolidation backfill instead)
+                     closed while DSH keeps running)
+collect fiber dispose ──▶ the same flush for every session still open, persisted
+                     before the queue stops; the model call finishes at the next start
+                     (a restart, a config-change restart, or a crash: the startup
+                     consolidation backfill)
 agent/session-start ──▶ rules/taboos inject()
 ```
 
@@ -178,6 +192,19 @@ agent/session-start ──▶ rules/taboos inject()
   and advances the watermark only that far, so the remainder is not silently
   marked done.
 
+  The extraction call asks for **no reasoning** on a route that advertises it.
+  Extraction is a mechanical transform into a fixed JSON shape, and on a
+  thinking route the reasoning is charged to the SAME `maxOutputTokens` as the
+  answer: measured live, a `deepseek-flash` route resolving to `high` spent
+  ~800–1400 of a 2000-token cap thinking and hit `max-tokens` with the JSON half
+  written (9.3 s, against 25 s for a completed run of the same kind on that
+  route). Where a route cannot be asked — or a provider ignores the control —
+  the budget carries a fixed thinking allowance instead, and a truncation is
+  **retried** rather than declared permanent: the retry asks for one work unit
+  instead of `maxWorkUnitsPerRun`, because the units are what make the reply
+  long. Cascade is the exception: it keeps thinking (it is compressing sixteen
+  summaries, not filling a shape) and pays for it in the same allowance.
+
 - **Cascade** archives sixteen unarchived tier-N summaries into one tier-(N+1)
   entry, using hypatia's own `$not-summaried` (which anti-joins on
   `statement.tail` and orders `created_at ASC`, giving FIFO batching for free).
@@ -200,22 +227,39 @@ agent/session-start ──▶ rules/taboos inject()
   re-log and a re-consolidation, so both passes act only on positive evidence:
   a failed shelf query or an empty session listing changes nothing.
 
-  A third pass consolidates what a restart interrupted. The session-end trigger
-  does not survive one: DSH runs its close path at shutdown (it appends
-  `session/end-seed`), but nothing queued there becomes durable before the
-  process is gone — measured on a live restart, the storage file was not written
-  and the session came back with `lastConsolidatedSeq: 0`. So a row whose logged
-  tail was never consolidated is queued at the next startup, gated by the same
-  `consolidation.minNewTokens` floor and read from the row rather than by
-  loading the session. Without that gate every restart would spend one model
-  call per session carrying any tail at all.
+  A third pass consolidates what a shutdown could only persist, and what a crash
+  or `kill -9` left behind. Nothing a closing session owes survives on its own:
+  `session/disposed` observers are fire-and-forget in DSH, the collect fiber is
+  torn down before the session store releases its sessions, and the queue dies
+  with the fiber — so an `enqueue` there was a silent no-op and a whole run's
+  tails were dropped. Two things fix that. The collect fiber's disposer now
+  **persists** both ranges for every session still open (registering the sweep
+  after the queue's own disposer, because cordis disposes a fiber's effects in
+  reverse order, so it runs while the queue can still write), and this pass
+  finishes the work at the next start. Only the final log write is waited for at
+  shutdown: a hypatia write is milliseconds, while the model call it may trigger
+  is measured in tens of seconds and could never fit inside DSH's 5 s shutdown
+  budget.
+
+  This pass deliberately ignores the `consolidation.minNewTokens` floor that
+  paces the live trigger. The floor is right while a conversation is running —
+  there is always a later turn — but at boot there is no later turn, and a tail
+  skipped here is skipped for good: measured on a live shelf, fifteen sessions
+  carried 1–1950 pending tokens, not one of them was ever consolidated, and
+  eight of nine sessions had messages with `lastConsolidatedSeq: 0`. Cost is
+  bounded by `housekeeping.consolidationBackfillPerScope` instead — at most that
+  many sessions **per project scope** per start, the largest tails first, so a
+  backlog drains over several starts rather than in one unbounded burst of model
+  calls. A range whose consolidate record is `failed` is taken first whatever its
+  size: `resumeKind` never re-schedules a failed row, and re-enqueueing it is the
+  only path back.
 
   Those tasks then read their events from **storage**, not only from the live
   store. `session/created` — the signal that wakes a deferred task — fires only
   where an agent actually runs, so a finished session may never emit it again,
   and a subagent session (which the sidebar does not even list) almost certainly
   will not: one sat `deferred` across a restart and stayed deferred while its
-  transcript was open on screen. `sessionPersistence.load()` returns the same
+  transcript was open on screen. `sessionPersistence.open(id, 'read')` returns the same
   log without publishing anything, and the executors use only `snapshotEvents`,
   `inheritedEventCount`, `seq` and `header`, so a tail nothing will reopen still
   becomes knowledge. A composition without `sessionPersistence` behaves as
@@ -276,16 +320,21 @@ agent/session-start ──▶ rules/taboos inject()
   from the in-memory state tables on every poll, the shelf content only when it
   can have changed (on open, on a session switch, on a manual refresh, and when
   consolidation advances the session's watermark), cached for 15 s in between.
+  The tab polls every five seconds while it is on screen, and a response is
+  bounded: the newest 40 summaries and 40 work units, 4000 characters per body
+  and 120 000 per response. JSE has no `ORDER BY`, so "newest" is decided only
+  after reading every candidate; when a scan reaches its cap the counts become
+  lower bounds, and the tab reports that response as truncated rather than
+  leaving a short list unexplained.
   Two channels were rejected on the way here. A **session projection** would be
   the best shape, but the event that would drive it cannot be written from
   outside this repository: `Session.append` offers no way to set the envelope's
   `ignorable` marker, and the persistence read path refuses a session log
   carrying an unknown event type without it — so a custom event would break
-  session reload. A **settings namespace** can be written safely but is
-  root-scoped: the Host cannot know which session the browser is showing, so it
-  would have to ship every session's data, and publishing means disposing and
-  re-creating the owning fiber, because `settings.register` refuses a duplicate
-  namespace and has no way to update a registered `base`.
+  session reload. A **settings namespace** was root-scoped even when it existed:
+  the Host cannot know which session the browser is showing, so it would have
+  to ship every session's data. (dsh 0.1.7 removed the Host-side settings
+  registration API entirely; the route family below is now the only channel.)
 
   The route is not one of the composed app's authenticated routes — a route a
   plugin registers never is — so it authenticates itself the way
@@ -299,8 +348,16 @@ agent/session-start ──▶ rules/taboos inject()
 
 ## Configuration
 
-Settings namespace `hypatia-auto-memory` (edit `settings.yaml` or Web
-settings; all fields optional, defaults shown):
+The plugin's cordis `Config` is its configuration form. dsh ≥ 0.1.7 projects a
+plugin's Config schema onto the sidebar's **Plugins** page, and the card renders
+on this bundle's own page there; a deployment whose profile renders no Plugins
+page gets the same card as a tab under **Settings → Built-in plugins**. The card
+takes whichever seat exists and moves between them without ever appearing twice
+(`src/client/plugin-card-seat.ts`). Every field below applies on
+save, without a profile reload. Stored as the plugin entry's `config:` in the
+profile patch; a pre-0.1.7 `settings.yaml` section is imported once on first
+launch. All fields optional, defaults shown. A blank consolidation route is
+refused on save; a duplicate one is dropped at runtime with a warning:
 
 ```yaml
 hypatia-auto-memory:
@@ -344,6 +401,7 @@ hypatia-auto-memory:
     reconcileOnStartup: true     # reset rows whose session has no msg-* left in the shelf
     pruneVanishedSessions: true  # drop rows and tasks of sessions DSH no longer has
     backfillConsolidation: true  # consolidate a logged tail the in-session trigger never reached
+    consolidationBackfillPerScope: 4  # sessions that pass may queue per scope, per start
 ```
 
 The cordis config block on the bundle row only carries skill packaging:
@@ -355,19 +413,24 @@ The cordis config block on the bundle row only carries skill packaging:
     skillsDir: /abs/path         # override the packaged skills/ directory
 ```
 
-`enabled` and `autoApprove` are read when the plugin starts, so changing either
-needs a profile reload; every other switch applies immediately.
+`enabled`, `shelf` and `autoApprove` are read when the collector starts, so
+saving a change to any of them restarts the collector (queue drained, state
+re-opened); every other switch applies in place. The same restart is what
+applies an imported pre-0.1.7 `settings.yaml`: dsh imports it only after every
+plugin has started, and the collector itself waits for that point before it
+starts, so it rarely runs on the defaults at all.
 
 ### Choosing the shelf
 
 `shelf` names the hypatia shelf every entry is written to and every lookup
 reads — logging, consolidation, the cascade, the rules/taboos preload, and the
 startup housekeeping. The settings card offers it as a dropdown of what
-`hypatia list` reports (refreshed about once a minute, and after every settings
-change), marking shelves that are registered but not connected.
+`hypatia list` reports — read on demand when the tab opens; a successful
+listing is cached for 60 s on the Host, a failed one never is — marking
+shelves that are registered but not connected.
 
-- **Takes effect after a profile reload**, like `enabled`. A running queue keeps
-  writing where it started; the log says so when the setting changes.
+- **Takes effect on save**, like `enabled`: the collector restarts on the new
+  shelf, and the log says so.
 - **Progress is kept per shelf.** Watermarks and queued tasks are stored per
   shelf, so a newly chosen shelf starts every session from zero, and switching
   back resumes exactly where that shelf left off — nothing is re-logged or
@@ -387,9 +450,12 @@ change), marking shelves that are registered but not connected.
   (`hypatia connect <dir> --name <name>`). Over MCP, that failure restarts the
   server, so the retry after a `connect` reaches the shelf.
 
-The listing reaches the browser as a second, read-only settings namespace,
-`hypatia-auto-memory-shelves`, which the Host re-registers whenever the listing
-changes. No card claims it, so it renders nowhere; nothing ever writes to it.
+The listing reaches the browser over the same route family as the Memory tab —
+`GET /api/dsh-hypatia-auto-memory/shelves`, mounted before the startup
+reconcile and backfill (and even while `enabled: false`), so the list is there
+when a broken shelf needs replacing. (It rode a read-only settings namespace until dsh 0.1.7 removed that
+Host-side API; a shelf listing is not configuration, and the settings domain
+now only projects plugin Config forms.)
 
 ## Operations checklist
 
@@ -428,22 +494,23 @@ changes. No card claims it, so it renders nowhere; nothing ever writes to it.
 
 | Symptom | Cause / handling |
 |---|---|
-| No entries after chatting | `enabled: false`, missing `hypatia` binary, or the collect fiber PENDING (needs `sessions`, `storageDomain`, `subprocess`, `settings` from the base composition) — check profile logs |
+| No entries after chatting | `enabled: false`, missing `hypatia` binary, or the collect fiber PENDING (needs `sessions`, `storageDomain`, `subprocess` from the base composition) — check profile logs |
 | Nothing logged for a whole run after a restart | The storage domain refused to open because a stored record failed its schema. The storage service validates on read, not on write, so a bad write only surfaces at the next startup — and one bad row fails the whole domain. Look for `startup failed` / `does not match its schema` in the profile log. Task rows missing `error` are now defaulted; for any other bad row, stop DSH, remove it from `~/.dsh/storages/hypatia_auto_memory.json`, and restart |
+| Memory tab never shows data, or shows a read failure | The page is not reached over a **loopback origin**. The route authenticates itself — loopback socket, loopback `Host`, same-origin — so reading DSH from another device (a LAN address, or a `0.0.0.0` binding) is refused by design, and so is a tunnel presenting a public `Host`. Both halves of the payload are refused together, so the tab reports a load failure rather than partial data. Open the GUI at `127.0.0.1` or `localhost` |
 | Entries appear only after a turn finishes | By design: spans are cut at `turn/end`, or at the first `step/end` once a turn has run longer than `flushWindowMs`, so an entry never lacks its own tool results |
 | Logging works, no summaries | `consolidation.models` is empty or invalid — one warning at first trigger |
 | Summaries but no `sum2-*` | Fewer than `cascade.batchSize` unarchived tier-1 summaries in that project yet |
 | Work units have no relationships | No embedding model on the shelf (`similar` fails), every candidate was beyond `dedupMaxDistance`, or the adjudication call itself produced no verdict — `model_calls` shows that as `incomplete` / `max-tokens`, which is what a thinking-enabled route does when it spends the whole output budget on reasoning before answering. The call now asks a route for `reasoningEffort: 'off'` once the adapter advertises it, and carries a 1024-token cap for routes that cannot honour it. Since hypatia #19 the local model is looked up in `~/.hypatia/models/<org>/<name>` (or the Hugging Face cache), no longer beside the shelf: a shelf that used to answer `similar` and now says `is not installed` needs `hypatia model install <model>`, or `hypatia model register <model> <dir>` pointing at the files it already has |
 | `similar` still returns `msg-*` rows | They were written before this plugin opted the log layer out of embedding, or by a hypatia without `--no-embed`. Retract the knowledge vectors once with `embedding.skip_tags = ["message"]` in the shelf's `shelf.toml` followed by `hypatia backfill` (a binary older than the key refuses to open the shelf, so upgrade every binary sharing it first). Do not add `session` to that list: `skip_tags` matches any entry carrying the tag, and knowledge people write about sessions carries it too — one such entry lost its vector on the shelf this was tried on. The plugin's own `session-*` nodes are few and now opt out per write. Statements have no tags and no update command, so `belongTo` / `summary` edges written before keep their vectors |
-| Task in `deferred` state | Neither the live store nor persistence could supply its session. Not an error: it spends no attempts and runs as soon as one of them can. Normally storage answers immediately — the state persists only when `sessionPersistence` is absent from the composition, or its read failed (look for `could not be read` in the log) |
+| Task in `deferred` state | Neither the live store nor persistence could supply its session. Not an error: it spends no attempts and runs as soon as one of them can. Normally storage answers immediately — the state persists only when `sessionPersistence` is absent from the composition, or its read failed (look for `could not be read` in the log). A deferred consolidation is re-queued by the next startup's backfill, so it does not wait for its session to be opened again |
 | Task in `failed` state | A hypatia or model error persisted after `maxAttempts`. Failed `log-message` records are pruned at the next startup, since the watermark re-derives their range; other kinds are kept for inspection — delete one to let the next trigger re-create it |
 | Watermark says logged, but the shelf has no entries | The shelf was reset or switched after logging. Handled at startup: `housekeeping.reconcileOnStartup` resets any row whose session has no `msg-*` left, and that session is re-logged — and re-consolidated — from the start on its next activity. A shelf query that fails leaves the row untouched. A session whose messages were all deleted on purpose is indistinguishable and is logged again; turn the switch off if that matters |
 | Warning `hypatia mcp unavailable: …; using the hypatia CLI until the profile reloads` | The binary predates `hypatia mcp` (the message quotes its `unrecognized subcommand`), lacks a tool the plugin calls, or answered the handshake with an error. Everything keeps working over the CLI; upgrade hypatia and reload the profile to use MCP |
 | Every call fails with `hypatia mcp exited …` or `timed out` | The binary starts but its MCP server does not come up — a wrapper script in `binaries` that changes clap's exit code or wording is not recognised as an old binary. Set `transport: cli` |
-| Every write fails right after changing `shelf` | The shelf is not registered or not connected — startup logs `shelf "<name>" is not registered`. Connect it (`hypatia connect <dir> --name <name>`) and reload the profile, or pick another |
+| Every write fails right after changing `shelf` | The shelf is not registered or not connected — startup logs `shelf "<name>" is not registered`. Connect it (`hypatia connect <dir> --name <name>`) and save the setting again (or reload the profile), or pick another |
 | The agent searches `default` while the plugin writes elsewhere | A disk copy of `hypatia-memory` (see below) replaced the bundled skill, or recall is disabled, so nothing told the agent which shelf to use |
 | Duplicate `msg-*` after weird manual edits | Delete the entry in hypatia and lower `lastLoggedSeq` for that session in the state domain — backfill recreates it once |
-| The agent's own `hypatia` write still asks for approval | `autoApprove: false` (needs a profile reload to change), the command pipes/redirects/chains outside quotes, or its first word is not one of `binaries` — only plain calls are answered, by design. Reads never reach approval at all, so nothing to fix there |
+| The agent's own `hypatia` write still asks for approval | `autoApprove: false`, the command pipes/redirects/chains outside quotes, or its first word is not one of `binaries` — only plain calls are answered, by design. Reads never reach approval at all, so nothing to fix there |
 | The agent got a memory protocol that tells it to log messages by hand | Another plugin registered `hypatia-memory` first (`dsh-hypatia` still in the profile), or a `hypatia-memory` exists on disk — typically `~/.agents/skills/hypatia-memory`, written by `hypatia skill install --agent codex`. Agent presets load disk skills in a layer nearer than plugins, so it wins in sessions even though the skill center may list this plugin. Remove the copy the startup warning names |
 | Can't tell which model actually ran | By design the choice rotates: one process-local cursor is shared by span summaries, adjudication and cascade, so consecutive calls alternate through `consolidation.models`. Each attempt lands in `~/.dsh/storages/hypatia_auto_memory_diag.json` (`model_calls`) with purpose, provider/model, outcome and duration. The usage ledger cannot answer this — it folds agent turns (`assistant/message`) and never sees a plugin's direct `llm.stream`. A `pending` row means the call is still in flight, or the process died mid-call: the row is written before the call and settled after it |
 | Startup warnings never appear in the terminal | `dsh web` mounts no log exporter, so plugin log lines of any level go nowhere; the console exporter's default threshold would also drop warnings (warn is level 2, above info's 1). Mount a logger such as `dsh-logbook` or `dsh-boot-doctor` temporarily to read them |
@@ -515,9 +582,9 @@ Deliberate, and worth knowing before you rely on them:
     the triples it actually reviews reach that limit.
 
   Its `evals/evals.json` gains cases 9 and 10 for these two patches.
-- **`enabled: false` at the top level is read at plugin startup**; toggling it
-  live requires a profile reload, while the per-feature switches apply
-  immediately.
+- **`enabled: false` at the top level is read when the collector starts**;
+  saving a change restarts the collector, while the per-feature switches apply
+  in place.
 
 ## Directory structure
 
@@ -530,8 +597,8 @@ dsh-hypatia-auto-memory/
 ├── tsdown.config.ts      # browser CJS factory build
 ├── src/
 │   ├── index.js          # fiber composition (collect + optional children)
-│   ├── config.js         # settings namespace, defaults, live updates
-│   ├── shelf.js          # per-shelf table views, `hypatia list`, shelf inventory
+│   ├── config.js         # cordis Config schema (volatile), defaults, live updates
+│   ├── shelf.js          # per-shelf table views, `hypatia list` parsing
 │   ├── state.js          # storageDomain spec + progress helpers
 │   ├── collector.js      # session/event filtering, ledger, backfill
 │   ├── content-policy.js # redaction, dates, caps, slugs (pure)
@@ -543,6 +610,8 @@ dsh-hypatia-auto-memory/
 │   ├── consolidator.js   # thresholds, prompt, llm.stream, validation
 │   ├── cascade.js        # log₁₆(n) hierarchical summary archive
 │   ├── model-log.js      # bounded record of which model each attempt ran on
+│   ├── memory-status.js  # per-session fold of the two state tables (pure)
+│   ├── memory-api.js     # Memory tab + shelf listing: read-only route family
 │   ├── recall.js         # rules/taboos preload at session start
 │   ├── auto-approve.js   # approves the agent's own plain bash hypatia calls
 │   ├── skills.js         # bundled skill registration (never shadows another provider)
@@ -550,7 +619,10 @@ dsh-hypatia-auto-memory/
 │   └── client/           # settings card + Memory tab
 │       ├── index.tsx     # client plugin entry + slot registration
 │       ├── SettingsCard.tsx
-│       ├── shelves.ts    # shelf dropdown choices from the inventory namespace
+│       ├── MemoryView.tsx     # the Memory tab body
+│       ├── memory-client.ts   # its fetch + merge rules (pure)
+│       ├── plugin-card-seat.ts # card seat: official Plugins page, else Settings tab
+│       ├── shelves.ts    # shelf dropdown choices (listing from the /shelves route)
 │       └── slot-contract.ts
 ├── lib/
 │   └── client.js         # built browser factory (commit this)

package/README.zh-CN.md

@@ -28,6 +28,14 @@
 检索。首次调用会记录二进制提供了哪些（`hypatia over mcp: no-embed yes, similar
 filters yes`）。
 
+本插件还需要 **dsh ≥ 0.1.7**，而且这个下限由 dsh 自己强制执行，不靠本 README：
+包里声明了 `peerDependencies["@deepseek-ai/dsh"]: ">=0.1.7-rc.1"`（同样的范围也写在
+`dsh.engines.dsh` 里，供展示），dsh 在安装 bundle 时、以及每次启动时，会把每个
+`@deepseek-ai/dsh*` peer 与自身版本比对——运行时太旧会直接拒绝安装，而不是加载一个
+面向它并不具备的 API 写成的插件；确实要接受风险时，用 `dsh plugin allow-version`
+授予精确版本豁免。该 peer 在 `peerDependenciesMeta` 里标为 optional，这样 npm 和
+profile 安装都不会把运行时本身拉成依赖：运行时由 launcher 提供。
+
 ```bash
 # 从本地 checkout 安装（开发）
 dsh plugin --profile web add link:/path/to/dsh-hypatia-auto-memory
@@ -75,7 +83,10 @@ session/event (emit)
   │                 └─ cascade      ──▶ $not-summaried ──▶ sum<N>-* (summary N)
   └─ session/title | compaction/summary ──▶ session-node ──▶ session-<sid> + belongTo
 session/disposed ──▶ final flush + consolidation, thresholds waived (DSH 仍在运行时
-                     关闭的会话；进程重启则由启动时的 consolidation backfill 覆盖)
+                     关闭的会话)
+collect fiber 拆除 ──▶ 对每个仍打开的会话做同样的收尾，并在队列停止前落盘；模型
+                     调用留到下次启动完成（重启、配置变更重启，或崩溃：启动时的
+                     consolidation backfill）
 agent/session-start ──▶ rules/taboos inject()
 ```
 
@@ -143,6 +154,15 @@ agent/session-start ──▶ rules/taboos inject()
   脱敏并绝对化日期，超预算的 span 只巩固其**最旧**的条目，水位也只推进到那里，剩下
   的不会被打成已完成。
 
+  抽取调用在**声明支持的路由上关闭推理**。抽取是朝固定 JSON 形状的机械变换，而在开启
+  thinking 的路由上，推理与答案**共享同一个 `maxOutputTokens`**：实测中一条解析为
+  `high` 的 `deepseek-flash` 路由在 2000 的预算里花掉约 800–1400 思考，然后带着写到
+  一半的 JSON 撞上 `max-tokens`（9.3s，而同一条路由上同类成功调用要 25s）。路由无法
+  被要求关闭（或 provider 忽略该控制）时，预算改为携带固定的思考余量；而**截断不再
+  算永久失败**，而是重试——重试时只要 1 个工作单元而不是 `maxWorkUnitsPerRun`，因为
+  正是工作单元让回复变长。Cascade 是例外：它保留 thinking（它是在压缩十六条摘要，不是
+  在填一个形状），并用同一份余量来支付。
+
 - **Cascade** 把十六个未归档的 tier-N 摘要归档为一条 tier-(N+1) 条目，用 hypatia 自带
   的 `$not-summaried`（它对 `statement.tail` 做反连接并按 `created_at ASC` 排序，
   免费得到 FIFO 分批）。这就是协议的 log₁₆(n) 归档：每一层只压缩上一层已经蒸馏过的
@@ -160,17 +180,28 @@ agent/session-start ──▶ rules/taboos inject()
   DSH 已不存在的会话的行和任务。重置的代价是一次重新记录和一次重新巩固，所以两遍
   都只在有正面证据时才行动：shelf 查询失败或空的会话列表都不做任何改动。
 
-  第三遍巩固那些被重启打断的内容。session-end 触发器活不过重启：DSH 在关闭时跑它的
-  关闭路径（追加 `session/end-seed`），但那里排入的任何东西在进程消失前都来不及
-  持久化——实测在一次真实重启中，storage 文件根本没写，会话回来时
-  `lastConsolidatedSeq: 0`。所以一个有已记录但从未巩固的尾部的行，会在下次启动时被
-  排入队列，受同样的 `consolidation.minNewTokens` 下限约束，并且从行里读取而不是
-  加载会话。没有这道门槛，每次重启都会为每个带尾部的会话花一次模型调用。
+  第三遍巩固那些关闭时只能落盘、以及崩溃或 `kill -9` 完全没留下的内容。关闭中的会话
+  所欠的东西本身活不下来：DSH 里 `session/disposed` 的观察者是 fire-and-forget，
+  collect fiber 先于 session store 释放会话就被拆除，而队列随 fiber 一起消失——所以在
+  那里 `enqueue` 是一次静默的空操作，一整轮的尾巴就这么丢了。两件事修好了它：collect
+  fiber 的 disposer 现在会为每个仍打开的会话**落盘**两段范围（把收尾 effect 注册在队列
+  自己的 disposer **之后**，因为 cordis 按注册逆序拆除 fiber 的 effects，于是它跑的时候
+  队列还能写），而这一遍在下一次启动把活干完。关闭时只等最后的日志写入：一次 hypatia
+  写入是毫秒级，而它可能触发的模型调用是几十秒，永远塞不进 DSH 5s 的关机预算。
+
+  这一遍**刻意不看**节流实时触发器的 `consolidation.minNewTokens` 下限。对话还在进行时
+  下限是对的——总还有下一轮——但启动时没有下一轮，在这里被跳过的尾部就是永久跳过：
+  实测一个 live shelf 上 15 个会话带着 1–1950 的 pending token，没有一个被巩固过，9 个
+  有消息的会话里 8 个 `lastConsolidatedSeq: 0`。成本改由
+  `housekeeping.consolidationBackfillPerScope` 封顶——每次启动**每个 project scope**
+  最多这么多个会话，尾巴最大的优先，于是积压分几次启动消化，而不是一次爆出无界的模型
+  调用。consolidate 记录处于 `failed` 的范围无论多小都优先：`resumeKind` 不会重排
+  failed 行，重新入队是它唯一的回头路。
 
   这些任务随后从 **storage** 读取事件，而不只是从活 store。`session/created`——唤醒
   被延迟任务的信号——只在 Agent 实际运行的地方触发，所以一个已结束的会话可能再也不
   会发它，而 subagent 会话（侧栏甚至不列出）几乎肯定不会：有一个就曾跨重启停留在
-  `deferred` 状态，尽管它的 transcript 正开在屏幕上。`sessionPersistence.load()`
+  `deferred` 状态，尽管它的 transcript 正开在屏幕上。`sessionPersistence.open(id, 'read')`
   返回同样的日志而不发布任何东西，执行器只用 `snapshotEvents`、
   `inheritedEventCount`、`seq` 和 `header`，所以一个不会再被重新打开的尾部仍能变成
   知识。没有 `sessionPersistence` 的组合行为照旧：任务等待。
@@ -215,13 +246,16 @@ agent/session-start ──▶ rules/taboos inject()
   数据经由本插件注册在 DSH web 服务器上的、会话作用域的只读 HTTP 路由
   `/api/dsh-hypatia-auto-memory/session` 到达浏览器：状态每次轮询都从内存中的状态表
   现算，shelf 内容只在可能变化时才读（打开时、切换会话时、手动刷新时，以及整合推进了
-  该会话水位时），其间缓存 15 秒。路上否掉了两条通道。**session projection** 形态最
+  该会话水位时），其间缓存 15 秒。标签页在屏幕上时每 5 秒轮询一次，响应是有界的：
+  最新的 40 条摘要与 40 条工作单元，每条正文 4000 字符、整份响应 120000 字符。
+  JSE 没有 `ORDER BY`，所以「最新」只能在读完所有候选之后判定；扫描触到上限时计数
+  变成下界，标签页会把该次响应标为已截断，而不是让短列表无从解释。路上否掉了两条
+  通道。**session projection** 形态最
   合适，但驱动它的事件在本仓库之外写不出来：`Session.append` 没有任何途径设置信封的
   `ignorable` 标记，而持久化读取路径会拒绝一个带着未知事件类型、又没有该标记的会话
-  日志——所以自定义事件会破坏会话重载。**设置命名空间**能安全写入，但它是根作用域的：
-  宿主无法知道浏览器正在看哪个会话，只能把每个会话的数据都发出去；而且发布意味着销毁
-  并重建持有它的 fiber，因为 `settings.register` 拒绝重名命名空间，也没有任何途径更新
-  已注册的 `base`。
+  日志——所以自定义事件会破坏会话重载。**设置命名空间**即便在还存在时也是根作用域的：
+  宿主无法知道浏览器正在看哪个会话，只能把每个会话的数据都发出去。（dsh 0.1.7 已整体移除
+  宿主侧的设置注册 API，下面的路由族现在是唯一通道。）
 
   这条路由不属于组合应用自己那批已鉴权的路由——插件注册的路由从来都不是——所以它像
   `dsh-hypatia-ui` 那样自鉴权：socket 必须是回环，`Host` 必须是回环名（`localhost`、
@@ -232,8 +266,14 @@ agent/session-start ──▶ rules/taboos inject()
 
 ## 配置
 
-设置命名空间 `hypatia-auto-memory`（编辑 `settings.yaml` 或 Web 设置；所有字段可选，
-展示的是默认值）：
+插件的 cordis `Config` 就是它的配置表单。dsh ≥ 0.1.7 把插件的 Config schema 投影到
+侧边栏的**「插件」页**，卡片渲染在该 bundle 自己的页面上；如果某个部署的 profile
+不渲染这个页面，同一张卡片会退到**「设置 → 内置插件」**里作为一个标签页。卡片落在
+存在的那个位置上，并在两者之间迁移时绝不会同时出现（`src/client/plugin-card-seat.ts`）。
+下面每个字段保存即生效，无需重载 profile。配置以插件条目 `config:`
+的形式存进 profile patch；0.1.7 之前的 `settings.yaml` 段落会在首次启动时被一次性导入。
+所有字段可选，展示的是默认值。空白的巩固路由在保存时就被拒绝；重复的路由在运行时被丢弃
+并记一条警告：
 
 ```yaml
 hypatia-auto-memory:
@@ -277,6 +317,7 @@ hypatia-auto-memory:
     reconcileOnStartup: true     # 重置 session 在 shelf 里已无 msg-* 的行
     pruneVanishedSessions: true  # 删除 DSH 已不存在的会话的行和任务
     backfillConsolidation: true  # 巩固会话内触发器从未到达的已记录尾部
+    consolidationBackfillPerScope: 4  # 每次启动每个 scope 允许排入的会话数
 ```
 
 bundle 行上的 cordis config 块只承载技能打包：
@@ -288,17 +329,19 @@ bundle 行上的 cordis config 块只承载技能打包：
     skillsDir: /abs/path         # 覆盖打包的 skills/ 目录
 ```
 
-`enabled` 和 `autoApprove` 在插件启动时读取，改动二者需要重载 profile；其它开关
-立即生效。
+`enabled`、`shelf` 和 `autoApprove` 在采集器启动时读取，所以保存其中任一项的改动都会
+重启采集器（排空队列、重新打开状态）；其它开关原地生效。0.1.7 之前的 `settings.yaml`
+也是靠这次重启生效的：dsh 在所有插件启动之后才导入它，而采集器本身会等到那一刻才启动，
+所以基本不会先按默认值跑起来。
 
 ### 选择 shelf
 
 `shelf` 指定所有条目写入、所有查找读取的 hypatia shelf——记录、巩固、级联、
 rules/taboos 预载、启动清理。设置卡片把它做成 `hypatia list` 所报告内容的下拉框
-（约每分钟刷新一次，每次设置变更后也刷新），并标注已注册但未连接的 shelf。
+——标签页打开时按需读取；成功的结果在宿主侧缓存 60 秒，失败的结果从不缓存——并标注
+已注册但未连接的 shelf。
 
-- **像 `enabled` 一样，profile 重载后才生效。** 运行中的队列会继续写到它开始的地方；
-  设置变更时日志会说明。
+- **像 `enabled` 一样，保存即生效**：采集器会在新 shelf 上重启，日志会说明。
 - **进度按 shelf 保存。** 水位和排队的任务按 shelf 存储，所以新选的 shelf 会让每个
   会话从零开始，而切回去会恰好从该 shelf 上次停下的地方继续——不会把已有的内容重新
   记录或重新巩固进某个 shelf。代价落在新 shelf 上：每个活会话从它的开头开始记录——
@@ -312,8 +355,10 @@ rules/taboos 预载、启动清理。设置卡片把它做成 `hypatia list` 所
   重试，直到它被连接（`hypatia connect <dir> --name <name>`）。走 MCP 时，该失败会
   重启 server，所以 `connect` 之后的重试能到达那个 shelf。
 
-列表以第二个只读设置命名空间 `hypatia-auto-memory-shelves` 到达浏览器，宿主在列表
-变化时重新注册它。没有卡片认领它，所以它不渲染在任何地方；也从不写入它。
+列表通过与 Memory 标签页相同的路由族到达浏览器——`GET /api/dsh-hypatia-auto-memory/shelves`，
+在启动时的对账与回填之前就挂载（`enabled: false` 时也挂载），所以 shelf 坏掉、需要换一个
+时列表就在那里。（0.1.7 之前它走一个只读设置命名空间，该宿主侧 API 已被移除；
+shelf 清单本来就不是配置，而设置域现在只投影插件的 Config 表单。）
 
 ## 运维清单
 
@@ -346,22 +391,23 @@ rules/taboos 预载、启动清理。设置卡片把它做成 `hypatia list` 所
 
 | 症状 | 原因 / 处理 |
 |---|---|
-| 聊完没有条目 | `enabled: false`、缺少 `hypatia` 二进制、或 collect fiber 处于 PENDING（需要基础组合里的 `sessions`、`storageDomain`、`subprocess`、`settings`）——查 profile 日志 |
+| 聊完没有条目 | `enabled: false`、缺少 `hypatia` 二进制、或 collect fiber 处于 PENDING（需要基础组合里的 `sessions`、`storageDomain`、`subprocess`）——查 profile 日志 |
 | 重启后一整轮什么都没记录 | storage domain 因为某条已存记录不符合 schema 而拒绝打开。storage service 在读时校验、不在写时校验，所以一次坏写入只会在下次启动时暴露——而一条坏记录会拖垮整个 domain。在 profile 日志里找 `startup failed` / `does not match its schema`。缺 `error` 的任务行现在已默认化；其它坏行则停 DSH、从 `~/.dsh/storages/hypatia_auto_memory.json` 删除它再重启 |
+| 「记忆」标签页始终读不到数据，或显示读取失败 | 页面不是通过**回环来源**访问的。该路由自鉴权——回环 socket、回环 `Host`、同源——所以从另一台设备读 DSH（LAN 地址，或绑定 `0.0.0.0`）会被按设计拒绝，隧道送来公网 `Host` 也一样。响应两半一起被拒，所以标签页报的是读取失败而不是部分数据。请用 `127.0.0.1` 或 `localhost` 打开 GUI |
 | 条目只在 turn 结束后才出现 | 设计如此：span 在 `turn/end` 切分，或当 turn 跑得比 `flushWindowMs` 久时在第一个 `step/end` 切分，所以条目不会缺它自己的工具结果 |
 | 有记录，没摘要 | `consolidation.models` 为空或无效——首次触发时告警一次 |
 | 有摘要但没有 `sum2-*` | 该项目里未归档的 tier-1 摘要还不足 `cascade.batchSize` 条 |
 | 工作单元没有关系 | shelf 没有嵌入模型（`similar` 失败），所有候选都超过了 `dedupMaxDistance`，或裁决调用本身没有产出裁决——`model_calls` 里表现为 `incomplete` / `max-tokens`，也就是开启了思考的路由把整个输出预算花在推理上、还没开始作答就撞了上限。现在裁决会先确认适配器声明了 `off`，再对该路由请求 `reasoningEffort: 'off'`；对无法接受它的路由则把上限提到 1024。自 hypatia #19 起，本地模型在 `~/.hypatia/models/<org>/<name>`（或 Hugging Face 缓存）里找，不再挨着 shelf：一个以前能回答 `similar`、现在说 `is not installed` 的 shelf，需要 `hypatia model install <model>`，或 `hypatia model register <model> <dir>` 指向它已有的文件 |
 | `similar` 仍返回 `msg-*` 行 | 它们是在本插件让日志层退出嵌入之前写的，或由一个没有 `--no-embed` 的 hypatia 写的。在 shelf 的 `shelf.toml` 里用 `embedding.skip_tags = ["message"]` 加一次 `hypatia backfill` 一次性收回知识向量（比该 key 旧的二进制会拒绝打开 shelf，所以先升级所有共享它的二进制）。不要把 `session` 加进那个列表：`skip_tags` 匹配任何带该 tag 的条目，而人们写的关于会话的知识也带它——在试过的 shelf 上就有一条这样的条目丢了向量。插件自己的 `session-*` 节点很少，现在已逐次写入退出。三元组没有 tags 也没有 update 命令，所以之前写的 `belongTo` / `summary` 边保留向量 |
-| 任务处于 `deferred` 状态 | live store 和 persistence 都没能提供它的会话。不是错误：它不消耗尝试次数，一旦二者之一能提供就运行。通常 storage 立即回答——只有组合里没有 `sessionPersistence`，或它的读取失败（日志里找 `could not be read`）时才会持久化这个状态 |
+| 任务处于 `deferred` 状态 | live store 和 persistence 都没能提供它的会话。不是错误：它不消耗尝试次数，一旦二者之一能提供就运行。通常 storage 立即回答——只有组合里没有 `sessionPersistence`，或它的读取失败（日志里找 `could not be read`）时才会持久化这个状态。被 deferred 的巩固任务会在下次启动时被 backfill 重新入队，所以它不必等会话被重新打开 |
 | 任务处于 `failed` 状态 | 一次 hypatia 或模型错误在 `maxAttempts` 之后持久化了。失败的 `log-message` 记录在下次启动时被修剪，因为水位会重新推导它们的范围；其它类型保留供检查——删掉一条好让下一个触发器重新创建它 |
 | 水位说已记录，但 shelf 里没条目 | shelf 在记录后被重置或切换。启动时处理：`housekeeping.reconcileOnStartup` 重置任何 session 已无 `msg-*` 的行，该会话下次活跃时从头重新记录——并重新巩固。shelf 查询失败则不动该行。一个所有消息都被故意删除的会话无法区分，会被重新记录；如果这要紧，关掉这个开关 |
 | 警告 `hypatia mcp unavailable: …; using the hypatia CLI until the profile reloads` | 二进制早于 `hypatia mcp`（消息会引用它的 `unrecognized subcommand`）、缺本插件调用的某工具、或握手返回错误。一切继续走 CLI；升级 hypatia 并重载 profile 以使用 MCP |
 | 每次调用都失败 `hypatia mcp exited …` 或 `timed out` | 二进制能启动但它的 MCP server 起不来——`binaries` 里一个改了 clap 退出码或措辞的包装脚本不会被识别为旧二进制。设 `transport: cli` |
-| 改了 `shelf` 之后每次写入都失败 | shelf 没注册或没连接——启动时记录 `shelf "<name>" is not registered`。连接它（`hypatia connect <dir> --name <name>`）并重载 profile，或换一个 |
+| 改了 `shelf` 之后每次写入都失败 | shelf 没注册或没连接——启动时记录 `shelf "<name>" is not registered`。连接它（`hypatia connect <dir> --name <name>`）后重新保存设置（或重载 profile），或换一个 |
 | Agent 在 `default` 里搜，而插件写在别处 | 一份磁盘上的 `hypatia-memory`（见下）替换了随包技能，或 recall 被禁用，所以没有东西告诉 Agent 用哪个 shelf |
 | 手动乱改后出现重复 `msg-*` | 在 hypatia 里删掉该条目，并在 state domain 里把该会话的 `lastLoggedSeq` 调低——回填会重新创建它一次 |
-| Agent 自己的 `hypatia` 写入仍要审批 | `autoApprove: false`（改动需重载 profile）、命令在引号外有管道/重定向/串联、或首词不是 `binaries` 之一——按设计只回答纯调用。读取根本不会走到审批，所以那里没有要修的 |
+| Agent 自己的 `hypatia` 写入仍要审批 | `autoApprove: false`、命令在引号外有管道/重定向/串联、或首词不是 `binaries` 之一——按设计只回答纯调用。读取根本不会走到审批，所以那里没有要修的 |
 | Agent 拿到了一份教它手动记录消息的记忆协议 | 另一个插件先注册了 `hypatia-memory`（profile 里还有 `dsh-hypatia`），或磁盘上有 `hypatia-memory`——通常是 `hypatia skill install --agent codex` 写的 `~/.agents/skills/hypatia-memory`。Agent 预设会在比插件更近的一层加载磁盘技能，所以它在会话里胜出，尽管技能中心可能列出本插件。删掉启动告警指出的那份拷贝 |
 | 不知道实际用了哪个模型 | 设计上就是轮流的：span 摘要、裁决、cascade 共用一个进程内游标，所以相邻调用在 `consolidation.models` 里交替。每次尝试都落在 `~/.dsh/storages/hypatia_auto_memory_diag.json`（`model_calls`），带 purpose、provider/model、outcome 和耗时。usage ledger 答不了这个问题——它只折算 Agent 的 turn（`assistant/message`），看不见插件直连的 `llm.stream`。`pending` 行表示调用仍在进行中，或进程在调用中途死了：记录在调用前先落盘、调用结束后回填 |
 | 启动告警从不出现在终端 | `dsh web` 不挂日志导出器，所以插件任何级别的日志行都没地方去；控制台导出器的默认阈值也会丢掉警告（warn 是 2 级，高于 info 的 1 级）。临时挂一个 logger，如 `dsh-logbook` 或 `dsh-boot-doctor` 来读它们 |
@@ -412,8 +458,8 @@ rules/taboos 预载、启动清理。设置卡片把它做成 `hypatia list` 所
     行上限里，它们会让技能在真正审阅的三元组远未达到上限前就停在截断检查上。
 
   它的 `evals/evals.json` 为这两处补丁新增 case 9 和 10。
-- **顶层的 `enabled: false` 在插件启动时读取**；实时切换需要重载 profile，而各特性
-  开关立即生效。
+- **顶层的 `enabled: false` 在采集器启动时读取**；保存改动会重启采集器，而各特性
+  开关原地生效。
 
 ## 目录结构
 
@@ -426,8 +472,8 @@ dsh-hypatia-auto-memory/
 ├── tsdown.config.ts      # 浏览器 CJS 工厂构建
 ├── src/
 │   ├── index.js          # fiber 组合（collect + 可选子模块）
-│   ├── config.js         # 设置命名空间、默认值、热更新
-│   ├── shelf.js          # 每 shelf 表视图、`hypatia list`、shelf 清单
+│   ├── config.js         # cordis Config schema（volatile）、默认值、热更新
+│   ├── shelf.js          # 每 shelf 表视图、`hypatia list` 解析
 │   ├── state.js          # storageDomain 规格 + 进度助手
 │   ├── collector.js      # session/event 过滤、台账、回填
 │   ├── content-policy.js # 脱敏、日期、上限、slug（纯函数）
@@ -439,6 +485,8 @@ dsh-hypatia-auto-memory/
 │   ├── consolidator.js   # 阈值、prompt、llm.stream、校验
 │   ├── cascade.js        # log₁₆(n) 分层摘要归档
 │   ├── model-log.js      # 每次尝试实际用了哪个模型的有界记录
+│   ├── memory-status.js  # 两张状态表按会话折叠（纯函数）
+│   ├── memory-api.js     # 记忆标签页与 shelf 清单：只读路由族 + JSE 读取
 │   ├── recall.js         # 会话启动时的 rules/taboos 预载
 │   ├── auto-approve.js   # 批准 Agent 自己的纯 bash hypatia 调用
 │   ├── skills.js         # 随包技能注册（从不遮蔽其它提供者）
@@ -446,7 +494,10 @@ dsh-hypatia-auto-memory/
 │   └── client/           # 设置卡片 + 记忆标签页
 │       ├── index.tsx     # client 插件入口 + slot 注册
 │       ├── SettingsCard.tsx
-│       ├── shelves.ts    # 来自清单命名空间的 shelf 下拉选项
+│       ├── MemoryView.tsx     # 记忆标签页主体
+│       ├── memory-client.ts   # 它的请求与合并规则（纯函数）
+│       ├── plugin-card-seat.ts # 卡片落座：官方「插件」页，否则设置标签页
+│       ├── shelves.ts    # shelf 下拉选项（清单来自 /shelves 路由）
 │       └── slot-contract.ts
 ├── lib/
 │   └── client.js         # 构建好的浏览器工厂（提交此文件）

package/cordis.patch.yml

@@ -3,9 +3,12 @@
 #   dsh plugin --profile <name> add dsh-hypatia-auto-memory          (registry)
 #   dsh plugin --profile <name> add link:/path/to/dsh-hypatia-auto-memory
 #
-# Behavior is configured through the `hypatia-auto-memory` settings namespace
-# (settings.yaml / Web settings), NOT through this config block. The only
-# cordis-level knobs are the bundled skill:
+# Behavior is configured through this entry's `config:` (edited live on the
+# bundle's own page of the sidebar's Plugins page, which dsh ≥ 0.1.7 projects
+# the plugin's Config schema onto; a deployment that renders no Plugins page
+# gets the same card under Settings → Built-in plugins).
+# The cordis-level knobs below are the non-volatile ones — changing them
+# remounts the plugin:
 #
 #   - id: hypatia-auto-memory
 #     config: