fix(memhub): harden mode card edge states

Co-authored-by: Cursor <cursoragent@cursor.com>
style(memhub): align mode dividers and clarify schedule
2026-11-06 14:30:18 +08:00 · 2026-11-06 14:26:02 +08:00 · 2026-11-06 14:26:02 +08:00 · 2026-11-06 14:26:02 +08:00 · 2026-11-06 14:26:02 +08:00 · 2026-11-06 14:04:03 +08:00
356 changed files with 41811 additions and 6124 deletions
@@ -4,16 +4,170 @@ Hy Memory and MemHub are versioned and released independently.

 ## Unreleased

-## MemHub 1.0.6 — 2026-11-02
+- MemHub host capture hooks no longer write the database. `one-memory
+  capture <host>` used to open the main SQLite file from its own short-lived
+  process on every hook, re-create the retired `evidence` / FTS tables on an
+  SDK-authority home and write the write queue outside Core's single writer,
+  contending for the file lock with Core and with other hosts' hooks. It now
+  reads only the runtime receipt and token and posts the hook's JSON to the
+  running Core (`POST /api/v1/live-capture/{source}`, 1.5 s budget). Core
+  applies the same gates (grant, sync switch, rejection counting, automated
+  sessions, the Cursor/Claude Code rule; the migration fence stays on the hook
+  side) and stages the turn in-process through the live file-sync path. When
+  Core is not running the turn is dropped silently; nothing falls back to a
+  local write.
+- MemHub no longer sends one turn to the SDK twice when a host's hook and live
+  file sync both see it. The two lanes gave the same message different
+  identities (the hook carries no workspace and often no message id) and
+  separate assembly rows, so both were written as raws. Hook input for a
+  source that live sync reads from its own files (every hooked host except
+  Qwen Work, while live sync is on) is now left to the file path; only a
+  source without file polling is staged from its hook. Tables an older hook
+  re-created on an SDK home are dropped by the existing startup cleanup.

-Build 37, on `hy-memory==2.0.11`. Linux x64/arm64 Runtime and macOS arm64
+## Hy Memory 2.0.14 — 2026-11-04
+
+- `search()` / `async_search()` take an optional `statuses` for explicit
+  L1_RAW search (`layers=["l1_raw"]`, or any search in lite mode), e.g.
+  `statuses=["active", "shadow"]`, so raw turns a pro extraction already
+  shadowed can still be searched. Default stays active-only. Raw hits now
+  report their real `status`. Passing `statuses` to a non-raw search or to
+  `scene="all"` raises `ValueError` instead of being ignored.
+
+## Hy Memory 2.0.13 — 2026-11-02
+
+- A model failure during a write now reports failure and stores
+  nothing. **Behaviour change for direct SDK users:** writes that used to
+  return `success: true` in a degraded state now return `success: false`;
+  retry them with a new `request_id` once the model is back.
+  - Reconcile (pro / ultra `add` and `add_extracted`): when the reconcile model
+    call fails, returns HTTP 200 with empty content, or returns a reply that
+    cannot be parsed, or reconcile raises before anything is stored, the write
+    used to fall back to adding every extracted memory as-is (no dedup or
+    evolution) and report success. That fallback is removed, with its
+    `degraded` / `degraded_reason` result fields. The write now returns
+    `success: false`, `error_code: 502`,
+    `agent_error_code: "RECONCILE_FAILED"`, and the cause in the new
+    `reconcile_error_code` (`LLM_UNAVAILABLE`, `EMPTY_RESPONSE`,
+    `JSON_PARSE_FAILED`, `RECONCILE_EXCEPTION`). None of the new memories are
+    stored, the episode counter does not advance, and `add` rolls back its
+    raw turn the same way as an extraction failure
+    (`l1_rollback.retry_safe: true`). An empty 200 reply was previously
+    counted as "no changes" and reported success with 0 memories; only a
+    literal `[]` reply still means that. `RECONCILE_ENABLED=false` is a
+    configuration choice and still writes directly.
+  - Working / coding path: an extraction model failure used to return
+    success with 0 operations. It now returns `success: false` with
+    `agent_error_code` `LLM_ERROR`, `EMPTY_RESPONSE` or `JSON_PARSE_FAILED`.
+    A model that answers with nothing worth remembering is still a success.
+    An embedding failure used to store the experience or fact without a
+    vector, where search never finds it, and report success; it now returns
+    `EMBEDDING_FAILED` and the node is not stored. A fact embedding is checked
+    before any older fact is superseded. A failed write no longer appends its
+    turns to the recent trace and records no `chain_rounds`.
+    With `MEMORY_CODING_VERBATIM_FALLBACK_ENABLED` turned on, extraction
+    failures keep the verbatim fallback.
+  - Working / coding reconcile: when the experience reconcile or the fact
+    reconcile model call fails, returns empty content, or returns a reply that
+    is not a JSON object with an `ops` list, the write returns
+    `success: false`, `agent_error_code: "RECONCILE_FAILED"` and the cause in
+    `reconcile_error_code` (`LLM_UNAVAILABLE`, `EMPTY_RESPONSE`,
+    `JSON_PARSE_FAILED`), the same as chat. Before, experience reconcile fell
+    back to adding every draft, and fact reconcile inserted the new fact
+    without superseding older ones. Both model decisions now run before
+    anything is stored, so a failure in either leaves no experience or fact
+    from the write and supersedes no older fact. An experience reply of
+    `{"ops": []}` is a valid "no changes" decision: the write succeeds and no
+    experience is stored. A non-empty `ops` list with no recognizable op is a
+    parse failure. A fact reply of `{"ops": []}` inserts the new fact without
+    superseding anything. Fact reconcile still makes no model call when there
+    are no candidates.
+
+## Hy Memory 2.0.12 — 2026-11-02
+
+- Intention dedup is now configurable per client
+  (`MemoryConfig.recall.intention_dedup_enabled`, default `true`;
+  `recall.intention_dedup_threshold`, default `MEMORY_DEDUP_THRESHOLD` or
+  `0.95`). Env defaults: `MEMORY_INTENTION_DEDUP_ENABLED`,
+  `MEMORY_INTENTION_DEDUP_THRESHOLD`. When on, behaviour is unchanged
+  (duplicates found at read time are still deleted); when off, no intention
+  dedup runs, at read time or within a write batch, and nothing is hidden,
+  dropped or deleted. The threshold applies to read-time dedup only. Refs #241.
+
+- MemHub pins `hy-memory==2.0.12` and exposes that intention dedup switch in
+  its memory-features setting (`GET`/`PUT /api/v1/settings/memory-features`,
+  `memhub settings features`): the feature `intention_dedup` (default on) and
+  the numeric `intention_dedup_threshold` (default 0.95, accepted 0.8–1.0,
+  anything else is 422 or a CLI usage error). Unset, both keep the SDK
+  default, so nothing changes for the App; a change rebuilds the SDK clients
+  like the other feature switches. The API answer gains `parameters`, and
+  `pipeline.features` can now carry the threshold as a number. Refs #241.
+
+## MemHub 1.0.6 — 2026-11-04
+
+Build 44, on `hy-memory==2.0.14`. Linux x64/arm64 Runtime and macOS arm64
 App and Runtime.

+- MemHub App now exposes the complete memory-mode lifecycle. New installs
+  explicitly choose lite or pro during onboarding; pro completes only after a
+  generation model is active, while ultra remains an advanced Settings choice.
+  Settings shows mode effects, graph backfill, the default 03:00 evolve
+  schedule and manual evolve. The memory page shows original conversations in
+  lite and advanced memories in pro/ultra. Existing installs remain pro unless
+  the user changes them, and embedding maintenance blocks mode/evolve changes.
+- MemHub pins `hy-memory==2.0.14`. Lite search is plain RAG over raw: the
+  App's lite search, CLI context search, `/api/v1/recall` and the Host Bridge
+  (`MemHub_recall`, context search) return every vector hit above the floor,
+  ranked by score, over active and shadow raws, so history pro already
+  processed is still found after switching to lite. The turn view no longer
+  drops a hit whose turns do not literally contain the query; it shows the
+  hit's closest turn instead. Pro and ultra raw search stays active-only.
+  Fixes every raw search failing in packaged builds since #316, which passed
+  `statuses` to an SDK (2.0.13) that did not accept it. The lite raw-turn
+  page also stops re-listing the whole raw layer on each poll when a live
+  session only adds new raws.
+- MemHub Core no longer stalls writes or freezes the App for tens of seconds
+  on a machine with a long live-sync history. Finished live-sync import jobs
+  are pruned to the newest 20 per source (at startup, in bounded batches, and
+  every 10 minutes); history imports and every unfinished job are kept. Job
+  lookups are filtered in SQL with new indexes (schema migration 63) instead
+  of reading the whole table. The durable write queue runs its claims,
+  settles and lease renewals on its own threads, so import work can no longer
+  starve a lease. Import abandon, resume and enqueue, and the file watcher's
+  path attribution, no longer touch the database or the disk on the event
+  loop, and the WAL cadence checkpoint runs on its own thread instead of on
+  the writer's. The write drain now restarts itself after an unexpected exit,
+  reports the failure with its stack, and shows `write_drain` /
+  `write_drain_error` in memory-processing and `memhub status`.
+- Model Center (#293, #295): Settings splits into 界面语言 / 记忆模式 /
+  模型配置 pages, with separate 记忆整理 (generation) and 记忆搜索
+  (embedding) lanes. Changing one lane sends only that lane's patch. An
+  embedding change shows the switch plan, confirmation, progress, cancel and
+  rollback, and the search model only changes after the rebuilt index is
+  verified. Model panels open inside the lane that launched them and close
+  only after Core confirms the profile is active (#310).
+- Lite keeps raw conversations (#297): lite raw writes are no longer stopped
+  by the "pause model sedimentation" switch, the memory page lists every
+  imported raw conversation by role (by turn since #316), and lite adds a
+  manual raw input (source `one-memory-manual`) that never calls a
+  generation model.
+- The home page follows the memory mode (#298): lite counts raw
+  conversations and previews the latest one; pro and ultra read memories.
+  Pro and ultra now require an active generation model, in both the mode
+  preview and the switch.
+- Onboarding (#304) asks for lite or pro and resumes after a restart (schema
+  migration 62); pro finishes only once a generation model is active.
+- Smaller App fixes: compact home status copy (#307), clearer mode-switch
+  effects (#312), Ultra topic nodes are hover-only (#315), and settings
+  controls use the content width (#317).
 - Interfaces in 11 languages: English, Simplified and Traditional Chinese,
  Japanese, Spanish, German, Portuguese, French, Korean, Russian and
-  Indonesian. Choosing any language other than Simplified Chinese also sets
-  the SDK prompt language; Simplified Chinese keeps the automatic zh/en
-  detection.
+  Indonesian. Every interface language, Simplified Chinese included, sets the
+  SDK prompt language (#270). **User-visible:** zh-Hans users now get Chinese
+  prompts and Chinese memory text for every conversation, English ones
+  included; the App sends the language it displays, also when it follows the
+  system. Only an unset language (CLI/API installs, `memhub settings language
+  system`) keeps the SDK's zh/en detection.
 - Memory modes: lite (no LLM, keeps raw conversations), pro (LLM extraction)
  and ultra (pro plus the knowledge graph and a nightly evolve run). Set with
  `GET`/`PUT /api/v1/settings/memory-mode` or `memhub settings mode`. Raw
@@ -26,10 +180,52 @@ App and Runtime.
  embedding service is unavailable, search returns `embedding_unavailable`.
 - Multi-user Runtime: memory APIs and the CLI take `user_id` (default
  `local`); records are isolated per user; Hermes profiles can be connected as
-  separate users. The App keeps using `local`.
+  separate users. The App keeps using `local`. Hardening (#280): read
+  responses echo `user_id`; deleting another user's memory, or one that does
+  not exist, is 404 `memory_not_found` (the App and `memhub memories delete`
+  treat it as already gone); Hermes never reads a `profiles/` directory, and
+  a root that is the `profiles` container or overlaps another user's grant is
+  refused (`hermes_root_is_profiles_container`,
+  `hermes_root_overlaps_other_user`).
 - Configurable SDK features through the CLI and API (`memhub settings
  features`): graph rerank, episode recall, session episodes, episode
-  summaries, intention and few-shot. Defaults are unchanged.
+  summaries, intention and few-shot, and the intention dedup switch with its
+  threshold (`intention_dedup`, `intention_dedup_threshold`, #277). Defaults
+  are unchanged.
+- Memory writes retry themselves (#278), each time under a new SDK request
+  id after checking whether the previous one landed; interrupted writes
+  re-run automatically. A model provider failure (401/403, 404, 408, 429,
+  5xx, timeout, unreachable) keeps the job pending in place without spending
+  a retry, and a per-profile circuit breaker paces the queue (5 s doubling to
+  180 s, one probe job at a time). Any other failure is retried after 30, 60
+  and 120 s, then `failed`. With `hy-memory==2.0.13` a model failure is no
+  longer a silent success, and a failed job's `error_code` names the SDK's
+  cause (`hy_sdk_reconcile_empty_response`, `hy_sdk_llm_error`, ...) rather
+  than `hy_sdk_write_failed`. **User-visible:** the manual 重新整理 button,
+  the "整理结果不确定" display and
+  `POST /api/v1/memory-processing/retry-unknown` are gone; a banner
+  ("模型配置有问题……记忆暂停处理，已有 N 条在排队") with a button to the model
+  settings shows while a model problem pauses processing, and clears on
+  recovery.
+- Queue, WAL and recall (#278): the WAL stays bounded (64 MiB journal limit,
+  idle `TRUNCATE` checkpoints); a disabled or revoked source's jobs are
+  `suspended` and resume when it is turned back on; SDK writes and recall
+  reads use separate thread pools, and recall has a total budget (504
+  `recall_timeout`, `broker_timeout` in clients) instead of starving behind
+  stuck writes.
+- One Runtime per data dir (#273). App quit asks the service manager at quit
+  time: an enabled background service is never stopped, a disabled one has
+  every Runtime of the data dir stopped (only after an authenticated identity
+  check), and an unknown state stops nothing. At start the App adopts a
+  Runtime of the same build, replaces an older one, and silently adopts a
+  newer one. The tray quit label follows the current state.
+- DeepSeek Harness: the app page's one switch installs and grants recall for
+  every detected profile, and keeps new profiles granted without a restart
+  (#230); versioned session files (`session.v3.jsonl.zstd`,
+  `session.v4.jsonl.zstd`) are imported, and v4 tool output goes through the
+  same clipping and scrubbing (#175).
+- The packaged Runtime accepts only a full 40-character commit, lowercased; a
+  malformed `ONE_MEMORY_COMMIT` fails the build (#235, #236).
 - Search and recall pass through the SDK's search parameters with server-side
  score floors; the memory library filters by layer; `/api/v2/raw` returns
  data again; v2 source and import routes; profile version history.
@@ -33,7 +33,7 @@ English | [中文](README.zh.md)
 ## Latest News

 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **Open-sourced** quantized **FP8** (**[Hy-Memory-30B-A3B-FP8](https://huggingface.co/tencent/Hy-Memory-30B-A3B-FP8)**) and **GGUF** (**[Hy-Memory-30B-A3B-GGUF](https://huggingface.co/tencent/Hy-Memory-30B-A3B-GGUF)**) versions of **Hy-Memory-30B-A3B** on Hugging Face!
-* *<mark>[new]</mark>* 🔥🔥🔥 **[2026-11]**: 📦 **Released [MemHub v1.0.6](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.6)** with interfaces in 11 languages, memory modes (lite / pro / ultra with nightly evolve), safe embedding-model switching, multi-user support for the CLI and API, and more reliable upgrades, on **`hy-memory==2.0.11`**. See the release notes for details.
+* *<mark>[new]</mark>* 🔥🔥🔥 **[2026-11]**: 📦 **Released [MemHub v1.0.6](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.6)** with interfaces in 11 languages, memory modes (lite / pro / ultra with nightly evolve), safe embedding-model switching, multi-user support for the CLI and API, memory writes that retry themselves and pause while the model provider is down, and more reliable upgrades, on **`hy-memory==2.0.14`**. See the release notes for details.
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 📦 **Released [MemHub v1.0.5](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.5)** with Chinese, English and Spanish interfaces, one-time pairing codes for more custom Harnesses, and smoother browsing, search, startup and recovery, on **`hy-memory==2.0.8`**. See the release notes for details.
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 📦 **Released [MemHub v1.0.4](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.4)** and **[memhub-cli 1.0.5](https://www.npmjs.com/package/memhub-cli/v/1.0.5)**, with a signed macOS desktop app and verified macOS/Linux Runtimes!
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **Released** **Hy Memory 2.0 (`hy-memory==2.0.4`)** on [PyPI](https://pypi.org/project/hy-memory/2.0.4/) and open-sourced the **Hy-Memory** monorepo together with **[MemHub](memhub/README.md)**!
@@ -33,7 +33,7 @@
 ## 最新动态

 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **模型开源** 在 Hugging Face 发布 **Hy-Memory-30B-A3B** 的 **FP8**（**[Hy-Memory-30B-A3B-FP8](https://huggingface.co/tencent/Hy-Memory-30B-A3B-FP8)**）与 **GGUF**（**[Hy-Memory-30B-A3B-GGUF](https://huggingface.co/tencent/Hy-Memory-30B-A3B-GGUF)**）量化版本模型！
-* *<mark>[new]</mark>* 🔥🔥🔥 **[2026-11]**: 📦 **正式发布 [MemHub v1.0.6](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.6)**：界面支持 11 种语言，新增记忆模式（lite / pro / ultra，ultra 每晚自动整理），可安全切换嵌入模型，CLI 和 API 支持多用户，升级更可靠；底层使用 **`hy-memory==2.0.11`**。详见发布说明。
+* *<mark>[new]</mark>* 🔥🔥🔥 **[2026-11]**: 📦 **正式发布 [MemHub v1.0.6](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.6)**：界面支持 11 种语言，新增记忆模式（lite / pro / ultra，ultra 每晚自动整理），可安全切换嵌入模型，CLI 和 API 支持多用户，记忆写入自动重试、模型服务异常时暂停排队，升级更可靠；底层使用 **`hy-memory==2.0.14`**。详见发布说明。
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 📦 **正式发布 [MemHub v1.0.5](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.5)**：支持中文、英文和西班牙语界面，可通过一次性配对码连接更多自定义 Harness，并优化了记忆浏览、搜索、启动和异常恢复；底层使用 **`hy-memory==2.0.8`**。详见发布说明。
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 📦 **正式发布 [MemHub v1.0.4](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.4)** 与 **[memhub-cli 1.0.5](https://www.npmjs.com/package/memhub-cli/v/1.0.5)**，提供已签名的 macOS 桌面应用及经过验证的 macOS/Linux Runtime！
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **正式发布** **Hy Memory 2.0 (`hy-memory==2.0.4`)**（已上线 [PyPI](https://pypi.org/project/hy-memory/2.0.4/)），并开源 **Hy-Memory** monorepo 与 **[MemHub](memhub/README.md)**！
@@ -182,9 +182,29 @@ SDK 不设置 Rerank Search 并发上限。开启后模型在 `HyMemoryClient`
 | `MEMORY_RECALL_STRENGTH_TAU` | `180` | 衰减时间常数，天 |
 | `MEMORY_RECALL_ACCESS_TRACKING` | `true` | Strength 开启时是否回写访问信息 |
 | `MEMORY_ENTITY_STORE_ENABLED` | `false` | 是否维护独立 entity collection；当前 Reader 不直接读取 |
+| `MEMORY_INTENTION_DEDUP_ENABLED` | `true` | 是否对 L7 Intention 判重（读侧和写入侧批内）；见下文 |
+| `MEMORY_INTENTION_DEDUP_THRESHOLD` | `MEMORY_DEDUP_THRESHOLD`，再缺省为 `0.95` | Intention 读侧判重的 cosine 阈值 |

 旧数据可调用当前公开方法 `client.build_entity_store(user_id)` 补建 Entity Store。

+Intention 判重：开启时（默认，与以往行为一致），Search 召回的 L7 Intention 中，
+同 `user_id` + 同 `agent_id` + `memory_at` 同一天 + `valid_until` 相同、且 cosine ≥ 阈值的
+条目视为复本，只返回最早写入的一条，其余在后台从向量库**删除**。判重不区分内容中的项目、
+对象等语义差异，内容高度相似但对象不同的意图可能被误删；写入时同一批抽取结果也会做一次
+批内判重。关闭后这两处都不判重，不隐藏、不丢弃、也不删除意图。两项对应
+`MemoryConfig.recall.intention_dedup_enabled` /
+`recall.intention_dedup_threshold`，按 client 生效，环境变量只提供默认值：
+
+```python
+client = HyMemoryClient.from_config({
+    "recall": {"intention_dedup_enabled": False},
+})
+```
+
+`MEMORY_DEDUP_THRESHOLD` 同时被写入侧批内意图判重和 dedup 内核使用；
+`MEMORY_INTENTION_DEDUP_THRESHOLD` 只影响读侧 Intention 判重，写入侧批内判重的阈值
+仍取 `MEMORY_DEDUP_THRESHOLD`。
+
 ## 日志、Trace 与历史

 | 变量 | 默认值 | 说明 |
@@ -107,5 +107,5 @@ L1_RAW 保存的内容使用上述渲染格式。历史回读时：
 ```bash
 python -m pytest -q \
  tests/test_multi_speaker_format.py \
-  tests/test_reconcile_fallback.py
+  tests/test_reconcile_failure.py
 ```
@@ -150,7 +150,23 @@ working/coding 写入返回双层结果：
 }
 ```

-`scene="coding"` 还会返回 `chain_rounds`。出于历史兼容，该字段当前统计本次识别并处理
+抽取 LLM 调用失败、返回空 content 或回复解析不出 JSON，以及经验 / 事实向量化失败时，
+写入返回 `success=False`、`error_code=502`，`agent_error_code` 依次为 `LLM_ERROR`、
+`EMPTY_RESPONSE`、`JSON_PARSE_FAILED`、`EMBEDDING_FAILED`，`error_message` 以
+`[CODE]` 开头；没有向量的经验 / 事实不会落库，失败的写入也不追加对话 trace，换一个
+`request_id` 重跑即可。模型正常作答但没有值得记的内容仍是 `success=True`、0 条。
+显式开启 `MEMORY_CODING_VERBATIM_FALLBACK_ENABLED` 时抽取失败沿用原文兜底。
+
+经验层 / 事实层 reconcile 的模型决策同样不再兜底：LLM 调用失败、返回空 content 或回复
+不是带 `ops` 列表的 JSON 对象时，写入返回 `success=False`、
+`agent_error_code="RECONCILE_FAILED"`，原因在 `reconcile_error_code`（`LLM_UNAVAILABLE` /
+`EMPTY_RESPONSE` / `JSON_PARSE_FAILED`，与 chat 链路一致）。两层的模型决策都在落库之前
+完成，任何一层失败时本次一条经验 / 事实都不存，旧事实也不会被覆盖。经验层回复
+`{"ops": []}` 表示「无需任何操作」，写入成功、经验层不存；`ops` 非空却没有一条可识别的
+op 视为解析失败。事实层回复 `{"ops": []}` 表示都不覆盖、照常插入新事实；没有候选时不
+调用 LLM。
+
+`scene="coding"` 还会返回 `chain_rounds`（写入失败时不记录演进链，也不返回该字段）。出于历史兼容，该字段当前统计本次识别并处理
 的 diff hunk 数，而不保证等于最终合并后的唯一演进 round 数。`0` 表示没有识别到可记录
 的代码修改，不代表双层 memory 写入失败。

@@ -128,6 +128,14 @@ result = client.add(
 双层 reconcile 操作、`experience_ids`、`fact_ids` 等字段，完整结构见
 [scene_coding_usage.md](scene_coding_usage.md#4-返回结构)。

+写入失败时 `success=False`，`error_code` 为 HTTP 风格的整数，`agent_error_code` 给出稳定
+失败码。pro / ultra 的 reconcile（新事实与已有记忆判重、合并）模型调用失败、返回空
+content 或回复解析不出时，`add` 与 `add_extracted` 都报 `agent_error_code="RECONCILE_FAILED"`，
+具体原因在 `reconcile_error_code`（`LLM_UNAVAILABLE` / `EMPTY_RESPONSE` /
+`JSON_PARSE_FAILED` / `RECONCILE_EXCEPTION`）。此时本次一条新记忆都不落库，`add` 已写入
+的原始对话按抽取失败同样回滚（`l1_rollback.retry_safe=True`）；模型恢复后换一个
+`request_id` 重跑即可。`RECONCILE_ENABLED=false` 时不调用 reconcile，直接写入。
+
 `mode="lite"` 不执行 LLM 抽取，写入内容直接以 `L1_RAW` 形式保存。lite 的 Search 是
 严格的 raw-only 向量检索：无论调用方传入什么 `layers`、`scene` 或 `search_mode`，都只
 召回 `L1_RAW`，不会进入 working/coding、Schema 或 Intention 链路，也不会调用场景判断
@@ -136,10 +136,10 @@ class ReconcileResult:
    ops: List[ReconcileOp] = field(default_factory=list)
    success: bool = True
    error: Optional[str] = None
-    # True = reconcile 失败后走了「全部 ADD」兜底（见 _fallback_add_ops）。
-    # 结果仍然可用（success=True），但没有做过去重/演化判定，可能引入重复。
-    degraded: bool = False
-    degraded_reason: Optional[str] = None
+    # success=False 时的稳定失败码：LLM_UNAVAILABLE / EMPTY_RESPONSE /
+    # JSON_PARSE_FAILED / RECONCILE_EXCEPTION。失败时 ops 恒为空：writer 什么都
+    # 不落库，整次写入报失败，调用方换个 request_id 重跑即可（reconcile 会判重）。
+    error_code: Optional[str] = None
    # reconcile 链路 LLM token 消耗（search-query + reconcile 两次 LLM 调用之和）
    prompt_tokens: int = 0
    completion_tokens: int = 0
@@ -151,7 +151,7 @@ class ReconcileResult:
    # 用 content 作 key 而不是 node_id：新记忆此刻还没入库、没有 id。
    candidate_scores: Dict[str, List[Tuple[str, float]]] = field(default_factory=dict)
    # reconcile 候选检索已经为每条新 memory 算过 embedding。把原始文本对应向量交回
-    # writer，ADD-all / degraded ADD 可直接落库，避免同一事实再次请求 embedding。
+    # writer，原文不变的 ADD 可直接落库，避免同一事实再次请求 embedding。
    # 仅按完全相同 content 复用；LLM 改写后的 UPDATE/SUPERSEDE 会重新计算，防止错配。
    new_memory_embeddings: Dict[str, List[float]] = field(default_factory=dict)

@@ -394,49 +394,6 @@ class MemoryReconciler:

        return [], None

-    @staticmethod
-    def _fallback_add_ops(
-        new_memories: List[str],
-        new_memories_with_meta: Optional[List[Dict]] = None,
-    ) -> List[ReconcileOp]:
-        """reconcile 彻底失败时的兜底：把抽取结果**原样全部 ADD**。
-
-        为什么必须有这个兜底：reconcile 只是决定「新事实和旧记忆怎么合」。它挂了（网关 500、
-        JSON 解析不出）不代表抽取结果没价值 —— 此前的行为是把一整批完好的事实**全部丢弃**，
-        线上实测因此丢掉过整块内容（含评测题的正确答案）。宁可留重复也不要丢内容：
-        重复还能被后续 dedup / reconcile 收拾，丢了就永远找不回来。
-        """
-        metas = new_memories_with_meta or []
-        by_content = {
-            (m.get("content") or ""): m for m in metas if isinstance(m, dict)
-        }
-        ops: List[ReconcileOp] = []
-        for text in new_memories:
-            if not text:
-                continue
-            meta = by_content.get(text) or {}
-            ops.append(ReconcileOp(
-                op="ADD",
-                content=text,
-                layer=meta.get("layer"),
-                tags=meta.get("tags") or [],
-                owner=meta.get("owner"),
-                topic_paths=meta.get("topic_paths") or [],
-                event_facet=meta.get("event_facet") or {},
-                topic_assignments=meta.get("topic_assignments") or [],
-                topic_paths_provided=bool(
-                    meta.get("topic_paths_provided", "topic_paths" in meta)
-                ),
-                event_facet_provided=bool(
-                    meta.get("event_facet_provided", "event_facet" in meta)
-                ),
-                topic_assignments_provided=bool(meta.get(
-                    "topic_assignments_provided", "topic_assignments" in meta,
-                )),
-                reason="reconcile unavailable → stored as-is (degraded)",
-            ))
-        return ops
-
    async def reconcile(
        self,
        new_memories: List[str],
@@ -1088,8 +1045,8 @@ class MemoryReconciler:
                    )
                except Exception as e:
                    # LLM 彻底不可用（provider 已按 max_retries 重试过，网关 500 /
-                    # 连接错误等）。**不能让它冒泡** —— 冒泡会让整批抽取结果连带丢弃。
-                    # 交给下面的 ADD-all 兜底。
+                    # 连接错误等）。不冒泡：下面统一记 RECONCILE 失败日志，再返回
+                    # success=False —— writer 不落任何新记忆，整次写入报失败。
                    _llm_error = f"{type(e).__name__}: {e}"
                    logger.warning(f"[reconciler] RECONCILE LLM unavailable: {_llm_error}")
                    break
@@ -1097,7 +1054,7 @@ class MemoryReconciler:
                _tok_pt += response.prompt_tokens
                _tok_ct += response.completion_tokens
                _tok_total += response.tokens_used
-                raw_response = response.content
+                raw_response = response.content or ""
                ops = self._parse_ops(raw_response)
                ops = enforce_time_order(ops, current_time, candidate_map)
                ops = self._inherit_exact_input_structure(
@@ -1106,7 +1063,9 @@ class MemoryReconciler:
                if _structure_metadata_on:
                    ops = self._resolve_structure_references(ops, candidate_map)

-                _is_empty_array = self._strip_code_fence(raw_response) in ("[]", "")
+                # 只有字面量 "[]" 才是「模型判定无需任何操作」。HTTP 200 但 content
+                # 为空不是决策，是失败：按 EMPTY_RESPONSE 处理，不能当成 0 条成功。
+                _is_empty_array = self._strip_code_fence(raw_response) == "[]"
                if ops or _is_empty_array:
                    _parse_ok = True
                    break
@@ -1136,7 +1095,7 @@ class MemoryReconciler:
                    error_msg = (
                        f"RECONCILE LLM returned empty response after {_n_attempts} attempts"
                    )
-                    error_code = "EMPTY_RESPONSE" 
+                    error_code = "EMPTY_RESPONSE"
                logger.warning(f"[reconciler] {error_msg}")

                if cache and request_id:
@@ -1153,14 +1112,13 @@ class MemoryReconciler:
                                {
                                    "error": error_code,
                                    "message": error_msg,
-                                    "fallback": "ADD_ALL",
-                                    "fallback_count": len(new_memories or []),
+                                    "stored": 0,
                                },
                                ensure_ascii=False,
                            ),
                            elapsed_ms=recon_elapsed,
-                            # LLM 彻底不可用时 response 是 None —— 这行本身会抛
-                            # AttributeError，而它正好在兜底路径上，会把兜底也一起废掉
+                            # LLM 彻底不可用时 response 是 None —— 直接取属性会抛
+                            # AttributeError，把失败日志本身也废掉
                            prompt_tokens=getattr(response, "prompt_tokens", 0) or 0,
                            completion_tokens=getattr(response, "completion_tokens", 0) or 0,
                            total_tokens=getattr(response, "tokens_used", 0) or 0,
@@ -1170,22 +1128,16 @@ class MemoryReconciler:
                            f"[reconciler] store failed RECONCILE log failed: {e}"
                        )

-                # 兜底：JSON 解析不出来不等于抽取结果没价值 —— 全部 ADD，别丢内容。
-                _fb = self._fallback_add_ops(new_memories, new_memories_with_meta)
-                logger.warning(
-                    f"[reconciler] falling back to ADD-all: {len(_fb)} memories "
-                    f"({error_code})"
-                )
+                # 不做 ADD-all 兜底：没经过判重 / 演化的整批 ADD 会在重跑时产生重复，
+                # 而且调用方看到 success 就不会重试。这里报失败、不落库，由调用方重跑。
                return ReconcileResult(
-                    ops=_fb,
-                    success=bool(_fb),
-                    error=None if _fb else error_msg,
-                    degraded=bool(_fb),
-                    degraded_reason=error_code,
+                    ops=[],
+                    success=False,
+                    error=error_msg,
+                    error_code=error_code,
                    prompt_tokens=_tok_pt,
                    completion_tokens=_tok_ct,
                    total_tokens=_tok_total,
-                    new_memory_embeddings=new_memory_embeddings,
                )

            # 写 RECONCILE pipeline log
@@ -1250,20 +1202,14 @@ class MemoryReconciler:

        except Exception as e:
            logger.error(f"[reconciler] failed: {e}", exc_info=True)
-            # 兜底同样适用于「reconcile 链路任意环节炸了」（候选检索、embed、
-            # prompt 组装…）。此前这里返回 ops=[] → writer 直接丢弃整批抽取结果。
-            _fb = self._fallback_add_ops(new_memories, new_memories_with_meta)
-            if _fb:
-                logger.warning(
-                    f"[reconciler] falling back to ADD-all after unexpected error: "
-                    f"{len(_fb)} memories"
-                )
-                return ReconcileResult(
-                    ops=_fb, success=True,
-                    degraded=True, degraded_reason=f"EXCEPTION:{type(e).__name__}",
-                    new_memory_embeddings=dict(new_memory_embeddings or {}),
-                )
-            return ReconcileResult(ops=[], success=False, error=str(e))
+            # reconcile 链路任意环节炸了（候选检索、embed、prompt 组装…）：此时还
+            # 没有任何新记忆落库，报失败让整次写入可以干净地重跑。
+            return ReconcileResult(
+                ops=[],
+                success=False,
+                error=f"{type(e).__name__}: {e}",
+                error_code="RECONCILE_EXCEPTION",
+            )

    @staticmethod
    def _inherit_exact_input_structure(
@@ -134,6 +134,7 @@ _WRITE_DIAGNOSTIC_KEYS = (
    "agent_status",
    "agent_error_code",
    "agent_error",
+    "reconcile_error_code",
    "l1_rollback",
    "l1_rollback_failed",
    "partial_agent_persist",
@@ -1863,6 +1864,7 @@ class HyMemoryClient:
        branch: Optional[str] = None,
        request_id: Optional[str] = None,
        layers: Optional[List[Any]] = None,
+        statuses: Optional[List[Any]] = None,
        embed_override: Optional[Dict[str, Any]] = None,
        query_embedding: Optional[List[float]] = None,
        rerank: bool = True,
@@ -1955,6 +1957,8 @@ class HyMemoryClient:
            layers:             可选。pro/ultra 下只召回指定层级（字符串或
                                MemoryLayer），在召回阶段生效。lite 下忽略该参数并
                                强制只召回 L1_RAW。
+            statuses:           仅用于 L1_RAW 定向搜索，可显式包含 active / shadow。
+                                非 raw 搜索或 scene="all" 传入时拒绝，避免静默忽略。
            rerank:             默认 True（原行为）。False 时本次调用跳过全部重排阶段：
                                chat 路的本地 cross-encoder 重排（recall.local_rerank_enabled）
                                与记忆关系图重排（graph_rerank / episode 扩展），working/
@@ -1998,7 +2002,7 @@ class HyMemoryClient:
            intention_limit=intention_limit, created_after=created_after,
            reader=reader,
            workspace_id=workspace_id, branch=branch,
-            request_id=request_id, layers=layers,
+            request_id=request_id, layers=layers, statuses=statuses,
            embed_override=embed_override,
            query_embedding=query_embedding,
            rerank=rerank,
@@ -3032,7 +3036,9 @@ class HyMemoryClient:
                # 版本演进链层（scene="coding" 独有）。放在 writer.write 之后、返回
                # 之前，因为它只依赖对话原文，与向量层写入结果无关。
                # best-effort：这层挂不上不影响本次 add 的向量层产出。
-                if scene_variant == "coding":
+                # 向量层写入失败（success=False）时跳过：调用方会重跑整段，失败的
+                # 那次不该先把改动记进演进链。
+                if scene_variant == "coding" and resp.get("success"):
                    resp["chain_rounds"] = self._observe_chain(
                        chat_messages, user_id=uid,
                        workspace_id=workspace_id, branch=branch,
@@ -3384,12 +3390,14 @@ class HyMemoryClient:
        request_id: str,
        t0: float,
        query_embedding: Optional[List[float]],
+        statuses: Optional[List[Any]],
    ) -> Dict[str, Any]:
        """Implement `search(..., layers=['l1_raw'])` without a second API."""
        from .models.memory import MemoryLayer, MemoryStatus

        embedding = query_embedding or await self._embed_service.embed(query)
        fetch = min(max(limit * (10 if session_ids else 2), limit), 10_000)
+        status_filter = self._normalize_statuses(statuses) or [MemoryStatus.ACTIVE]
        hits = await self._vector_store.search(
            query_embedding=embedding,
            user_ids=user_ids,
@@ -3399,7 +3407,7 @@ class HyMemoryClient:
            layers=[MemoryLayer.L1_RAW],
            limit=fetch,
            score_threshold=min_score,
-            status_filter=[MemoryStatus.ACTIVE],
+            status_filter=status_filter,
            only_latest=False,
            created_after=created_after,
        )
@@ -3417,7 +3425,7 @@ class HyMemoryClient:
                    "memory_id": row.pop("raw_id"),
                    **row,
                    "layer": MemoryLayer.L1_RAW.value,
-                    "status": MemoryStatus.ACTIVE.value,
+                    "status": node.status.value,
                    "score": round(float(hit.get("score", 0.0)), 4),
                }
            )
@@ -3861,6 +3869,7 @@ class HyMemoryClient:
        branch: Optional[str] = None,
        request_id: Optional[str] = None,
        layers: Optional[List[Any]] = None,
+        statuses: Optional[List[Any]] = None,
        embed_override: Optional[Dict[str, Any]] = None,
        query_embedding: Optional[List[float]] = None,
        rerank: bool = True,
@@ -3890,7 +3899,7 @@ class HyMemoryClient:
                    schema_min_score=schema_min_score, schema_limit=schema_limit,
                    intention_limit=intention_limit, created_after=created_after,
                    reader=reader, workspace_id=workspace_id, branch=branch,
-                    request_id=request_id, layers=layers,
+                    request_id=request_id, layers=layers, statuses=statuses,
                    query_embedding=query_embedding,
                    rerank=rerank,
                )
@@ -3905,7 +3914,7 @@ class HyMemoryClient:
            schema_min_score=schema_min_score, schema_limit=schema_limit,
            intention_limit=intention_limit, created_after=created_after,
            reader=reader, workspace_id=workspace_id, branch=branch,
-            request_id=request_id, layers=layers,
+            request_id=request_id, layers=layers, statuses=statuses,
            query_embedding=query_embedding,
            rerank=rerank,
        )
@@ -3935,6 +3944,7 @@ class HyMemoryClient:
        branch: Optional[str] = None,
        request_id: Optional[str] = None,
        layers: Optional[List[Any]] = None,
+        statuses: Optional[List[Any]] = None,
        query_embedding: Optional[List[float]] = None,
        rerank: bool = True,
    ) -> Dict[str, Any]:
@@ -4020,6 +4030,17 @@ class HyMemoryClient:
                "Use single agent_id with multiple session_ids, or multiple agent_ids without session_ids."
            )

+        if statuses is not None:
+            from .models.memory import MemoryLayer
+
+            requested_layers = self._normalize_layers(layers)
+            if scene_all or (
+                not lite_mode and requested_layers != [MemoryLayer.L1_RAW]
+            ):
+                raise ValueError(
+                    "statuses is supported only for explicit L1_RAW search"
+                )
+
        if scene_all:
            return await self._search_all_scenes(
                query, queries=queries, search_mode=search_mode,
@@ -4355,6 +4376,7 @@ class HyMemoryClient:
                request_id=request_id,
                t0=t0,
                query_embedding=query_embedding,
+                statuses=statuses,
            )

        read_req = ReadRequest(
@@ -12,6 +12,7 @@ HY Memory - Coding Memory 模块

 from .types import (
    CodingMemory,
+    CodingWriteError,
    CodingMemoryDraft,
    ReconcileOp,
    WorkingFact,
@@ -26,6 +27,7 @@ from .types import (

 __all__ = [
    "CodingMemory",
+    "CodingWriteError",
    "CodingMemoryDraft",
    "ReconcileOp",
    "WorkingFact",
@@ -33,7 +33,7 @@ from .preproc import (
    prepare_extractor_messages,
 )
 from .judge import _store_coding_log
-from .types import CodingMemoryDraft, WorkingFactDraft
+from .types import CodingMemoryDraft, CodingWriteError, WorkingFactDraft



@@ -217,6 +217,10 @@ class CodingMemoryExtractor:
        Returns:
            (经验草稿, 事实草稿)。两层都可能为空。只有显式启用
            verbatim_fallback_enabled 时，模型没产出 fact 才调用 _verbatim_fact。
+
+        Raises:
+            CodingWriteError: 未开启原文兜底时，LLM 调用失败（LLM_ERROR）、返回空
+                content（EMPTY_RESPONSE）或回复解析不出 JSON 对象（JSON_PARSE_FAILED）。
        """
        if not messages:
            return [], []
@@ -268,8 +272,9 @@ class CodingMemoryExtractor:
            )
        except Exception as e:
            logger.warning(f"[coding-extract] LLM call failed: {e}")
-            # 经验层不兜底。事实层原文兜底也默认关闭，避免 assistant/tool 轨迹被
-            # 当作 statement 直接展示；仅在配置显式开启时保留旧行为。
+            # 经验层不兜底。事实层原文兜底默认关闭，避免 assistant/tool 轨迹被
+            # 当作 statement 直接展示；关闭时 LLM 失败抛 CodingWriteError(LLM_ERROR)，
+            # 整次写入报失败，而不是「成功、0 条」。仅在配置显式开启时保留旧行为。
            verbatim = (
                self._verbatim_fact(messages)
                if self.verbatim_fallback_enabled else None
@@ -296,9 +301,33 @@ class CodingMemoryExtractor:
                ),
                elapsed_ms=round((time.perf_counter() - _t0) * 1000, 2),
            )
+            if not self.verbatim_fallback_enabled:
+                raise CodingWriteError(
+                    "LLM_ERROR",
+                    f"coding extract LLM call failed: {type(e).__name__}: {e}",
+                ) from e
            return [], ([verbatim] if verbatim else [])
        _elapsed = round((time.perf_counter() - _t0) * 1000, 2)

+        # 模型答了且没有可记的内容（如 {"experiences": [], "fact": null}）是正常的空
+        # 抽取；200 但 content 为空、或回复解析不出 JSON 对象，是模型失败，不能当成
+        # 「成功、0 条」。原文兜底显式开启时沿用旧行为（交给下面的 verbatim 兜底）。
+        failure = self._output_failure(resp.content)
+        if failure is not None and not self.verbatim_fallback_enabled:
+            code, message = failure
+            await _store_coding_log(
+                self.cache, request_id=request_id, user_id=user_id, agent_id=agent_id,
+                session_id=session_id or "", step="CODING_EXTRACT", prompt=prompt,
+                response=resp.content or "",
+                parsed=json.dumps(
+                    {"drafts": 0, "error": code, "message": message},
+                    ensure_ascii=False,
+                ),
+                elapsed_ms=_elapsed, prompt_tokens=resp.prompt_tokens,
+                completion_tokens=resp.completion_tokens, total_tokens=resp.tokens_used,
+            )
+            raise CodingWriteError(code, message)
+
        raw_experiences, raw_facts = self._parse_output(resp.content)

        # 经验层的 files 走规则抽取（整段轨迹碰过的文件）；事实层的 files 由 LLM
@@ -478,12 +507,22 @@ class CodingMemoryExtractor:
        return "\n".join(rows)

    @classmethod
-    def _parse_output(
-        cls, text: str
-    ) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
-        """宽松解析 LLM 输出 JSON，返回 (experiences, facts) 两个原始列表。"""
+    def _output_failure(cls, text: Optional[str]) -> Optional[Tuple[str, str]]:
+        """回复本身是失败时返回 (error_code, message)；正常（含空抽取）返回 None。"""
+        if not (text or "").strip():
+            return "EMPTY_RESPONSE", "coding extract LLM returned empty response"
+        if cls._load_output_object(text) is None:
+            return (
+                "JSON_PARSE_FAILED",
+                f"coding extract output is not a JSON object ({len(text)} chars)",
+            )
+        return None
+
+    @staticmethod
+    def _load_output_object(text: Optional[str]) -> Optional[Dict[str, Any]]:
+        """宽松解析 LLM 输出，返回顶层 JSON 对象；解析不出返回 None。"""
        if not text:
-            return [], []
+            return None
        s = text.strip()
        # 去 markdown fence
        if s.startswith("```"):
@@ -509,8 +548,17 @@ class CodingMemoryExtractor:
                    obj = json.loads(s[start: end + 1])
                except Exception:
                    obj = None
+        return obj if isinstance(obj, dict) else None

-        if not isinstance(obj, dict):
+    @classmethod
+    def _parse_output(
+        cls, text: str
+    ) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+        """宽松解析 LLM 输出 JSON，返回 (experiences, facts) 两个原始列表。"""
+        if not text:
+            return [], []
+        obj = cls._load_output_object(text)
+        if obj is None:
            logger.warning(
                f"[coding-extract] failed to parse output ({len(text or '')} chars)"
            )
@@ -18,6 +18,7 @@ import json
 import logging
 import os
 import uuid
+from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Any, Dict, List, Optional, Tuple

@@ -34,6 +35,7 @@ from .types import (


    MAX_FACT_CHAIN_ENTRIES,
+    CodingWriteError,
    FactReconcileOp,
    WorkingFact,
    WorkingFactDraft,
@@ -259,6 +261,16 @@ def build_chain_summary_prompt(
    return with_output_language(prompt, code, explicit=explicit is not None), code


+@dataclass
+class FactReconcilePlan:
+    """plan() 的产物：覆盖判定已完成、尚未落库。apply() 才执行 store 操作。"""
+
+    drafts: List[WorkingFactDraft]
+    candidates: List[List[WorkingFact]] = field(default_factory=list)
+    supersedes: Dict[int, List[str]] = field(default_factory=dict)
+    context: Dict[str, Any] = field(default_factory=dict)
+
+
 # ================================================================
 # WorkingFactReconciler
 # ================================================================
@@ -327,15 +339,63 @@ class WorkingFactReconciler:
        language: Optional[str] = None,
    ) -> Tuple[List[WorkingFact], List[FactReconcileOp]]:
        """
-        执行 reconcile + 持久化。memory_at 是这段对话的时间，记到新事实上。
-        language 为显式 prompt 语言码（None → zh/en 自动检测），同时用于演变总结。
+        执行 reconcile + 持久化（plan() 后紧接 apply()）。memory_at 是这段对话的
+        时间，记到新事实上。language 为显式 prompt 语言码（None → zh/en 自动检测），
+        同时用于演变总结。

        Returns:
-            (真正落库的新事实, 执行过的 ops)。LLM 挂掉时退化为全 INSERT 不覆盖，
-            宁可多留一条过期事实，也不因为一次调用失败丢结论。
+            (真正落库的新事实, 执行过的 ops)。
+
+        Raises:
+            CodingWriteError(RECONCILE_FAILED)：覆盖判定的 LLM 失败 / 空回复 /
+                解析不出。此时既不插入新事实，也不覆盖任何旧事实。
        """
+        plan = await self.plan(
+            drafts,
+            user_id=user_id,
+            agent_id=agent_id,
+            session_id=session_id,
+            workspace_id=workspace_id,
+            branch=branch,
+            source=source,
+            memory_at=memory_at,
+            language=language,
+        )
+        return await self.apply(plan)
+
+    async def plan(
+        self,
+        drafts: List[WorkingFactDraft],
+        *,
+        user_id: str,
+        agent_id: str = "default_agent",
+        session_id: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+        branch: Optional[str] = None,
+        source: str = "default",
+        memory_at: Optional[datetime] = None,
+        language: Optional[str] = None,
+    ) -> FactReconcilePlan:
+        """检索 candidates + 覆盖判定，不落库。
+
+        没有任何候选时不调 LLM（全部 INSERT 是确定的结论，不是兜底）。调了 LLM 时，
+        有效回复 = JSON 对象且 "ops" 是列表（空列表 = 都不覆盖、只插入）。LLM 调用
+        失败（LLM_UNAVAILABLE）、200 但 content 为空（EMPTY_RESPONSE）、回复不是
+        上述形状（JSON_PARSE_FAILED）时抛 CodingWriteError(RECONCILE_FAILED)。
+        此前 LLM 失败会退化为全 INSERT 不覆盖，留下本该被接续的旧事实。
+        """
+        context = dict(
+            user_id=user_id,
+            agent_id=agent_id,
+            session_id=session_id,
+            workspace_id=workspace_id,
+            branch=branch,
+            source=source,
+            memory_at=memory_at,
+            language=language,
+        )
        if not drafts:
-            return [], []
+            return FactReconcilePlan(drafts=[], context=context)

        candidates = await self._retrieve_candidates(
            drafts,
@@ -349,27 +409,37 @@ class WorkingFactReconciler:

        try:
            supersedes = await self._llm_decide(drafts, candidates, language=language)
+        except CodingWriteError:
+            raise
        except Exception as e:
-            logger.warning(
-                f"[fact-reconcile] LLM decide failed, insert without supersede: {e}"
-            )
-            supersedes = {}
+            logger.warning(f"[fact-reconcile] LLM decide failed: {e}")
+            raise CodingWriteError(
+                "RECONCILE_FAILED",
+                f"working fact reconcile LLM call failed: {type(e).__name__}: {e}",
+                cause="LLM_UNAVAILABLE",
+            ) from e

+        return FactReconcilePlan(
+            drafts=list(drafts),
+            candidates=candidates,
+            supersedes=supersedes,
+            context=context,
+        )
+
+    async def apply(
+        self, plan: FactReconcilePlan,
+    ) -> Tuple[List[WorkingFact], List[FactReconcileOp]]:
+        """执行 plan() 的决策（覆盖旧事实 + 插入新事实）。"""
+        if not plan.drafts:
+            return [], []
        facts, ops = await self._execute(
-            drafts,
-            candidates,
-            supersedes,
-            user_id=user_id,
-            agent_id=agent_id,
-            session_id=session_id,
-            workspace_id=workspace_id,
-            branch=branch,
-            source=source,
-            memory_at=memory_at,
-            language=language,
+            plan.drafts,
+            plan.candidates,
+            plan.supersedes,
+            **plan.context,
        )
        logger.info(
-            f"[fact-reconcile] drafts={len(drafts)} inserted={len(facts)} "
+            f"[fact-reconcile] drafts={len(plan.drafts)} inserted={len(facts)} "
            f"superseded={sum(1 for o in ops if o.action == 'SUPERSEDE')}"
        )
        return facts, ops
@@ -473,6 +543,11 @@ class WorkingFactReconciler:
            max_tokens=self.max_tokens,
            audit_stage="coding_fact_reconcile",
        )
+        failure = self._reply_failure(resp.content)
+        if failure is not None:
+            code, message = failure
+            logger.warning(f"[fact-reconcile] {code}: {message}")
+            raise CodingWriteError("RECONCILE_FAILED", message, cause=code)
        return self._parse_ops(resp.content)

    # ------------------------------------------------------------
@@ -599,11 +674,24 @@ class WorkingFactReconciler:
            rows.append(f"for draft[{i}]:\n" + "\n".join(cand_rows))
        return "\n\n".join(rows) if rows else "(none)"

+    @classmethod
+    def _reply_failure(cls, text: Optional[str]) -> Optional[Tuple[str, str]]:
+        """回复本身是失败时返回 (cause, message)；有效回复（含 {"ops": []}）返回 None。"""
+        if not (text or "").strip():
+            return "EMPTY_RESPONSE", "working fact reconcile LLM returned empty response"
+        obj = cls._load_object(text)
+        if not isinstance(obj, dict) or not isinstance(obj.get("ops"), list):
+            return (
+                "JSON_PARSE_FAILED",
+                f"working fact reconcile output has no ops list ({len(text)} chars)",
+            )
+        return None
+
    @staticmethod
-    def _parse_ops(text: str) -> Dict[int, List[str]]:
-        """宽松解析 ops，返回 {draft_idx: [fact_id...]}。"""
+    def _load_object(text: Optional[str]) -> Optional[Dict[str, Any]]:
+        """宽松解析出顶层 JSON 对象；解析不出返回 None。"""
        if not text:
-            return {}
+            return None
        s = text.strip()
        # 去 markdown fence
        if s.startswith("```"):
@@ -621,7 +709,14 @@ class WorkingFactReconciler:
                    obj = json.loads(s[start: end + 1])
                except Exception:
                    obj = None
+        return obj if isinstance(obj, dict) else None

+    @classmethod
+    def _parse_ops(cls, text: str) -> Dict[int, List[str]]:
+        """宽松解析 ops，返回 {draft_idx: [fact_id...]}。"""
+        if not text:
+            return {}
+        obj = cls._load_object(text)
        if not isinstance(obj, dict):
            logger.warning(
                f"[fact-reconcile] failed to parse ops output ({len(text or '')} chars)"
@@ -689,6 +784,11 @@ class WorkingFactReconciler:
                memory_at=memory_at,
            )

+            # 先确认新事实能向量化，再去覆盖旧事实：否则 embedding 挂掉时旧事实
+            # 已被软删、新事实又落不了库，这条结论就凭空没了。失败抛
+            # CodingWriteError(EMBEDDING_FAILED)，整次写入报失败。
+            new_embedding = await self.store.embed_fact(new_fact)
+
            allowed = {c.fact_id for c in (candidates[idx] if idx < len(candidates) else [])}
            targets = [
                fid for fid in supersedes.get(idx, [])
@@ -769,7 +869,9 @@ class WorkingFactReconciler:
                        )

            try:
-                await self.store.insert_fact(new_fact)
+                await self.store.insert_fact(new_fact, embedding=new_embedding)
+            except CodingWriteError:
+                raise
            except Exception as e:
                logger.warning(f"[fact-reconcile] INSERT failed: {e}")
                continue
@@ -7,6 +7,9 @@ Coding Memory Reconciler
        （DELETE 由 LLM 在 draft 与 candidate 关系中观察到"明确否定/作废"时附带产出）

 执行端：reconcile() 调用 store 完成实际 ADD / UPDATE / DELETE 持久化操作。
+CodingWriter 分两步用：先 plan()（检索 + LLM 决策，不落库），等经验层与事实层的
+模型决策都成功后再 apply()（落库）。LLM 失败 / 空回复 / 解析不出时 plan() 抛
+CodingWriteError(RECONCILE_FAILED)，本次写入什么都不存。

 复用 LLMConfig.model（与 chat reconciler 共用）。

@@ -17,6 +20,7 @@ import json
 import logging
 import time
 import uuid
+from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional, Tuple

 from ..agent.llm_provider import LLMProvider
@@ -29,7 +33,7 @@ from ..prompts import (
 )
 from .judge import _store_coding_log
 from .store import CodingMemoryStore
-from .types import CodingMemory, CodingMemoryDraft, ReconcileOp
+from .types import CodingMemory, CodingMemoryDraft, CodingWriteError, ReconcileOp



@@ -93,6 +97,15 @@ def build_experience_reconcile_prompt(
    return with_output_language(prompt, code, explicit=explicit is not None), code


+@dataclass
+class ExperienceReconcilePlan:
+    """plan() 的产物：模型已决策、尚未落库。apply() 才执行 store 操作。"""
+
+    drafts: List[CodingMemoryDraft]
+    candidates_per_draft: List[List[CodingMemory]] = field(default_factory=list)
+    ops: List[ReconcileOp] = field(default_factory=list)
+
+
 # ================================================================
 # CodingMemoryReconciler
 # ================================================================
@@ -143,21 +156,52 @@ class CodingMemoryReconciler:
        language: Optional[str] = None,
    ) -> List[ReconcileOp]:
        """
-        执行 reconcile + 持久化。返回执行的 ReconcileOp[]（含成功执行的 ADD/UPDATE/DELETE/SKIP）。
+        执行 reconcile + 持久化（plan() 后紧接 apply()）。返回执行的 ReconcileOp[]
+        （含成功执行的 ADD/UPDATE/DELETE/SKIP）。

-        执行错误（如 LLM 失败）会 fail-safe 回退到对每个 draft 直接 ADD。
+        LLM 失败、空回复或解析不出时抛 CodingWriteError(RECONCILE_FAILED)，什么都
+        不落库——不再回退成「全部 ADD」。
+        """
+        plan = await self.plan(
+            drafts,
+            request_id=request_id,
+            user_id=user_id,
+            agent_id=agent_id,
+            session_id=session_id,
+            language=language,
+        )
+        return await self.apply(plan)

-        cache 非空时落 CODING_RECONCILE pipeline log——在 LLM 决策后、执行入库前打点，
-        这样即使 store 入库崩溃，reconcile 决策仍已可见（crash 不丢）。
+    async def plan(
+        self,
+        drafts: List[CodingMemoryDraft],
+        *,
+        request_id: str = "",
+        user_id: str = "",
+        agent_id: str = "default_agent",
+        session_id: str = "",
+        language: Optional[str] = None,
+    ) -> ExperienceReconcilePlan:
+        """检索 candidates + LLM 决策，不落库。
+
+        有效回复 = 一个 JSON 对象，其 "ops" 是列表：
+          - {"ops": []}：模型判定「无需任何操作」（与 chat reconcile 的 [] 同义），
+            成功、本层什么都不存；
+          - 非空列表：至少要有一条可识别的 op（ADD/UPDATE/DELETE/SKIP），否则视为
+            解析失败。漏掉的 draft 仍按原规则补 ADD（那是对有效回复的校验兜底，
+            不是模型失败兜底）。
+        LLM 调用失败（LLM_UNAVAILABLE）、200 但 content 为空（EMPTY_RESPONSE）、
+        回复不是上述形状（JSON_PARSE_FAILED）时抛 CodingWriteError(RECONCILE_FAILED)。
+
+        cache 非空时落 CODING_RECONCILE pipeline log（成功、失败都落）。
        """
        if not drafts:
-            return []
+            return ExperienceReconcilePlan(drafts=[])

        # 从 draft 回填 trace 身份（writer 通常显式传，这里兜底）
-        if drafts:
-            user_id = user_id or drafts[0].user_id
-            agent_id = agent_id or drafts[0].agent_id
-            session_id = session_id or (drafts[0].session_id or "")
+        user_id = user_id or drafts[0].user_id
+        agent_id = agent_id or drafts[0].agent_id
+        session_id = session_id or (drafts[0].session_id or "")

        # 1. 检索 candidates
        candidates_per_draft: List[List[CodingMemory]] = await self._retrieve_candidates(drafts)
@@ -167,19 +211,20 @@ class CodingMemoryReconciler:
        _decide_prompt = ""
        _decide_raw = ""
        _decide_resp = None
+        failure: Optional[Tuple[str, str]] = None
+        ops: List[ReconcileOp] = []
        try:
            ops, _decide_prompt, _decide_raw, _decide_resp = await self._llm_decide(
                drafts, candidates_per_draft, language=language,
            )
+            failure = self._reply_failure(_decide_raw)
        except Exception as e:
-            logger.warning(f"[coding-reconcile] LLM decide failed, fallback to ADD-all: {e}")
-            ops = [ReconcileOp(action="ADD", draft_idx=i) for i in range(len(drafts))]
+            logger.warning(f"[coding-reconcile] LLM decide failed: {e}")
            _decide_raw = f"[LLM error] {type(e).__name__}: {str(e)[:300]}"
-
-        if not ops:
-            # LLM 输出无 ops，但有 drafts → fallback ADD-all
-            logger.info("[coding-reconcile] LLM returned no ops, fallback to ADD-all")
-            ops = [ReconcileOp(action="ADD", draft_idx=i) for i in range(len(drafts))]
+            failure = (
+                "LLM_UNAVAILABLE",
+                f"coding reconcile LLM call failed: {type(e).__name__}: {e}",
+            )

        _decide_elapsed = round((time.perf_counter() - _t0) * 1000, 2)
        # CODING_RECONCILE：LLM 决策完成即打点（执行入库之前，crash 不丢）
@@ -187,17 +232,42 @@ class CodingMemoryReconciler:
            self.cache, request_id=request_id, user_id=user_id, agent_id=agent_id,
            session_id=session_id, step="CODING_RECONCILE",
            prompt=_decide_prompt, response=_decide_raw,
-            parsed=json.dumps({"ops": [o.to_dict() for o in ops]}, ensure_ascii=False, default=str),
+            parsed=json.dumps(
+                {"error": failure[0], "message": failure[1], "stored": 0}
+                if failure else {"ops": [o.to_dict() for o in ops]},
+                ensure_ascii=False, default=str,
+            ),
            elapsed_ms=_decide_elapsed,
            prompt_tokens=getattr(_decide_resp, "prompt_tokens", 0) if _decide_resp else 0,
            completion_tokens=getattr(_decide_resp, "completion_tokens", 0) if _decide_resp else 0,
            total_tokens=getattr(_decide_resp, "tokens_used", 0) if _decide_resp else 0,
        )
+        if failure is not None:
+            code, message = failure
+            logger.warning(f"[coding-reconcile] {code}: {message}")
+            raise CodingWriteError("RECONCILE_FAILED", message, cause=code)

-        # 3. 校验 + 执行
-        executed = await self._execute(ops, drafts, candidates_per_draft)
+        return ExperienceReconcilePlan(
+            drafts=list(drafts),
+            candidates_per_draft=candidates_per_draft,
+            ops=ops,
+        )
+
+    async def apply(self, plan: ExperienceReconcilePlan) -> List[ReconcileOp]:
+        """执行 plan() 的决策（store ADD / UPDATE / DELETE）。"""
+        if not plan.drafts:
+            return []
+        if not plan.ops:
+            # 有效的 {"ops": []}：模型判定无需任何操作，本层什么都不存。
+            logger.info(
+                f"[coding-reconcile] drafts={len(plan.drafts)} LLM decided no ops"
+            )
+            return []
+        executed = await self._execute(
+            plan.ops, plan.drafts, plan.candidates_per_draft,
+        )
        logger.info(
-            f"[coding-reconcile] drafts={len(drafts)} ops={len(executed)} "
+            f"[coding-reconcile] drafts={len(plan.drafts)} ops={len(executed)} "
            + ", ".join(f"{a}={sum(1 for o in executed if o.action == a)}"
                        for a in ("ADD", "UPDATE", "DELETE", "SKIP"))
        )
@@ -316,11 +386,30 @@ class CodingMemoryReconciler:
            rows.append(f"for draft[{i}]:\n" + "\n".join(cand_rows))
        return "\n\n".join(rows) if rows else "(none)"

+    @classmethod
+    def _reply_failure(cls, text: Optional[str]) -> Optional[Tuple[str, str]]:
+        """回复本身是失败时返回 (cause, message)；有效回复（含 {"ops": []}）返回 None。"""
+        if not (text or "").strip():
+            return "EMPTY_RESPONSE", "coding reconcile LLM returned empty response"
+        obj = cls._load_object(text)
+        ops_raw = obj.get("ops") if isinstance(obj, dict) else None
+        if not isinstance(ops_raw, list):
+            return (
+                "JSON_PARSE_FAILED",
+                f"coding reconcile output has no ops list ({len(text)} chars)",
+            )
+        if ops_raw and not cls._parse_ops(text):
+            return (
+                "JSON_PARSE_FAILED",
+                f"coding reconcile output has no recognizable op ({len(text)} chars)",
+            )
+        return None
+
    @staticmethod
-    def _parse_ops(text: str) -> List[ReconcileOp]:
-        """宽松解析 ops 列表。"""
+    def _load_object(text: Optional[str]) -> Optional[Dict[str, Any]]:
+        """宽松解析出顶层 JSON 对象；解析不出返回 None。"""
        if not text:
-            return []
+            return None
        s = text.strip()
        # 去 markdown fence
        if s.startswith("```"):
@@ -344,8 +433,15 @@ class CodingMemoryReconciler:
                    obj = json.loads(s[start: end + 1])
                except Exception:
                    obj = None
+        return obj if isinstance(obj, dict) else None

-        if not obj or not isinstance(obj, dict):
+    @classmethod
+    def _parse_ops(cls, text: str) -> List[ReconcileOp]:
+        """宽松解析 ops 列表。"""
+        if not text:
+            return []
+        obj = cls._load_object(text)
+        if not obj:
            logger.warning(
                f"[coding-reconcile] failed to parse ops output ({len(text or '')} chars)"
            )
@@ -394,6 +490,9 @@ class CodingMemoryReconciler:
        - UPDATE  需 draft_idx 合法 + target_experience_id 非空
        - DELETE  需 target_experience_id 非空
        - SKIP    不执行任何 store 操作
+
+        向量化失败（CodingWriteError(EMBEDDING_FAILED)）不吞成「少执行一条」，
+        原样抛给 CodingWriter，整次写入报失败。
        """
        executed: List[ReconcileOp] = []
        # 已被 UPDATE 占用的 draft_idx → 防止同 draft 被重复 ADD/UPDATE
@@ -414,6 +513,8 @@ class CodingMemoryReconciler:
                    op.target_experience_id = memory.experience_id  # 回写 id 供 caller 读
                    executed.append(op)
                    consumed.add(op.draft_idx)
+                except CodingWriteError:
+                    raise
                except Exception as e:
                    logger.warning(f"[coding-reconcile] ADD failed: {e}")

@@ -444,6 +545,8 @@ class CodingMemoryReconciler:
                    await self.store.update(memory)
                    executed.append(op)
                    consumed.add(op.draft_idx)
+                except CodingWriteError:
+                    raise
                except Exception as e:
                    logger.warning(f"[coding-reconcile] UPDATE failed: {e}")

@@ -487,6 +590,8 @@ class CodingMemoryReconciler:
                    target_experience_id=memory.experience_id,
                    reason="fallback ADD (no LLM op)",
                ))
+            except CodingWriteError:
+                raise
            except Exception as e:
                logger.warning(f"[coding-reconcile] fallback ADD failed: {e}")

@@ -44,7 +44,7 @@ from ..data.vector_store import create_vector_store
 from ..data.vector_store_base import VectorStoreBase
 from ..models.memory import MemoryLayer, MemoryNode, MemoryStatus
 from ..utils.async_executor import run_in_executor_guarded
-from .types import CodingMemory, WorkingFact
+from .types import CodingMemory, CodingWriteError, WorkingFact

 logger = logging.getLogger(__name__)

@@ -599,10 +599,15 @@ class CodingMemoryStore:
    # ------------------------------------------------------------

    async def insert(self, memory: CodingMemory) -> None:
-        """新增一条 coding memory（SQLite + VDB 全套）"""
+        """新增一条 coding memory（SQLite + VDB 全套）。
+
+        先向量化再落 SQLite：向量化失败抛 CodingWriteError(EMBEDDING_FAILED)，
+        什么都不写，不留一条没有向量、永远检索不到的经验。
+        """
        self._fill_timestamps(memory)
+        embeddings = await self._embed_vec_keys(memory)
        await _run_in_pool(self._upsert_sql_sync, memory)
-        await self._upsert_vec_keys(memory)
+        await self._upsert_vec_keys(memory, embeddings=embeddings)
        logger.info(
            f"[coding-store] inserted experience_id={memory.experience_id} "
            f"keys={1 + len(memory.search_keys)}"
@@ -627,6 +632,8 @@ class CodingMemoryStore:
        ):
            raise ValueError("coding_memory_update_authority_mismatch")
        prev_key_count = 1 + len(prev.search_keys)
+        # 先向量化：失败时旧经验（SQLite 与向量行）原样保留，不改一个字。
+        embeddings = await self._embed_vec_keys(memory)

        memory.updated_at = datetime.utcnow()
        if memory.created_at is None:
@@ -637,7 +644,7 @@ class CodingMemoryStore:
        # 删旧 VDB
        await self._delete_vec_keys_by_count(memory.experience_id, prev_key_count)
        # 写新 VDB
-        await self._upsert_vec_keys(memory)
+        await self._upsert_vec_keys(memory, embeddings=embeddings)
        logger.info(
            f"[coding-store] updated experience_id={memory.experience_id} "
            f"old_keys={prev_key_count} new_keys={1 + len(memory.search_keys)}"
@@ -1000,12 +1007,22 @@ class CodingMemoryStore:
    # 事实层
    # ------------------------------------------------------------

-    async def insert_fact(self, fact: WorkingFact) -> None:
-        """新增一条事实（SQLite + 事实 collection 各一行）。"""
+    async def insert_fact(
+        self, fact: WorkingFact, embedding: Optional[List[float]] = None,
+    ) -> None:
+        """新增一条事实（SQLite + 事实 collection 各一行）。
+
+        embedding 可由调用方预先用 embed_fact() 算好（fact reconcile 要在覆盖旧
+        事实之前确认新事实能向量化）；不传时这里算。向量化失败抛
+        CodingWriteError(EMBEDDING_FAILED)，什么都不写。
+        """
        if fact.created_at is None:
            fact.created_at = datetime.utcnow()
+        # 先向量化再落 SQLite，理由同 insert()：不落没有向量的事实。
+        if embedding is None:
+            embedding = await self.embed_fact(fact)
        await _run_in_pool(self._upsert_fact_sql_sync, fact)
-        await self._upsert_fact_vec(fact)
+        await self._upsert_fact_vec(fact, embedding=embedding)
        logger.info(f"[coding-store] inserted fact_id={fact.fact_id}")
        logger.debug(
            f"[coding-store] inserted fact_id={fact.fact_id} "
@@ -1574,25 +1591,64 @@ class CodingMemoryStore:
    # VDB 实现
    # ------------------------------------------------------------

-    async def _upsert_vec_keys(self, memory: CodingMemory) -> None:
-        """把 task + search_keys 写入 VDB（每行一个 MemoryNode）。"""
-        if self._vec is None:
-            return
-
+    @staticmethod
+    def _vec_key_texts(memory: CodingMemory) -> List[Tuple[str, str]]:
        all_keys: List[Tuple[str, str]] = [("task", memory.task)]
        for k in memory.search_keys:
            if k:
                all_keys.append(("aspect", k))
+        return all_keys
+
+    async def _embed_vec_keys(
+        self, memory: CodingMemory
+    ) -> Optional[List[List[float]]]:
+        """写入链路用：向量化 task + search_keys，失败抛 CodingWriteError。
+
+        无 VDB 时返回 None（不需要向量）。
+        """
+        if self._vec is None:
+            return None
+        texts = [t for _, t in self._vec_key_texts(memory)]
+        try:
+            embeddings = await self.embed_service.embed_batch(texts)
+        except Exception as e:
+            logger.warning(f"[coding-store] embed_batch failed: {e}")
+            raise CodingWriteError(
+                "EMBEDDING_FAILED",
+                f"coding experience embedding failed: {type(e).__name__}: {e}",
+            ) from e
+        if len(embeddings or []) != len(texts) or not all(embeddings):
+            raise CodingWriteError(
+                "EMBEDDING_FAILED",
+                "coding experience embedding returned no vector",
+            )
+        return embeddings
+
+    async def _upsert_vec_keys(
+        self,
+        memory: CodingMemory,
+        embeddings: Optional[List[List[float]]] = None,
+    ) -> None:
+        """把 task + search_keys 写入 VDB（每行一个 MemoryNode）。
+
+        embeddings 由写入链路预先算好（见 _embed_vec_keys）；不传时现算，
+        失败只记 warning（edit_experience 的手动编辑路径沿用这一行为）。
+        """
+        if self._vec is None:
+            return
+
+        all_keys = self._vec_key_texts(memory)
        if not all_keys:
            return

        # batch embed
        texts = [t for _, t in all_keys]
-        try:
-            embeddings = await self.embed_service.embed_batch(texts)
-        except Exception as e:
-            logger.warning(f"[coding-store] embed_batch failed: {e}")
-            return
+        if embeddings is None:
+            try:
+                embeddings = await self.embed_service.embed_batch(texts)
+            except Exception as e:
+                logger.warning(f"[coding-store] embed_batch failed: {e}")
+                return

        nodes: List[MemoryNode] = []
        for i, ((kind, text), emb) in enumerate(zip(all_keys, embeddings)):
@@ -1623,7 +1679,34 @@ class CodingMemoryStore:
        except Exception as e:
            logger.warning(f"[coding-store] vdb upsert_batch failed: {e}")

-    async def _upsert_fact_vec(self, fact: WorkingFact) -> None:
+    @staticmethod
+    def _fact_vector_text(fact: WorkingFact) -> str:
+        return f"{fact.subject}: {fact.statement}" if fact.subject else fact.statement
+
+    async def embed_fact(self, fact: WorkingFact) -> Optional[List[float]]:
+        """写入链路用：向量化事实检索文本，失败抛 CodingWriteError。
+
+        无事实 VDB 或 statement 为空时返回 None（不需要向量）。
+        """
+        if self._fact_vec is None or not fact.statement:
+            return None
+        try:
+            embedding = await self.embed_service.embed(self._fact_vector_text(fact))
+        except Exception as e:
+            logger.warning(f"[coding-store] fact embed failed: {e}")
+            raise CodingWriteError(
+                "EMBEDDING_FAILED",
+                f"working fact embedding failed: {type(e).__name__}: {e}",
+            ) from e
+        if not embedding:
+            raise CodingWriteError(
+                "EMBEDDING_FAILED", "working fact embedding returned no vector",
+            )
+        return embedding
+
+    async def _upsert_fact_vec(
+        self, fact: WorkingFact, embedding: Optional[List[float]] = None,
+    ) -> None:
        """事实入向量库。一条事实一行，node_id 就是 fact_id。

        检索文本是 statement，前面缀上 subject（有的话）。subject 通常已经在
@@ -1634,14 +1717,14 @@ class CodingMemoryStore:
        """
        if self._fact_vec is None or not fact.statement:
            return
-        vector_text = (
-            f"{fact.subject}: {fact.statement}" if fact.subject else fact.statement
-        )
-        try:
-            embedding = await self.embed_service.embed(vector_text)
-        except Exception as e:
-            logger.warning(f"[coding-store] fact embed failed: {e}")
-            return
+        vector_text = self._fact_vector_text(fact)
+        if embedding is None:
+            # edit_fact 的手动编辑路径：现算，失败只记 warning。
+            try:
+                embedding = await self.embed_service.embed(vector_text)
+            except Exception as e:
+                logger.warning(f"[coding-store] fact embed failed: {e}")
+                return

        node = MemoryNode(
            node_id=fact.fact_id,
@@ -25,6 +25,25 @@ FactStatus = Literal["active", "superseded"]
 MAX_FACT_CHAIN_ENTRIES = 8


+class CodingWriteError(RuntimeError):
+    """working / coding 写入链路里让整次写入失败的模型错误。
+
+    error_code 是稳定失败码，CodingWriter 原样透传为 agent_error_code：
+    - LLM_ERROR          抽取 LLM 调用失败
+    - EMPTY_RESPONSE     抽取 LLM 返回 200 但 content 为空
+    - JSON_PARSE_FAILED  抽取 LLM 的回复解析不出 JSON 对象
+    - EMBEDDING_FAILED   经验 / 事实向量化失败（不落没有向量的节点）
+    - RECONCILE_FAILED   经验 / 事实 reconcile 的模型决策失败；具体原因在 cause
+                         （LLM_UNAVAILABLE / EMPTY_RESPONSE / JSON_PARSE_FAILED），
+                         透传为 reconcile_error_code，与 chat 链路一致
+    """
+
+    def __init__(self, error_code: str, message: str, cause: Optional[str] = None):
+        super().__init__(message)
+        self.error_code = error_code
+        self.cause = cause
+
+
 def _epoch(value: Optional[datetime]) -> Optional[int]:
    """memory_at 对外是秒级 epoch，与 chat 一致。"""
    return int(value.timestamp()) if isinstance(value, datetime) else None
@@ -10,8 +10,9 @@ CodingWriter - 写入端协调器
             ├── recent history: 最近 K 个 user-turn（只作上下文）
             ├── new messages: 本次全部 turn（只做单条限长）
             ├── extractor.extract(...)            ← 一次 LLM 产出双层草稿
-             ├── reconciler.reconcile(经验草稿)     ← ADD/UPDATE/DELETE/SKIP
-             ├── fact_reconciler.reconcile(事实草稿) ← INSERT/SUPERSEDE
+             ├── reconciler.plan(经验草稿)          ← ADD/UPDATE/DELETE/SKIP 决策
+             ├── fact_reconciler.plan(事实草稿)      ← INSERT/SUPERSEDE 决策
+             ├── reconciler.apply / fact_reconciler.apply ← 两层决策都成功后才落库
             └── _crosslink(...)                   ← 同批全互链回填
 """

@@ -30,7 +31,7 @@ from .judge import classify_messages_is_coding
 from .preproc import has_any_tool_message, prepare_extractor_messages
 from .reconciler import CodingMemoryReconciler
 from .store import CodingMemoryStore
-from .types import FactReconcileOp, ReconcileOp, WorkingFact
+from .types import CodingWriteError, FactReconcileOp, ReconcileOp, WorkingFact

 logger = logging.getLogger(__name__)

@@ -104,6 +105,13 @@ class CodingWriter:
                ],
                "fact_ids": ["..."],         # 这趟真正落库的 fact_id
            }
+
+        模型失败（抽取 LLM 调用失败 / 空回复 / 解析不出）或向量化失败时返回
+        success=False，agent_error_code 为 LLM_ERROR / EMPTY_RESPONSE /
+        JSON_PARSE_FAILED / EMBEDDING_FAILED，error_code=502。经验层 / 事实层
+        reconcile 的模型决策失败时 agent_error_code=RECONCILE_FAILED，原因在
+        reconcile_error_code（LLM_UNAVAILABLE / EMPTY_RESPONSE / JSON_PARSE_FAILED），
+        本次什么都不落库。模型答了但没有值得记的内容仍是 success=True、0 条。
        """
        request_id = request_id or str(uuid.uuid4())
        t0 = time.perf_counter()
@@ -143,6 +151,10 @@ class CodingWriter:
        # 跟库里已有的什么关系是 reconcile 的事。把已有 task 摆到它面前，它会把
        # 一个其实不同的任务往清单里某个措辞上靠，reconciler 随后判成 UPDATE 合并
        # 掉，那个区别就没了——措辞对不上顶多多存一条，措辞被带偏是直接写错。
+        #
+        # 模型失败（LLM 调用失败 / 空回复 / 解析不出）抛 CodingWriteError：整次写入
+        # 报失败、什么都不存，连 trace 也不追加——调用方换个 request_id 重跑时，
+        # 历史窗口里不会多出这段本该是「新消息」的对话。
        try:
            drafts, fact_drafts = await self.extractor.extract(
                messages,
@@ -156,26 +168,26 @@ class CodingWriter:
                request_id=request_id,
                language=language,
            )
-        finally:
-            # 历史服务于下一次 write；即使本次没跨过价值门槛，也不能丢掉上下文。
-            try:
-                await self.store.append_trace(
-                    current_messages,
-                    request_id=request_id,
-                    user_id=user_id,
-                    agent_id=agent_id or "default_agent",
-                    session_id=session_id,
-                    workspace_id=workspace_id,
-                    branch=branch,
-                    source=source,
-                )
-            except Exception as e:
-                logger.warning(f"[coding-write] append trace failed: {e}")
+        except CodingWriteError as e:
+            return self._failure_response(request_id, t0, e)
+
+        trace_kwargs = dict(
+            request_id=request_id,
+            user_id=user_id,
+            agent_id=agent_id or "default_agent",
+            session_id=session_id,
+            workspace_id=workspace_id,
+            branch=branch,
+            source=source,
+        )

        if not drafts and not fact_drafts:
+            # 模型答了、只是没有值得记的：正常的空抽取，仍算成功。历史服务于下一次
+            # write；即使本次没跨过价值门槛，也不能丢掉上下文。
            logger.info(
                f"[coding-write] no drafts produced (value bar); request_id={request_id}"
            )
+            await self._append_trace(current_messages, **trace_kwargs)
            return self._empty_response(request_id, t0)

        # extractor 只负责内容；调用来源由 SDK 入口注入，不能交给 LLM 生成。
@@ -183,34 +195,51 @@ class CodingWriter:
            draft.source = source
            draft.memory_at = memory_at

-        # 3. 经验层 reconcile + 持久化
-        ops: List[ReconcileOp] = (
-            await self.reconciler.reconcile(
-                drafts,
-                request_id=request_id,
-                user_id=user_id,
-                agent_id=agent_id,
-                session_id=session_id or "",
-                language=language,
-            )
-            if drafts else []
-        )
-
-        # 4. 事实层 reconcile + 持久化（独立链路，不受经验层结果影响）
+        # 3. 两层 reconcile 的模型决策（只检索 + 调 LLM，不落库）
+        # 4. 两层决策都成功后才落库：经验层 apply → 事实层 apply
+        #
+        # 先把所有模型决策做完再写库，任何一层的决策失败（LLM 失败 / 空回复 /
+        # 解析不出 → CodingWriteError(RECONCILE_FAILED)）都发生在落库之前，本次
+        # 写入一条经验 / 事实都没存、也没覆盖旧事实，换个 request_id 重跑即干净。
+        # 两层决策互不依赖（各自检索各自的候选），提前做不改变结果。
+        #
+        # 向量化失败抛 CodingWriteError(EMBEDDING_FAILED)：不落没有向量的节点，
+        # 整次写入报失败。
        facts: List[WorkingFact] = []
        fact_ops: List[FactReconcileOp] = []
-        if fact_drafts:
-            facts, fact_ops = await self.fact_reconciler.reconcile(
-                fact_drafts,
-                user_id=user_id,
-                agent_id=agent_id,
-                session_id=session_id,
-                workspace_id=workspace_id,
-                branch=branch,
-                source=source,
-                memory_at=memory_at,
-                language=language,
+        ops: List[ReconcileOp] = []
+        try:
+            experience_plan = (
+                await self.reconciler.plan(
+                    drafts,
+                    request_id=request_id,
+                    user_id=user_id,
+                    agent_id=agent_id,
+                    session_id=session_id or "",
+                    language=language,
+                )
+                if drafts else None
            )
+            fact_plan = (
+                await self.fact_reconciler.plan(
+                    fact_drafts,
+                    user_id=user_id,
+                    agent_id=agent_id,
+                    session_id=session_id,
+                    workspace_id=workspace_id,
+                    branch=branch,
+                    source=source,
+                    memory_at=memory_at,
+                    language=language,
+                )
+                if fact_drafts else None
+            )
+            if experience_plan is not None:
+                ops = await self.reconciler.apply(experience_plan)
+            if fact_plan is not None:
+                facts, fact_ops = await self.fact_reconciler.apply(fact_plan)
+        except CodingWriteError as e:
+            return self._failure_response(request_id, t0, e)

        experience_ids = [op.target_experience_id for op in ops
                          if op.action in ("ADD", "UPDATE") and op.target_experience_id]
@@ -218,6 +247,7 @@ class CodingWriter:

        # 5. 同批全互链
        await self._crosslink(experience_ids, facts, user_id=user_id)
+        await self._append_trace(current_messages, **trace_kwargs)

        add_cnt = sum(1 for op in ops if op.action == "ADD")
        update_cnt = sum(1 for op in ops if op.action == "UPDATE")
@@ -298,6 +328,41 @@ class CodingWriter:
                        f"[coding-write] crosslink fact {f.fact_id} failed: {e}"
                    )

+    async def _append_trace(self, current_messages: List[ChatMessage], **kwargs) -> None:
+        """把本次对话追加进 recent trace（下一次 write 的历史上下文），best-effort。"""
+        try:
+            await self.store.append_trace(current_messages, **kwargs)
+        except Exception as e:
+            logger.warning(f"[coding-write] append trace failed: {e}")
+
+    def _failure_response(
+        self, request_id: str, t0: float, error: CodingWriteError,
+    ) -> Dict[str, Any]:
+        """模型 / 向量化失败：success=False，稳定失败码在 agent_error_code。
+
+        形状与 chat 链路的失败回执一致（error_code=502，error_message 带
+        「[CODE] 」前缀），调用方据 success 判定并重跑。
+        """
+        code = error.error_code
+        cause = getattr(error, "cause", None)
+        message = f"{cause}: {error}" if cause else str(error)
+        logger.warning(
+            f"[coding-write] failed: code={code} request_id={request_id}: {message}"
+        )
+        resp = self._empty_response(request_id, t0)
+        resp.update({
+            "success": False,
+            "error_code": 502,
+            "error_message": f"[{code}] {message}",
+            "agent_status": "failed",
+            "agent_error_code": code,
+            "agent_error": message,
+        })
+        if cause:
+            # 与 chat 链路一致：reconcile 失败的具体原因
+            resp["reconcile_error_code"] = cause
+        return resp
+
    def _empty_response(self, request_id: str, t0: float) -> Dict[str, Any]:
        return {
            "success": True,
@@ -432,6 +432,14 @@ class RecallConfig:
    retrieval_clauses_require_keyword: bool = None  # env: MEMORY_RETRIEVAL_CLAUSES_REQUIRE_KEYWORD
    retrieval_clauses_min_keyword_score: float = None  # normalized BM25 floor
    supplemental_propositions_enabled: bool = None  # env: MEMORY_SUPPLEMENTAL_PROPOSITIONS_ENABLED
+    # ── Intention（L7）判重 ──
+    # 开启（默认）：召回时同 user+agent+同天 memory_at+同 valid_until 且
+    # cosine≥阈值 的意图视为复本，只返回最早一条，其余异步从 VDB 删除（历史行为）。
+    # 关闭：读侧与写入侧批内都不判重——不隐藏、不丢弃、不删除任何意图。
+    intention_dedup_enabled: bool = None       # env: MEMORY_INTENTION_DEDUP_ENABLED
+    # 读侧意图判重 cosine 阈值。env: MEMORY_INTENTION_DEDUP_THRESHOLD，
+    # 未设置时回退到共享的 MEMORY_DEDUP_THRESHOLD（兼容旧部署），默认 0.95。
+    intention_dedup_threshold: float = None

    # 最小分数阈值
    min_score_threshold: float = 0.0
@@ -750,6 +758,15 @@ class RecallConfig:
            self.supplemental_propositions_enabled = _get_env_bool(
                "MEMORY_SUPPLEMENTAL_PROPOSITIONS_ENABLED", False
            )
+        if self.intention_dedup_enabled is None:
+            self.intention_dedup_enabled = _get_env_bool(
+                "MEMORY_INTENTION_DEDUP_ENABLED", True
+            )
+        if self.intention_dedup_threshold is None:
+            self.intention_dedup_threshold = _get_env_float(
+                "MEMORY_INTENTION_DEDUP_THRESHOLD",
+                _get_env_float("MEMORY_DEDUP_THRESHOLD", 0.95),
+            )


@dataclass
@@ -1384,6 +1401,8 @@ class MemoryConfig:
                "supplemental_propositions_enabled": (
                    self.recall.supplemental_propositions_enabled
                ),
+                "intention_dedup_enabled": self.recall.intention_dedup_enabled,
+                "intention_dedup_threshold": self.recall.intention_dedup_threshold,
            },
            "pipeline": {
                "default_version": self.pipeline.default_version,
@@ -15,6 +15,9 @@ HY Memory - Intention (L7) 召回 + 惰性过期转换 + 复本判定
    → 视为同一个意图的复本（extractor 复读机 / 多 session 重复表达）。
    保留组里 `gmt_created` 最早的（老的先来先得，稳定 id）；
  - **异步删库**：其余复本 fire-and-forget 从 VDB 删除，不影响本次调用 RT。
+  - **开关**：判重受 `MemoryConfig.recall.intention_dedup_enabled`（默认开）与
+    `recall.intention_dedup_threshold` 控制，由 reader 按 client 配置传入。
+    关闭时完全跳过判重：不隐藏、不删除任何意图（写入侧批内判重同样跳过）。

 Q: 为什么要看 memory_at 和 valid_until？
 A: 意图是 point-in-time 信号。同一句"我周五要开会"，如果一条 memory_at 在
@@ -38,8 +41,14 @@ from ...models.memory import MemoryLayer, MemoryStatus
 logger = logging.getLogger(__name__)


-def _get_dedup_threshold() -> float:
-    """去重 cosine 阈值：沿用 dedup 内核的 MEMORY_DEDUP_THRESHOLD，默认 0.95。"""
+def _get_dedup_threshold(configured: Optional[float] = None) -> float:
+    """去重 cosine 阈值：优先用 client 配置；否则（或配置非法）沿用 dedup 内核的
+    MEMORY_DEDUP_THRESHOLD，默认 0.95。"""
+    try:
+        if configured is not None:
+            return float(configured)
+    except (TypeError, ValueError):
+        logger.warning(f"[intention] invalid dedup threshold: {configured!r}")
    try:
        return float(os.environ.get("MEMORY_DEDUP_THRESHOLD", 0.95))
    except (TypeError, ValueError):
@@ -244,6 +253,8 @@ async def recall_intentions(
    stats_out: Optional[Dict[str, Any]] = None,
    include_sources: Optional[List[str]] = None,
    exclude_sources: Optional[List[str]] = None,
+    dedup_enabled: bool = True,
+    dedup_threshold: Optional[float] = None,
 ) -> List[Dict[str, Any]]:
    """
    召回未过期的 L7_INTENTION 节点（VDB），惰性过期转 L2_FACT，判重并异步删复本。
@@ -260,6 +271,11 @@ async def recall_intentions(
        now: 当前时间（默认 datetime.now()，测试可注入）
        stats_out: 可选 dict，本函数把分段耗时与数量**原地回填**进去，供调用方落
            READ_INTENTION pipeline log。传 None 则完全不统计（零开销）。
+        dedup_enabled: 是否执行读侧判重（及复本异步删库）。False 时跳过判重，
+            所有未过期意图原样返回，不删除任何节点。默认 True（历史行为）。
+        dedup_threshold: 判重 cosine 阈值。None 时回退到 env
+            MEMORY_DEDUP_THRESHOLD（默认 0.95），兼容直接调用本函数的旧代码；
+            reader 总是传入 `recall.intention_dedup_threshold`。

    Returns:
        [{"node_id", "score", "node", "layer": "l7_intention", "source": "vdb_intention"}, ...]
@@ -272,7 +288,7 @@ async def recall_intentions(
    埋点字段（回填进 stats_out）:
      耗时(ms): vdb_search_ms / expire_ms / backfill_embed_ms / dedup_ms / total_ms
      数量: fetched / expired / survivors / dedup_dropped / returned
-      配置: fetch_limit / out_limit / dedup_threshold
+      配置: fetch_limit / out_limit / dedup_enabled / dedup_threshold
      说明: expire_ms、backfill_embed_ms 只有真的发生了对应操作才非 0，
            借此可判断慢在 VDB 检索、逐条过期转换、补拉向量还是判重计算。
    """
@@ -358,7 +374,7 @@ async def recall_intentions(
    _t = time.perf_counter()
    _backfilled = 0
    _missing_cnt = 0
-    if survivors:
+    if survivors and dedup_enabled:  # 补拉只为判重；关闭时无需这次 VDB 读
        missing_ids = [
            h.get("node_id") for h in survivors
            if h.get("node_id") and not getattr(h.get("node"), "embedding", None)
@@ -391,18 +407,23 @@ async def recall_intentions(
    )

    # 2. 判重：同 user + 同天 memory_at + valid_until 同日 + cosine≥threshold
+    #    dedup_enabled=False → 完全跳过：不隐藏、不删除。
    _t = time.perf_counter()
-    threshold = _get_dedup_threshold()
-    try:
-        kept, delete_ids = _partition_duplicates(survivors, threshold)
-    except Exception as e:
-        # 任何 dedup 异常 → 降级为不去重（返回全部 survivors 截断 limit）
-        logger.warning(f"[intention] dedup partition failed, degrade to raw: {e}")
+    threshold = _get_dedup_threshold(dedup_threshold)
+    if dedup_enabled:
+        try:
+            kept, delete_ids = _partition_duplicates(survivors, threshold)
+        except Exception as e:
+            # 任何 dedup 异常 → 降级为不去重（返回全部 survivors 截断 limit）
+            logger.warning(f"[intention] dedup partition failed, degrade to raw: {e}")
+            kept, delete_ids = survivors, []
+    else:
        kept, delete_ids = survivors, []
    # 纯 CPU（cosine 两两比较）；survivors 多时可能显著
    _stat(
        dedup_ms=round((time.perf_counter() - _t) * 1000, 2),
        dedup_dropped=len(delete_ids),
+        dedup_enabled=bool(dedup_enabled),
        dedup_threshold=threshold,
    )

@@ -1856,6 +1856,12 @@ class BaseReadPipeline(ReadPipeline):
                    stats_out=_intent_stats,
                    include_sources=request.include_sources,
                    exclude_sources=request.exclude_sources,
+                    dedup_enabled=bool(getattr(
+                        self.config.recall, "intention_dedup_enabled", True
+                    )),
+                    dedup_threshold=getattr(
+                        self.config.recall, "intention_dedup_threshold", None
+                    ),
                )
                await trace_log.log_intention(
                    stats=_intent_stats,
@@ -73,6 +73,19 @@ def _write_apply_verify_enabled() -> bool:
 _RECONCILE_LOOP_USER_LOCKS = weakref.WeakKeyDictionary()


+class ReconcileFailure(str):
+    """reconcile 失败时 `_reconcile_and_store` 返回的 error：仍是错误信息字符串，
+    另带稳定的失败码 `code`（LLM_UNAVAILABLE / EMPTY_RESPONSE / JSON_PARSE_FAILED /
+    RECONCILE_EXCEPTION），供 writer 透传给调用方。"""
+
+    code: str = "RECONCILE_FAILED"
+
+    def __new__(cls, message: str, code: str = "RECONCILE_FAILED"):
+        obj = super().__new__(cls, message)
+        obj.code = code
+        return obj
+
+
 def _reconcile_user_lock(user_id: str) -> asyncio.Lock:
    loop = asyncio.get_running_loop()
    locks = _RECONCILE_LOOP_USER_LOCKS.get(loop)
@@ -635,6 +648,7 @@ class MemoryWriter(WritePipeline):
        不查 VDB、不做"新写入 vs 库里已有"的对比，避免给 VDB 增加读压力。
        库内存量污染由 recall 侧异步删除逐步清理。best-effort：任何异常都
        回退到"不判重、全写入"，绝不影响 upsert 主流程。
+        `recall.intention_dedup_enabled=False` 时跳过批内判重，全部写入。
        """
        if not intentions:
            return []
@@ -660,7 +674,11 @@ class MemoryWriter(WritePipeline):
        # ============ 批内 dedup（不查 VDB，只对本批 intentions 互斥判重） ============
        keep_mask: List[bool] = [True] * len(intentions)
        try:
-            dropped = self._intention_batch_dedup(intentions, embeddings)
+            dropped = (
+                self._intention_batch_dedup(intentions, embeddings)
+                if getattr(self.config.recall, "intention_dedup_enabled", True)
+                else []
+            )
            for i in dropped:
                if 0 <= i < len(keep_mask):
                    keep_mask[i] = False
@@ -1257,15 +1275,6 @@ class MemoryWriter(WritePipeline):
            recon_tokens 含 prompt/completion/total（reconcile 链路 LLM 消耗）
        """
        stored_ids: List[str] = []
-        # Episode：本次写入归属的内部会话 id（跨 write 把"一件事"归到一起）。
-        # 只数 user 侧记忆（与 rolling summary 只数 pending_user_count 一致）——
-        # agent 侧记忆若参与计数会把 episode 提前撑到上限、切得过碎，白付摘要的 token。
-        episode_id = await self._resolve_episode_id(
-            request, _count_user_owned(new_memories_meta)
-        )
-        session_episode_id = self._session_episode_id(request)
-        if session_episode_id:
-            episode_id = session_episode_id
        # 关系图用：收集本次落库的 (node, op)，供 graph 投影建边。
        # 收 op 是为了拿 op.related（LLM 标注的 typed 关系）。
        graph_payload: List[Tuple[Any, Any]] = []
@@ -1292,7 +1301,32 @@ class MemoryWriter(WritePipeline):
        )

        if not recon_result.success:
-            return [], recon_result.error, {"add": 0, "supersede": 0, "update": 0, "total": 0}, {"prompt": 0, "completion": 0, "total": 0}
+            # reconcile 失败：本次一条新记忆都不落库（不做 ADD-all 兜底），由调用方重跑。
+            # episode 状态也还没推进，重跑不会把同一批记忆重复计数。
+            error = ReconcileFailure(
+                recon_result.error or "reconcile failed",
+                code=recon_result.error_code or "RECONCILE_FAILED",
+            )
+            logger.warning(
+                f"TRACE_PERF [{req_id}] S1_RECONCILE_FAILED "
+                f"code={error.code} candidates={len(new_memory_texts)} stored=0"
+            )
+            return [], error, {"add": 0, "supersede": 0, "update": 0, "total": 0}, {
+                "prompt": recon_result.prompt_tokens,
+                "completion": recon_result.completion_tokens,
+                "total": recon_result.total_tokens,
+            }
+
+        # Episode：本次写入归属的内部会话 id（跨 write 把"一件事"归到一起）。
+        # 只数 user 侧记忆（与 rolling summary 只数 pending_user_count 一致）——
+        # agent 侧记忆若参与计数会把 episode 提前撑到上限、切得过碎，白付摘要的 token。
+        # 放在 reconcile 成功之后：失败的写入不能推进 episode 计数。
+        episode_id = await self._resolve_episode_id(
+            request, _count_user_owned(new_memories_meta)
+        )
+        session_episode_id = self._session_episode_id(request)
+        if session_episode_id:
+            episode_id = session_episode_id

        # 分类统计
        _op_counts = {}
@@ -1303,16 +1337,7 @@ class MemoryWriter(WritePipeline):
        logger.info(
            f"TRACE_PERF [{req_id}] S1_RECONCILE_DONE "
            f"ops={len(recon_result.ops)} candidates={len(new_memory_texts)} | {_op_counts_str}"
-            + (f" | DEGRADED({recon_result.degraded_reason})"
-               if getattr(recon_result, "degraded", False) else "")
        )
-        if getattr(recon_result, "degraded", False):
-            # 走了 ADD-all 兜底：内容保住了，但没做去重/演化判定。必须可观测，
-            # 否则线上只会看到"记忆变多了"而不知道为什么。
-            logger.warning(
-                f"[write] reconcile degraded → ADD-all "
-                f"({recon_result.degraded_reason}), {len(recon_result.ops)} memories stored as-is"
-            )
        # 逐条 op 详情由 reconciler 的 "[reconciler] ops detail" 单条 JSON list 输出，
        # 这里不再逐条打印（避免重复刷屏）。

@@ -2502,12 +2527,10 @@ class MemoryWriter(WritePipeline):
            response.extra["extract_tokens"] = {"prompt": 0, "completion": 0, "total": 0}

            if recon_error is not None:
-                response.success = False
-                response.error_code = 502
-                response.error_message = f"[RECONCILE_FAILED] {recon_error}"
-                response.extra["agent_status"] = "failed"
-                response.extra["agent_error"] = recon_error
-                response.extra["agent_nodes"] = 0
+                # 与 write() 一致：reconcile 失败不落任何记忆，报失败供调用方重跑。
+                self._mark_reconcile_failure(response, recon_error)
+                response.extra["agent_mode"] = "extracted"
+                logger.warning(f"[write_extracted] reconcile failed: {recon_error}")
                return response

            response.success = True
@@ -3526,12 +3549,11 @@ class MemoryWriter(WritePipeline):
                response.extra["reconcile_ops"] = ops_counts
                response.extra["reconcile_tokens"] = recon_tokens
                if recon_error is not None:
+                    # stored_ids 为空：reconcile 失败时一条新记忆都不落库，write()
+                    # 随后回滚 L1_RAW（retry_safe=True），换个 request_id 重跑即可。
                    response.extra["agent_stored_ids"] = stored_ids
-                    self._mark_agent_failure(
-                        response,
-                        error_code="RECONCILE_FAILED",
-                        error_message=recon_error,
-                        agent_nodes=len(stored_ids),
+                    self._mark_reconcile_failure(
+                        response, recon_error, agent_nodes=len(stored_ids),
                    )
                    logger.warning(f"[write] reconcile failed: {recon_error}")
                    return
@@ -3654,6 +3676,29 @@ class MemoryWriter(WritePipeline):
        response.error_code = 502
        response.error_message = f"[{code}] {message}"

+    @classmethod
+    def _mark_reconcile_failure(
+        cls,
+        response: WriteResponse,
+        recon_error: str,
+        *,
+        agent_nodes: int = 0,
+    ) -> None:
+        """reconcile 失败：agent_error_code 恒为 RECONCILE_FAILED，具体原因
+        （LLM_UNAVAILABLE / EMPTY_RESPONSE / JSON_PARSE_FAILED / RECONCILE_EXCEPTION）
+        放在 reconcile_error_code。"""
+        reason = getattr(recon_error, "code", "") or "RECONCILE_FAILED"
+        response.extra["reconcile_error_code"] = reason
+        cls._mark_agent_failure(
+            response,
+            error_code="RECONCILE_FAILED",
+            error_message=(
+                f"{reason}: {recon_error}"
+                if reason != "RECONCILE_FAILED" else str(recon_error)
+            ),
+            agent_nodes=agent_nodes,
+        )
+
    async def _handle_agent_failure(self, request, response, agent_result, tracer_span, extract_timing: Optional[Dict[str, Any]] = None) -> None:
        """处理 agent extract 失败的情况。"""
        if agent_result is None:
@@ -137,6 +137,15 @@ memhub profile
 `user-profile` / `memhub profile` 调用 SDK `get_user_profile()`，返回组装后的
 用户长期画像，不通过普通 Search 拼装。

+读接口都回显 `user_id`（实际读的用户，未指定时为 `local`）：
+`GET /api/v2/memory-library`、`/memory-library/layers`、`/user-profile`、
+`/user-profile/versions`、`/home-summary`、`/memories/graph`、`/raw`，
+`POST /api/v2/context/search`、`/api/v1/recall`、`/api/v2/memories/ask`；
+`/memories/ask/stream` 写在第一个 `recall` 事件上。
+`DELETE /api/v2/memories/{id}` 只在删掉调用者自己的记忆时回 204；另一个用户的
+记忆和不存在的 ID 一律回 404 `memory_not_found`（不暴露是否存在），调用方按
+「已不存在」处理。
+
 返回值：

 ```python
@@ -18,8 +18,8 @@ If you run into a problem, please open an Issue with the version, platform,repro

 ## 发行与平台合同

-源码当前固定使用公开 PyPI 正式版 `hy-memory==2.0.11`。MemHub 源码版本为 `1.0.6`
-（build 37），GitHub 仓库为
+源码当前固定使用公开 PyPI 正式版 `hy-memory==2.0.14`。MemHub 源码版本为 `1.0.6`
+（build 44），GitHub 仓库为
 [`Tencent-Hunyuan/Hy-Memory`](https://github.com/Tencent-Hunyuan/Hy-Memory)，npm 包名为
 `memhub-cli`。当前代码架构见
 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。
@@ -118,7 +118,7 @@ MemHub 的 SQLite 数据默认位于 `~/.one-memory`，不在 npm 包或 Runtime

 ## Hy Memory

-SDK 依赖固定为公开 PyPI 正式版 `hy-memory==2.0.11`。SDK 配置、权限边界及 search
+SDK 依赖固定为公开 PyPI 正式版 `hy-memory==2.0.14`。SDK 配置、权限边界及 search
 返回格式见 [`MEMORY.md`](MEMORY.md)。HY search 返回的 `content` 已包含 SDK 统一生成的
 逻辑时间和演化上下文；调用方不应再次转换时间戳或重复拼接 `When`。

@@ -2352,7 +2352,7 @@
    {
      "SPDXID": "SPDXRef-Package-hy-memory",
      "name": "hy-memory",
-      "versionInfo": "2.0.11",
+      "versionInfo": "2.0.14",
      "downloadLocation": "NOASSERTION",
      "filesAnalyzed": false,
      "licenseConcluded": "Apache-2.0",
@@ -9,7 +9,7 @@ Per-package license texts are not reproduced here yet; the license
 column is filled in as part of release review, and the SBOM records
 `NOASSERTION` until then rather than guessing.

-## hy-memory 2.0.11
+## hy-memory 2.0.14

 License: Apache-2.0

@@ -1938,7 +1938,7 @@ async function runCommand(
      return reject(
        descriptor,
        asJson,
-        "--user-id 和 --root 只能用于接入单个 hermes 来源（Hermes profile），用户 ID 只能是 1–64 位字母、数字、点、下划线或连字符。",
+        "--user-id 和 --root 只能用于接入单个 hermes 来源（Hermes profile），用户 ID 只能是 1–64 位字母、数字、点、下划线或连字符。用户 ID 不必等于 Hermes profile 名，例如 --user-id wife-work --root ~/.hermes/profiles/wife:work。",
      );
    }
    if (!parsed) return usage();
@@ -2328,29 +2328,41 @@ async function runCommand(
              ...userIdParameters(userId),
            }),
          );
+    // A delete answered 404 `memory_not_found` is already gone (deleted
+    // before, or never this user's): what was asked for holds, so it exits 0
+    // as committed and says so, instead of failing a retry or a double run.
+    const alreadyGone =
+      parsed.kind === "delete" &&
+      outcome.state === "rejected" &&
+      outcome.code === "memory_not_found";
+    const state = alreadyGone ? "committed" : outcome.state;
    const document = {
      schema_version: 2,
      product: PRODUCT,
      command: `memories ${parsed.kind}`,
-      state: outcome.state,
+      state,
      operation: parsed.kind,
      memory_id: parsed.memoryId,
-      ...(outcome.state === "committed"
-        ? parsed.kind === "update"
-          ? { result: outcome.data }
-          : {}
-        : { code: outcome.code }),
+      ...(alreadyGone
+        ? { already_gone: true }
+        : outcome.state === "committed"
+          ? parsed.kind === "update"
+            ? { result: outcome.data }
+            : {}
+          : { code: outcome.code }),
    };
    emit(
      asJson
        ? `${JSON.stringify(document)}\n`
-        : outcome.state === "committed"
-          ? `已${parsed.kind === "update" ? "更新" : "删除"}记忆 ${parsed.memoryId}\n`
-          : outcome.code === "memory_id_ambiguous"
-            ? "这个 ID 同时存在于多个场景；请加 --kind（以及 --variant）指明是哪一条。\n"
-            : `操作失败：${outcome.code}\n`,
+        : alreadyGone
+          ? `未找到记忆 ${parsed.memoryId}（可能已删除），无需再删。\n`
+          : outcome.state === "committed"
+            ? `已${parsed.kind === "update" ? "更新" : "删除"}记忆 ${parsed.memoryId}\n`
+            : outcome.code === "memory_id_ambiguous"
+              ? "这个 ID 同时存在于多个场景；请加 --kind（以及 --variant）指明是哪一条。\n"
+              : `操作失败：${outcome.code}\n`,
    );
-    return outcome.state === "committed" ? EXIT_OK : EXIT_FAILED;
+    return state === "committed" ? EXIT_OK : EXIT_FAILED;
  }
  if (
    named === "settings" &&
@@ -4371,6 +4383,10 @@ function renderWriteReceiptText(receipt: MemoryWriteReceipt): string {
    ...(receipt.memory_ids && receipt.memory_ids.length > 0
      ? [`memory_ids: ${receipt.memory_ids.join(",")}`]
      : []),
+    ...(receipt.error_code ? [`error_code: ${receipt.error_code}`] : []),
+    ...(receipt.next_retry_at
+      ? [`next_retry_at: ${receipt.next_retry_at}`]
+      : []),
    "",
  ].join("\n");
 }
@@ -258,7 +258,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
  {
    name: "sources",
    summary:
-      "列出来源，直接接入来源，或按 request id 查接入回执。connect 不加 --import 只授权（处理保持冻结：不导入历史、不扫描新会话）；加 --import 同时导入历史并开启持续同步，返回 request id。目录来自环境变量覆盖的来源必须加 --confirm-overrides。Hermes 的每个 profile 是一个独立用户：用 --user-id 和 --root 接入，授权并导入历史（会自动排除 ~/.hermes/profiles/**，各用户互不读取）。",
+      "列出来源，直接接入来源，或按 request id 查接入回执。connect 不加 --import 只授权（处理保持冻结：不导入历史、不扫描新会话）；加 --import 同时导入历史并开启持续同步，返回 request id。目录来自环境变量覆盖的来源必须加 --confirm-overrides。Hermes 的每个 profile 是一个独立用户：用 --user-id 和 --root 接入，授权并导入历史（任何层级的 profiles/ 目录都会被排除，各用户互不读取）。--root 不能是 profiles 目录本身，也不能与另一个用户的 Hermes 目录相同或互相包含（~/.hermes 与 ~/.hermes/profiles/<name> 除外）。",
    usage:
      "memhub sources list [--json]\n            memhub sources connect <id> [<id> ...] [--import] [--confirm-overrides] [--request-id <uuid>] [--json]\n            memhub sources connect hermes --user-id <id> --root <path> [--import] [--request-id <uuid>] [--json]\n            memhub sources connect --all-detected [--import] [--confirm-overrides] [--json]\n            memhub sources receipt <request-id> [--json]",
    options: [
@@ -270,7 +270,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
      {
        flag: "--user-id <id>",
        summary:
-          "只用于 hermes：这条接入属于哪个用户（默认 local）。和 --root 一起接入一个 Hermes profile，例如 --user-id wife --root ~/.hermes/profiles/wife；其他来源只能是 local。",
+          "只用于 hermes：这条接入属于哪个用户（默认 local）。和 --root 一起接入一个 Hermes profile，例如 --user-id wife --root ~/.hermes/profiles/wife；用户 ID 不必等于 profile 名，例如 --user-id wife-work --root ~/.hermes/profiles/wife:work。其他来源只能是 local。",
      },
      {
        flag: "--root <path>",
@@ -397,7 +397,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
  {
    name: "memories",
    summary:
-      "列出、搜索、查看、添加、修改或物理删除记忆（对话、工作、编码三个场景）。add 和 App 的「添加记忆」是同一个入口；delete 不可逆，需 --yes。",
+      "列出、搜索、查看、添加、修改或物理删除记忆（对话、工作、编码三个场景）。add 和 App 的「添加记忆」是同一个入口；delete 不可逆，需 --yes；要删的记忆已不存在（或不属于该用户）时提示未找到，按已删除处理并退出 0。",
    usage:
      "memhub memories list [--scene <all|chat|working|coding>] [--source <id>] [--query <text>] [--status <state>] [--offset <n>] [--limit <n>] [--user-id <id>] [--json]\n            memhub memories show <memory-id> [--kind <kind>] [--variant <variant>] [--user-id <id>] [--json]\n            memhub memories add <text> [--request-id <uuid>] [--user-id <id>] [--json]\n            memhub memories add --content-file <path> [--request-id <uuid>] [--user-id <id>] [--json]\n            memhub memories add-status <request-id> [--user-id <id>] [--json]\n            memhub memories update <memory-id> --content-file <path> [--kind <kind>] [--variant <variant>] [--task <text>] [--user-id <id>] [--json]\n            memhub memories delete <memory-id> [--kind <kind>] [--variant <variant>] [--yes] [--user-id <id>] [--json]",
    options: [
@@ -461,11 +461,12 @@ export const COMMANDS: readonly CommandDescriptor[] = [
  {
    name: "settings",
    summary:
-      "查看或切换记忆模式（lite / pro / ultra）。lite 不调用模型，只在原始对话里检索；pro 由模型提取记忆（System 1）；ultra 在 pro 之上每晚自动进化（System 2，使用知识图谱）。任何模式都保留全部原始对话。切换不迁移数据：已处理的不会重做，排队中的和新的按新模式处理；需 --yes，不加时只显示计划。环境变量 ONE_MEMORY_GRAPH_STORE 会强制 ultra。settings features 查看或开关 SDK 的可选检索与提取功能（全局设置，默认全部保持 SDK 默认值）：graph_rerank 图谱重排（仅 ultra）、same_series_timeline 同系列时间线（需 graph_rerank）、episode_recall 片段召回（pro / ultra，需先开 session_episodes 写入片段）、session_episodes 片段写入、episode_summary 片段摘要（每个片段一次模型调用）、intention 意图提取（默认开）、few_shot 提取示例；set 需 --yes，不加时只显示计划；reset 恢复默认值。settings language 查看或设置界面语言（App 切换语言时会自动设置）：简体中文（zh-Hans）和 system 不指定 SDK 语言，SDK 照旧自动识别中文或英文；其余语言（en、zh-Hant、ja、es、de、pt、fr、ko、ru、id）会让提取等 SDK 提示使用该语言，立即生效。",
+      "查看或切换记忆模式（lite / pro / ultra）。lite 不调用模型，只在原始对话里检索；pro 由模型提取记忆（System 1）；ultra 在 pro 之上每晚自动进化（System 2，使用知识图谱）。任何模式都保留全部原始对话。切换不迁移数据：已处理的不会重做，排队中的和新的按新模式处理；需 --yes，不加时只显示计划。环境变量 ONE_MEMORY_GRAPH_STORE 会强制 ultra。settings features 查看或开关 SDK 的可选检索与提取功能（全局设置，默认全部保持 SDK 默认值）：graph_rerank 图谱重排（仅 ultra）、same_series_timeline 同系列时间线（需 graph_rerank）、episode_recall 片段召回（pro / ultra，需先开 session_episodes 写入片段）、session_episodes 片段写入、episode_summary 片段摘要（每个片段一次模型调用）、intention 意图提取（默认开）、intention_dedup 意图判重（默认开；关闭则检索与写入都不判重、不删除意图）、few_shot 提取示例，以及数值 intention_dedup_threshold 意图判重阈值（默认 0.95，可设 0.8–1.0）；set 需 --yes，不加时只显示计划；reset 恢复默认值。settings language 查看或设置界面语言（App 切换语言时会自动设置）：简体中文（zh-Hans）和 system 不指定 SDK 语言，SDK 照旧自动识别中文或英文；其余语言（en、zh-Hant、ja、es、de、pt、fr、ko、ru、id）会让提取等 SDK 提示使用该语言，立即生效。",
    usage:
      "memhub settings mode [lite|pro|ultra] [--yes] [--json]\n" +
      "            memhub settings features [--json]\n" +
      "            memhub settings features set <name>=<true|false> [...] [--yes] [--json]\n" +
+      "            memhub settings features set intention_dedup_threshold=<0.8-1.0> [--yes] [--json]\n" +
      "            memhub settings features reset [<name> ...] [--json]\n" +
      "            memhub settings language [<code>|system] [--json]",
    options: [
@@ -476,7 +477,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
      {
        flag: "features set <name>=<true|false>",
        summary:
-          "开关一个或多个 SDK 功能；功能在当前模式下不生效时会注明原因（例如 graph_rerank 需要 ultra）。",
+          "开关一个或多个 SDK 功能；功能在当前模式下不生效时会注明原因（例如 graph_rerank 需要 ultra）。intention_dedup_threshold 取 0.8–1.0 的数值。",
      },
      {
        flag: "features reset [<name> ...]",
@@ -17,11 +17,14 @@ const READ_ONLY_PATHS = [
  "/api/v1/model-profiles",
  "/api/v1/source-grants",
  "/api/v1/sources",
+  "/api/v2/home-projection",
  "/api/v2/home-summary",
+  "/api/v2/raw",
  "/api/v2/memory-library",
  "/api/v2/user-profile",
  "/api/v2/user-profile/versions",
  "/api/v1/settings/memory-mode",
+  "/api/v1/settings/memory-mode/plan",
  "/api/v1/settings/memory-features",
  "/api/v1/settings/ui-language",
  "/api/v2/evolve",
@@ -268,6 +271,11 @@ export interface MemoryWriteReceipt {
  detail?: string;
  raw_ids?: string[];
  memory_ids?: string[];
+  /** Stable code of the last failure while the write still waits; null when
+   * none. Optional so older Runtimes stay readable. */
+  error_code?: string | null;
+  /** When Core will try this write again (ISO); null when not scheduled. */
+  next_retry_at?: string | null;
 }

 export interface OpenAIMessage {
@@ -1,4 +1,5 @@
 import type {
+  HomeProjectionV1,
  ImportIssue,
  ImportJob,
  LiveSyncHealth,
@@ -26,6 +27,9 @@ export const MEMORY_STATUSES = [
 const ID_MAX = 128;
 const LABEL_MAX = 256;
 const LIST_MAX = 500;
+const USER_ID = /^[A-Za-z0-9._-]{1,64}$/;
+const ISO_TIME =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
 const LIVE_SYNC_STATES = [
  "idle",
  "running",
@@ -406,6 +410,153 @@ export function validateHomeSummary(value: unknown): SdkHomeSummary | null {
  return summary as unknown as SdkHomeSummary;
 }

+/** `GET /api/v2/home-projection`: the mode-aware home content plane. */
+export function validateHomeProjection(
+  value: unknown,
+): HomeProjectionV1 | null {
+  const projection = exactRecord(value, [
+    "projection_version",
+    "user_id",
+    "effective_mode",
+    "capabilities",
+    "visible_count",
+    "display_state",
+    "latest",
+    "observed_at",
+  ]);
+  if (!projection) return null;
+  const mode = projection.effective_mode;
+  const capabilities = exactRecord(projection.capabilities, [
+    "content_plane",
+    "generation_required",
+    "graph_enabled",
+    "evolve_available",
+  ]);
+  if (
+    projection.projection_version !== 1 ||
+    typeof projection.user_id !== "string" ||
+    !USER_ID.test(projection.user_id) ||
+    !oneOf(mode, ["lite", "pro", "ultra"] as const) ||
+    !capabilities ||
+    capabilities.content_plane !== (mode === "lite" ? "raw" : "memory") ||
+    capabilities.generation_required !== (mode !== "lite") ||
+    capabilities.graph_enabled !== (mode === "ultra") ||
+    capabilities.evolve_available !== (mode === "ultra") ||
+    count(projection.visible_count) === null ||
+    !oneOf(projection.display_state, [
+      "empty",
+      "excerpt",
+      "no_user_excerpt",
+      "no_displayable_memory",
+    ] as const) ||
+    !isoTime(projection.observed_at) ||
+    !validProjectionLatest(projection.latest, mode)
+  ) {
+    return null;
+  }
+  const visible = projection.visible_count as number;
+  const latest = projection.latest as Record<string, unknown> | null;
+  if (
+    (visible === 0 &&
+      (latest !== null || projection.display_state !== "empty")) ||
+    (visible > 0 && projection.display_state === "empty") ||
+    (latest === null &&
+      ["excerpt", "no_user_excerpt"].includes(
+        projection.display_state as string,
+      )) ||
+    (latest?.type === "raw" &&
+      projection.display_state !== latest.display_state) ||
+    (latest?.type === "memory" && projection.display_state !== "excerpt")
+  ) {
+    return null;
+  }
+  return projection as unknown as HomeProjectionV1;
+}
+
+function validProjectionLatest(
+  value: unknown,
+  mode: "lite" | "pro" | "ultra",
+): boolean {
+  if (value === null) return true;
+  const base = [
+    "type",
+    "time",
+    "time_basis",
+    "excerpt",
+    "truncated",
+    "source_id",
+  ];
+  const candidate = record(value);
+  if (!candidate) return false;
+  const keys =
+    candidate.type === "raw"
+      ? [...base, "raw_id", "session_id", "display_state"]
+      : [...base, "memory_id", "scene", "kind", "variant"];
+  const latest = exactRecord(value, keys);
+  if (
+    !latest ||
+    !(latest.time === null || isoTime(latest.time)) ||
+    ![null, "conversation", "import", "write", "update"].includes(
+      latest.time_basis as null | string,
+    ) ||
+    text(latest.excerpt, 200) === null ||
+    typeof latest.truncated !== "boolean" ||
+    text(latest.source_id, ID_MAX) === null
+  ) {
+    return false;
+  }
+  if (latest.type === "raw") {
+    return (
+      mode === "lite" &&
+      nonemptyText(latest.raw_id, ID_MAX) &&
+      nonemptyText(latest.session_id, LABEL_MAX) &&
+      oneOf(latest.display_state, ["excerpt", "no_user_excerpt"] as const) &&
+      (latest.display_state !== "no_user_excerpt" ||
+        (latest.excerpt === "" && latest.truncated === false))
+    );
+  }
+  return (
+    latest.type === "memory" &&
+    mode !== "lite" &&
+    nonemptyText(latest.memory_id, ID_MAX) &&
+    oneOf(latest.scene, ["chat", "working", "coding"] as const) &&
+    oneOf(latest.kind, ["chat", "experience"] as const) &&
+    [null, "working", "coding"].includes(latest.variant as null | string) &&
+    ((latest.kind === "chat" &&
+      latest.scene === "chat" &&
+      latest.variant === null) ||
+      (latest.kind === "experience" &&
+        latest.scene === latest.variant &&
+        oneOf(latest.scene, ["working", "coding"] as const)))
+  );
+}
+
+/** The bounded `/api/v2/raw?limit=1` envelope used only for its real total. */
+export function validateRawTotal(value: unknown): number | null {
+  const page = exactRecord(value, [
+    "user_id",
+    "items",
+    "total",
+    "offset",
+    "limit",
+    "time_filtered",
+  ]);
+  if (
+    !page ||
+    typeof page.user_id !== "string" ||
+    !USER_ID.test(page.user_id) ||
+    !Array.isArray(page.items) ||
+    page.items.length > 1 ||
+    count(page.total) === null ||
+    page.offset !== 0 ||
+    page.limit !== 1 ||
+    page.time_filtered !== false
+  ) {
+    return null;
+  }
+  return page.total as number;
+}
+
 function identifiers(value: unknown): string[] | null {
  return list(value ?? [], (item) => text(item, ID_MAX));
 }
@@ -430,6 +581,30 @@ function record(value: unknown): Record<string, unknown> | null {
    : null;
 }

+function exactRecord(
+  value: unknown,
+  keys: readonly string[],
+): Record<string, unknown> | null {
+  const item = record(value);
+  return item &&
+    Object.keys(item).length === keys.length &&
+    keys.every((key) => Object.hasOwn(item, key))
+    ? item
+    : null;
+}
+
+function isoTime(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    ISO_TIME.test(value) &&
+    Number.isFinite(Date.parse(value))
+  );
+}
+
+function nonemptyText(value: unknown, max: number): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= max;
+}
+
 function text(value: unknown, max: number): string | null {
  return typeof value === "string" && value.length <= max ? value : null;
 }
@@ -250,6 +250,20 @@ describe("models activate with an embedding change", () => {
      code: "embedding_switch_required",
    });
  });
+
+  it("does not treat a domain 404 as an old-Core route miss", async () => {
+    transport.post.mockResolvedValue({
+      status: 404,
+      data: { detail: "embedding_switch_not_found" },
+    });
+    const result = await capturedRun(["models", "activate", PROFILE, "--json"]);
+    expect(result.code).toBe(1);
+    expect(
+      transport.post.mock.calls.some(([url]) =>
+        String(url).endsWith("/activate"),
+      ),
+    ).toBe(false);
+  });
 });

 describe("models switch and spaces", () => {
@@ -9,6 +9,7 @@
 * makes it live. The CLI shows the plan, asks, starts the job and follows it.
 */

+import { isBareNotFound } from "@one-memory/operations";
 import type { CoreReader } from "./core-client.js";
 import type {
  CoreDeleteOperations,
@@ -387,7 +388,11 @@ async function requestPlan(
  }
  if (outcome.state === "rejected") {
    // A Core before the registry has no plan route: activation as before.
-    if (outcome.http_status === 404 && outcome.code === "http_404") {
+    if (
+      outcome.http_status === 404 &&
+      outcome.code === "http_404" &&
+      isBareNotFound(outcome.body)
+    ) {
      return { state: "unsupported" };
    }
    const plan = parsePlan(record(outcome.body)?.plan);
@@ -348,12 +348,25 @@ export function parseApiKey(bytes: Buffer | null): string | undefined {
  return value;
 }

+/** What to do about a refusal whose code alone does not say. */
+const FLOW_CODE_HINTS: Record<string, string> = {
+  hermes_root_is_profiles_container:
+    "--root 指向的是 profiles 目录本身；请指向其中一个 profile，例如 ~/.hermes/profiles/wife。",
+  hermes_root_overlaps_other_user:
+    "--root 与另一个用户已接入的 Hermes 目录相同或互相包含，会读到对方的记录；请换一个目录，或先撤销对方的接入。~/.hermes 与 ~/.hermes/profiles/<name> 可以分属两个用户。",
+};
+
 export function renderFlowText(document: FlowDocument): string {
  const lines = [
    `操作状态：${document.state}`,
    `操作 ID：${document.operation_id ?? "无"}`,
    "code" in document ? `代码：${document.code}` : "已返回有界回执。",
  ];
+  const hint =
+    "code" in document && typeof document.code === "string"
+      ? FLOW_CODE_HINTS[document.code]
+      : undefined;
+  if (hint) lines.push(hint);
  // A partial success or an all-rejected batch must name each source that was
  // not accepted; a bare "partial" leaves the user with nothing to act on.
  if (
@@ -233,6 +233,31 @@ describe("memories add-status", () => {
    });
  });

+  it("passes the retry code and time of an addition still waiting", async () => {
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: {
+        ...addReceipt("pending"),
+        error_code: "model_auth_failed",
+        next_retry_at: "2026-11-02T10:00:00+00:00",
+      },
+    });
+    const json = await capturedRun([
+      "memories",
+      "add-status",
+      REQUEST,
+      "--json",
+    ]);
+    expect(JSON.parse(json.stdout).receipt).toMatchObject({
+      state: "pending",
+      error_code: "model_auth_failed",
+      next_retry_at: "2026-11-02T10:00:00+00:00",
+    });
+    const text = await capturedRun(["memories", "add-status", REQUEST]);
+    expect(text.stdout).toContain("error_code: model_auth_failed");
+    expect(text.stdout).toContain("next_retry_at: 2026-11-02T10:00:00+00:00");
+  });
+
  it("reports an unknown request id as not_found, exit 1", async () => {
    transport.get.mockResolvedValue({
      status: 404,
@@ -366,6 +391,33 @@ describe("memories update / delete pass the namespace", () => {
    );
  });

+  it("reports a delete answered 404 as already gone and exits 0", async () => {
+    transport.delete.mockResolvedValue({
+      status: 404,
+      data: { detail: "memory_not_found" },
+    });
+    const json = await capturedRun([
+      "memories",
+      "delete",
+      "gone-1",
+      "--yes",
+      "--json",
+    ]);
+    expect(json.code).toBe(0);
+    expect(JSON.parse(json.stdout)).toEqual({
+      schema_version: 2,
+      product: expect.any(String),
+      command: "memories delete",
+      state: "committed",
+      operation: "delete",
+      memory_id: "gone-1",
+      already_gone: true,
+    });
+    const text = await capturedRun(["memories", "delete", "gone-1", "--yes"]);
+    expect(text.code).toBe(0);
+    expect(text.stdout).toContain("未找到记忆 gone-1");
+  });
+
  it("explains an ambiguous id instead of a bare code", async () => {
    transport.delete.mockResolvedValue({
      status: 409,
@@ -36,15 +36,17 @@ const DEFAULTS: Record<string, boolean> = {
  session_episodes: false,
  episode_summary: false,
  intention: true,
+  intention_dedup: true,
  few_shot: false,
 };
+const THRESHOLD_DEFAULT = 0.95;

 function featuresState(
-  configured: Record<string, boolean> = {},
+  configured: Record<string, boolean | number> = {},
  mode = "pro",
  extra: Record<string, unknown> = {},
 ) {
-  const nonDefault: Record<string, boolean> = {};
+  const nonDefault: Record<string, boolean | number> = {};
  const features = Object.entries(DEFAULTS).map(([name, fallback]) => {
    const enabled = configured[name] ?? fallback;
    if (enabled !== fallback) nonDefault[name] = enabled;
@@ -70,7 +72,34 @@ function featuresState(
      description: name,
    };
  });
-  return { mode, features, non_default: nonDefault, ...extra };
+  const threshold =
+    (configured.intention_dedup_threshold as number | undefined) ??
+    THRESHOLD_DEFAULT;
+  if (threshold !== THRESHOLD_DEFAULT)
+    nonDefault.intention_dedup_threshold = threshold;
+  const dedupOn =
+    (configured.intention_dedup as boolean | undefined) ??
+    DEFAULTS.intention_dedup;
+  const parameters = [
+    {
+      name: "intention_dedup_threshold",
+      value: threshold,
+      configured:
+        "intention_dedup_threshold" in configured
+          ? configured.intention_dedup_threshold
+          : null,
+      default: THRESHOLD_DEFAULT,
+      minimum: 0.8,
+      maximum: 1,
+      active: dedupOn,
+      reason: dedupOn ? null : "requires_intention_dedup",
+      requires_feature: "intention_dedup",
+      sdk_field: "recall.intention_dedup_threshold",
+      env: "MEMORY_INTENTION_DEDUP_THRESHOLD",
+      description: "threshold",
+    },
+  ];
+  return { mode, features, parameters, non_default: nonDefault, ...extra };
 }

 beforeEach(() => {
@@ -110,11 +139,16 @@ describe("memhub settings features", () => {
    expect(result.code).toBe(0);
    const json = JSON.parse(result.stdout);
    expect(json.state).toBe("ok");
-    expect(json.features.features).toHaveLength(7);
+    expect(json.features.features).toHaveLength(8);
+    expect(json.features.parameters[0].name).toBe("intention_dedup_threshold");
    expect(transport.put).not.toHaveBeenCalled();
    const text = (await capturedRun(["settings", "features"])).stdout;
    expect(text).toContain("graph_rerank：关（默认）");
    expect(text).toContain("intention：开（默认）");
+    expect(text).toContain("intention_dedup：开（默认）");
+    expect(text).toContain(
+      "intention_dedup_threshold：0.95（默认，可设 0.8–1）",
+    );
    expect(text).toContain("先开启 session_episodes");
  });

@@ -160,6 +194,130 @@ describe("memhub settings features", () => {
    );
  });

+  it("turns intention dedup off and sets its threshold, round trip", async () => {
+    transport.put.mockResolvedValueOnce({
+      status: 200,
+      data: featuresState({ intention_dedup: false }, "pro", {
+        changed: ["intention_dedup"],
+      }),
+    });
+    const off = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "intention_dedup=false",
+      "--yes",
+      "--json",
+    ]);
+    expect(off.code).toBe(0);
+    expect(transport.put).toHaveBeenLastCalledWith(
+      "/api/v1/settings/memory-features",
+      { intention_dedup: false },
+      undefined,
+    );
+    const offJson = JSON.parse(off.stdout);
+    expect(offJson.state).toBe("committed");
+    expect(offJson.changed).toEqual(["intention_dedup"]);
+    expect(offJson.features.parameters[0].reason).toBe(
+      "requires_intention_dedup",
+    );
+
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: featuresState({ intention_dedup: false }),
+    });
+    transport.put.mockResolvedValueOnce({
+      status: 200,
+      data: featuresState(
+        { intention_dedup: true, intention_dedup_threshold: 0.9 },
+        "pro",
+        { changed: ["intention_dedup", "intention_dedup_threshold"] },
+      ),
+    });
+    const on = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "intention_dedup=true",
+      "intention_dedup_threshold=0.9",
+      "--yes",
+    ]);
+    expect(on.code).toBe(0);
+    expect(transport.put).toHaveBeenLastCalledWith(
+      "/api/v1/settings/memory-features",
+      { intention_dedup: true, intention_dedup_threshold: 0.9 },
+      undefined,
+    );
+    expect(on.stdout).toContain(
+      "已更新：intention_dedup、intention_dedup_threshold",
+    );
+    expect(on.stdout).toContain("intention_dedup_threshold：0.9（已设置");
+
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: featuresState({ intention_dedup_threshold: 0.9 }),
+    });
+    transport.put.mockResolvedValueOnce({
+      status: 200,
+      data: featuresState({}, "pro", {
+        changed: ["intention_dedup_threshold"],
+      }),
+    });
+    const reset = await capturedRun([
+      "settings",
+      "features",
+      "reset",
+      "intention_dedup_threshold",
+    ]);
+    expect(reset.code).toBe(0);
+    expect(transport.put).toHaveBeenLastCalledWith(
+      "/api/v1/settings/memory-features",
+      { intention_dedup_threshold: null },
+      undefined,
+    );
+  });
+
+  it("previews a threshold without --yes and refuses one out of range", async () => {
+    const preview = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "intention_dedup_threshold=0.85",
+    ]);
+    expect(preview.code).toBe(0);
+    expect(preview.stdout).toContain("- intention_dedup_threshold = 0.85");
+    for (const value of ["0.5", "0.79", "1.01", "2", "-0.9", "abc", "1e0"]) {
+      const result = await capturedRun([
+        "settings",
+        "features",
+        "set",
+        `intention_dedup_threshold=${value}`,
+        "--yes",
+      ]);
+      expect(result.code, value).toBe(2);
+    }
+    expect(transport.put).not.toHaveBeenCalled();
+  });
+
+  it("does not send a threshold to a Runtime that does not list it", async () => {
+    const { parameters: _unused, ...older } = featuresState();
+    transport.get.mockResolvedValue({ status: 200, data: older });
+    const result = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "intention_dedup_threshold=0.9",
+      "--yes",
+      "--json",
+    ]);
+    expect(result.code).toBe(1);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      state: "rejected",
+      code: "memory_feature_unsupported",
+    });
+    expect(transport.put).not.toHaveBeenCalled();
+  });
+
  it("does nothing when the values are already set", async () => {
    transport.get.mockResolvedValue({
      status: 200,
@@ -210,6 +368,8 @@ describe("memhub settings features", () => {
      ["settings", "features", "set", "graph_rerank=yes"],
      ["settings", "features", "set", "graph_rerank"],
      ["settings", "features", "set", "few_shot=true", "few_shot=false"],
+      ["settings", "features", "set", "intention_dedup=0.9"],
+      ["settings", "features", "set", "intention_dedup_threshold=true"],
      ["settings", "features", "reset", "nope"],
      ["settings", "features", "toggle"],
    ]) {
@@ -269,7 +429,11 @@ describe("status pipeline features", () => {
        last_evolve_at: null,
        graph_build: { state: "idle", users: {} },
        evolve: { mode: "pro", schedule: null, running: [], users: {} },
-        features: { episode_recall: true, intention: false },
+        features: {
+          episode_recall: true,
+          intention: false,
+          intention_dedup_threshold: 0.9,
+        },
      },
    };
    const report = await composeStatusReport({
@@ -284,9 +448,12 @@ describe("status pipeline features", () => {
    expect(report.pipeline?.features).toEqual({
      episode_recall: true,
      intention: false,
+      intention_dedup_threshold: 0.9,
    });
    const text = renderStatusText(report, "MemHub");
-    expect(text).toContain("SDK 功能：episode_recall=开、intention=关");
+    expect(text).toContain(
+      "SDK 功能：episode_recall=开、intention=关、intention_dedup_threshold=0.9",
+    );
  });
 });

@@ -2,7 +2,8 @@
 * `memhub settings features [set <name>=<true|false> ... | reset [<name> ...]]`.
 *
 * The SDK's optional retrieval and extraction features (graph rerank, episode
- * recall, the episode write side, intention, few-shot). One global setting in
+ * recall, the episode write side, intention and its dedup, few-shot), plus the
+ * intention dedup threshold, the one numeric setting. One global setting in
 * the Runtime; an unset feature keeps the SDK default, so an install nobody
 * touched behaves as before. `set` prints its plan first and needs `--yes`,
 * like `settings mode`, because some features spend model calls; `reset`
@@ -20,10 +21,19 @@ export const MEMORY_FEATURES = [
  "session_episodes",
  "episode_summary",
  "intention",
+  "intention_dedup",
  "few_shot",
 ] as const;
 export type MemoryFeature = (typeof MEMORY_FEATURES)[number];

+/** Numeric settings, with the range the Runtime accepts (inclusive). */
+export const MEMORY_PARAMETERS = {
+  intention_dedup_threshold: { minimum: 0.8, maximum: 1 },
+} as const;
+export type MemoryParameter = keyof typeof MEMORY_PARAMETERS;
+export type MemorySetting = MemoryFeature | MemoryParameter;
+type SettingValues = Partial<Record<MemorySetting, boolean | number>>;
+
 const FEATURE_LABEL: Record<MemoryFeature, string> = {
  graph_rerank: "图谱重排（沿知识图谱的边传播支持度；仅 ultra）",
  same_series_timeline:
@@ -33,6 +43,8 @@ const FEATURE_LABEL: Record<MemoryFeature, string> = {
  session_episodes: "片段写入（同一会话提取的记忆归入同一片段）",
  episode_summary: "片段摘要（片段结束时总结一次；每个片段一次模型调用）",
  intention: "意图提取（随事实一起提取用户的计划与意图）",
+  intention_dedup:
+    "意图判重（检索时把同一天、相似度达到阈值的意图视为重复，只返回最早一条并删除其余；关闭则不判重、不删除）",
  few_shot: "提取示例（在提取提示里附上示例；不加调用，输入更长）",
 };

@@ -41,21 +53,42 @@ const REASON_TEXT: Record<string, string> = {
  requires_pro: "lite 模式下不生效（需要 pro 或 ultra）",
  requires_ultra: "当前模式下不生效（需要 ultra）",
  requires_graph_rerank: "需要先开启并生效 graph_rerank",
+  requires_intention_dedup: "intention_dedup 已关闭，阈值不起作用",
+};
+
+const PARAMETER_LABEL: Record<MemoryParameter, string> = {
+  intention_dedup_threshold: "意图判重阈值（余弦相似度，越高保留越多）",
 };

 export type FeaturesCommand =
  | { kind: "show" }
  | {
      kind: "set";
-      values: Partial<Record<MemoryFeature, boolean>>;
+      values: SettingValues;
      confirmed: boolean;
    }
-  | { kind: "reset"; names: MemoryFeature[] };
+  | { kind: "reset"; names: MemorySetting[] };

 function isFeature(value: string): value is MemoryFeature {
  return (MEMORY_FEATURES as readonly string[]).includes(value);
 }

+function isParameter(value: string): value is MemoryParameter {
+  return Object.hasOwn(MEMORY_PARAMETERS, value);
+}
+
+function isSetting(value: string): value is MemorySetting {
+  return isFeature(value) || isParameter(value);
+}
+
+/** A parameter's value: a plain decimal in its range; null = usage. */
+function parameterValue(name: MemoryParameter, raw: string): number | null {
+  if (!/^\d+(\.\d+)?$/.test(raw)) return null;
+  const value = Number(raw);
+  const { minimum, maximum } = MEMORY_PARAMETERS[name];
+  return value >= minimum && value <= maximum ? value : null;
+}
+
 /** Arguments after `settings features`; null = usage. */
 export function parseFeaturesCommand(
  values: readonly string[],
@@ -68,18 +101,28 @@ export function parseFeaturesCommand(
  const positional = tail.filter((value) => value !== "--yes");
  if (verb === "set") {
    if (positional.length === 0) return null;
-    const parsed: Partial<Record<MemoryFeature, boolean>> = {};
+    const parsed: SettingValues = {};
    for (const item of positional) {
-      const match = /^([a-z_]+)=(true|false)$/.exec(item);
-      if (!match || !isFeature(match[1]) || match[1] in parsed) return null;
-      parsed[match[1]] = match[2] === "true";
+      const match = /^([a-z_]+)=(.+)$/.exec(item);
+      if (!match || match[1] in parsed) return null;
+      const [, name, raw] = match;
+      if (isFeature(name)) {
+        if (raw !== "true" && raw !== "false") return null;
+        parsed[name] = raw === "true";
+      } else if (isParameter(name)) {
+        const value = parameterValue(name, raw);
+        if (value === null) return null;
+        parsed[name] = value;
+      } else {
+        return null;
+      }
    }
    return { kind: "set", values: parsed, confirmed: yes === 1 };
  }
  if (verb === "reset") {
    if (new Set(positional).size !== positional.length) return null;
-    if (!positional.every(isFeature)) return null;
-    return { kind: "reset", names: positional as MemoryFeature[] };
+    if (!positional.every(isSetting)) return null;
+    return { kind: "reset", names: positional as MemorySetting[] };
  }
  return null;
 }
@@ -96,11 +139,26 @@ export interface FeatureState {
  description: string;
 }

+export interface ParameterState {
+  name: MemoryParameter;
+  value: number;
+  configured: number | null;
+  default: number;
+  minimum: number;
+  maximum: number;
+  active: boolean;
+  reason: string | null;
+  requires_feature: string;
+  description: string;
+}
+
 export interface FeaturesState {
  mode: string;
  features: FeatureState[];
-  non_default: Partial<Record<MemoryFeature, boolean>>;
-  changed?: MemoryFeature[];
+  /** Absent from a Runtime older than the intention dedup threshold. */
+  parameters?: ParameterState[];
+  non_default: SettingValues;
+  changed?: MemorySetting[];
 }

 function featuresState(value: unknown): FeaturesState | null {
@@ -125,6 +183,20 @@ function featuresState(value: unknown): FeaturesState | null {
      return null;
    }
  }
+  if (item.parameters !== undefined) {
+    if (!Array.isArray(item.parameters)) return null;
+    for (const parameter of item.parameters) {
+      if (
+        !parameter ||
+        typeof parameter !== "object" ||
+        typeof (parameter as ParameterState).name !== "string" ||
+        typeof (parameter as ParameterState).value !== "number" ||
+        typeof (parameter as ParameterState).active !== "boolean"
+      ) {
+        return null;
+      }
+    }
+  }
  return item as unknown as FeaturesState;
 }

@@ -137,12 +209,12 @@ export type FeaturesDocument = {
  | {
      state: "preview";
      features: FeaturesState;
-      target: Partial<Record<MemoryFeature, boolean>>;
+      target: SettingValues;
      applied: false;
      next_step: string;
    }
  | { state: "unchanged"; features: FeaturesState }
-  | { state: "committed"; features: FeaturesState; changed: MemoryFeature[] }
+  | { state: "committed"; features: FeaturesState; changed: MemorySetting[] }
  | { state: "rejected" | "unknown" | "unavailable"; code: string }
 );

@@ -170,13 +242,23 @@ export async function runFeaturesCommand(
  if (command.kind === "show") {
    return { ...BASE, state: "ok", features: current };
  }
+  // What a person set, per name this Runtime lists; null = the default.
+  const configured = new Map<string, boolean | number | null>([
+    ...current.features.map(
+      (feature) => [feature.name, feature.configured] as const,
+    ),
+    ...(current.parameters ?? []).map(
+      (parameter) => [parameter.name, parameter.configured] as const,
+    ),
+  ]);
  let body: Record<string, unknown>;
  if (command.kind === "set") {
-    const configured = new Map(
-      current.features.map((feature) => [feature.name, feature.configured]),
-    );
+    if (Object.keys(command.values).some((name) => !configured.has(name))) {
+      // An older Runtime does not know the name; it would answer 422.
+      return { ...BASE, state: "rejected", code: "memory_feature_unsupported" };
+    }
    const differs = Object.entries(command.values).some(
-      ([name, value]) => configured.get(name as MemoryFeature) !== value,
+      ([name, value]) => configured.get(name) !== value,
    );
    if (!differs) return { ...BASE, state: "unchanged", features: current };
    if (!command.confirmed) {
@@ -197,16 +279,10 @@ export async function runFeaturesCommand(
    const names =
      command.names.length > 0
        ? command.names
-        : current.features
-            .filter((feature) => feature.configured !== null)
-            .map((feature) => feature.name);
-    if (
-      names.every(
-        (name) =>
-          current.features.find((feature) => feature.name === name)
-            ?.configured === null,
-      )
-    ) {
+        : [...configured]
+            .filter(([, value]) => value !== null)
+            .map(([name]) => name as MemorySetting);
+    if (names.every((name) => (configured.get(name) ?? null) === null)) {
      return { ...BASE, state: "unchanged", features: current };
    }
    body = Object.fromEntries(names.map((name) => [name, null]));
@@ -233,6 +309,16 @@ export function featuresExitCode(document: FeaturesDocument): number {
    : 1;
 }

+function parameterLine(parameter: ParameterState): string {
+  const label = PARAMETER_LABEL[parameter.name] ?? parameter.name;
+  const origin = parameter.configured === null ? "默认" : "已设置";
+  const activity =
+    !parameter.active && parameter.reason
+      ? `，${REASON_TEXT[parameter.reason] ?? parameter.reason}`
+      : "";
+  return `${parameter.name}：${parameter.value}（${origin}${activity}，可设 ${parameter.minimum}–${parameter.maximum}）— ${label}`;
+}
+
 function featureLine(feature: FeatureState): string {
  const label = FEATURE_LABEL[feature.name] ?? feature.name;
  const value = feature.enabled ? "开" : "关";
@@ -251,6 +337,8 @@ export function renderFeaturesText(document: FeaturesDocument): string {
  const state = document.features;
  const lines = [`当前模式：${state.mode}`];
  for (const feature of state.features) lines.push(featureLine(feature));
+  for (const parameter of state.parameters ?? [])
+    lines.push(parameterLine(parameter));
  lines.push(
    "片段召回（episode_recall）只对带片段的记忆有用：先开启 session_episodes，之后提取的记忆才会带片段。",
  );
@@ -258,7 +346,9 @@ export function renderFeaturesText(document: FeaturesDocument): string {
  if (document.state === "preview") {
    lines.push("将设置：");
    for (const [name, value] of Object.entries(document.target)) {
-      lines.push(`- ${name} = ${value ? "开" : "关"}`);
+      lines.push(
+        `- ${name} = ${typeof value === "number" ? value : value ? "开" : "关"}`,
+      );
    }
    lines.push(`未执行任何改动。确认后运行：${document.next_step}`);
  }
@@ -248,6 +248,10 @@ function addReceipt(receipt: MemoryAddReceipt): Record<string, unknown> {
    task_id: receipt.task_id,
    memory_ids: receipt.memory_ids,
    error: receipt.error,
+    error_code:
+      typeof receipt.error_code === "string" ? receipt.error_code : null,
+    next_retry_at:
+      typeof receipt.next_retry_at === "string" ? receipt.next_retry_at : null,
  };
 }

@@ -347,6 +351,12 @@ export function renderMemoryAddText(document: MemoryAddDocument): string {
      ...((document.receipt.memory_ids as string[]).length > 0
        ? [`memory_ids: ${(document.receipt.memory_ids as string[]).join(",")}`]
        : []),
+      ...(document.receipt.error_code
+        ? [`error_code: ${document.receipt.error_code}`]
+        : []),
+      ...(document.receipt.next_retry_at
+        ? [`next_retry_at: ${document.receipt.next_retry_at}`]
+        : []),
      document.command === "memories add"
        ? `查询进度：memhub memories add-status ${document.request_id}；重试请带上同一个 --request-id，不会重复添加。`
        : "",
@@ -161,6 +161,7 @@ const CORE = new Map<string, { status: number; data: unknown }>([
        blocked_stages: [
          { kind: "extract", reason: "model_missing", count: 2 },
        ],
+        pipeline: { mode: "pro", configured_mode: "pro" },
      },
    },
  ],
@@ -202,7 +203,9 @@ const READ_ONLY_PATHS = [
  "/api/v1/live-sync",
  "/api/v1/memory-processing",
  "/api/v1/model-profiles",
+  "/api/v2/home-projection",
  "/api/v2/home-summary",
+  "/api/v2/raw",
  "/api/v2/memory-library",
  "/api/v2/memories/",
  "/api/v2/user-profile",
@@ -257,6 +260,9 @@ describe("CLI-20 status summary", () => {
    expect(report.sections.model).toMatchObject({ state: "ok", profiles: 1 });
    expect(report.sections.memories).toMatchObject({
      state: "ok",
+      content_plane: "memory",
+      visible_count: 42,
+      effective_mode: "pro",
      memory_count: 42,
    });
    expect(report.summary.state).toBe("ok");
@@ -903,7 +909,10 @@ describe("CLI-21 memory reads", () => {
    expect(isReadOnlyPath("/api/v2/memories/ask")).toBe(false);
    expect(isReadOnlyPath("/api/v2/memories/m1")).toBe(true);
    expect(isReadOnlyPath("/api/v2/memory-library")).toBe(true);
+    expect(isReadOnlyPath("/api/v2/home-projection")).toBe(true);
    expect(isReadOnlyPath("/api/v2/home-summary")).toBe(true);
+    expect(isReadOnlyPath("/api/v2/raw")).toBe(true);
+    expect(isReadOnlyPath("/api/v1/settings/memory-mode/plan")).toBe(true);
    // The retired v1 data plane is no longer a CLI read.
    expect(isReadOnlyPath("/api/v1/memories/m1")).toBe(false);
    expect(isReadOnlyPath("/api/v1/home-summary")).toBe(false);
@@ -1085,7 +1094,8 @@ describe("malformed success responses", () => {

  it("refuses a model profile whose string fields are not strings", async () => {
    transport.get.mockImplementation(async (url: string) => {
-      if (url !== "/api/v1/model-profiles") return CORE.get(url);
+      if (url !== "/api/v1/model-profiles")
+        return CORE.get(url) ?? { status: 404, data: { detail: "not_found" } };
      return {
        status: 200,
        data: [
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";

+import type { CoreReader, ReadOutcome } from "./core-client.js";
 import { composeDoctorReport, renderDoctorText } from "./doctor-report.js";
 import {
  composeStatusReport,
@@ -41,6 +42,108 @@ describe("status default output", () => {
  });
 });

+describe("status on a paused model", () => {
+  const processing = (backoff: {
+    llm_backoff_until: string | null;
+    llm_backoff_error: string | null;
+  }) => ({
+    pending: 4,
+    fresh_pending: 4,
+    backlog_pending: 0,
+    outside_window_pending: 0,
+    running: 0,
+    waiting_for_model: 0,
+    completed: 1,
+    failed: 0,
+    blocked_stages: [],
+    suspended: 2,
+    ...backoff,
+  });
+  const reader =
+    (summary: unknown): CoreReader =>
+    async <T>(path: string) =>
+      (path === "/api/v1/memory-processing"
+        ? { state: "ok", data: summary }
+        : { state: "unavailable", code: "x" }) as ReadOutcome<T>;
+  const compose = (summary: unknown) =>
+    composeStatusReport({
+      dataDir: "/tmp/isolated/.one-memory",
+      runtime: {
+        state: "running",
+        code: "runtime_verified",
+        host: "127.0.0.1",
+        port: 30001,
+      },
+      background: null,
+      reader: reader(summary),
+    });
+
+  it("names the code and the retry time while the breaker pauses", async () => {
+    const report = await compose(
+      processing({
+        llm_backoff_until: "2026-11-02T10:00:00+00:00",
+        llm_backoff_error: "model_auth_failed",
+      }),
+    );
+    expect(report.sections.processing).toMatchObject({
+      state: "ok",
+      pending: 4,
+      suspended: 2,
+      llm_backoff_until: "2026-11-02T10:00:00+00:00",
+      llm_backoff_error: "model_auth_failed",
+    });
+    const text = renderStatusText(report, "MemHub");
+    expect(text).toContain(
+      "模型暂停：model_auth_failed，将于 2026-11-02T10:00:00+00:00 自动重试",
+    );
+    expect(text).not.toContain("llm_backoff");
+  });
+
+  it("prints no pause line and null fields when nothing is paused", async () => {
+    const report = await compose(
+      processing({ llm_backoff_until: null, llm_backoff_error: null }),
+    );
+    expect(report.sections.processing).toMatchObject({
+      llm_backoff_until: null,
+      llm_backoff_error: null,
+    });
+    expect(renderStatusText(report, "MemHub")).not.toContain("模型暂停");
+  });
+
+  it("reports a restarting write drain and its exit code", async () => {
+    const report = await compose({
+      ...processing({ llm_backoff_until: null, llm_backoff_error: null }),
+      write_drain: "restarting",
+      write_drain_error: "operational_error",
+    });
+    expect(report.sections.processing).toMatchObject({
+      write_drain: "restarting",
+      write_drain_error: "operational_error",
+    });
+    const text = renderStatusText(report, "MemHub");
+    expect(text).toContain(
+      "写入队列：异常退出（operational_error），正在自动重启",
+    );
+    expect(text).not.toContain("write_drain");
+  });
+
+  it("says nothing about a running drain and nulls what an older Core omits", async () => {
+    const running = await compose({
+      ...processing({ llm_backoff_until: null, llm_backoff_error: null }),
+      write_drain: "running",
+      write_drain_error: null,
+    });
+    expect(renderStatusText(running, "MemHub")).not.toContain("写入队列");
+    const older = await compose(
+      processing({ llm_backoff_until: null, llm_backoff_error: null }),
+    );
+    expect(older.sections.processing).toMatchObject({
+      write_drain: null,
+      write_drain_error: null,
+    });
+  });
+});
+
 describe("status and doctor on an unfinished upgrade migration", () => {
  it("names the migration log and the issues page", async () => {
    const report = await composeStatusReport({
@@ -77,3 +180,140 @@ describe("status and doctor on an unfinished upgrade migration", () => {
    expect(report.runtime.log_file).toBeUndefined();
  });
 });
+
+describe("mode-aware status content projection", () => {
+  const runtime = {
+    state: "running" as const,
+    code: "runtime_verified",
+    host: "127.0.0.1",
+    port: 30001,
+  };
+  const processing = (mode: "lite" | "pro" | "ultra") => ({
+    pending: 0,
+    fresh_pending: 0,
+    backlog_pending: 0,
+    outside_window_pending: 0,
+    running: 0,
+    waiting_for_model: 0,
+    completed: 0,
+    failed: 0,
+    pipeline: { mode, configured_mode: mode },
+  });
+  const projection = {
+    projection_version: 1,
+    user_id: "local",
+    effective_mode: "lite",
+    capabilities: {
+      content_plane: "raw",
+      generation_required: false,
+      graph_enabled: false,
+      evolve_available: false,
+    },
+    visible_count: 7,
+    display_state: "excerpt",
+    latest: {
+      type: "raw",
+      raw_id: "raw-1",
+      session_id: "session-1",
+      display_state: "excerpt",
+      time: null,
+      time_basis: null,
+      excerpt: "hello",
+      truncated: false,
+      source_id: "cursor",
+    },
+    observed_at: "2026-11-04T00:00:00Z",
+  };
+
+  it("uses the projection without reading either legacy count endpoint", async () => {
+    const calls: string[] = [];
+    const reader: CoreReader = async <T>(path: string) => {
+      calls.push(path);
+      const data =
+        path === "/api/v2/home-projection"
+          ? projection
+          : path === "/api/v1/memory-processing"
+            ? processing("lite")
+            : null;
+      return { state: "ok", data } as ReadOutcome<T>;
+    };
+    const report = await composeStatusReport({
+      dataDir: "/tmp/isolated",
+      runtime,
+      background: null,
+      reader,
+    });
+    expect(report.sections.memories).toEqual({
+      state: "ok",
+      content_plane: "raw",
+      visible_count: 7,
+      effective_mode: "lite",
+      raw_count: 7,
+    });
+    expect(calls).not.toContain("/api/v2/raw");
+    expect(calls).not.toContain("/api/v2/home-summary");
+    expect(renderStatusText(report, "MemHub")).toContain(
+      "原始对话：原始对话 7",
+    );
+  });
+
+  it("falls back to the real raw total only for an old Lite Core", async () => {
+    const reader: CoreReader = async <T>(path: string) => {
+      if (path === "/api/v2/home-projection")
+        return { state: "not_found", code: "http_404" } as ReadOutcome<T>;
+      if (path === "/api/v1/memory-processing")
+        return {
+          state: "ok",
+          data: processing("lite"),
+        } as ReadOutcome<T>;
+      if (path === "/api/v2/raw")
+        return {
+          state: "ok",
+          data: {
+            user_id: "local",
+            items: [],
+            total: 9,
+            offset: 0,
+            limit: 1,
+            time_filtered: false,
+          },
+        } as ReadOutcome<T>;
+      return { state: "unavailable", code: "x" } as ReadOutcome<T>;
+    };
+    const report = await composeStatusReport({
+      dataDir: "/tmp/isolated",
+      runtime,
+      background: null,
+      reader,
+    });
+    expect(report.sections.memories).toMatchObject({
+      state: "ok",
+      content_plane: "raw",
+      visible_count: 9,
+      raw_count: 9,
+    });
+    expect(report.sections.memories).not.toHaveProperty("memory_count");
+  });
+
+  it("rejects extra projection fields instead of falling back or leaking them", async () => {
+    const reader: CoreReader = async <T>(path: string) =>
+      ({
+        state: "ok",
+        data:
+          path === "/api/v2/home-projection"
+            ? { ...projection, secret: "must-not-leak" }
+            : processing("lite"),
+      }) as ReadOutcome<T>;
+    const report = await composeStatusReport({
+      dataDir: "/tmp/isolated",
+      runtime,
+      background: null,
+      reader,
+    });
+    expect(report.sections.memories).toEqual({
+      state: "invalid",
+      code: "response_invalid",
+    });
+    expect(JSON.stringify(report)).not.toContain("must-not-leak");
+  });
+});
@@ -1,4 +1,5 @@
 import type {
+  HomeProjectionV1,
  LiveSyncHealth,
  MemoryProcessingSummary,
  ModelProfile,
@@ -12,10 +13,12 @@ import { sdkMigrationLogPath } from "@one-memory/runtime-control";
 import type { CoreReader, ReadOutcome } from "./core-client.js";
 import {
  type SdkHomeSummary,
+  validateHomeProjection,
  validateHomeSummary,
  validateLiveSync,
  validateModelProfiles,
  validateProcessing,
+  validateRawTotal,
  validateSources,
 } from "./core-responses.js";
 import { describeEmbeddingSwitchSummary } from "./embedding-switch-flow.js";
@@ -85,7 +88,7 @@ export interface PipelineSummary {
  >;
  graph_build: string | null;
  /** SDK features (`memory_features`) whose value differs from the default. */
-  features: Record<string, boolean>;
+  features: Record<string, boolean | number>;
  /** The App's display language; null = never chosen or "follow the system". */
  ui_language: string | null;
  /** The SDK prompt language: `auto` (zh/en detection) or the code passed. */
@@ -134,12 +137,13 @@ export function describePipeline(value: unknown): PipelineSummary | null {
      };
    }
  }
-  const features: Record<string, boolean> = {};
+  const features: Record<string, boolean | number> = {};
  if (item.features && typeof item.features === "object") {
    for (const [name, value] of Object.entries(
      item.features as Record<string, unknown>,
    )) {
-      if (typeof value === "boolean") features[name] = value;
+      if (typeof value === "boolean" || typeof value === "number")
+        features[name] = value;
    }
  }
  const graph =
@@ -210,12 +214,12 @@ export async function composeStatusReport(options: {
    for (const name of SECTION_NAMES) sections[name] = { state, code };
  } else {
    const reader = options.reader;
-    const [sources, sync, processing, model, memories] = await Promise.all([
+    const [sources, sync, processing, model, projection] = await Promise.all([
      reader<unknown>("/api/v1/sources"),
      reader<unknown>("/api/v1/live-sync"),
      reader<unknown>("/api/v1/memory-processing"),
      reader<unknown>("/api/v1/model-profiles"),
-      reader<unknown>("/api/v2/home-summary"),
+      reader<unknown>("/api/v2/home-projection"),
    ]);
    sections.sources = section(sources, validateSources, describeSources);
    sections.sync = section(sync, validateLiveSync, describeSync);
@@ -227,11 +231,7 @@ export async function composeStatusReport(options: {
    pipeline =
      processing.state === "ok" ? describePipeline(processing.data) : null;
    sections.model = section(model, validateModelProfiles, describeModel);
-    sections.memories = section(
-      memories,
-      validateHomeSummary,
-      describeMemories,
-    );
+    sections.memories = await memorySection(reader, projection, pipeline);
  }
  // A bridge we could not inspect is unknown, not broken and not fine.
  const bridge: StatusDocument["bridge"] =
@@ -311,7 +311,9 @@ export function renderStatusText(
  ];
  for (const name of SECTION_NAMES) {
    lines.push(
-      `${SECTION_LABELS[name]}：${sectionLine(report.sections[name])}`,
+      `${sectionLabel(name, report.sections[name])}：${sectionLine(
+        report.sections[name],
+      )}`,
    );
  }
  if (report.pipeline) lines.push(`记忆模式：${pipelineLine(report.pipeline)}`);
@@ -319,6 +321,10 @@ export function renderStatusText(
    report.sections.processing?.embedding_switch,
  );
  if (embeddingSwitch !== null) lines.push(`向量模型：${embeddingSwitch}`);
+  const backoff = modelBackoffLine(report.sections.processing);
+  if (backoff !== null) lines.push(backoff);
+  const drain = writeDrainLine(report.sections.processing);
+  if (drain !== null) lines.push(drain);
  if (report.summary.state === "partial") {
    const notes = [
      report.summary.degraded.length > 0
@@ -334,6 +340,35 @@ export function renderStatusText(
  return lines.join("\n");
 }

+/** "Model paused" while Core's circuit breaker holds model work back; null
+ * otherwise. Nothing to do here: the queue resumes by itself once the model
+ * answers again (or after the model is fixed). */
+function modelBackoffLine(section: Section | undefined): string | null {
+  if (section?.state !== "ok") return null;
+  const error = section.llm_backoff_error;
+  if (typeof error !== "string" || error.length === 0) return null;
+  const until = section.llm_backoff_until;
+  return `模型暂停：${error}，${
+    typeof until === "string" && until.length > 0
+      ? `将于 ${until} 自动重试`
+      : "稍后自动重试"
+  }`;
+}
+
+/** The durable write drain, when it is not simply running: it exited on an
+ * error and is coming back (`restarting`), or it is not running at all. */
+function writeDrainLine(section: Section | undefined): string | null {
+  if (section?.state !== "ok") return null;
+  const state = section.write_drain;
+  if (state !== "restarting" && state !== "stopped") return null;
+  const error = section.write_drain_error;
+  const reason =
+    typeof error === "string" && error.length > 0 ? `（${error}）` : "";
+  return state === "restarting"
+    ? `写入队列：异常退出${reason}，正在自动重启`
+    : `写入队列：已停止${reason}`;
+}
+
 export function pipelineLine(pipeline: PipelineSummary): string {
  const parts: string[] = [pipeline.mode];
  if (pipeline.forced_by_env)
@@ -357,7 +392,10 @@ export function pipelineLine(pipeline: PipelineSummary): string {
  if (changed.length > 0) {
    parts.push(
      `；SDK 功能：${changed
-        .map(([name, value]) => `${name}=${value ? "开" : "关"}`)
+        .map(
+          ([name, value]) =>
+            `${name}=${typeof value === "number" ? value : value ? "开" : "关"}`,
+        )
        .join("、")}`,
    );
  }
@@ -380,15 +418,33 @@ function runtimeLine(report: StatusDocument): string {
  }）`;
 }

+/** Fields that have their own line (or none) instead of a place in the
+ * section's one-line summary. */
+const SECTION_LINE_OMITTED = new Set([
+  "state",
+  "code",
+  "embedding_switch",
+  "llm_backoff_until",
+  "llm_backoff_error",
+  "write_drain",
+  "write_drain_error",
+  "content_plane",
+  "visible_count",
+  "effective_mode",
+]);
+
+function sectionLabel(name: string, section: Section | undefined): string {
+  return name === "memories" && section?.content_plane === "raw"
+    ? "原始对话"
+    : SECTION_LABELS[name];
+}
+
 function sectionLine(section: Section | undefined): string {
  if (!section) return "未检查";
  if (section.state === "not_checked") return "未检查";
  if (section.state !== "ok") return "暂时不可用，请稍后重试";
  return Object.entries(section)
-    .filter(
-      ([key]) =>
-        key !== "state" && key !== "code" && key !== "embedding_switch",
-    )
+    .filter(([key]) => !SECTION_LINE_OMITTED.has(key))
    .map(([key, value]) => `${fieldLabel(key)} ${formatValue(value)}`)
    .join(" ");
 }
@@ -424,6 +480,7 @@ function fieldLabel(key: string): string {
    backlog_pending: "历史待处理",
    outside_window_pending: "稍后处理",
    waiting_for_model: "等待模型",
+    suspended: "来源已暂停",
    completed: "已完成",
    failed: "失败",
    blocked: "卡住",
@@ -433,6 +490,10 @@ function fieldLabel(key: string): string {
    profiles: "配置",
    active: "当前",
    memory_count: "记忆",
+    raw_count: "原始对话",
+    visible_count: "可见",
+    content_plane: "内容层",
+    effective_mode: "模式",
  };
  return labels[key] ?? key;
 }
@@ -504,10 +565,47 @@ function describeProcessing(
      reason: block.reason,
      count: block.count,
    })),
+    suspended: typeof summary.suspended === "number" ? summary.suspended : 0,
+    ...llmBackoffFields(summary),
+    ...writeDrainFields(summary),
    ...embeddingSwitchField(summary),
  };
 }

+/** The model circuit breaker: set only while Core pauses model work because
+ * the provider keeps failing. Both null when nothing is paused. */
+function llmBackoffFields(summary: MemoryProcessingSummary): {
+  llm_backoff_until: string | null;
+  llm_backoff_error: string | null;
+} {
+  const until = summary.llm_backoff_until;
+  const error = summary.llm_backoff_error;
+  return {
+    llm_backoff_until:
+      typeof until === "string" && until.length <= 64 ? until : null,
+    llm_backoff_error:
+      typeof error === "string" && /^[a-z_]{1,64}$/.test(error) ? error : null,
+  };
+}
+
+/** Durable write drain liveness. Null when Core does not report it (older
+ * Core, or recovery has not started the drain yet). */
+function writeDrainFields(summary: MemoryProcessingSummary): {
+  write_drain: "running" | "restarting" | "stopped" | null;
+  write_drain_error: string | null;
+} {
+  const state = summary.write_drain;
+  const error = summary.write_drain_error;
+  return {
+    write_drain:
+      state === "running" || state === "restarting" || state === "stopped"
+        ? state
+        : null,
+    write_drain_error:
+      typeof error === "string" && /^[a-z_]{1,64}$/.test(error) ? error : null,
+  };
+}
+
 /** The running switch or merge, projected; absent when none runs. */
 function embeddingSwitchField(
  summary: MemoryProcessingSummary,
@@ -548,6 +646,70 @@ function describeMemories(summary: SdkHomeSummary): Record<string, unknown> {
  };
 }

+async function memorySection(
+  reader: CoreReader,
+  projection: ReadOutcome<unknown>,
+  pipeline: PipelineSummary | null,
+): Promise<Section> {
+  if (projection.state === "ok") {
+    const parsed = validateHomeProjection(projection.data);
+    return parsed === null
+      ? { state: "invalid", code: "response_invalid" }
+      : { state: "ok", ...describeProjection(parsed) };
+  }
+  if (projection.state !== "not_found") {
+    return {
+      state: projection.state === "denied" ? "denied" : "unavailable",
+      code: projection.code,
+    };
+  }
+  if (pipeline === null) {
+    return { state: "unavailable", code: "effective_mode_unavailable" };
+  }
+  if (pipeline.mode === "lite") {
+    const raw = await reader<unknown>("/api/v2/raw", {
+      limit: 1,
+      offset: 0,
+    });
+    if (raw.state !== "ok") {
+      return {
+        state: raw.state === "denied" ? "denied" : "unavailable",
+        code: raw.code,
+      };
+    }
+    const total = validateRawTotal(raw.data);
+    return total === null
+      ? { state: "invalid", code: "response_invalid" }
+      : {
+          state: "ok",
+          content_plane: "raw",
+          visible_count: total,
+          effective_mode: "lite",
+          raw_count: total,
+        };
+  }
+  const legacy = await reader<unknown>("/api/v2/home-summary");
+  return section(legacy, validateHomeSummary, (summary) => ({
+    content_plane: "memory",
+    visible_count: summary.memory_count,
+    effective_mode: pipeline.mode,
+    ...describeMemories(summary),
+  }));
+}
+
+function describeProjection(
+  projection: HomeProjectionV1,
+): Record<string, unknown> {
+  return {
+    content_plane: projection.capabilities.content_plane,
+    visible_count: projection.visible_count,
+    effective_mode: projection.effective_mode,
+    ...(projection.capabilities.content_plane === "raw"
+      ? { raw_count: projection.visible_count }
+      : { memory_count: projection.visible_count }),
+  };
+}
+
 function sum(
  sources: SourceResponse[],
  key: "imported_conversations" | "imported_messages",
@@ -208,6 +208,27 @@ describe("--user-id on the memory commands", () => {
    expect(direct.get.mock.calls[0][1].params).toEqual({ user_id: "wife" });
  });

+  it("prints the retry code and time of a write still waiting", async () => {
+    direct.get.mockResolvedValue({
+      data: {
+        request_id: REQUEST,
+        state: "accepted",
+        created_at: "T1",
+        updated_at: "T2",
+        error_code: "model_timeout",
+        next_retry_at: "2026-11-02T10:00:00+00:00",
+      },
+    });
+    const text = await capturedRun(["write", "status", REQUEST]);
+    expect(text.stdout).toContain("error_code: model_timeout");
+    expect(text.stdout).toContain("next_retry_at: 2026-11-02T10:00:00+00:00");
+    const json = await capturedRun(["write", "status", REQUEST, "--json"]);
+    expect(JSON.parse(json.stdout).write).toMatchObject({
+      error_code: "model_timeout",
+      next_retry_at: "2026-11-02T10:00:00+00:00",
+    });
+  });
+
  it("passes the user in the body of memory writes and searches", async () => {
    await capturedRun(["memories", "add", "Prefers tea", "--user-id", "wife"]);
    expect(transport.post.mock.calls[0][0]).toBe("/api/v2/memories");
@@ -373,6 +394,48 @@ describe("sources connect for a Hermes profile", () => {
    }
    expect(transport.post).not.toHaveBeenCalled();
  });
+
+  it("says the user id need not equal the Hermes profile name", async () => {
+    const result = await capturedRun([
+      "sources",
+      "connect",
+      "hermes",
+      "--user-id",
+      "wife:work",
+      "--root",
+      "~/.hermes/profiles/wife:work",
+    ]);
+    expect(result.code).toBe(2);
+    expect(result.stderr).toContain("用户 ID 不必等于 Hermes profile 名");
+    expect(result.stderr).toContain(
+      "--user-id wife-work --root ~/.hermes/profiles/wife:work",
+    );
+    expect(transport.post).not.toHaveBeenCalled();
+  });
+
+  it("explains a refused overlapping or profiles-container root", async () => {
+    for (const code of [
+      "hermes_root_is_profiles_container",
+      "hermes_root_overlaps_other_user",
+    ]) {
+      transport.post.mockResolvedValueOnce({
+        status: code.endsWith("container") ? 422 : 409,
+        data: { detail: code },
+      });
+      const result = await capturedRun([
+        "sources",
+        "connect",
+        "hermes",
+        "--user-id",
+        "kid",
+        "--root",
+        "/profiles",
+      ]);
+      expect(result.code).toBe(1);
+      expect(result.stdout).toContain(code);
+      expect(result.stdout).toContain("--root");
+    }
+  });
 });

 async function capturedRun(arguments_: string[]) {
@@ -12,7 +12,7 @@ dependencies = [
    "fastapi>=0.141.1",
    "filelock>=3.32.4",
    # Public SDK version validated against MemHub's permission and recall contracts.
-    "hy-memory==2.0.11",
+    "hy-memory==2.0.14",
    # chromadb arrives through the HY SDK; locked here so an unrelated upgrade
    # cannot move the SDK's store. Built-in embedding consumes numpy directly.
    "chromadb==1.5.9",
@@ -15,6 +15,20 @@ BULK_WORKERS = 3
 SNAPSHOT_WORKERS = 8
 INTERACTIVE_READ_WORKERS = 4
 SOURCE_READER_WORKERS = 4
+# One per source the drain runs side by side (`max_concurrent_sources`), and
+# two over for the outcome inquiries that follow them.
+SDK_WRITE_WORKERS = 12
+# Recall's SDK reads: one search and the `get`s behind it (`_SDK_GET_CONCURRENCY`).
+SDK_READ_WORKERS = 8
+# The durable write queue's own bookkeeping: claim, settle, the per-job reads
+# around an SDK write, and the drain's maintenance passes. Each is one short
+# statement on the single writer or a reader; the drain runs at most
+# `max_concurrent_sources` jobs, and they wait for the writer, not for CPU.
+DURABLE_QUEUE_WORKERS = 4
+# Lease renewal alone. Renewal is the drain's ownership fence: a lease that
+# lapses while its SDK write is still running hands the job to recovery, so it
+# must never wait for a thread behind any other work, its own queue's included.
+LEASE_RENEWAL_WORKERS = 2

 _pool: ThreadPoolExecutor | None = None
 _snapshot_pool: ThreadPoolExecutor | None = None
@@ -22,6 +36,9 @@ _interactive_pool: ThreadPoolExecutor | None = None
 _raw_read_pool: ThreadPoolExecutor | None = None
 _memory_read_pool: ThreadPoolExecutor | None = None
 _source_reader_pool: ThreadPoolExecutor | None = None
+_sdk_write_pool: ThreadPoolExecutor | None = None
+_durable_queue_pool: ThreadPoolExecutor | None = None
+_lease_renewal_pool: ThreadPoolExecutor | None = None
 _warmed_readers: weakref.WeakSet[ThreadPoolExecutor] = weakref.WeakSet()
 _reader_warm_lock = threading.Lock()
 _interactive_reads = 0
@@ -71,15 +88,67 @@ def raw_read_pool() -> ThreadPoolExecutor:


 def memory_read_pool() -> ThreadPoolExecutor:
+    """Recall's own threads: SDK searches, gets, and what decides between them.
+
+    Recall used to hand these to the default pool, which SDK writes share. A
+    write that times out keeps its thread until the SDK returns (#231), so a
+    few stuck writes left recall waiting for a thread while `/health`, which
+    needs none, still answered.
+    """
    global _memory_read_pool
    if _memory_read_pool is None:
        _memory_read_pool = ThreadPoolExecutor(
-            max_workers=INTERACTIVE_READ_WORKERS,
+            max_workers=SDK_READ_WORKERS,
            thread_name_prefix="one-memory-memory-read",
        )
    return _memory_read_pool


+def sdk_write_pool() -> ThreadPoolExecutor:
+    """SDK writes, bounded and apart from everything else.
+
+    Each thread here only waits for the SDK's own loop thread to answer
+    (`_LoopThread.run`), so any thread outside that loop may make the call; a
+    stuck write therefore costs a thread of this pool and nobody else's.
+    """
+    global _sdk_write_pool
+    if _sdk_write_pool is None:
+        _sdk_write_pool = ThreadPoolExecutor(
+            max_workers=SDK_WRITE_WORKERS,
+            thread_name_prefix="one-memory-sdk-write",
+        )
+    return _sdk_write_pool
+
+
+def durable_queue_pool() -> ThreadPoolExecutor:
+    """The durable write queue's database work, apart from bulk work.
+
+    The queue used to hand its claims, settles and maintenance to the bulk
+    pool, whose three threads also carry import heartbeats and job listings.
+    Under an import peak all three sat in those for tens of seconds, and the
+    queue's next statement waited for a thread before it could even join the
+    writer's line, and leases lapsed while their SDK writes were still running.
+    """
+    global _durable_queue_pool
+    if _durable_queue_pool is None:
+        _durable_queue_pool = ThreadPoolExecutor(
+            max_workers=DURABLE_QUEUE_WORKERS,
+            thread_name_prefix="one-memory-write-queue",
+        )
+    return _durable_queue_pool
+
+
+def lease_renewal_pool() -> ThreadPoolExecutor:
+    """Threads that only renew durable write leases (`DurableWriteDrain.renew`)."""
+    global _lease_renewal_pool
+    if _lease_renewal_pool is None:
+        _lease_renewal_pool = ThreadPoolExecutor(
+            max_workers=LEASE_RENEWAL_WORKERS,
+            thread_name_prefix="one-memory-lease-renewal",
+        )
+    return _lease_renewal_pool
+
+
 def source_reader_pool() -> ThreadPoolExecutor:
    """Bounded process-wide pool for source iteration and parsing."""
    global _source_reader_pool
@@ -99,9 +168,21 @@ def warm_bulk_pool() -> None:
    Starting a thread is nothing on an idle machine and 2.5 seconds on a busy
    one, which is precisely when bulk work is being handed over. So it is
    done here instead, at startup, before there is anything to be late for.
+
+    The durable write queue's pools are warmed here too, for the same reason:
+    their first renewal must not pay for starting a thread.
    """
-    pool = bulk_pool()
-    started = tuple(threading.Event() for _ in range(BULK_WORKERS))
+    _start_every_worker(bulk_pool(), BULK_WORKERS, "bulk_pool_warmup_timeout")
+    _start_every_worker(
+        durable_queue_pool(), DURABLE_QUEUE_WORKERS, "durable_queue_pool_warmup_timeout"
+    )
+    _start_every_worker(
+        lease_renewal_pool(), LEASE_RENEWAL_WORKERS, "lease_renewal_pool_warmup_timeout"
+    )
+
+
+def _start_every_worker(pool: ThreadPoolExecutor, workers: int, timeout_code: str) -> None:
+    started = tuple(threading.Event() for _ in range(workers))
    release = threading.Event()

    def occupy(marker: threading.Event) -> None:
@@ -117,7 +198,7 @@ def warm_bulk_pool() -> None:
    try:
        for marker in started:
            if not marker.wait(10):
-                raise RuntimeError("bulk_pool_warmup_timeout")
+                raise RuntimeError(timeout_code)
    finally:
        release.set()
    for future in futures:
@@ -175,6 +256,62 @@ async def in_interactive_read[T](
    return await in_read_pool(interactive_read_pool(), work, *args, **kwargs)


+async def in_sdk_read[T](
+    work: Callable[..., T],
+    /,
+    *args: object,
+    **kwargs: object,
+) -> T:
+    """A recall-path read, in recall's own pool (`memory_read_pool`)."""
+    return await in_read_pool(memory_read_pool(), work, *args, **kwargs)
+
+
+async def in_sdk_write[T](
+    work: Callable[..., T],
+    /,
+    *args: object,
+    **kwargs: object,
+) -> T:
+    """One SDK write call, in the write pool (`sdk_write_pool`)."""
+    return await asyncio.get_running_loop().run_in_executor(
+        sdk_write_pool(),
+        copy_context().run,
+        partial(work, *args, **kwargs),
+    )
+
+
+async def in_the_write_queue[T](
+    work: Callable[..., T],
+    /,
+    *args: object,
+    **kwargs: object,
+) -> T:
+    """One durable write queue statement, in the queue's pool (`durable_queue_pool`).
+
+    It still goes through the one writer and its line, like every write; what
+    it no longer does is wait for a bulk thread first.
+    """
+    return await asyncio.get_running_loop().run_in_executor(
+        durable_queue_pool(),
+        copy_context().run,
+        partial(work, *args, **kwargs),
+    )
+
+
+async def in_lease_renewal[T](
+    work: Callable[..., T],
+    /,
+    *args: object,
+    **kwargs: object,
+) -> T:
+    """One lease renewal, in the threads kept for nothing else (`lease_renewal_pool`)."""
+    return await asyncio.get_running_loop().run_in_executor(
+        lease_renewal_pool(),
+        copy_context().run,
+        partial(work, *args, **kwargs),
+    )
+
+
 def _retrieve[T](future: "asyncio.Future[T]") -> None:
    """Mark a shielded read's outcome as seen.

@@ -261,7 +398,16 @@ def _warm_reader_pool(reader: ThreadPoolExecutor) -> None:

 def shutdown_bulk_pool() -> None:
    global _pool, _snapshot_pool, _interactive_pool, _raw_read_pool, _memory_read_pool
-    global _source_reader_pool
+    global _source_reader_pool, _sdk_write_pool, _durable_queue_pool, _lease_renewal_pool
+    if _durable_queue_pool is not None:
+        _durable_queue_pool.shutdown(wait=False, cancel_futures=True)
+        _durable_queue_pool = None
+    if _lease_renewal_pool is not None:
+        _lease_renewal_pool.shutdown(wait=False, cancel_futures=True)
+        _lease_renewal_pool = None
+    if _sdk_write_pool is not None:
+        _sdk_write_pool.shutdown(wait=False, cancel_futures=True)
+        _sdk_write_pool = None
    if _pool is not None:
        _pool.shutdown(wait=False, cancel_futures=True)
        _pool = None
@@ -0,0 +1,133 @@
+"""The hook side of live capture: hand the turn to the running Core, nothing more.
+
+A host runs `one-memory capture <source>` as a short-lived process on every
+hook, often several at once. That process used to open the main database
+itself and write Evidence and the write queue from outside Core's single
+writer. It now never opens the database: it reads the hook's JSON, posts it to
+the running Core over loopback with the runtime token, and exits. Core applies
+every gate and stages the turn in-process (`live_capture.capture_hook`).
+
+Anything that goes wrong — Core not running, a stale receipt, a slow answer —
+drops the turn silently. There is no local fallback write: file-backed sources
+are read again by live sync from their persisted cursor once Core is back.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import TextIO
+
+CAPTURE_SOURCES = frozenset(
+    {
+        "workbuddy",
+        "claude-code",
+        "codex",
+        "cursor",
+        "pi",
+        "qwen-code",
+        "qwenwork",
+        "hermes",
+        "deepseek-harness",
+        "opencode",
+        "openclaw",
+    }
+)
+SDK_MIGRATION_CAPTURE_FENCE = ".sdk-migration-capture-fence.json"
+#: Core's in-process intake for a hook's payload; see `live_capture`.
+CAPTURE_ROUTE = "/api/v1/live-capture/{source_id}"
+#: Whole request, connect to answer. Pi and OpenCode wait for the hook
+#: synchronously (3 s, interpreter start included), so this stays well under.
+HANDOFF_TIMEOUT_SECONDS = 1.5
+#: A hook carries one turn, or one session's visible text at most.
+MAX_PAYLOAD_BYTES = 8 * 1024 * 1024
+
+
+def data_directory() -> Path:
+    from one_memory.config import load_settings
+
+    return load_settings().data_dir
+
+
+def capture_stdio(source_id: str, stdin: TextIO, output: TextIO) -> int:
+    """Host hooks must stay silent. A bad payload or an absent Core does not fail the turn."""
+
+    del output
+    if source_id not in CAPTURE_SOURCES:
+        return 2
+    try:
+        data_dir = data_directory()
+        if sdk_migration_capture_fenced(data_dir):
+            return 0
+        payload = json.loads(stdin.read() or "")
+    except Exception:
+        return 0
+    if not isinstance(payload, dict):
+        return 0
+    try:
+        hand_to_core(source_id, payload, data_dir)
+    except Exception:
+        return 0
+    return 0
+
+
+def hand_to_core(
+    source_id: str,
+    payload: dict[str, object],
+    data_dir: Path,
+    *,
+    timeout: float = HANDOFF_TIMEOUT_SECONDS,
+) -> bool:
+    """Post the payload to the Core named by this home's receipt. True when Core took it.
+
+    Only the receipt, the runtime token and a loopback socket are touched; the
+    main database is never opened from here.
+    """
+    from one_memory.runtime_client import core_endpoint
+
+    endpoint = core_endpoint(data_dir)
+    if endpoint is None:
+        return False
+    body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    if len(body) > MAX_PAYLOAD_BYTES:
+        return False
+    from one_memory.http_client import create_client
+
+    with create_client(timeout=timeout) as client:
+        response = client.post(
+            f"http://{endpoint.host}:{endpoint.port}{CAPTURE_ROUTE.format(source_id=source_id)}",
+            content=body,
+            headers={
+                "Authorization": f"Bearer {endpoint.token}",
+                "Content-Type": "application/json",
+            },
+        )
+    return response.status_code == 202
+
+
+def sdk_migration_capture_fenced(data_dir: Path) -> bool:
+    """Ignore stale fences; a live migration or a failed one pauses hook writes.
+
+    A failed upgrade migration leaves the fence `frozen` (no pid): the home was
+    put back as it was before the upgrade and takes no writes until the next
+    migration attempt, which replaces the fence and lifts it on success.
+    """
+    marker = data_dir / SDK_MIGRATION_CAPTURE_FENCE
+    try:
+        document = json.loads(marker.read_text(encoding="utf-8"))
+        if isinstance(document, dict) and document.get("frozen") is True:
+            return True
+        pid = int(document["pid"])
+        if pid < 1:
+            raise ValueError("invalid migration fence pid")
+        os.kill(pid, 0)
+        return True
+    except FileNotFoundError:
+        return False
+    except ProcessLookupError:
+        marker.unlink(missing_ok=True)
+        return False
+    except PermissionError:
+        return True
+    except (KeyError, TypeError, ValueError, json.JSONDecodeError, OSError):
+        marker.unlink(missing_ok=True)
+        return False
@@ -119,7 +119,7 @@ def run(arguments: Sequence[str], *, output: TextIO | None = None) -> int:
    if command == "sdk-migration-status":
        return sdk_migration_status(options, stream)
    if command == "capture" and len(options) == 1:
-        from one_memory.live_capture import capture_stdio
+        from one_memory.capture_handoff import capture_stdio

        return capture_stdio(options[0], sys.stdin, stream)
    if command not in {"status", "doctor"} or options not in ([], ["--json"]):
@@ -11,14 +11,14 @@ from one_memory.context_models import ContextSearchRequest
 from one_memory.external_memory_access import ExternalMemoryAccess
 from one_memory.memory_server.store_binding import store_for

-#: The revoked-source query, per engine.
+#: The connected-source query, per engine.
 #:
 #: Identical text today because it uses no placeholders and reads by position,
 #: which both engines support. Kept as a named constant so that adding a
 #: parameter later forces the `?`/`%s` difference to be considered here rather
 #: than being introduced silently at the call site.
-REVOKED_SOURCES_SQL = (
-    "SELECT source_id FROM source_grants WHERE user_id='local' AND revoked_at IS NOT NULL"
+CONNECTED_SOURCES_SQL = (
+    "SELECT DISTINCT source_id FROM source_grants WHERE user_id='local' AND revoked_at IS NULL"
 )


@@ -49,16 +49,10 @@ def resolve_context_authority(
        scope for scope in access.scopes if scope == "all-apps" or scope.startswith("workspace:v1:")
    )
    memory_allowed = memory_requested and "om_recall" in access.tools and bool(memory_scopes)
-    declared_sources = frozenset(
-        scope.removeprefix("source:") for scope in access.scopes if scope.startswith("source:")
-    )
    raw_allowed = (
-        raw_requested
-        and "om_conversations" in access.tools
-        and "all-apps" in access.scopes
-        and bool(declared_sources)
+        raw_requested and "om_conversations" in access.tools and "all-apps" in access.scopes
    )
-    if explicit is not None and (not raw_allowed or not explicit <= declared_sources):
+    if explicit is not None and not raw_allowed:
        raise HTTPException(403, "external_context_scope_denied")

    raw_sources: frozenset[str] = frozenset()
@@ -70,10 +64,10 @@ def resolve_context_authority(
            # the same code runs on both engines without a branch per engine.
            if hasattr(db, "set_progress_handler"):
                db.set_progress_handler(lambda: int(time.monotonic() >= deadline), 1000)
-            revoked = frozenset(str(row[0]) for row in db.execute(REVOKED_SOURCES_SQL))
+            connected = frozenset(str(row[0]) for row in db.execute(CONNECTED_SOURCES_SQL))
        if time.monotonic() >= deadline:
            raise TimeoutError
-        raw_sources = declared_sources - revoked
+        raw_sources = connected
        if explicit is not None:
            if not explicit <= raw_sources:
                raise HTTPException(403, "external_context_scope_denied")
@@ -66,6 +66,8 @@ class SdkContextSearchRequest(ContextSearchRequest, SdkSearchOptions):
    limit: int = Field(default=10, ge=1, le=20, strict=True)
    schema_limit: int = Field(default=3, ge=0, le=20, strict=True)
    intention_limit: int = Field(default=1, ge=0, le=20, strict=True)
+    #: Product callers can request one item per turn instead of SDK raw batches.
+    raw_unit: Literal["raw", "turn"] = "raw"
    #: Whose memories to search. The App never sends it and reads `local`.
    user_id: UserId = DEFAULT_USER_ID

@@ -123,6 +125,9 @@ class SdkRawContextItem(BaseModel):
    memory_at: datetime | None = None
    score: float = Field(ge=0, le=1)
    truncated: bool = False
+    turn_id: str | None = Field(default=None, min_length=1, max_length=96)
+    turn_index: int | None = Field(default=None, ge=0)
+    turn_count: int | None = Field(default=None, ge=1)


 class SdkMemoryContextItem(BaseModel):
@@ -155,6 +160,8 @@ class SdkContextSearchResponse(BaseModel):
    used_characters: int = Field(ge=0, le=20000)
    truncated: bool
    total_ms: float = Field(ge=0)
+    #: Whose memories were searched: the request's `user_id`, else `local`.
+    user_id: str = Field(min_length=1, max_length=64)


 class ContextLaneResult(BaseModel):
@@ -1,6 +1,7 @@
 """Authenticated SDK context search route, without generation or reindex side effects."""

 import asyncio
+import logging
 import time
 from collections.abc import Sequence
 from datetime import UTC, datetime
@@ -30,11 +31,14 @@ from one_memory.hy_sdk_types import (
    parse_sdk_search,
 )
 from one_memory.imports.storage import EvidenceStore
+from one_memory.raw_turns import raw_display_turns, turns_for_hit
 from one_memory.sdk_search_options import SdkSearchFilters, SearchLane
 from one_memory.semantic_deadline import SemanticMemoryHit
 from one_memory.user_scope import owns

 CALL_EVENT_RESPONSE_BUDGET_MS = 250
+SDK_CONTEXT_CONTENT_LIMIT = 20_000
+logger = logging.getLogger(__name__)

 #: Pass-through filters the raw lane honours. Scene, layers, reader and the
 #: schema/working floors describe memory lanes; the raw lane is always the
@@ -70,6 +74,18 @@ def raw_lane_overrides(value: SdkSearchFilters) -> dict[str, object]:
    return found


+def raw_lane_statuses(*, lite: bool) -> dict[str, list[str]]:
+    """Which raw statuses the raw lane searches.
+
+    Lite extracts nothing, so its search is plain RAG over every raw,
+    including the shadow raws pro already processed before the switch to
+    lite. Pro and ultra keep the SDK default (active only): a shadow raw is
+    already represented by the memories extracted from it, and returning it
+    again would repeat that content in the caller's context budget.
+    """
+    return {"statuses": ["active", "shadow"]} if lite else {}
+
+
 def hit_namespace(hit: SemanticMemoryHit) -> dict[str, str]:
    """The `get` namespace of a hit: nothing for chat, kind and variant otherwise."""
    if hit.kind in {"experience", "fact"} and hit.variant is not None:
@@ -77,6 +93,13 @@ def hit_namespace(hit: SemanticMemoryHit) -> dict[str, str]:
    return {}


+def bounded_context_content(content: str) -> tuple[str, bool]:
+    """Fit SDK text into its wire contract before Pydantic validates it."""
+    if len(content) <= SDK_CONTEXT_CONTENT_LIMIT:
+        return content, False
+    return content[:SDK_CONTEXT_CONTENT_LIMIT], True
+
+
 def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
    """SDK-native context: no Evidence/Governance ids or fabricated revisions."""
    router = APIRouter(prefix="/api/v2/context", dependencies=dependencies)
@@ -120,6 +143,9 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
            sources = raw_lane_sources(authority.raw_sources, value.include_sources)
            if sources is None:
                return ()
+            # Plain RAG: every vector hit over the floor is an answer, ranked
+            # by its score. Each hit yields at least one item, so the SDK
+            # needs to return no more hits than the caller's limit.
            raw = await asyncio.to_thread(
                client.search,
                value.query,
@@ -135,27 +161,65 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
                    "scene": "chat",
                    "reader": HY_MEMORY_READER,
                    "layers": ["l1_raw"],
+                    **raw_lane_statuses(lite=lite),
                    **raw_lane_overrides(value),
                },
            )
            hits = tuple(
                hit for hit in parse_sdk_raw_search(raw) if value.passes_floor("raw", hit.score)
            )
-            return tuple(
-                SdkRawContextItem(
-                    raw_id=hit.raw_id,
-                    content=hit.content,
-                    source=hit.source,
-                    session_id=hit.session_id,
-                    memory_at=(
-                        datetime.fromtimestamp(hit.memory_at, tz=UTC)
-                        if hit.memory_at is not None
-                        else None
-                    ),
-                    score=hit.score,
+            # One item per hit first, so a hit is never crowded out by another
+            # hit's sibling turns; the siblings fill whatever room is left.
+            primary: list[SdkRawContextItem] = []
+            siblings: list[SdkRawContextItem] = []
+            for hit in hits:
+                memory_at = (
+                    datetime.fromtimestamp(hit.memory_at, tz=UTC)
+                    if hit.memory_at is not None
+                    else None
                )
-                for hit in hits
-            )
+                turns = raw_display_turns(hit) if value.raw_unit == "turn" else ()
+                if not turns:
+                    content, truncated = bounded_context_content(hit.content)
+                    primary.append(
+                        SdkRawContextItem(
+                            raw_id=hit.raw_id,
+                            content=content,
+                            source=hit.source,
+                            session_id=hit.session_id,
+                            memory_at=memory_at,
+                            score=hit.score,
+                            truncated=truncated,
+                        )
+                    )
+                    continue
+                # The embedding is the batch's: the hit is shown by the turns
+                # that contain the query, or else by its closest turn, each
+                # with the hit's score.
+                shown: list[SdkRawContextItem] = []
+                for turn in turns_for_hit(turns, value.query):
+                    content, truncated = bounded_context_content(turn.content)
+                    shown.append(
+                        SdkRawContextItem(
+                            raw_id=hit.raw_id,
+                            turn_id=turn.turn_id,
+                            turn_index=turn.turn_index,
+                            turn_count=turn.turn_count,
+                            content=content,
+                            source=hit.source,
+                            session_id=hit.session_id,
+                            memory_at=memory_at,
+                            score=hit.score,
+                            truncated=truncated,
+                        )
+                    )
+                primary.append(shown[0])
+                siblings.extend(shown[1:])
+            chosen = primary[: value.limit]
+            chosen.extend(siblings[: value.limit - len(chosen)])
+            # Stable: a hit's turns stay together, in hit-score order.
+            chosen.sort(key=lambda item: item.score, reverse=True)
+            return tuple(chosen)

        async def memory_lane() -> tuple[SdkMemoryContextItem, ...]:
            # lite extracts nothing: its search answers raw turns, which the
@@ -201,16 +265,15 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
                    or not owns(memory.user_id, value.user_id)
                ):
                    continue
+                content, truncated = bounded_context_content(
+                    hit.formatted_content
+                    if hit.sdk_formatted and hit.formatting_complete and hit.formatted_content
+                    else memory.content
+                )
                items.append(
                    SdkMemoryContextItem(
                        memory_id=memory.memory_id,
-                        content=(
-                            hit.formatted_content
-                            if hit.sdk_formatted
-                            and hit.formatting_complete
-                            and hit.formatted_content
-                            else memory.content
-                        ),
+                        content=content,
                        layer=memory.layer,
                        status=memory.status,
                        source=memory.source,
@@ -220,6 +283,7 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
                            else None
                        ),
                        score=hit.score,
+                        truncated=truncated,
                    )
                )
            return tuple(items)
@@ -261,6 +325,7 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
                used_characters=0,
                truncated=True,
                total_ms=(time.monotonic() - started) * 1000,
+                user_id=value.user_id,
            )
            await record(final, timed_out=True)
            return final
@@ -268,10 +333,45 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
            if isinstance(lane, EmbeddingUnavailableError):
                # No lexical fallback: the query could not be embedded.
                raise HTTPException(503, EMBEDDING_UNAVAILABLE)
-        partial = isinstance(raw_items, Exception) or isinstance(memory_items, Exception)
+        requested_lanes = {
+            "raw": raw_items,
+            "memory": memory_items,
+        }
+        failed_lanes = {
+            name: lane
+            for name, lane in requested_lanes.items()
+            if name in value.kinds and isinstance(lane, Exception)
+        }
+        for name, error in failed_lanes.items():
+            logger.warning(
+                "sdk_context_lane_failed lane=%s error_class=%s",
+                name,
+                type(error).__name__,
+            )
+        all_requested_failed = len(failed_lanes) == len(value.kinds)
+        partial = bool(failed_lanes)
        raw_candidates = (
            () if isinstance(raw_items, Exception) else cast(tuple[SdkContextItem, ...], raw_items)
        )
+        if access is not None and raw_candidates:
+            try:
+                current = await asyncio.to_thread(
+                    resolve_context_authority,
+                    value,
+                    access,
+                    database,
+                    deadline=started + value.timeout_ms / 1000,
+                )
+            except HTTPException:
+                raise
+            except Exception:
+                raise HTTPException(503, "context_authority_unavailable") from None
+            current_sources = current.raw_sources or frozenset()
+            raw_candidates = tuple(
+                item
+                for item in raw_candidates
+                if item.kind == "raw" and item.source in current_sources
+            )
        memory_candidates = (
            ()
            if isinstance(memory_items, Exception)
@@ -297,15 +397,25 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
            if len(content) > remaining:
                item = item.model_copy(update={"content": content[:remaining], "truncated": True})
                truncated = True
+            truncated = truncated or item.truncated
            selected.append(item)
            used += len(item.content)
        final = SdkContextSearchResponse(
            request_id=str(uuid4()),
-            state=("partial" if partial else "grounded" if selected else "empty"),
+            state=(
+                "unavailable"
+                if all_requested_failed
+                else "partial"
+                if partial
+                else "grounded"
+                if selected
+                else "empty"
+            ),
            items=tuple(selected),
            used_characters=used,
            truncated=truncated,
            total_ms=(time.monotonic() - started) * 1000,
+            user_id=value.user_id,
        )
        await record(final, timed_out=False)
        return final
@@ -111,10 +111,26 @@ MAIN_DATABASE_CHECKPOINT_WRITE_INTERVAL = 64
 MAIN_DATABASE_CHECKPOINT_SECONDS = 30.0

 # Advisory only: PASSIVE cannot force a frame past a long reader. Crossing this
-# threshold is a signal that the WAL is not converging and that read snapshots
-# or write volume need investigation.
+# threshold with frames still waiting to be copied back is a signal that the
+# WAL is not converging and that read snapshots or write volume need
+# investigation. A large file whose frames are all checkpointed is not: the
+# idle TRUNCATE below gives that space back.
 MAIN_DATABASE_WAL_WARN_BYTES = 512 * 1024 * 1024

+# What a WAL file is cut back to once a checkpoint has copied every frame and
+# the writer starts it over. Without a limit SQLite reuses the file in place
+# and never shrinks it, so one import peak left a 639 MB WAL behind for good
+# (#245). 64 MiB is about sixteen times what the default autocheckpoint (1000
+# pages) lets build up between checkpoints, so ordinary write bursts reuse the
+# file without growing and shrinking it each time, and it is still a tenth of
+# what that user's disk was left holding.
+MAIN_DATABASE_JOURNAL_SIZE_LIMIT_BYTES = 64 * 1024 * 1024
+
+# How long an idle TRUNCATE may wait for the writer or for a reader to leave.
+# It runs only when nothing holds the database; anyone arriving in the
+# meantime wins, and the checkpoint is tried again on the next pass.
+MAIN_DATABASE_IDLE_CHECKPOINT_WAIT_MS = 50
+

 def checkpoint_write_interval() -> int:
    raw = os.environ.get(
@@ -226,6 +242,75 @@ class _InTurn:
            self._line.remove(place)


+class _Checkpointer:
+    """The one thread that runs cadence checkpoints, for every main database.
+
+    A database asks for at most one checkpoint at a time: a request made
+    while one is already waiting is the same request. The checkpoint goes
+    through the database's own writer, in its line, like any other write.
+    A waiting request holds the database weakly: it must not keep alive a
+    database nobody else holds any more.
+    """
+
+    def __init__(self) -> None:
+        self._state = threading.Condition()
+        self._due: OrderedDict[int, weakref.ref[MainDatabase]] = OrderedDict()
+        self._running = 0
+        self._thread: threading.Thread | None = None
+
+    def request(self, database: "MainDatabase") -> None:
+        with self._state:
+            self._due.setdefault(id(database), weakref.ref(database))
+            if self._thread is None or not self._thread.is_alive():
+                self._thread = threading.Thread(
+                    target=self._run,
+                    name="one-memory-checkpoint",
+                    daemon=True,
+                )
+                self._thread.start()
+            self._state.notify_all()
+
+    def forget(self, database: "MainDatabase") -> None:
+        with self._state:
+            self._due.pop(id(database), None)
+            self._state.notify_all()
+
+    def wait_idle(self, timeout: float) -> bool:
+        """Whether every requested checkpoint has run within `timeout` seconds."""
+        with self._state:
+            return self._state.wait_for(lambda: not self._due and not self._running, timeout)
+
+    def _run(self) -> None:
+        while True:
+            with self._state:
+                self._state.wait_for(lambda: bool(self._due))
+                _key, reference = self._due.popitem(last=False)
+                database = reference()
+                if database is None:
+                    self._state.notify_all()
+                    continue
+                self._running += 1
+            try:
+                database._cadence_checkpoint()
+            except Exception:  # noqa: BLE001 - maintenance must not end the thread
+                logger.warning(
+                    "main_database_checkpoint_failed file=%s", database.path.name, exc_info=True
+                )
+            finally:
+                del database
+                with self._state:
+                    self._running -= 1
+                    self._state.notify_all()
+
+
+_checkpointer = _Checkpointer()
+
+
+def wait_for_cadence_checkpoints(timeout: float = 5.0) -> bool:
+    """Wait for the cadence checkpoints already requested; for tests and shutdown."""
+    return _checkpointer.wait_idle(timeout)
+
+
 def _locked() -> sqlite3.OperationalError:
    # Callers tell a busy database from a broken one by these, as they would
    # for SQLite's own refusal.
@@ -276,6 +361,8 @@ class MainDatabase:
        self._writes_since_checkpoint = 0
        self._last_checkpoint_at = time.monotonic()
        self._wal_warned_at = 0.0
+        #: Learned from the first checkpoint; turns WAL frames into bytes.
+        self._page_size = 4096
        self._reader_started_at: dict[int, float] = {}

    @contextmanager
@@ -542,24 +629,77 @@ class MainDatabase:
    def _checkpoint_from_maintenance(self, mode: str) -> tuple[int, int, int]:
        return self._checkpoint(mode, maintenance=True)

-    def _checkpoint(self, mode: str, *, maintenance: bool) -> tuple[int, int, int]:
+    def _checkpoint(
+        self,
+        mode: str,
+        *,
+        maintenance: bool,
+        busy_timeout_ms: int = WRITE_LOCK_WAIT_MS,
+    ) -> tuple[int, int, int]:
        normalized = mode.strip().upper()
        if normalized not in {"PASSIVE", "FULL", "RESTART", "TRUNCATE"}:
            raise ValueError("unsupported WAL checkpoint mode")
-        with self.write(autocommit=True, maintenance=maintenance) as connection:
+        with self.write(
+            autocommit=True, maintenance=maintenance, busy_timeout_ms=busy_timeout_ms
+        ) as connection:
            row = connection.execute(f"PRAGMA wal_checkpoint({normalized})").fetchone()
+            page_size = connection.execute("PRAGMA page_size").fetchone()
        if row is None or len(row) != 3:
            raise sqlite3.DatabaseError("SQLite returned an invalid checkpoint result")
+        if page_size is not None:
+            self._page_size = int(page_size[0])
        return int(row[0]), int(row[1]), int(row[2])

+    def idle(self) -> bool:
+        """Nobody holds or waits for a connection to this database right now."""
+        with self._state:
+            return (
+                self._writer_owner is None
+                and not self._reader_holders
+                and not len(self._write_line)
+                and not len(self._read_line)
+            )
+
+    def checkpoint_if_idle(self) -> tuple[int, int, int] | None:
+        """Give the WAL file back to the disk while nothing is using the database.
+
+        PASSIVE copies frames back but leaves the file its size; only TRUNCATE
+        empties it, and TRUNCATE has to wait for every reader to finish, so it
+        is attempted only when this process holds no checkout at all, and with
+        a wait of a few milliseconds. A busy result, or someone arriving in
+        between, is not a failure: the next idle pass tries again. Returns the
+        checkpoint result, or None when it was not attempted or not admitted.
+        """
+        if not self.idle() or self._wal_bytes() == 0:
+            return None
+        try:
+            return self._checkpoint(
+                "TRUNCATE",
+                maintenance=True,
+                busy_timeout_ms=MAIN_DATABASE_IDLE_CHECKPOINT_WAIT_MS,
+            )
+        except sqlite3.Error:
+            logger.debug("main_database_idle_checkpoint_skipped file=%s", self.path.name)
+            return None
+
    def _maybe_checkpoint_after_write(self) -> None:
-        """Checkpoint on a write cadence without opening another connection.
+        """Count a write, and hand a due cadence checkpoint to the checkpointer.

        SQLite's default autocheckpoint only runs when the writer itself
        crosses the page threshold. Production hit a state where the WAL grew
        to 13GB, so the main database needs its own bounded, observable
-        maintenance path. This runs after the caller's checkout has been reset
-        and only re-enters the same serialized writer queue.
+        maintenance path: every `checkpoint_write_interval()` writes or
+        `MAIN_DATABASE_CHECKPOINT_SECONDS`, whichever comes first.
+
+        The checkpoint itself used to run right here, on the thread that had
+        just written, as one more turn in the writer's line. That thread was
+        an import heartbeat or a durable lease renewal as often as not, and
+        it then waited behind the whole line a second time before it could
+        return. The idle TRUNCATE (#278) cannot replace the cadence: under a
+        sustained import the database is never idle, and that is exactly when
+        the WAL grows. So the cadence stays, and one checkpointer thread runs
+        it (`_Checkpointer`); the writer stays the only connection that
+        writes, and no caller waits for maintenance it did not ask for.
        """
        now = time.monotonic()
        with self._state:
@@ -571,25 +711,35 @@ class MainDatabase:
            if due:
                self._writes_since_checkpoint = 0
                self._last_checkpoint_at = now
-        if not due:
-            return
+        if due:
+            _checkpointer.request(self)
+
+    def _cadence_checkpoint(self) -> None:
+        """One PASSIVE checkpoint through the writer, and the WAL alert after it."""
+        now = time.monotonic()
        try:
            busy, log_frames, checkpointed = self._checkpoint_from_maintenance("PASSIVE")
        except sqlite3.Error:
            logger.warning("main_database_checkpoint_failed file=%s", self.path.name, exc_info=True)
            return
        wal_bytes = self._wal_bytes()
-        if wal_bytes >= MAIN_DATABASE_WAL_WARN_BYTES:
+        # Frames the checkpoint could not copy back yet: what a reader is
+        # holding up. The file size alone also counts space already
+        # checkpointed and only waiting to be reused or truncated, which is
+        # not the WAL failing to converge.
+        pending_bytes = max(0, log_frames - checkpointed) * self._page_size
+        if pending_bytes >= MAIN_DATABASE_WAL_WARN_BYTES:
            with self._state:
                should_warn = now - self._wal_warned_at >= MAIN_DATABASE_REPORT_SECONDS
                if should_warn:
                    self._wal_warned_at = now
            if should_warn:
                logger.warning(
-                    "main_database_wal_high file=%s wal_bytes=%d busy=%d "
+                    "main_database_wal_high file=%s wal_bytes=%d pending_bytes=%d busy=%d "
                    "log_frames=%d checkpointed=%d readers_in_use=%d",
                    self.path.name,
                    wal_bytes,
+                    pending_bytes,
                    busy,
                    log_frames,
                    checkpointed,
@@ -640,6 +790,8 @@ class MainDatabase:

    def close(self) -> None:
        """Close every idle connection now; ones in use close when handed back."""
+        # A checkpoint still waiting would open the writer again after this.
+        _checkpointer.forget(self)
        with self._state:
            self._generation += 1
            self._identity = None
@@ -784,6 +936,10 @@ class MainDatabase:
        try:
            if wal:
                enable_write_ahead_log(connection, wait_ms=busy_timeout_ms)
+            # Only the writer restarts the WAL, so only the writer needs the cap.
+            connection.execute(
+                f"PRAGMA journal_size_limit = {int(MAIN_DATABASE_JOURNAL_SIZE_LIMIT_BYTES)}"
+            )
            _seal(connection)
            if busy_timeout_ms != WRITE_LOCK_WAIT_MS:
                # Opened at the caller's wait; every checkout starts at the default.
@@ -1027,6 +1183,18 @@ def main_database_transaction(
        yield connection


+def checkpoint_idle_main_databases() -> int:
+    """TRUNCATE the WAL of every database nobody is using; how many were emptied."""
+    with _databases_lock:
+        databases = list(_alive.values())
+    emptied = 0
+    for database in databases:
+        result = database.checkpoint_if_idle()
+        if result is not None and result[0] == 0:
+            emptied += 1
+    return emptied
+
+
 def close_main_databases() -> None:
    """Close every connection this process holds; used when the Core stops."""
    with _databases_lock:
@@ -1050,6 +1218,9 @@ async def report_main_database(seconds: float) -> None:
    while True:
        await asyncio.sleep(seconds)
        log_main_database_stats("periodic")
+        # The idle signal is this process's own checkouts: none held, none
+        # waiting. Off the loop, since a checkpoint is disk work however short.
+        await asyncio.to_thread(checkpoint_idle_main_databases)


 def main_database_stats() -> dict[str, float | int]:
@@ -126,15 +126,23 @@ def embedding_switch_router(dependencies: Sequence[Depends]) -> APIRouter:

    @router.post("/api/v1/embedding-switches", status_code=202, response_model=None)
    async def start_embedding_switch(value: EmbeddingSwitchStartRequest, request: Request) -> Any:
-        try:
-            job = await _service(request).start_switch(
-                value.profile_id,
-                expected_revision=value.expected_revision,
-                plan_token=value.plan_token,
-                requested_by=value.requested_by,
-            )
-        except EmbeddingSwitchError as error:
-            return refusal(error.code, plan=error.plan)
+        # One lifecycle lock orders mode/evolve/backfill and embedding
+        # maintenance. Without it each endpoint could pass its own preflight
+        # and then begin concurrently.
+        async with request.app.state.memory_mode_lock:
+            evolve = request.app.state.evolve_service
+            backfill = request.app.state.memory_graph_backfill
+            if evolve.running() or backfill.running:
+                return refusal("memory_lifecycle_busy")
+            try:
+                job = await _service(request).start_switch(
+                    value.profile_id,
+                    expected_revision=value.expected_revision,
+                    plan_token=value.plan_token,
+                    requested_by=value.requested_by,
+                )
+            except EmbeddingSwitchError as error:
+                return refusal(error.code, plan=error.plan)
        return job.model_dump(mode="json")

    @router.get("/api/v1/embedding-switches/current")
@@ -14,7 +14,7 @@ from pathlib import Path
 from typing import Literal, cast

 HY_MEMORY_DISTRIBUTION = "hy-memory"
-HY_MEMORY_VERSION = "2.0.11"
+HY_MEMORY_VERSION = "2.0.14"
 HY_MEMORY_NAMESPACE = "governed-v2"
 DiagnosticLogLevel = Literal["error", "warning", "info", "debug"]

@@ -503,7 +503,7 @@ def _ensure_coding_schema(path: Path) -> None:
        CodingMemoryStore,
    )

-    # Relies on the pinned SDK's internals (hy-memory==2.0.11 is pinned exactly).
+    # Relies on the pinned SDK's internals (hy-memory==2.0.14 is pinned exactly).
    store = CodingMemoryStore.__new__(CodingMemoryStore)
    store._db_path = str(path)
    store._conn = None
@@ -47,8 +47,10 @@ from one_memory.local_embedding import LocalEmbedder
 from one_memory.log_file import confine_hy_sdk_logging
 from one_memory.memory_features import (
    FEATURES,
-    FEATURES_BY_NAME,
+    PARAMETERS,
+    SETTINGS_BY_NAME,
    FeatureOverrides,
+    SettingValue,
    feature_overrides,
 )
 from one_memory.model_profiles import (
@@ -321,21 +323,27 @@ def sdk_relevance_floor() -> float:
    return min(1.0, max(0.0, value))


-def sdk_feature_defaults() -> dict[str, bool]:
-    """Each `memory_features` feature's SDK default, as a fresh config has it.
+def sdk_feature_defaults() -> dict[str, SettingValue]:
+    """Each `memory_features` setting's SDK default, as a fresh config has it.

    That is the SDK's code default unless the process environment sets the
    SDK's own variable (`FeatureSpec.env`), exactly what an unset feature
    leaves on a client.
    """
    config = MemoryConfig()
-    return {
+    defaults: dict[str, SettingValue] = {
        spec.name: bool(getattr(getattr(config, spec.section), spec.field)) for spec in FEATURES
    }
+    for parameter in PARAMETERS:
+        defaults[parameter.name] = float(
+            getattr(getattr(config, parameter.section), parameter.field)
+        )
+    return defaults


 def apply_sdk_features(
-    config: MemoryConfig, features: Mapping[str, bool] | Iterable[tuple[str, bool]]
+    config: MemoryConfig,
+    features: Mapping[str, SettingValue] | Iterable[tuple[str, SettingValue]],
 ) -> MemoryConfig:
    """Set each feature a person chose on its `MemoryConfig` field.

@@ -346,7 +354,7 @@ def apply_sdk_features(
    """
    values = dict(features.items() if isinstance(features, Mapping) else features)
    for name, value in feature_overrides(values):
-        spec = FEATURES_BY_NAME[name]
+        spec = SETTINGS_BY_NAME[name]
        setattr(getattr(config, spec.section), spec.field, value)
    return config

@@ -368,8 +376,9 @@ def apply_sdk_language(config: MemoryConfig, language: str | None) -> MemoryConf
    """Set the SDK prompt language (`MemoryConfig.language`), when there is one.

    None (no language set) sets nothing: the SDK detects zh/en as it always
-    did. Every display language, zh-Hans included, is set explicitly. Like a feature, the language never touches `vector_store`, so
-    the collection identity never depends on it.
+    did. Every display language, zh-Hans included, is set explicitly. Like a
+    feature, the language never touches `vector_store`, so the collection
+    identity never depends on it.
    """
    if language is not None:
        config.language = language
@@ -383,7 +392,7 @@ def build_sdk_config(
    *,
    api_key: str | None,
    data_dir: Path,
-    features: Mapping[str, bool] | Iterable[tuple[str, bool]] = (),
+    features: Mapping[str, SettingValue] | Iterable[tuple[str, SettingValue]] = (),
    language: str | None = None,
 ) -> MemoryConfig:
    """Map a model snapshot and its embedding space to an SDK configuration.
@@ -75,6 +75,9 @@ class HySdkMemoryRecord(BaseModel):
    # Epoch seconds. `updated_at` falls back to `created_at`.
    created_at: int | None = None
    updated_at: int | None = None
+    # Actual scene=all ordering timestamp before the public fallback above.
+    # Internal-only: callers keep the existing SdkMemoryRecord wire shape.
+    sort_updated_at: int | None = Field(default=None, exclude=True, repr=False)

    @classmethod
    def from_sdk(cls, raw: object) -> HySdkMemoryRecord:
@@ -95,6 +98,8 @@ class HySdkMemoryRecord(BaseModel):
            if created_at is None:
                created_at = gmt_created
            updated_at = _epoch(raw.get("updated_at"))
+            modified_at = _epoch(raw.get("gmt_modified"))
+            sort_updated_at = modified_at if modified_at is not None else updated_at
            return cls(
                memory_id=str(raw["memory_id"]),
                content=str(raw["content"]),
@@ -116,6 +121,7 @@ class HySdkMemoryRecord(BaseModel):
                gmt_created=gmt_created,
                created_at=created_at,
                updated_at=updated_at if updated_at is not None else created_at,
+                sort_updated_at=sort_updated_at,
            )
        except (KeyError, TypeError, ValueError) as error:
            raise HySdkReadError("hy_memory_record_shape_unknown") from error
@@ -180,6 +186,7 @@ class HySdkMemoryRecord(BaseModel):
                solution=solution,
                created_at=created_at,
                updated_at=updated_at if updated_at is not None else created_at,
+                sort_updated_at=updated_at,
            )
        except (KeyError, TypeError, ValueError) as error:
            raise HySdkReadError("hy_memory_record_shape_unknown") from error
@@ -436,6 +436,11 @@ def root_identity_matches(root: Path, expected: str) -> bool:
    return _root_identity_matches_details(resolved, details, expected)


+def resolved_source_root(root: Path) -> Path:
+    """The real directory a root names (symlinks followed), as a grant records it."""
+    return _root_details(root)[0]
+
+
 def _check_root_identity(root: Path, expected: str | None) -> None:
    if expected is not None and not root_identity_matches(root, expected):
        raise SourceAccessError(SourceAccessErrorCode.SOURCE_IDENTITY_CHANGED)
@@ -1,6 +1,6 @@
 import hashlib
 import os
-from collections.abc import AsyncIterator, Iterator
+from collections.abc import AsyncIterator, Callable, Iterator
 from dataclasses import dataclass
 from pathlib import Path

@@ -27,7 +27,8 @@ def discovered_off_loop(
    *,
    suffixes: frozenset[str],
    max_targets: int,
-    excluded_top_directories: frozenset[str] = frozenset(),
+    excluded_directory_names: frozenset[str] = frozenset(),
+    directory_predicate: Callable[[Path], bool] | None = None,
 ) -> AsyncIterator[SourceFileDiscoveryEvent]:
    """The same walk, for callers that have an event loop to keep free.

@@ -42,7 +43,8 @@ def discovered_off_loop(
            grant,
            suffixes=suffixes,
            max_targets=max_targets,
-            excluded_top_directories=excluded_top_directories,
+            excluded_directory_names=excluded_directory_names,
+            directory_predicate=directory_predicate,
        ),
        scope_key=grant.source_id,
    )
@@ -53,15 +55,18 @@ def discover_source_files(
    *,
    suffixes: frozenset[str],
    max_targets: int,
-    excluded_top_directories: frozenset[str] = frozenset(),
+    excluded_directory_names: frozenset[str] = frozenset(),
+    directory_predicate: Callable[[Path], bool] | None = None,
 ) -> Iterator[SourceFileDiscoveryEvent]:
    """Metadata only: one lstat per candidate, no open and no per-file grant lookup.

    The grant and root identity are checked once before the walk. Each listed
    file keeps the grant's check, which runs again when that file is opened;
    the open itself refuses symlinks and any inode other than the one listed.
-    `excluded_top_directories` are directories directly under the root that
-    are never entered, such as another user's Hermes profiles.
+    `excluded_directory_names` are directory names never entered, at any
+    depth under the root, such as the `profiles` container that holds other
+    users' Hermes profiles. Any depth, because the granted root may sit above
+    the Hermes home (`~/.hermes` inside it is then `.hermes/profiles`).
    """
    grant.check_root()
    inspected = 0
@@ -69,12 +74,16 @@ def discover_source_files(
        grant.root,
        followlinks=False,
    ):
-        at_root = Path(directory) == grant.root
+        current = Path(directory)
        child_directories[:] = sorted(
            child
            for child in child_directories
-            if not (Path(directory) / child).is_symlink()
-            and not (at_root and child in excluded_top_directories)
+            if not (current / child).is_symlink()
+            and child not in excluded_directory_names
+            and (
+                directory_predicate is None
+                or directory_predicate((current / child).relative_to(grant.root))
+            )
        )
        for filename in sorted(filenames):
            if Path(filename).suffix.lower() not in suffixes:
@@ -1,6 +1,7 @@
 import logging
 import re
 import sqlite3
+from collections.abc import Iterable
 from contextlib import AbstractContextManager, nullcontext
 from datetime import UTC, datetime
 from enum import StrEnum
@@ -18,13 +19,27 @@ from one_memory.imports.adapters import ScanPhase, SourceCursor
 #: the drift would only surface on a fresh database.
 #:
 #: This runs on SQLite today, so the SQLite rendering is used.
-from one_memory.memory_server.migrations import import_jobs_ddl
+from one_memory.memory_server.migrations import (
+    import_job_lookup_indexes_ddl,
+    import_jobs_ddl,
+)

 logger = logging.getLogger("one_memory.imports.jobs")

 JOB_SCHEMA = import_jobs_ddl("sqlite")
+#: Migration 63, applied by the store as well so a running home gets it.
+JOB_LOOKUP_INDEXES = import_job_lookup_indexes_ddl("sqlite")
 MAX_LIVE_BACKLOG_BYTES = 256 * 1024

+#: Finished live syncs kept per (user, source). Live sync opens a job for every
+#: change it imports, and nothing removed them: hundreds a day on an active
+#: machine. The App shows the latest job per source and the active ones; twenty is
+#: that plus enough recent history to read a failure back.
+SYNC_JOBS_KEPT_PER_SOURCE = 20
+#: Rows one pruning transaction may delete, so it holds the single writer for
+#: a few milliseconds at most however large the table grew.
+PRUNE_BATCH_ROWS = 200
+

 class ImportStatus(StrEnum):
    PENDING = "pending"
@@ -36,6 +51,12 @@ class ImportStatus(StrEnum):
    CANCELLED = "cancelled"


+#: States no job ever leaves (`ImportJobStore._TRANSITIONS`). Failed and
+#: interrupted are not among them: both can be resumed, and both still hold the
+#: source's one active slot.
+FINISHED_STATUSES = (ImportStatus.COMPLETED, ImportStatus.CANCELLED)
+
+
 class ImportJob(BaseModel):
    model_config = ConfigDict(frozen=True, extra="forbid")

@@ -272,6 +293,9 @@ class ImportJobStore:
                WHERE status IN ('pending', 'running', 'paused', 'interrupted', 'failed')
                """
            )
+        for statement in JOB_LOOKUP_INDEXES.split(";"):
+            if statement.strip():
+                connection.execute(statement)

    def create(
        self,
@@ -334,8 +358,8 @@ class ImportJobStore:
        read again.
        """
        opened: list[ImportJob] = []
-        for job in self.list_jobs(status=ImportStatus.FAILED):
-            if job.operation != "history" or job.stored != 0:
+        for job in self.find_jobs(operation="history", statuses=(ImportStatus.FAILED,)):
+            if job.stored != 0:
                continue
            reasons = {issue.reason for issue in self.list_issues(job.job_id)}
            if not reasons or not reasons <= self._UNPUBLISHED_SNAPSHOT_FAILURES:
@@ -799,16 +823,172 @@ class ImportJobStore:
        return self.require(job_id)

    def list_jobs(self, *, status: ImportStatus | None = None) -> list[ImportJob]:
+        """Every job, oldest first. Hot paths ask `find_jobs` a narrower question."""
+        return self.find_jobs(statuses=(status,) if status is not None else None)
+
+    def find_jobs(
+        self,
+        *,
+        user_id: str | None = None,
+        source_id: str | None = None,
+        operation: Literal["history", "sync"] | None = None,
+        statuses: Iterable[ImportStatus] | None = None,
+        newest_first: bool = False,
+        limit: int | None = None,
+    ) -> list[ImportJob]:
+        """The jobs matching every given filter, oldest first unless asked otherwise.
+
+        The filters are SQL, served by `import_jobs_lane` / `import_jobs_status`
+        (migration 63). Reading the whole table and filtering here was what
+        three bulk threads and three request threads were all inside, for tens
+        of seconds, while the loop waited on them.
+        """
+        clauses: list[str] = []
+        parameters: list[str | int] = []
+        if user_id is not None:
+            clauses.append("user_id = ?")
+            parameters.append(user_id)
+        if source_id is not None:
+            clauses.append("source_id = ?")
+            parameters.append(source_id)
+        if operation is not None:
+            clauses.append("operation = ?")
+            parameters.append(operation)
+        if statuses is not None:
+            wanted = tuple(dict.fromkeys(ImportStatus(status) for status in statuses))
+            if not wanted:
+                return []
+            clauses.append(f"status IN ({', '.join('?' for _ in wanted)})")
+            parameters.extend(wanted)
        query = "SELECT * FROM import_jobs"
-        parameters: tuple[str, ...] = ()
-        if status is not None:
-            query += " WHERE status = ?"
-            parameters = (status,)
-        query += " ORDER BY created_at, job_id"
+        if clauses:
+            query += " WHERE " + " AND ".join(clauses)
+        query += (
+            " ORDER BY created_at DESC, job_id DESC"
+            if newest_first
+            else " ORDER BY created_at, job_id"
+        )
+        if limit is not None:
+            if limit < 1:
+                raise ValueError("limit must be positive")
+            query += " LIMIT ?"
+            parameters.append(limit)
        with self._connect() as connection:
            rows = connection.execute(query, parameters).fetchall()
        return [self._to_job(row) for row in rows]

+    def latest_job(
+        self,
+        *,
+        user_id: str,
+        source_id: str,
+        operation: Literal["history", "sync"] | None = None,
+        statuses: Iterable[ImportStatus] | None = None,
+    ) -> ImportJob | None:
+        jobs = self.find_jobs(
+            user_id=user_id,
+            source_id=source_id,
+            operation=operation,
+            statuses=statuses,
+            newest_first=True,
+            limit=1,
+        )
+        return jobs[0] if jobs else None
+
+    def prune_finished_sync_jobs(
+        self,
+        *,
+        keep: int = SYNC_JOBS_KEPT_PER_SOURCE,
+        max_rows: int = PRUNE_BATCH_ROWS,
+    ) -> int:
+        """Delete finished live-sync jobs beyond the newest `keep` of each source.
+
+        One bounded transaction: at most `max_rows` jobs, with their issues and
+        skip counts. Returns how many jobs went; fewer than `max_rows` means
+        nothing is left to prune, so calling again until then finishes the job.
+
+        Only `sync` jobs in a state nothing leaves (completed, cancelled) are
+        ever deleted. Failed and interrupted jobs hold the source's active slot
+        and can be resumed; history jobs are named by connection receipts, by
+        the onboarding gate and by the first-import review, and there are a
+        handful per source, so they are all kept. Cursors live in their own
+        tables keyed by file, not by job, so a pruned job takes no position
+        with it. The newest job of every source is always among those kept,
+        which is the one the App and live sync health name.
+        """
+        if keep < 1:
+            raise ValueError("keep must be positive")
+        if max_rows < 1:
+            raise ValueError("max_rows must be positive")
+        finished = tuple(FINISHED_STATUSES)
+        placeholders = ", ".join("?" for _ in finished)
+        deleted = 0
+        with self._connect(writing=True) as connection:
+            lanes = connection.execute(
+                f"""
+                SELECT user_id, source_id, COUNT(*) AS finished
+                FROM import_jobs
+                WHERE operation = 'sync' AND status IN ({placeholders})
+                GROUP BY user_id, source_id
+                HAVING COUNT(*) > ?
+                """,
+                (*finished, keep),
+            ).fetchall()
+            for lane in lanes:
+                if deleted >= max_rows:
+                    break
+                # The oldest job still kept: everything strictly older goes.
+                boundary = connection.execute(
+                    f"""
+                    SELECT created_at, job_id FROM import_jobs
+                    WHERE user_id = ? AND source_id = ? AND operation = 'sync'
+                      AND status IN ({placeholders})
+                    ORDER BY created_at DESC, job_id DESC
+                    LIMIT 1 OFFSET ?
+                    """,
+                    (lane["user_id"], lane["source_id"], *finished, keep - 1),
+                ).fetchone()
+                if boundary is None:
+                    continue
+                victims = [
+                    str(row["job_id"])
+                    for row in connection.execute(
+                        f"""
+                        SELECT job_id FROM import_jobs
+                        WHERE user_id = ? AND source_id = ? AND operation = 'sync'
+                          AND status IN ({placeholders})
+                          AND (created_at < ? OR (created_at = ? AND job_id < ?))
+                        ORDER BY created_at, job_id
+                        LIMIT ?
+                        """,
+                        (
+                            lane["user_id"],
+                            lane["source_id"],
+                            *finished,
+                            boundary["created_at"],
+                            boundary["created_at"],
+                            boundary["job_id"],
+                            max_rows - deleted,
+                        ),
+                    )
+                ]
+                if not victims:
+                    continue
+                marks = ", ".join("?" for _ in victims)
+                # Foreign keys cascade these too; deleting them by name keeps
+                # the outcome the same on a connection that has them off.
+                connection.execute(f"DELETE FROM import_issues WHERE job_id IN ({marks})", victims)
+                connection.execute(
+                    f"DELETE FROM import_skip_reason_counts WHERE job_id IN ({marks})", victims
+                )
+                removed = connection.execute(
+                    f"DELETE FROM import_jobs WHERE job_id IN ({marks}) "
+                    f"AND operation = 'sync' AND status IN ({placeholders})",
+                    (*victims, *finished),
+                )
+                deleted += removed.rowcount
+        return deleted
+
    def get_source_cursors(
        self,
        *,
@@ -28,7 +28,7 @@ from one_memory.imports.adapters import (
 )
 from one_memory.imports.jobs import ImportJob, ImportJobStore, ImportStatus
 from one_memory.imports.supervisor import ImportSupervisor
-from one_memory.user_scope import DEFAULT_USER_ID, lane_key, split_lane
+from one_memory.user_scope import DEFAULT_USER_ID, split_lane

 #: How long an automatic retry will wait for a wedged worker to notice cancel.
 ABANDON_TIMEOUT_SECONDS = 5.0
@@ -249,13 +249,15 @@ class PollingLiveSyncSupervisor:
                    ),
                )
                return None
-            source_jobs = await in_the_background(self.job_store.list_jobs)
+            # This lane's unfinished jobs only: the newest unfinished sync, and
+            # whatever history shares its cursor. Asked in SQL; listing every
+            # job ever run and filtering here was the poll's biggest read.
+            source_jobs = await in_the_background(self._lane_jobs, source_id)
            active_sync = next(
                (
                    job
                    for job in reversed(source_jobs)
-                    if lane_key(job.user_id, job.source_id) == source_id
-                    and job.operation == "sync"
+                    if job.operation == "sync"
                    and job.status
                    in {
                        ImportStatus.PENDING,
@@ -275,7 +277,9 @@ class PollingLiveSyncSupervisor:
                    active_sync.job_id
                ):
                    attempted_at = datetime.now(UTC)
-                    self.import_supervisor.enqueue(active_sync.job_id)
+                    await self.import_supervisor.enqueue_off_loop(
+                        active_sync.job_id, job=active_sync
+                    )
                    if not wait_for_completion:
                        self._observe_sync(source_id, attempted_at, active_sync.job_id)
                        return active_sync
@@ -295,22 +299,20 @@ class PollingLiveSyncSupervisor:
                # by a process restart between yield and claim.  Enqueue is
                # the operation that actually creates the task.
                attempted_at = datetime.now(UTC)
-                self.import_supervisor.resume(active_sync.job_id)
-                self.import_supervisor.enqueue(active_sync.job_id)
+                resumed = await self.import_supervisor.resume_off_loop(active_sync.job_id)
+                await self.import_supervisor.enqueue_off_loop(active_sync.job_id, job=resumed)
                completed = await self.import_supervisor.wait(active_sync.job_id)
                self._record_outcome(source_id, attempted_at, completed)
                return completed
            competing = [
                job
                for job in source_jobs
-                if lane_key(job.user_id, job.source_id) == source_id
-                and job.operation != "sync"
+                if job.operation != "sync"
                and job.status
                in {ImportStatus.PENDING, ImportStatus.RUNNING, ImportStatus.INTERRUPTED}
            ]
            bounded_history_incomplete = any(
-                lane_key(job.user_id, job.source_id) == source_id
-                and job.operation == "history"
+                job.operation == "history"
                and job.history_after is not None
                and job.status is not ImportStatus.COMPLETED
                for job in source_jobs
@@ -354,6 +356,38 @@ class PollingLiveSyncSupervisor:
            # automatically after the realtime slice completes.
            return await self._run_sync(source_id, wait_for_completion=wait_for_completion)

+    def _lane_jobs(self, source_id: str) -> list[ImportJob]:
+        """The lane's jobs `_sync` decides on, oldest first.
+
+        Everything not completed, of either operation: an unfinished sync to
+        pick up, a history that competes for the cursor, and a bounded history
+        that has not completed yet (which includes a cancelled one). Finished
+        syncs, the rows that grow without end, are never read.
+        """
+        user_id, bare_source_id = split_lane(source_id)
+        unfinished = tuple(
+            status for status in ImportStatus if status is not ImportStatus.COMPLETED
+        )
+        return [
+            *self.job_store.find_jobs(
+                user_id=user_id,
+                source_id=bare_source_id,
+                operation="history",
+                statuses=unfinished,
+            ),
+            *self.job_store.find_jobs(
+                user_id=user_id,
+                source_id=bare_source_id,
+                operation="sync",
+                statuses=(
+                    ImportStatus.PENDING,
+                    ImportStatus.RUNNING,
+                    ImportStatus.PAUSED,
+                    ImportStatus.INTERRUPTED,
+                ),
+            ),
+        ]
+
    async def _has_work(self, source_id: str) -> bool:
        """Ask the source whether a scan would write anything, before taking a job out.

@@ -452,7 +486,7 @@ class PollingLiveSyncSupervisor:
            ),
        )
        self._active_jobs[source_id] = job.job_id
-        self.import_supervisor.enqueue(job.job_id)
+        await self.import_supervisor.enqueue_off_loop(job.job_id, job=job)
        if not wait_for_completion:
            self._observe_sync(source_id, attempted_at, job.job_id)
            return job
@@ -557,7 +591,11 @@ class PollingLiveSyncSupervisor:

    async def _poll_source(self, source_id: str) -> None:
        while True:
-            await asyncio.sleep(self.interval_seconds)
+            # A watched source is normally triggered by its filesystem event.
+            # Its timer is only a missed-event backstop; recursively walking
+            # every multi-gigabyte host root once a minute starved unrelated
+            # Core reads even when no source had changed.
+            await asyncio.sleep(self._poll_interval(source_id))
            try:
                await self.trigger(source_id)
            except asyncio.CancelledError:
@@ -574,6 +612,11 @@ class PollingLiveSyncSupervisor:
                except Exception as again:
                    self._note_internal_error(source_id, again)

+    def _poll_interval(self, source_id: str) -> float:
+        if source_id in (self._watched_sources or ()):
+            return max(self.interval_seconds, 15 * 60)
+        return self.interval_seconds
+
    def _note_worker_still_running(self, source_id: str) -> None:
        current = self.health(source_id)
        self._set_health(
@@ -23,6 +23,7 @@ from pathlib import Path

 from watchfiles import awatch

+from one_memory.background_work import in_the_background
 from one_memory.diagnostic_log import diagnostic_event
 from one_memory.imports.jobs import ImportStatus
 from one_memory.imports.live_sync import PollingLiveSyncSupervisor
@@ -90,7 +91,8 @@ class FileWatchLiveSync:
                # turn that caused setup. The watcher cannot observe a change
                # from before it existed, so immediately run the same bounded
                # trigger once instead of waiting for the 60-second backstop.
-                self._queue_changes(set(self.roots.values()))
+                # The roots are this watcher's own sources: nothing to resolve.
+                self._queue_sources(tuple(self.roots), count=len(self.roots))

    async def shutdown(self) -> None:
        task = self._task
@@ -139,28 +141,54 @@ class FileWatchLiveSync:
        observed_at: datetime | None = None,
    ) -> tuple[str, ...]:
        """Queue affected sources and wait for their coalesced work to settle."""
-        workers = self._queue_changes(changed, observed_at=observed_at)
+        workers = await self._queue_changes(changed, observed_at=observed_at)
        await asyncio.gather(*(asyncio.shield(worker) for worker in workers.values()))
        return tuple(workers)

-    def _queue_changes(
+    def sources_for(self, changed: set[Path]) -> tuple[str, ...]:
+        """The sources owning `changed`, in path order. Resolves every path."""
+        return tuple(
+            dict.fromkeys(
+                source
+                for source in (self.source_for(path) for path in sorted(changed))
+                if source is not None
+            )
+        )
+
+    async def _queue_changes(
        self, changed: set[Path], *, observed_at: datetime | None = None
+    ) -> dict[str, asyncio.Task[None]]:
+        """Attribute a batch of changed paths to sources and queue them.
+
+        Attributing resolves each path, a `stat` per component, and a busy
+        host reports hundreds of paths at once. On the loop that was the main
+        thread inside `source_for` while nothing else was answered, so the
+        resolving happens off it and only the queueing here.
+        """
+        if self._stop.is_set():
+            return {}
+        observed = observed_at or datetime.now(UTC)
+        sources = await in_the_background(self.sources_for, changed)
+        return self._queue_sources(sources, count=len(changed), observed_at=observed)
+
+    def _queue_sources(
+        self,
+        sources: tuple[str, ...],
+        *,
+        count: int,
+        observed_at: datetime | None = None,
    ) -> dict[str, asyncio.Task[None]]:
        if self._stop.is_set():
            return {}
        observed = observed_at or datetime.now(UTC)
        workers: dict[str, asyncio.Task[None]] = {}
-        for source_id in dict.fromkeys(
-            source
-            for source in (self.source_for(path) for path in sorted(changed))
-            if source is not None
-        ):
+        for source_id in sources:
            diagnostic_event(
                level="debug",
                component="import.live_watch",
                event="live_sync.hook_received",
                outcome="queued",
-                details={"source_id": source_id, "count": len(changed)},
+                details={"source_id": source_id, "count": count},
            )
            self._pending[source_id] = max(self._pending.get(source_id, observed), observed)
            worker = self._workers.get(source_id)
@@ -239,7 +267,7 @@ class FileWatchLiveSync:
                stop_event=self._stop,
                ignore_permission_denied=True,
            ):
-                self._queue_changes({Path(path) for _change, path in changes})
+                await self._queue_changes({Path(path) for _change, path in changes})
        except asyncio.CancelledError:
            raise
        except Exception:
@@ -209,6 +209,7 @@ class JsonlSourceAdapter:
        file_predicate: Callable[[AuthorizedSourceFile], bool] | None = None,
        suffixes: frozenset[str] = frozenset({".jsonl"}),
        header_selector: Callable[[dict[str, JsonValue]], bool] | None = None,
+        header_gate: Callable[[dict[str, JsonValue] | None], bool] | None = None,
    ) -> None:
        if descriptor.source_id != grant.source_id:
            raise ValueError("Descriptor and authorized root source IDs must match")
@@ -219,8 +220,15 @@ class JsonlSourceAdapter:
        self.file_predicate = file_predicate or (lambda _: True)
        self.suffixes = suffixes
        self.header_selector = header_selector
+        # False refuses the whole file before any record is read. It reports
+        # and leaves no cursor, so a release that learns the format reads the
+        # file from the top instead of finding it already behind a checkpoint.
+        self.header_gate = header_gate
        self._header_cache: dict[str, tuple[str, dict[str, JsonValue] | None]] = {}
        self._history_listing_cache: SourceListing | None = None
+        self._probe_listing_cache: (
+            tuple[dict[str, SourceCursor], int | None, SourceListing] | None
+        ) = None

    @property
    def descriptor(self) -> SourceDescriptor:
@@ -276,6 +284,11 @@ class JsonlSourceAdapter:
            predicate=self.file_predicate,
            cursors=options.cursors,
        )
+        self._probe_listing_cache = (
+            dict(options.cursors),
+            options.max_scan_targets,
+            listing,
+        )
        return bool(listing.changed or listing.failures)

    async def live_baseline(self) -> dict[str, SourceCursor]:
@@ -310,9 +323,11 @@ class JsonlSourceAdapter:
            async for event in self._scan_frozen(options):
                yield event
            return
-        listing = await asyncio.to_thread(
-            self._history_listing if options.reuse_listing else self._fresh_listing,
-            options,
+        listing = (
+            await asyncio.to_thread(self._history_listing, options)
+            if options.reuse_listing
+            else self._take_probe_listing(options)
+            or await asyncio.to_thread(self._fresh_listing, options)
        )
        for failure in listing.failures:
            yield ScanFailure(reason_code=discovery_failure_code(failure))
@@ -344,6 +359,16 @@ class JsonlSourceAdapter:
            self._history_listing_cache = listing
        return listing

+    def _take_probe_listing(self, options: ScanOptions) -> "SourceListing | None":
+        cached = self._probe_listing_cache
+        self._probe_listing_cache = None
+        if cached is None:
+            return None
+        cursors, max_scan_targets, listing = cached
+        if cursors != options.cursors or max_scan_targets != options.max_scan_targets:
+            return None
+        return listing
+
    def _fresh_listing(self, options: ScanOptions) -> "SourceListing":
        return list_changed_files(
            self.grant,
@@ -371,6 +396,9 @@ class JsonlSourceAdapter:
                source_file, checkpoint, header = await asyncio.to_thread(
                    self._prepare, listed, options
                )
+                if self.header_gate is not None and not self.header_gate(header):
+                    yield ScanFailure(reason_code=ScanIssueCode.UNSUPPORTED_SCHEMA)
+                    continue
                _log.debug(
                    "import_file_read source=%s file=%d/%d file_bytes=%d planned_bytes=%d",
                    self.descriptor.source_id,
@@ -574,6 +602,9 @@ class JsonlSourceAdapter:
            # resumed scan starts past the header, and the records after it need
            # it just as much as the first batch did.
            header = await _read_header(reader, source_file, self.header_selector)
+            if self.header_gate is not None and not self.header_gate(header):
+                yield ScanFailure(reason_code=ScanIssueCode.UNSUPPORTED_SCHEMA)
+                continue
            last: SourceCursor = _start_cursor(source_file, options, checkpoint)
            async for raw in iterate_in_worker(
                partial(reader, source_file, checkpoint=checkpoint),
@@ -9,6 +9,7 @@ from collections.abc import AsyncIterator, Iterator
 from dataclasses import dataclass, replace
 from datetime import UTC, datetime, timedelta, timezone
 from functools import partial
+from pathlib import Path

 from pydantic import JsonValue

@@ -175,6 +176,9 @@ class CursorUnifiedSourceAdapter:
        self.grant = grant
        self.source_version = source_version
        self._history_listing_cache: _CursorListing | None = None
+        self._probe_listing_cache: (
+            tuple[dict[str, SourceCursor], int | None, _CursorListing] | None
+        ) = None

    @property
    def descriptor(self) -> SourceDescriptor:
@@ -207,6 +211,15 @@ class CursorUnifiedSourceAdapter:
        state = await self.install_state()
        return min(state.session_count, limit) if limit is not None else state.session_count

+    async def has_changes(self, options: ScanOptions) -> bool:
+        listing = await asyncio.to_thread(self._fresh_listing, options)
+        self._probe_listing_cache = (
+            dict(options.cursors),
+            options.max_scan_targets,
+            listing,
+        )
+        return bool(listing.transcripts or listing.stores or listing.legacy or listing.failures)
+
    async def live_baseline(self) -> dict[str, SourceCursor]:
        """Capture Cursor's current tail so the realtime lane never backfills history."""
        listing = await asyncio.to_thread(
@@ -222,9 +235,11 @@ class CursorUnifiedSourceAdapter:
            async for event in self._scan_frozen(options):
                yield event
            return
-        listing = await asyncio.to_thread(
-            self._history_listing if options.reuse_listing else self._fresh_listing,
-            options,
+        listing = (
+            await asyncio.to_thread(self._history_listing, options)
+            if options.reuse_listing
+            else self._take_probe_listing(options)
+            or await asyncio.to_thread(self._fresh_listing, options)
        )
        for failure in listing.failures:
            yield ScanFailure(reason_code=discovery_failure_code(failure))
@@ -329,6 +344,16 @@ class CursorUnifiedSourceAdapter:
            self._history_listing_cache = listing
        return listing

+    def _take_probe_listing(self, options: ScanOptions) -> "_CursorListing | None":
+        cached = self._probe_listing_cache
+        self._probe_listing_cache = None
+        if cached is None:
+            return None
+        cursors, max_scan_targets, listing = cached
+        if cursors != options.cursors or max_scan_targets != options.max_scan_targets:
+            return None
+        return listing
+
    def _fresh_listing(self, options: ScanOptions) -> "_CursorListing":
        return _list_cursor_files(
            self.grant,
@@ -376,6 +401,7 @@ class CursorUnifiedSourceAdapter:
            self.grant,
            suffixes=frozenset({".db"}),
            max_targets=options.max_scan_targets or 100_000,
+            directory_predicate=_cursor_data_directory,
        ):
            if isinstance(discovered, SourceFileDiscoveryFailure):
                yield ScanFailure(reason_code=discovery_failure_code(discovered))
@@ -477,7 +503,10 @@ def _list_cursor_files(
    legacy: list[AuthorizedSourceFile] = []
    failures: list[SourceFileDiscoveryFailure] = []
    for item in discover_source_files(
-        grant, suffixes=frozenset({".jsonl", ".db", ".vscdb"}), max_targets=max_targets
+        grant,
+        suffixes=frozenset({".jsonl", ".db", ".vscdb"}),
+        max_targets=max_targets,
+        directory_predicate=_cursor_data_directory,
    ):
        if isinstance(item, SourceFileDiscoveryFailure):
            failures.append(item)
@@ -586,6 +615,25 @@ def _is_cursor_data_file(source_file: AuthorizedSourceFile) -> bool:
    )


+def _cursor_data_directory(relative_path: Path) -> bool:
+    """Enter only Cursor directories that can contain conversation authority.
+
+    The granted root also contains extensions, skills, caches, logs and agent
+    artifacts. Recursively walking all of them every live-sync poll made the
+    reader monopolize Core even though none can pass the file predicates.
+    """
+    parts = relative_path.parts
+    if not parts:
+        return False
+    if parts[0] in {"chats", "acp-sessions"}:
+        return True
+    if parts[0] == "projects":
+        return len(parts) <= 2 or parts[2] == "agent-transcripts"
+    if parts[0] == "User":
+        return len(parts) == 1 or parts[1] in {"globalStorage", "workspaceStorage"}
+    return False
+
+
 def _is_transcript_file(source_file: AuthorizedSourceFile) -> bool:
    parts = source_file.relative_path.parts
    return source_file.relative_path.suffix == ".jsonl" and "agent-transcripts" in parts
@@ -634,6 +682,7 @@ def _select_transcript_files(
        grant,
        suffixes=frozenset({".jsonl"}),
        max_targets=100_000,
+        directory_predicate=_cursor_data_directory,
    ):
        if not isinstance(item, AuthorizedSourceFile) or not _is_transcript_file(item):
            continue
@@ -654,6 +703,7 @@ def _subagent_conversation_ids(grant: AuthorizedSourceRoot) -> set[str]:
            grant,
            suffixes=frozenset({".jsonl"}),
            max_targets=100_000,
+            directory_predicate=_cursor_data_directory,
        )
        if isinstance(item, AuthorizedSourceFile)
        and _is_transcript_file(item)
@@ -1,3 +1,4 @@
+import re
 from pathlib import PurePosixPath

 from pydantic import JsonValue
@@ -37,6 +38,19 @@ DEEPSEEK_HARNESS_DESCRIPTOR = SourceDescriptor(
    ),
 )

+#: One session is one file, and the name carries the format generation it was
+#: written in: `session.jsonl[.zstd]` for the first format, then
+#: `session.v3.jsonl.zstd` and `session.v4.jsonl.zstd`. The version segment is
+#: part of the published on-disk contract, so discovery must accept it — the
+#: earlier exact-name match imported none of the versioned files.
+SESSION_FILE = re.compile(r"^session(?:\.v[0-9]+)?\.jsonl(?:\.zstd)?$")
+
+#: Session generations this parser has been verified against: the first format
+#: (header `version: 0`), v3 and v4. Discovery is intentionally wider than
+#: parsing: a future generation is found by pattern and then skipped from its
+#: header, so it is reported as unsupported instead of silently vanishing.
+SUPPORTED_SESSION_VERSIONS = frozenset({0, 3, 4})
+

 def create_deepseek_harness_adapter(
    grant: AuthorizedSourceRoot,
@@ -49,25 +63,43 @@ def create_deepseek_harness_adapter(
        grant=grant,
        parser=parse_deepseek_harness_record,
        source_version=source_version,
-        file_predicate=lambda source_file: (
-            source_file.relative_path.name in {"session.jsonl", "session.jsonl.zstd"}
-        ),
+        file_predicate=lambda source_file: bool(SESSION_FILE.match(source_file.relative_path.name)),
        suffixes=frozenset({".jsonl", ".zstd"}),
        header_selector=_is_session_header,
+        header_gate=_supported_session,
    )


 def _is_session_header(record: dict[str, JsonValue]) -> bool:
    """Harness writes the session's `cwd` once, in the first line only.

-    Verified against a session this machine produced: the header is
-    `{"type":"session","version":0,"id":...,"cwd":"/private/tmp/dsh-verify"}`
-    and no later record repeats it. Read per-record, `cwd` is therefore always
-    absent and every turn imports with no workspace.
+    Verified against sessions this machine produced: the header is
+    `{"type":"session","version":0|4,"id":...,"cwd":...}` and no later record
+    repeats it. Read per-record, `cwd` is therefore always absent and every turn
+    imports with no workspace.
    """
    return record.get("type") == "session"


+def _supported_session(header: dict[str, JsonValue] | None) -> bool:
+    """Whether the session's declared format generation is one we can read.
+
+    A missing header, or a header without `version`, is the first format — the
+    earliest files this adapter already read. Any declared version outside
+    `SUPPORTED_SESSION_VERSIONS` is refused rather than interpreted with today's
+    field rules: a future format may change field semantics, and importing it
+    wrongly is harder to undo than not importing it yet.
+    """
+    if header is None:
+        return True
+    version = header.get("version")
+    if version is None:
+        return True
+    if not isinstance(version, int) or isinstance(version, bool):
+        return False
+    return version in SUPPORTED_SESSION_VERSIONS
+
+
 def parse_deepseek_harness_record(
    record: dict[str, JsonValue],
    context: SourceRecordContext,
@@ -80,6 +112,11 @@ def parse_deepseek_harness_record(
    )
    event_type = record.get("type")
    data = as_record(record.get("data"))
+    if not _supported_session(context.header):
+        return ParsedSkip(
+            reason_code=ScanIssueCode.UNSUPPORTED_SCHEMA,
+            conversation_id=conversation_id,
+        )
    if event_type == "session":
        return ParsedSkip(reason_code=ScanIssueCode.UNKNOWN_RECORD)
    if data is None:
@@ -148,11 +185,18 @@ def _tool_message(
    """`tool/call` carries name and arguments; `tool/result` a user-role message.

    The same call also appears as a `tool-call` block in `assistant/message`;
-    only the event is read, so it is stored once.
+    only the event is read, so it is stored once. The first format and v3 wrap
+    the result in `tool-result` blocks; v4 writes plain `text` blocks, so both
+    shapes are read through the same clipping and credential-scrubbing path.
    """
    message = as_record(data.get("message"))
    if record.get("type") == "tool/result" and message is not None:
        text = tool_blocks_evidence(message.get("content"), block_types=frozenset({"tool-result"}))
+        if text is None:
+            text = tool_blocks_evidence(
+                [{"type": "tool-result", "content": message.get("content")}],
+                block_types=frozenset({"tool-result"}),
+            )
        message_id = first_string(message.get("id"), data.get("callId"))
    else:
        text = tool_evidence_text(data)
@@ -1,9 +1,9 @@
 import json
 import re
 import sqlite3
-from collections.abc import AsyncIterator, Iterator
+from collections.abc import AsyncIterator, Iterable, Iterator
 from functools import partial
-from pathlib import PurePosixPath
+from pathlib import Path, PurePosixPath

 from pydantic import JsonValue

@@ -88,7 +88,7 @@ class HermesSourceAdapter:
            self.grant,
            suffixes=frozenset({".jsonl", ".db"}),
            max_targets=10_000,
-            excluded_top_directories=frozenset({HERMES_PROFILES_DIRECTORY}),
+            excluded_directory_names=frozenset({HERMES_PROFILES_DIRECTORY}),
        ):
            if isinstance(item, AuthorizedSourceFile) and _is_hermes_target(
                item.relative_path.as_posix()
@@ -102,7 +102,7 @@ class HermesSourceAdapter:
            self.grant,
            suffixes=frozenset({".jsonl", ".db"}),
            max_targets=options.max_scan_targets or 100_000,
-            excluded_top_directories=frozenset({HERMES_PROFILES_DIRECTORY}),
+            excluded_directory_names=frozenset({HERMES_PROFILES_DIRECTORY}),
        ):
            yield ScanProgressEvent(
                phase=ScanPhase.DISCOVER,
@@ -253,16 +253,62 @@ def parse_hermes_rollout_record(
 #: own `state.db` and sessions. A profile is another person's history: it is
 #: read only through its own grant (its own MemHub user), never as part of the
 #: root above it. Hermes' own export skips this directory for the same reason.
+#:
+#: Skipped at any depth, not only directly under the root: a root granted
+#: above the Hermes home holds `.hermes/profiles/`. Hermes keeps nothing of
+#: its own under a directory of that name (its history is `state.db` and
+#: `sessions/`), so nothing real is lost.
 HERMES_PROFILES_DIRECTORY = "profiles"


 def _is_hermes_target(relative_path: str) -> bool:
    path = PurePosixPath(relative_path)
-    if path.parts and path.parts[0] == HERMES_PROFILES_DIRECTORY:
+    if HERMES_PROFILES_DIRECTORY in path.parts[:-1]:
        return False
    return path.name == "state.db" or (path.suffix == ".jsonl" and "sessions" in path.parts)


+def hermes_root_is_profiles_container(root: Path) -> bool:
+    """`profiles` itself holds everyone's profiles; it is never one person's history."""
+    return root.name == HERMES_PROFILES_DIRECTORY
+
+
+def hermes_root_conflict(mine: Path, other_users_roots: Iterable[Path]) -> str | None:
+    """Why the resolved root `mine` may not be granted beside other users' Hermes roots.
+
+    Paths are compared resolved (symlinks followed; the other users' roots are
+    resolved here). Two roots that are equal or nest would read the same files
+    for two users, except when one is exactly the other's `profiles/<name>`:
+    the scan above never enters `profiles/`, so the two stay apart (`local` on
+    `~/.hermes`, a user on `~/.hermes/profiles/<name>`). None when it may.
+    """
+    if hermes_root_is_profiles_container(mine):
+        return HERMES_ROOT_IS_PROFILES_CONTAINER
+    for other in other_users_roots:
+        theirs = _real(other)
+        if mine == theirs:
+            return HERMES_ROOT_OVERLAPS_OTHER_USER
+        for parent, child in ((mine, theirs), (theirs, mine)):
+            if parent in child.parents:
+                relative = child.relative_to(parent).parts
+                if len(relative) != 2 or relative[0] != HERMES_PROFILES_DIRECTORY:
+                    return HERMES_ROOT_OVERLAPS_OTHER_USER
+    return None
+
+
+#: 422: the root is the `profiles` container, not a profile.
+HERMES_ROOT_IS_PROFILES_CONTAINER = "hermes_root_is_profiles_container"
+#: 409: the root is, holds or sits inside another user's Hermes root.
+HERMES_ROOT_OVERLAPS_OTHER_USER = "hermes_root_overlaps_other_user"
+
+
+def _real(path: Path) -> Path:
+    try:
+        return path.expanduser().resolve(strict=False)
+    except (OSError, RuntimeError):
+        return path.expanduser().absolute()
+
+
 def _read_rollout(
    source_file: AuthorizedSourceFile,
    options: ScanOptions,
@@ -10,7 +10,10 @@ from pydantic import JsonValue
 from one_memory.input_sanitization import sanitize_model_input

 _REMINDER_TAGS = r"additional_data|system[-_]reminder|working_memory_reminder"
-_CONTEXT_TAGS = r"user_info|rules|agent_transcripts|system[-_]notification|pipeline_log"
+_CONTEXT_TAGS = (
+    r"user_info|rules|agent_transcripts|attached_files|image_local_path|"
+    r"system[-_]notification|pipeline_log"
+)
 _TAG_ATTRIBUTES = r"""(?:\s+[\w:-]+\s*=\s*(?:"[^"<>]*"|'[^'<>]*'))*\s*"""
 _HOST_PREFIX = re.compile(rf"<(?P<tag>{_REMINDER_TAGS}|{_CONTEXT_TAGS}){_TAG_ATTRIBUTES}>")
 _REMINDER_START = re.compile(rf"<(?P<tag>{_REMINDER_TAGS}){_TAG_ATTRIBUTES}>")
@@ -1,6 +1,7 @@
 import asyncio
 from collections.abc import Awaitable, Callable, Mapping
 from contextlib import suppress
+from functools import partial
 from time import monotonic
 from typing import Literal

@@ -82,6 +83,10 @@ class ImportSupervisor:
        )
        self._tasks: dict[str, asyncio.Task[None]] = {}
        self._drains: dict[str, asyncio.Task[None]] = {}
+        #: Pause and cancel settle a stopped job with a read and a transition.
+        #: Made on the loop, two of them could not interleave; made off it,
+        #: they are serialized here so they still land in the order they woke.
+        self._settling = asyncio.Lock()

    def register_adapter(self, adapter: SourceAdapter, *, user_id: str = "local") -> None:
        """Adapters are keyed by lane: the source id for `local`, `source@user`
@@ -116,11 +121,44 @@ class ImportSupervisor:
            raise UnknownSourceError(lane)
        if self.source_enabled is not None and not self.source_enabled(lane):
            return job
-        existing = self._tasks.get(job_id)
+        self._start(job)
+        return job
+
+    async def enqueue_off_loop(self, job_id: str, *, job: ImportJob | None = None) -> ImportJob:
+        """`enqueue`, with its job read and its grant check made off the loop.
+
+        Both are database reads, and the grant check resolves the source root
+        on disk. Live sync enqueues from its poll, so on the loop they were
+        the main thread waiting for a reader behind an import peak. `job` is
+        the row the caller has just read, when it has one.
+        """
+        if job_id in self._drains:
+            raise InvalidJobTransitionError("import_cleanup_in_progress")
+
+        def admit() -> tuple[ImportJob, bool]:
+            current = job if job is not None and job.job_id == job_id else None
+            if current is None:
+                current = self.job_store.require(job_id)
+            lane = self.lane_of(current)
+            return current, self.source_enabled is None or self.source_enabled(lane)
+
+        current, enabled = await in_the_background(admit)
+        lane = self.lane_of(current)
+        if lane not in self.adapters:
+            raise UnknownSourceError(lane)
+        if job_id in self._drains:
+            raise InvalidJobTransitionError("import_cleanup_in_progress")
+        if enabled:
+            self._start(current)
+        return current
+
+    def _start(self, job: ImportJob) -> None:
+        lane = self.lane_of(job)
+        existing = self._tasks.get(job.job_id)
        if existing is None or existing.done():
-            self._tasks[job_id] = asyncio.create_task(
+            self._tasks[job.job_id] = asyncio.create_task(
                self._execute(
-                    job_id,
+                    job.job_id,
                    source_id=lane,
                    operation=job.operation,
                )
@@ -130,10 +168,24 @@ class ImportSupervisor:
                component="import.supervisor",
                event="import.queued",
                outcome="queued",
-                job_id=job_id,
+                job_id=job.job_id,
                details={"source_id": job.source_id, "mode": job.operation},
            )
-        return job
+
+    async def resume_interrupted_off_loop(self) -> None:
+        """`resume_interrupted` for the running Core: every read and write off the loop."""
+        for status in (ImportStatus.INTERRUPTED, ImportStatus.PENDING):
+            jobs = await in_the_background(partial(self.job_store.find_jobs, statuses=(status,)))
+            for job in jobs:
+                if self.lane_of(job) not in self.adapters:
+                    continue
+                if job.status is not ImportStatus.PENDING:
+                    if self.source_enabled is not None and not await in_the_background(
+                        self.source_enabled, self.lane_of(job)
+                    ):
+                        continue
+                    job = await in_the_background(self.job_store.queue_for_resume, job.job_id)
+                await self.enqueue_off_loop(job.job_id, job=job)

    def resume_interrupted(self) -> None:
        # A process restart must not place recoverable work behind every newly
@@ -166,40 +218,64 @@ class ImportSupervisor:
        self.enqueue(job_id)
        return queued

+    async def resume_off_loop(self, job_id: str) -> ImportJob:
+        """`resume`, with its reads and its write made off the event loop."""
+        if job_id in self._drains:
+            raise InvalidJobTransitionError("import_cleanup_in_progress")
+        queued = await in_the_background(self._queue_resumable, job_id)
+        if queued.status is not ImportStatus.PENDING:
+            return queued
+        return await self.enqueue_off_loop(job_id, job=queued)
+
+    def _queue_resumable(self, job_id: str) -> ImportJob:
+        job = self.job_store.require(job_id)
+        if job.status not in {
+            ImportStatus.PENDING,
+            ImportStatus.PAUSED,
+            ImportStatus.INTERRUPTED,
+            ImportStatus.FAILED,
+        }:
+            return job
+        return self.job_store.queue_for_resume(job_id)
+
    async def wait(self, job_id: str) -> ImportJob:
        task = self._tasks.get(job_id)
        if task is not None:
            await asyncio.shield(task)
-        return self.job_store.require(job_id)
+        return await in_the_background(self.job_store.require, job_id)

    async def pause(self, job_id: str) -> ImportJob:
-        job = self.job_store.require(job_id)
+        job = await in_the_background(self.job_store.require, job_id)
        if job.status in {ImportStatus.PAUSED, ImportStatus.INTERRUPTED}:
            return job
        await self._cancel_task(job_id)
-        current = self.job_store.require(job_id)
-        if current.status is ImportStatus.COMPLETED:
-            return current
-        return self.job_store.transition(job_id, ImportStatus.PAUSED)
+        async with self._settling:
+            return await in_the_background(self._settle_stopped, job_id, ImportStatus.PAUSED)

    async def cancel(self, job_id: str) -> ImportJob:
-        job = self.job_store.require(job_id)
+        job = await in_the_background(self.job_store.require, job_id)
        if job.status is ImportStatus.CANCELLED:
            return job
        await self._cancel_task(job_id)
+        async with self._settling:
+            return await in_the_background(self._settle_stopped, job_id, ImportStatus.CANCELLED)
+
+    def _settle_stopped(self, job_id: str, target: ImportStatus) -> ImportJob:
+        """A stopped runner's job moves to `target`, unless it completed first."""
        current = self.job_store.require(job_id)
        if current.status is ImportStatus.COMPLETED:
            return current
-        return self.job_store.transition(job_id, ImportStatus.CANCELLED)
+        return self.job_store.transition(job_id, target)

    async def shutdown(self) -> None:
-        running = [
-            job
-            for job in self.job_store.list_jobs(status=ImportStatus.RUNNING)
-            if job.job_id in self._tasks
-        ]
-        for job in running:
-            self.job_store.interrupt_running(job.job_id)
+        mine = frozenset(self._tasks)
+
+        def interrupt_mine() -> None:
+            for job in self.job_store.find_jobs(statuses=(ImportStatus.RUNNING,)):
+                if job.job_id in mine:
+                    self.job_store.interrupt_running(job.job_id)
+
+        await in_the_background(interrupt_mine)
        await asyncio.gather(
            *(self._cancel_task(job_id) for job_id in tuple(self._tasks)),
        )
@@ -355,9 +431,7 @@ class ImportSupervisor:
            try:
                await asyncio.wait_for(asyncio.shield(task), timeout)
            except TimeoutError:
-                current = self.job_store.require(job_id)
-                if current.status is ImportStatus.RUNNING:
-                    self.job_store.interrupt_running(job_id)
+                await in_the_background(self._interrupt_if_running, job_id)
                return False
            except asyncio.CancelledError:
                # The worker noticed cancel and exited. A cancel of this
@@ -365,10 +439,16 @@ class ImportSupervisor:
                caller = asyncio.current_task()
                if caller is not None and caller.cancelling():
                    raise
+        # A read and a write on the single writer: off the loop. Live sync
+        # calls this from its poll, and on the loop it was the main thread
+        # waiting its turn for the writer behind an import peak.
+        await in_the_background(self._interrupt_if_running, job_id)
+        return True
+
+    def _interrupt_if_running(self, job_id: str) -> None:
        current = self.job_store.require(job_id)
        if current.status is ImportStatus.RUNNING:
            self.job_store.interrupt_running(job_id)
-        return True

    async def _cancel_task(self, job_id: str) -> None:
        drain = self._drains.get(job_id)
@@ -15,9 +15,7 @@ class HyLifecycle:
        object.__setattr__(self, "hidden", MappingProxyType(dict(self.hidden)))

    def __eq__(self, other: object) -> bool:
-        return isinstance(other, HyLifecycle) and dict(self.hidden) == dict(
-            other.hidden
-        )
+        return isinstance(other, HyLifecycle) and dict(self.hidden) == dict(other.hidden)

    def __hash__(self) -> int:
        return hash(tuple(sorted(self.hidden.items())))
@@ -27,9 +25,5 @@ class HyLifecycle:

    def replacing(self, memory_id: str) -> tuple[str, ...]:
        return tuple(
-            sorted(
-                old
-                for old, replacements in self.hidden.items()
-                if memory_id in replacements
-            )
+            sorted(old for old, replacements in self.hidden.items() if memory_id in replacements)
        )
@@ -1,15 +1,35 @@
-"""Write visible hook text into Evidence. Tool output stays out."""
+"""Core's intake for host hooks: visible text only, staged under Core's writer.

+The hook process (`capture_handoff`) never opens the database; it posts the
+hook's JSON to `POST /api/v1/live-capture/{source}` on the running Core, which
+calls `capture_hook` here. Tool output stays out.
+
+A source that live sync already reads from its own files is left to that
+path: the hook and the file name the same message differently (the hook has
+no workspace and often no message id), so staging both sent one turn to the
+SDK twice. Only a source no file poller follows is staged from the hook.
+"""
+
+import asyncio
 import json
-import os
 import time
+from collections.abc import Callable
 from datetime import UTC, datetime
 from enum import StrEnum
 from pathlib import Path
-from typing import TextIO, cast
+from typing import cast

+from fastapi import APIRouter, HTTPException, Request
+from fastapi.params import Depends
 from pydantic import JsonValue

+from one_memory.capture_handoff import (
+    CAPTURE_ROUTE,
+    CAPTURE_SOURCES,
+    MAX_PAYLOAD_BYTES,
+    SDK_MIGRATION_CAPTURE_FENCE,
+    sdk_migration_capture_fenced,
+)
 from one_memory.database_access import main_database
 from one_memory.derived_echo import PREFACE, strip_injected_memory
 from one_memory.imports.access import opaque_workspace_id, safe_project_label
@@ -19,6 +39,7 @@ from one_memory.imports.models import (
    EvidenceRecord,
    OriginMetadata,
    WrittenBy,
+    materialize_write_input,
 )
 from one_memory.imports.sources.claude_code import parse_claude_code_record
 from one_memory.imports.sources.codex import HARNESS_PREFIXES, parse_codex_record
@@ -38,23 +59,21 @@ from one_memory.imports.sources.parsing import (
 )
 from one_memory.imports.sources.pi import _is_automated_session
 from one_memory.imports.sources.workbuddy import _is_scheduled_automation, parse_workbuddy_record
-from one_memory.imports.storage import EvidenceStore
+from one_memory.memory_server.durable_queue import DurableWriteQueue
+from one_memory.sdk_data_plane_migration import MemoryAuthority
+
+__all__ = [
+    "CAPTURE_SOURCES",
+    "SDK_MIGRATION_CAPTURE_FENCE",
+    "CaptureOutcome",
+    "CaptureRejection",
+    "capture_hook",
+    "capture_rejection",
+    "live_capture_router",
+    "record_capture_rejection",
+    "sdk_migration_capture_fenced",
+]

-CAPTURE_SOURCES = frozenset(
-    {
-        "workbuddy",
-        "claude-code",
-        "codex",
-        "cursor",
-        "pi",
-        "qwen-code",
-        "qwenwork",
-        "hermes",
-        "deepseek-harness",
-        "opencode",
-        "openclaw",
-    }
-)
 _UNKNOWN_USER = frozenset({"hermes", "opencode", "openclaw"})
 _USER_FIELDS = {
    "UserPromptSubmit": "prompt",
@@ -75,112 +94,130 @@ _FILE_FALLBACK = {
 }
 _FALLBACK_EVENTS = frozenset({"Stop", "stop", "SubagentStop", "StopFailure"})
 _TEXT_BLOCKS = frozenset({"text"})
-SDK_MIGRATION_CAPTURE_FENCE = ".sdk-migration-capture-fence.json"


-def database_path() -> Path:
-    from one_memory.config import load_settings
+class CaptureOutcome(StrEnum):
+    """What Core did with one hook payload. Never the payload itself."""

-    return load_settings().data_dir / "one-memory.sqlite3"
+    STAGED = "staged"
+    #: Live sync reads this source's own files; that path owns the turn.
+    FILE_POLLED = "file_polled"
+    REJECTED = "rejected"
+    IGNORED = "ignored"


-def capture_stdio(source_id: str, stdin: TextIO, output: TextIO) -> int:
-    """Host hooks must stay silent. A bad payload does not fail the turn."""
+def capture_hook(
+    source_id: str,
+    payload: object,
+    database: Path,
+    *,
+    queue: DurableWriteQueue,
+    file_polled: Callable[[str], bool] = lambda _source_id: False,
+) -> CaptureOutcome:
+    """Gate one hook payload and stage its visible lines, inside Core.

-    del output
-    if source_id not in CAPTURE_SOURCES:
-        return 2
-    database = database_path()
-    if sdk_migration_capture_fenced(database.parent):
-        return 0
-    try:
-        payload = json.loads(stdin.read() or "")
-    except json.JSONDecodeError:
-        return 0
-    try:
-        capture_hook(source_id, payload, database)
-    except Exception:
-        return 0
-    return 0
-
-
-def sdk_migration_capture_fenced(data_dir: Path) -> bool:
-    """Ignore stale fences; a live migration or a failed one pauses hook writes.
-
-    A failed upgrade migration leaves the fence `frozen` (no pid): the home was
-    put back as it was before the upgrade and takes no writes until the next
-    migration attempt, which replaces the fence and lifts it on success.
+    Runs on SDK authority through Core's single writer: the lines become
+    write-job input exactly as live file sync stages them
+    (`materialize_write_input` -> `stage_sdk_input` -> `finalize_sdk_file`,
+    live priority). No Evidence table is involved.
    """
-    marker = data_dir / SDK_MIGRATION_CAPTURE_FENCE
-    try:
-        document = json.loads(marker.read_text(encoding="utf-8"))
-        if isinstance(document, dict) and document.get("frozen") is True:
-            return True
-        pid = int(document["pid"])
-        if pid < 1:
-            raise ValueError("invalid migration fence pid")
-        os.kill(pid, 0)
-        return True
-    except FileNotFoundError:
-        return False
-    except ProcessLookupError:
-        marker.unlink(missing_ok=True)
-        return False
-    except PermissionError:
-        return True
-    except (KeyError, TypeError, ValueError, json.JSONDecodeError, OSError):
-        marker.unlink(missing_ok=True)
-        return False
-
-
-def capture_hook(source_id: str, payload: object, database: Path) -> bool:
    if source_id not in CAPTURE_SOURCES or not isinstance(payload, dict):
-        return False
+        return CaptureOutcome.IGNORED
    # Cursor also runs ~/.claude/settings.json hooks; its own hook already files the turn.
    if source_id != "cursor" and "cursor_version" in payload:
-        return False
+        return CaptureOutcome.IGNORED
    if not database.is_file():
-        return False
+        return CaptureOutcome.IGNORED
    rejection = capture_rejection(database, source_id)
    if rejection is not None:
        # Silent, and the reason is counted rather than printed: a hook that
        # spoke would put this into the host's turn as text.
        record_capture_rejection(database, source_id, rejection)
-        return False
+        return CaptureOutcome.REJECTED
    if source_id == "pi" and _is_automated_session(first_string(payload.get("cwd"))):
-        return False
-    lines = _messages(source_id, payload)
-    if lines:
-        conversation_id = _conversation(payload)
-        store = EvidenceStore(database)
-        wrote = False
-        for role, written_by, verbatim, message_id in lines:
-            target = conversation_id
-            if target is None:
-                continue
-            result = store.put(
-                EvidenceInput(
-                    source_id=source_id,
-                    conversation_id=target,
-                    message_id=message_id,
-                    source_ordinal=None if message_id else "hook-visible",
-                    role=role,
-                    written_by=written_by,
-                    created_at=datetime.now(UTC),
-                    verbatim=verbatim,
-                    origin_meta={EvidenceOrigin.HOOK: OriginMetadata()},
-                )
-            )
-            _submit_live_memory(
-                store, result.record, changed=result.was_created or result.was_revised
-            )
-            wrote = True
-        return wrote
-    return _capture_transcript(source_id, payload, database)
+        return CaptureOutcome.IGNORED
+    if file_polled(source_id):
+        # The same turn reaches the SDK once, from the file: the two lanes give
+        # one message different identities, so staging both wrote it twice.
+        return CaptureOutcome.FILE_POLLED
+    inputs = _hook_inputs(source_id, payload) or _capture_transcript(source_id, payload, database)
+    if not inputs:
+        return CaptureOutcome.IGNORED
+    observed = datetime.now(UTC)
+    conversations: dict[str, list[EvidenceRecord]] = {}
+    for value in inputs:
+        conversations.setdefault(value.conversation_id, []).append(
+            materialize_write_input(value, observed_at=observed)
+        )
+    for conversation_id, records in conversations.items():
+        # The turn rule decides what is written (`turn_batches`): a turn is
+        # complete when the next user message arrives, batches are 5 turns or
+        # 8000 characters, and Core writes the rest after 10 quiet minutes.
+        queue.assemble_live_records(tuple(records), file_key=f"hook:{conversation_id}")
+    return CaptureOutcome.STAGED


-def _sync_open(database: Path, source_id: str) -> bool:
-    return capture_rejection(database, source_id) is None
+def _hook_inputs(source_id: str, payload: dict[str, object]) -> list[EvidenceInput]:
+    conversation_id = _conversation(payload)
+    if conversation_id is None:
+        return []
+    observed = datetime.now(UTC)
+    return [
+        EvidenceInput(
+            source_id=source_id,
+            conversation_id=conversation_id,
+            message_id=message_id,
+            source_ordinal=None if message_id else "hook-visible",
+            role=role,
+            written_by=written_by,
+            created_at=observed,
+            verbatim=verbatim,
+            origin_meta={EvidenceOrigin.HOOK: OriginMetadata()},
+        )
+        for role, written_by, verbatim, message_id in _messages(source_id, payload)
+    ]
+
+
+def live_capture_router(
+    dependencies: list[Depends],
+    *,
+    file_polled: Callable[[Request, str], bool],
+) -> APIRouter:
+    """`POST /api/v1/live-capture/{source_id}`: a hook's payload, handed over by the hook.
+
+    202 whatever the gates decide, so a hook has nothing to print. The answer
+    names the outcome only, never any of the payload.
+    """
+    router = APIRouter(dependencies=dependencies)
+
+    @router.post(CAPTURE_ROUTE, status_code=202)
+    async def live_capture(source_id: str, request: Request) -> dict[str, str]:
+        if source_id not in CAPTURE_SOURCES:
+            raise HTTPException(status_code=404, detail="capture_source_not_found")
+        body = await request.body()
+        if len(body) > MAX_PAYLOAD_BYTES:
+            raise HTTPException(status_code=413, detail="capture_payload_too_large")
+        try:
+            payload = json.loads(body)
+        except (json.JSONDecodeError, UnicodeError) as error:
+            raise HTTPException(status_code=422, detail="capture_payload_invalid") from error
+        state = request.app.state
+        queue = getattr(state, "memory_write_queue", None)
+        if getattr(state, "memory_authority", None) is not MemoryAuthority.SDK or queue is None:
+            # Only an SDK-authority home is served; nothing here may bring the
+            # retired Evidence tables back for any other.
+            return {"outcome": CaptureOutcome.IGNORED.value}
+        outcome = await asyncio.to_thread(
+            capture_hook,
+            source_id,
+            payload,
+            queue.database_path,
+            queue=queue,
+            file_polled=lambda source: file_polled(request, source),
+        )
+        return {"outcome": outcome.value}
+
+    return router


 class CaptureRejection(StrEnum):
@@ -255,22 +292,6 @@ def record_capture_rejection(
        return


-def _submit_live_memory(store: EvidenceStore, record: EvidenceRecord, *, changed: bool) -> None:
-    """Add the record to its conversation's live assembling row.
-
-    The turn rule decides what is written (`turn_batches`): a turn is
-    complete when the next user message arrives, batches are 5 turns or
-    8000 characters, and Core writes the rest after 10 quiet minutes.
-    """
-    if not changed or not _sync_open(store.database_path, record.source_id):
-        return
-    from one_memory.memory_server.durable_queue import DurableWriteQueue
-
-    DurableWriteQueue(store.database_path, evidence=store).assemble_live_records(
-        (record,), file_key=f"hook:{record.conversation_id}"
-    )
-
-
 def _conversation(payload: dict[str, object]) -> str | None:
    return first_string(
        cast(JsonValue | None, payload.get("session_id")),
@@ -470,34 +491,35 @@ def _opencode_messages(
    return lines


-def _capture_transcript(source_id: str, payload: dict[str, object], database: Path) -> bool:
+def _capture_transcript(
+    source_id: str, payload: dict[str, object], database: Path
+) -> list[EvidenceInput]:
    """Stop without in-memory text reads the granted transcript, then the same parser."""

    event = payload.get("hook_event_name") or payload.get("hookEventName")
    parser = _FILE_FALLBACK.get(source_id)
    transcript = payload.get("transcript_path")
    if event not in _FALLBACK_EVENTS or parser is None or not isinstance(transcript, str):
-        return False
+        return []
    root = _grant_root(database, source_id)
    if root is None:
-        return False
+        return []
    try:
        granted = root.resolve()
        target = Path(transcript).resolve()
    except OSError:
-        return False
+        return []
    if target != granted and granted not in target.parents:
-        return False
+        return []
    if not target.is_file():
-        return False
+        return []
    _wait_stable(target)
    try:
        raw = target.read_text(encoding="utf-8")
    except OSError:
-        return False
+        return []
    relative = target.relative_to(granted).as_posix()
-    store = EvidenceStore(database)
-    wrote = False
+    inputs: list[EvidenceInput] = []
    for index, line in enumerate(raw.splitlines()):
        if not line.strip():
            continue
@@ -514,7 +536,7 @@ def _capture_transcript(source_id: str, payload: dict[str, object], database: Pa
        if not isinstance(parsed, ParsedMessage):
            continue
        for row_index, row in enumerate(parsed.rows()):
-            result = store.put(
+            inputs.append(
                EvidenceInput(
                    source_id=source_id,
                    workspace=opaque_workspace_id(source_id, row.workspace),
@@ -533,11 +555,7 @@ def _capture_transcript(source_id: str, payload: dict[str, object], database: Pa
                    origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
                )
            )
-            _submit_live_memory(
-                store, result.record, changed=result.was_created or result.was_revised
-            )
-        wrote = True
-    return wrote
+    return inputs


 def _grant_root(database: Path, source_id: str) -> Path | None:
@@ -34,6 +34,7 @@ from one_memory.memory_governance import MemoryGovernanceStore, MemoryStatus
 from one_memory.memory_server.durable_queue import DurableWriteQueue
 from one_memory.memory_server.unified_entry import UnifiedWriteIntake
 from one_memory.memory_tasks import MemoryTaskStatus, MemoryTaskStore
+from one_memory.model_backoff import next_retry_at
 from one_memory.secrets import SecretStoreUnavailableError
 from one_memory.user_scope import DEFAULT_USER_ID, USER_ID_PATTERN, UserId

@@ -77,6 +78,12 @@ class MemoryAddReceipt(BaseModel):
    task_id: str | None = None
    memory_ids: list[str] = Field(default_factory=list)
    error: str | None = None
+    #: Why a note still being worked on last failed (`model_auth_failed`, ...),
+    #: or why a failed one failed. A provider failure keeps it `pending`.
+    error_code: str | None = None
+    #: When a pending note is next tried: its own retry wait, or the model
+    #: provider's pause while the provider is failing.
+    next_retry_at: str | None = None


 class LegacyMemoryAdditionReader:
@@ -258,6 +265,8 @@ class MemoryAdditionStore:
            durable_state = durable.state if durable is not None else "failed"
            mapped: MemoryAddState = {
                "pending": "pending",
+                # Re-run automatically within seconds (`recover_unknown`).
+                "unknown": "pending",
                "running": "running",
                "waiting_for_model": "waiting_for_model",
                "waiting_for_permission": "waiting_for_permission",
@@ -272,6 +281,12 @@ class MemoryAdditionStore:
                state=mapped,
                memory_ids=(list(durable.sdk_memory_ids) if durable is not None else []),
                error=durable.detail if durable is not None else "write_missing",
+                error_code=(
+                    durable.error_code
+                    if durable is not None and durable.state != "completed"
+                    else None
+                ),
+                next_retry_at=durable.retry_at if durable is not None else None,
            )
        if self.processor is None:
            raise RuntimeError("legacy_memory_add_processor_unavailable")
@@ -402,10 +417,15 @@ def memory_add_router(dependencies: Sequence[Depends]) -> APIRouter:
        user_id: str = Query(default=DEFAULT_USER_ID, pattern=USER_ID_PATTERN),
    ) -> MemoryAddReceipt:
        try:
-            return store(request).receipt_for_request(request_id, user_id=user_id)
+            receipt = store(request).receipt_for_request(request_id, user_id=user_id)
        except KeyError as error:
            raise HTTPException(404, "memory_add_not_found") from error
        except ValueError as error:
            raise HTTPException(409, str(error)) from error
+        return receipt.model_copy(
+            update={
+                "next_retry_at": next_retry_at(request.app, receipt.state, receipt.next_retry_at)
+            }
+        )

    return router
@@ -465,12 +465,16 @@ class EvolveScheduler:
        service: EvolveService,
        schedule: Callable[[], EvolveSchedule],
        users_with_memories: Callable[[], Awaitable[Iterable[str]]],
+        lifecycle_lock: asyncio.Lock | None = None,
+        lifecycle_open: Callable[[], bool] = lambda: True,
        now: Callable[[], datetime] = lambda: datetime.now().astimezone(),
        check_seconds: float = SCHEDULE_CHECK_SECONDS,
    ) -> None:
        self.service = service
        self.schedule = schedule
        self.users_with_memories = users_with_memories
+        self.lifecycle_lock = lifecycle_lock
+        self.lifecycle_open = lifecycle_open
        self._now = now
        self.check_seconds = check_seconds
        self._task: asyncio.Task[None] | None = None
@@ -492,7 +496,15 @@ class EvolveScheduler:
            if not evolve_due(now, schedule, last, anchor):
                continue
            try:
-                receipt = self.service.start(user_id, trigger="scheduled")
+                if self.lifecycle_lock is None:
+                    if not self.lifecycle_open():
+                        break
+                    receipt = self.service.start(user_id, trigger="scheduled")
+                else:
+                    async with self.lifecycle_lock:
+                        if not self.lifecycle_open():
+                            break
+                        receipt = self.service.start(user_id, trigger="scheduled")
            except EvolveModeError:
                break
            await self.service.wait(receipt.run_id)
@@ -533,10 +545,12 @@ class MemoryGraphBackfill:
        *,
        coordinator: EvolveCoordinator,
        state: EvolveStateStore,
+        lifecycle_open: Callable[[], bool] = lambda: True,
        now: Callable[[], datetime] = lambda: datetime.now(UTC),
    ) -> None:
        self.coordinator = coordinator
        self.state = state
+        self.lifecycle_open = lifecycle_open
        self._now = now
        self._task: asyncio.Task[None] | None = None

@@ -557,6 +571,35 @@ class MemoryGraphBackfill:
        self._task = asyncio.create_task(self._run(users), name="one-memory-graph-backfill")
        return state

+    def recover(self, user_ids: Iterable[str]) -> GraphBuildState:
+        """Resume an interrupted backfill without repeating completed users."""
+        if self.running:
+            return self.state.graph_build()
+        saved = self.state.graph_build()
+        if saved.state != "running":
+            return saved
+        users = tuple(dict.fromkeys((*saved.users.keys(), *user_ids)))
+        pending = tuple(
+            user_id
+            for user_id in users
+            if saved.users.get(user_id, GraphBuildUser()).state != "succeeded"
+        )
+        resumed = saved.model_copy(deep=True)
+        for user_id in pending:
+            resumed.users[user_id] = GraphBuildUser()
+        if not pending:
+            resumed.state = "succeeded"
+            resumed.finished_at = self._now()
+            self.state.set_graph_build(resumed)
+            return resumed
+        resumed.state = "running"
+        resumed.finished_at = None
+        self.state.set_graph_build(resumed)
+        self._task = asyncio.create_task(
+            self._run(pending), name="one-memory-graph-backfill-recovery"
+        )
+        return resumed
+
    async def wait(self) -> None:
        if self._task is not None:
            await asyncio.shield(self._task)
@@ -564,6 +607,8 @@ class MemoryGraphBackfill:
    async def _run(self, users: tuple[str, ...]) -> None:
        state = self.state.graph_build()
        for user_id in users:
+            while not self.lifecycle_open():
+                await asyncio.sleep(0.2)
            state.users[user_id] = GraphBuildUser(state="running")
            await asyncio.to_thread(self.state.set_graph_build, state.model_copy(deep=True))
            try:
@@ -21,6 +21,11 @@ exercises (query rewrite needs `queries=[...]`, session narratives need
 cross-encoder download, access write-back); and everything MemHub already
 controls elsewhere (pipeline log, trace, memory operations, telemetry, mode).

+Beside the on/off features there is one numeric parameter,
+`intention_dedup_threshold` (`PARAMETERS`): the cosine similarity at which the
+read-time intention dedup treats two intentions as copies. It is set, stored,
+reset and keyed exactly like a feature.
+
 No SDK import here: only `hy_sdk_runtime` and `hy_sdk_migration` import it.
 `config_state` imports this module, so it imports nothing from there.
 """
@@ -31,7 +36,7 @@ from collections.abc import Mapping
 from dataclasses import dataclass
 from typing import Literal

-from pydantic import BaseModel, ConfigDict, StrictBool
+from pydantic import BaseModel, ConfigDict, Field, StrictBool

 MemoryFeatureName = Literal[
    "graph_rerank",
@@ -40,8 +45,13 @@ MemoryFeatureName = Literal[
    "session_episodes",
    "episode_summary",
    "intention",
+    "intention_dedup",
    "few_shot",
 ]
+#: Numeric settings beside the on/off features.
+MemoryParameterName = Literal["intention_dedup_threshold"]
+#: Every key of the setting: a feature or a parameter.
+MemorySettingName = MemoryFeatureName | MemoryParameterName
 #: Read features change search; write features change what extraction stores.
 FeatureSide = Literal["read", "write"]
 #: none: no extra call. extra_query: one more store query per search.
@@ -49,9 +59,25 @@ FeatureSide = Literal["read", "write"]
 #: a longer extraction prompt.
 FeatureCost = Literal["none", "extra_query", "llm_call", "prompt_tokens"]
 #: Why an enabled feature does nothing right now (`active: false`).
-FeatureReason = Literal["disabled", "requires_pro", "requires_ultra", "requires_graph_rerank"]
+FeatureReason = Literal[
+    "disabled",
+    "requires_pro",
+    "requires_ultra",
+    "requires_graph_rerank",
+    "requires_intention_dedup",
+]
+#: A feature is on or off; a parameter is a number.
+type SettingValue = bool | float
 #: A client's features as a hashable key: sorted (name, value) pairs, set ones only.
-type FeatureOverrides = tuple[tuple[str, bool], ...]
+type FeatureOverrides = tuple[tuple[str, SettingValue], ...]
+
+#: The range a person may set `intention_dedup_threshold` to. With dedup on,
+#: the SDK deletes every intention at or above it from the store at read time,
+#: which cannot be undone; below 0.8 the embedding models MemHub uses score
+#: different plans on one topic as that close, so a lower value would delete
+#: intentions that are not copies. 1.0 keeps only exact copies' dedup.
+INTENTION_DEDUP_THRESHOLD_MIN = 0.8
+INTENTION_DEDUP_THRESHOLD_MAX = 1.0

 _MODE_RANK: dict[str, int] = {"lite": 0, "pro": 1, "ultra": 2}

@@ -169,6 +195,23 @@ FEATURES: tuple[FeatureSpec, ...] = (
            "No extra call."
        ),
    ),
+    FeatureSpec(
+        name="intention_dedup",
+        section="recall",
+        field="intention_dedup_enabled",
+        env="MEMORY_INTENTION_DEDUP_ENABLED",
+        side="read",
+        requires_mode="pro",
+        requires_feature=None,
+        cost="none",
+        description=(
+            "Treat same-day intentions (L7) with the same expiry and a cosine "
+            "similarity at or above intention_dedup_threshold as copies: a "
+            "search returns the earliest and deletes the others from the store. "
+            "On by default; off hides, drops and deletes no intention, at read "
+            "time or in a write batch. No extra call."
+        ),
+    ),
    FeatureSpec(
        name="few_shot",
        section="llm",
@@ -189,12 +232,57 @@ FEATURE_NAMES: tuple[MemoryFeatureName, ...] = tuple(spec.name for spec in FEATU
 FEATURES_BY_NAME: dict[str, FeatureSpec] = {spec.name: spec for spec in FEATURES}


+@dataclass(frozen=True)
+class ParameterSpec:
+    """A numeric setting; it acts only while `requires_feature` acts."""
+
+    name: MemoryParameterName
+    section: Literal["recall"]
+    field: str
+    env: str
+    minimum: float
+    maximum: float
+    requires_feature: MemoryFeatureName
+    description: str
+
+    @property
+    def sdk_field(self) -> str:
+        return f"{self.section}.{self.field}"
+
+
+PARAMETERS: tuple[ParameterSpec, ...] = (
+    ParameterSpec(
+        name="intention_dedup_threshold",
+        section="recall",
+        field="intention_dedup_threshold",
+        env="MEMORY_INTENTION_DEDUP_THRESHOLD",
+        minimum=INTENTION_DEDUP_THRESHOLD_MIN,
+        maximum=INTENTION_DEDUP_THRESHOLD_MAX,
+        requires_feature="intention_dedup",
+        description=(
+            "Cosine similarity at or above which intention_dedup treats two "
+            "intentions as copies. Higher keeps more. The SDK default is 0.95 "
+            "(MEMORY_DEDUP_THRESHOLD also sets it when its own env var is unset)."
+        ),
+    ),
+)
+PARAMETER_NAMES: tuple[MemoryParameterName, ...] = tuple(spec.name for spec in PARAMETERS)
+PARAMETERS_BY_NAME: dict[str, ParameterSpec] = {spec.name: spec for spec in PARAMETERS}
+#: Every key of the setting, features first, each in its catalog order.
+SETTING_NAMES: tuple[MemorySettingName, ...] = (*FEATURE_NAMES, *PARAMETER_NAMES)
+SETTINGS_BY_NAME: dict[str, FeatureSpec | ParameterSpec] = {
+    **FEATURES_BY_NAME,
+    **PARAMETERS_BY_NAME,
+}
+
+
 class MemoryFeatures(BaseModel):
    """`config.json` `memory_features`, and the `PUT` body.

    Every key is optional; absent (or null) means the SDK default. In a `PUT`
-    an absent key is left as it is and null resets it. Unknown keys and
-    non-boolean values are refused (422).
+    an absent key is left as it is and null resets it. Unknown keys,
+    non-boolean feature values and a threshold that is not a number in its
+    range are refused (422).
    """

    model_config = ConfigDict(frozen=True, extra="forbid", strict=True)
@@ -205,7 +293,14 @@ class MemoryFeatures(BaseModel):
    session_episodes: StrictBool | None = None
    episode_summary: StrictBool | None = None
    intention: StrictBool | None = None
+    intention_dedup: StrictBool | None = None
    few_shot: StrictBool | None = None
+    intention_dedup_threshold: float | None = Field(
+        default=None,
+        ge=INTENTION_DEDUP_THRESHOLD_MIN,
+        le=INTENTION_DEDUP_THRESHOLD_MAX,
+        allow_inf_nan=False,
+    )

    def overrides(self) -> FeatureOverrides:
        """The features a person set, as the client key."""
@@ -221,24 +316,47 @@ class MemoryFeatures(BaseModel):
        return MemoryFeatures(**{key: value for key, value in values.items() if value is not None})


-def feature_overrides(values: Mapping[str, bool]) -> FeatureOverrides:
-    unknown = set(values) - set(FEATURES_BY_NAME)
+def feature_overrides(values: Mapping[str, SettingValue]) -> FeatureOverrides:
+    unknown = set(values) - set(SETTINGS_BY_NAME)
    if unknown:
        raise ValueError("unknown_memory_feature")
-    return tuple(sorted((name, bool(value)) for name, value in values.items()))
+    return tuple(sorted((name, _setting_value(name, value)) for name, value in values.items()))
+
+
+def _setting_value(name: str, value: SettingValue) -> SettingValue:
+    parameter = PARAMETERS_BY_NAME.get(name)
+    if parameter is None:
+        return bool(value)
+    if isinstance(value, bool) or not parameter.minimum <= float(value) <= parameter.maximum:
+        raise ValueError("invalid_memory_feature_value")
+    return float(value)


 def effective_features(
-    overrides: FeatureOverrides, defaults: Mapping[str, bool]
-) -> dict[str, bool]:
-    """Every feature's value: what a person set, else the SDK default."""
-    values: dict[str, bool] = {spec.name: bool(defaults.get(spec.name, False)) for spec in FEATURES}
+    overrides: FeatureOverrides, defaults: Mapping[str, SettingValue]
+) -> dict[str, SettingValue]:
+    """Every setting's value: what a person set, else the SDK default."""
+    values: dict[str, SettingValue] = {
+        spec.name: bool(defaults.get(spec.name, False)) for spec in FEATURES
+    }
+    for parameter in PARAMETERS:
+        if parameter.name in defaults:
+            values[parameter.name] = float(defaults[parameter.name])
    values.update(dict(overrides))
    return values


-def feature_activity(name: str, effective: Mapping[str, bool], mode: str) -> FeatureReason | None:
-    """None when the feature acts in this mode; else why it does not."""
+def feature_activity(
+    name: str, effective: Mapping[str, SettingValue], mode: str
+) -> FeatureReason | None:
+    """None when the feature acts in this mode; else why it does not.
+
+    A parameter acts exactly when the feature it tunes acts.
+    """
+    parameter = PARAMETERS_BY_NAME.get(name)
+    if parameter is not None:
+        reason = feature_activity(parameter.requires_feature, effective, mode)
+        return "requires_intention_dedup" if reason == "disabled" else reason
    spec = FEATURES_BY_NAME[name]
    if not effective.get(name, False):
        return "disabled"
@@ -252,11 +370,12 @@ def feature_activity(name: str, effective: Mapping[str, bool], mode: str) -> Fea


 def non_default_features(
-    overrides: FeatureOverrides, defaults: Mapping[str, bool]
-) -> dict[str, bool]:
-    """The features whose value differs from the SDK default, for status."""
+    overrides: FeatureOverrides, defaults: Mapping[str, SettingValue]
+) -> dict[str, SettingValue]:
+    """The settings whose value differs from the SDK default, for status."""
+    baseline = effective_features((), defaults)
    return {
        name: value
        for name, value in effective_features(overrides, defaults).items()
-        if value != bool(defaults.get(name, False))
+        if value != baseline.get(name)
    }
@@ -153,6 +153,11 @@ class ConfigStore:
        with self._lock:
            return self._document.memory_mode

+    def memory_mode_explicitly_configured(self) -> bool:
+        """Whether a person chose the mode, including choosing the default."""
+        with self._lock:
+            return "memory_mode" in self._document.model_fields_set
+
    def set_memory_mode(self, mode: MemoryMode) -> ConfigDocument:
        if mode not in MEMORY_MODES:
            raise ValueError("invalid_memory_mode")
@@ -3163,6 +3163,137 @@ async def _060_memory_note_requests(cursor: Any) -> None:
        await cursor.execute(statement)


+def write_job_retries_ddl(dialect: str = "mysql") -> str:
+    """Per-job retry state: which SDK request id is next, and retries spent.
+
+    The SDK replays a request id's first outcome forever, so every re-run of
+    a job needs an id of its own (`sdk_attempt`). `retries` counts automatic
+    retries after failures of the job itself; provider failures spend none.
+    """
+    if dialect == "sqlite":
+        return """
+ALTER TABLE memory_write_jobs
+ADD COLUMN sdk_attempt INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memory_write_jobs
+ADD COLUMN retries INTEGER NOT NULL DEFAULT 0;
+"""
+    return """
+ALTER TABLE memory_write_jobs
+ADD COLUMN sdk_attempt INT NOT NULL DEFAULT 0;
+ALTER TABLE memory_write_jobs
+ADD COLUMN retries INT NOT NULL DEFAULT 0;
+"""
+
+
+async def _061_write_job_retries(cursor: Any) -> None:
+    for statement in _split_statements(write_job_retries_ddl(_dialect(cursor))):
+        await cursor.execute(statement)
+
+
+ONBOARDING_PROGRESS_MIGRATION_VERSION = 62
+
+
+def onboarding_progress_ddl(dialect: str = "mysql") -> str:
+    """Append resumable onboarding choices without rewriting migration 12."""
+    if dialect == "sqlite":
+        return """
+ALTER TABLE onboarding_state
+ADD COLUMN mode_intent TEXT NULL;
+ALTER TABLE onboarding_state
+ADD COLUMN setup_step TEXT NULL;
+ALTER TABLE onboarding_state
+ADD COLUMN model_profile_id TEXT NULL;
+"""
+    return """
+ALTER TABLE onboarding_state
+ADD COLUMN mode_intent VARCHAR(16) NULL AFTER updated_at;
+ALTER TABLE onboarding_state
+ADD COLUMN setup_step VARCHAR(16) NULL AFTER mode_intent;
+ALTER TABLE onboarding_state
+ADD COLUMN model_profile_id VARCHAR(36) NULL AFTER setup_step;
+"""
+
+
+async def _062_onboarding_progress(cursor: Any) -> None:
+    if _dialect(cursor) == "sqlite":
+        existing = await cursor.columns("onboarding_state")
+        statements = _split_statements(onboarding_progress_ddl("sqlite"))
+        for column, statement in zip(
+            ("mode_intent", "setup_step", "model_profile_id"),
+            statements,
+            strict=True,
+        ):
+            if column not in existing:
+                await cursor.execute(statement)
+        return
+    for statement in _split_statements(onboarding_progress_ddl("mysql")):
+        try:
+            await cursor.execute(statement)
+        except Exception as error:  # noqa: BLE001 - MySQL driver error type varies
+            if _is_duplicate_column(error):
+                continue
+            raise
+
+
+IMPORT_JOB_LOOKUP_INDEXES_MIGRATION_VERSION = 63
+
+
+def import_job_lookup_indexes_ddl(dialect: str = "mysql") -> str:
+    """Index the per-source and per-status import job lookups.
+
+    Migration 7 gave SQLite `import_jobs` no index beyond its primary key (the
+    one-active-job index is partial), so every "this source's jobs" or "the
+    jobs in this state" question read and sorted the whole table. Live sync
+    adds a row per change it imports and nothing removed them, so on a machine
+    a few weeks old that table was thousands of rows read several times a poll.
+
+    `import_jobs_lane` serves the lane lookups (one user, one source, one
+    operation, a status, newest first) and the pruning of finished syncs;
+    `import_jobs_status` serves restart recovery and the status filters.
+    MySQL's migration 7 already has a status index and no `operation` column,
+    so it only gains the ordered source index.
+    """
+    if dialect == "sqlite":
+        return """
+CREATE INDEX IF NOT EXISTS import_jobs_lane
+ON import_jobs(user_id, source_id, operation, status, created_at);
+CREATE INDEX IF NOT EXISTS import_jobs_status
+ON import_jobs(status, created_at);
+"""
+    return """
+CREATE INDEX idx_import_jobs_source_created
+ON import_jobs(user_id, source_id, created_at);
+"""
+
+
+def _is_duplicate_index(error: Exception) -> bool:
+    """MySQL's "index name already there" (1061): the index is in place."""
+    args: tuple[object, ...] = getattr(error, "args", ())
+    return bool(args) and args[0] == 1061
+
+
+async def _063_import_job_lookup_indexes(cursor: Any) -> None:
+    dialect = _dialect(cursor)
+    if dialect == "sqlite":
+        # `operation` was added by the job store, not by migration 7, so a
+        # database built from the catalog alone may not have it yet. Same
+        # declaration as the store's own addition.
+        if "operation" not in await cursor.columns("import_jobs"):
+            await cursor.execute(
+                "ALTER TABLE import_jobs ADD COLUMN operation TEXT NOT NULL DEFAULT 'history'"
+            )
+        for statement in _split_statements(import_job_lookup_indexes_ddl(dialect)):
+            await cursor.execute(statement)
+        return
+    for statement in _split_statements(import_job_lookup_indexes_ddl(dialect)):
+        try:
+            await cursor.execute(statement)
+        except Exception as error:  # noqa: BLE001 - MySQL driver error type varies
+            if _is_duplicate_index(error):
+                continue
+            raise
+
+
 def _split_statements(sql: str) -> list[str]:
    """Split a multi-statement script, dropping blanks, PRAGMA and comments.

@@ -3462,4 +3593,16 @@ MIGRATIONS: tuple[Migration, ...] = (
        _060_memory_note_requests,
        ("memory_note_requests",),
    ),
+    Migration(61, "write_job_retries", _061_write_job_retries),
+    Migration(
+        ONBOARDING_PROGRESS_MIGRATION_VERSION,
+        "onboarding_progress",
+        _062_onboarding_progress,
+        ("onboarding_state",),
+    ),
+    Migration(
+        IMPORT_JOB_LOOKUP_INDEXES_MIGRATION_VERSION,
+        "import_job_lookup_indexes",
+        _063_import_job_lookup_indexes,
+    ),
 )
@@ -57,6 +57,11 @@ class WriteRecord:
    detail: str = ""
    raw_ids: tuple[str, ...] = ()
    memory_ids: tuple[str, ...] = ()
+    #: The stable code of the last failure of a job still being worked on
+    #: (or of a failed one).
+    error_code: str | None = None
+    #: When a waiting job is next tried, if a retry wait holds it.
+    next_retry_at: str | None = None


 def _now() -> str:
@@ -44,6 +44,7 @@ from one_memory.memory_server.durable_queue import (
 )
 from one_memory.memory_server.registry import WriteRegistry, WriteState
 from one_memory.memory_server.submit import WriteConflictError
+from one_memory.model_backoff import next_retry_at
 from one_memory.user_scope import DEFAULT_USER_ID, USER_ID_PATTERN, UserId

 #: Durable keys of another user's writes start with this. A `local` request
@@ -72,6 +73,12 @@ class MemoryWriteReceipt(BaseModel):
    detail: str = ""
    raw_ids: tuple[str, ...] = ()
    memory_ids: tuple[str, ...] = ()
+    #: Why a job still being worked on last failed (`model_auth_failed`, ...),
+    #: or why a failed one failed. A provider failure keeps `state` queued.
+    error_code: str | None = None
+    #: When it is next tried: the job's own retry wait, or the model
+    #: provider's pause (`model_backoff`) while the provider is failing.
+    next_retry_at: str | None = None


 class OpenAIMessage(BaseModel):
@@ -235,6 +242,8 @@ def sdk_router(dependencies: list[Any] | None = None) -> APIRouter:
            detail=record.detail,
            raw_ids=record.raw_ids,
            memory_ids=record.memory_ids,
+            error_code=record.error_code,
+            next_retry_at=next_retry_at(request.app, record.state, record.next_retry_at),
        )

    return instance
@@ -0,0 +1,330 @@
+"""One pause for every model request while the provider keeps failing (#245).
+
+A broken model configuration (a revoked key, a wrong base URL, a model that
+does not exist, a provider that is down) used to fail each queued job on its
+own: the drain claimed the next job the moment the last one failed, so a
+backlog of hundreds of jobs turned into requests as fast as the provider could
+refuse them. The pause is global, not per job: a failure says something about
+the provider, not about the conversation that happened to hit it.
+
+After the first failure no further model work is claimed for 5 seconds; each
+failed probe after that doubles the pause, up to 3 minutes. A pause admits one
+probe job at a time. The first success, or any change the user makes to the
+model configuration, ends it at once. Jobs not yet sent stay `pending`.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+BACKOFF_FIRST_SECONDS = 5.0
+BACKOFF_CAP_SECONDS = 180.0
+#: How long one probe may hold the pause open before another is admitted. A
+#: probe job that never reaches the provider (nothing to remember, a refusal
+#: before the SDK) reports nothing, and the queue must not wait on it forever.
+PROBE_HOLD_SECONDS = 30.0
+#: Requests already in flight when the pause began are refused without going
+#: out once this many failures in a row confirm it is not a one-off.
+REFUSE_IN_FLIGHT_AFTER = 2
+
+#: Statuses that say the configuration or the provider is wrong, not the one
+#: request: authentication, a missing model or route, throttling, a timeout
+#: and the provider's own failures. A 400/413/422 is about the request's
+#: content and is left to that job.
+_PROVIDER_STATUSES = {401: "model_auth_failed", 403: "model_auth_failed", 404: "model_not_found"}
+
+#: Every code a provider failure is recorded under: a job that failed with one
+#: of these waits for the provider instead of spending a retry.
+MODEL_FAILURE_CODES = frozenset(
+    {
+        "model_auth_failed",
+        "model_not_found",
+        "model_timeout",
+        "model_rate_limited",
+        "model_server_error",
+        "model_unreachable",
+        "model_transport_failed",
+    }
+)
+
+
+def backoff_seconds(level: int) -> float:
+    """The pause after the `level`-th failed attempt in a row (1-based)."""
+    if level < 1:
+        return 0.0
+    return min(BACKOFF_FIRST_SECONDS * float(2 ** min(level - 1, 16)), BACKOFF_CAP_SECONDS)
+
+
+def failure_code(status: int) -> str | None:
+    """The stable code for a provider HTTP status, or None if it is no provider failure."""
+    if status in _PROVIDER_STATUSES:
+        return _PROVIDER_STATUSES[status]
+    if status in {408, 504}:
+        return "model_timeout"
+    if status == 429:
+        return "model_rate_limited"
+    if status >= 500:
+        return "model_server_error"
+    return None
+
+
+def transport_failure_code(error: BaseException) -> str:
+    if isinstance(error, httpx.TimeoutException):
+        return "model_timeout"
+    if isinstance(error, httpx.ConnectError | httpx.NetworkError):
+        return "model_unreachable"
+    return "model_transport_failed"
+
+
+def request_kind(request: httpx.Request) -> str:
+    """`embedding` for the embeddings route, `chat` for everything else."""
+    return "embedding" if request.url.path.rstrip("/").endswith("/embeddings") else "chat"
+
+
+@dataclass(frozen=True)
+class ModelBackoffState:
+    #: When the pause ends; None when no pause is in force.
+    until: datetime | None
+    #: Failed attempts in a row.
+    failures: int
+    #: The last failure's stable code (`model_auth_failed`, ...).
+    last_error: str | None
+    profile_id: str | None
+
+
+class ModelBackoffRefusal(httpx.TransportError):
+    """A request refused locally because the provider is being given a rest."""
+
+
+@dataclass(eq=False)
+class ModelAttempt:
+    """One job's write, as the provider saw it.
+
+    `failure` is the code of the first provider failure (or local refusal)
+    that happened while this write was in flight, None if there was none.
+    """
+
+    failure: str | None = None
+
+
+class ModelBackoff:
+    """Process-wide circuit breaker for the active model profile.
+
+    Thread-safe: the transport records from the SDK's own loop thread, the
+    drain asks from its claim thread, and status reads from the event loop.
+    """
+
+    def __init__(
+        self,
+        *,
+        clock: Callable[[], float] = time.monotonic,
+        wall_clock: Callable[[], datetime] = lambda: datetime.now(UTC),
+    ) -> None:
+        self._clock = clock
+        self._wall_clock = wall_clock
+        self._lock = threading.Lock()
+        #: Writes in flight (`attempt`); never cleared by a reset.
+        self._attempts: set[ModelAttempt] = set()
+        self._reset_locked()
+
+    def _reset_locked(self) -> None:
+        #: Which kinds of request are failing (`chat`, `embedding`): a working
+        #: embedding endpoint says nothing about a chat model that is gone.
+        self._failing: set[str] = set()
+        self._level = 0
+        self._failures = 0
+        self._until = 0.0
+        self._probe_until = 0.0
+        self._last_error: str | None = None
+        self._profile_id: str | None = None
+
+    def reset(self, reason: str = "model_configuration_changed") -> None:
+        """Forget every failure: the user changed what is being called."""
+        with self._lock:
+            was_paused = self._failures > 0
+            self._reset_locked()
+        if was_paused:
+            logger.info("model_backoff_reset reason=%s", reason)
+
+    def record_success(self, profile_id: str | None = None, kind: str = "model") -> None:
+        with self._lock:
+            if self._failures == 0:
+                return
+            if profile_id is not None and self._profile_id not in {None, profile_id}:
+                return
+            self._failing.discard(kind)
+            if self._failing:
+                return
+            self._reset_locked()
+        logger.info("model_backoff_cleared profile_id=%s", profile_id)
+
+    def record_failure(self, code: str, profile_id: str | None = None, kind: str = "model") -> None:
+        now = self._clock()
+        with self._lock:
+            if profile_id is not None and self._profile_id not in {None, profile_id}:
+                # Another profile's history says nothing about this one.
+                self._reset_locked()
+            self._profile_id = profile_id
+            self._failing.add(kind)
+            self._mark_attempts_locked(code)
+            self._failures += 1
+            self._last_error = code
+            self._probe_until = 0.0
+            # Requests that were already out when the pause began fail too;
+            # they are the same outage, not a reason to wait longer.
+            if now >= self._until:
+                self._level += 1
+                self._until = now + backoff_seconds(self._level)
+            level, pause = self._level, self._until - now
+        logger.warning(
+            "model_backoff_failure error_code=%s level=%d pause_s=%.0f profile_id=%s",
+            code,
+            level,
+            pause,
+            profile_id,
+        )
+
+    @contextmanager
+    def attempt(self) -> Iterator[ModelAttempt]:
+        """Hold one job's write open, and learn whether the provider failed it.
+
+        Every provider failure and every local refusal while the write is in
+        flight is charged to it. A request cannot be traced to the job that
+        made it: the SDK sends embeddings from one shared batching worker, so
+        neither the calling thread nor a context variable identifies the job.
+        Charging every write then in flight can name a write the provider did
+        not fail (another job's request failed beside it); that write waits
+        for the provider and is retried with the rest. It can never miss the
+        write the provider did fail, which would spend that job's retries on
+        an outage.
+        """
+        record = ModelAttempt()
+        with self._lock:
+            self._attempts.add(record)
+        try:
+            yield record
+        finally:
+            with self._lock:
+                self._attempts.discard(record)
+
+    def record_refusal(self) -> str:
+        """A request refused locally; charged to the writes in flight like a failure."""
+        with self._lock:
+            code = self._last_error or "model_transport_failed"
+            self._mark_attempts_locked(code)
+        return code
+
+    def _mark_attempts_locked(self, code: str) -> None:
+        for record in self._attempts:
+            if record.failure is None:
+                record.failure = code
+
+    def paused(self) -> bool:
+        with self._lock:
+            return self._failures > 0 and self._clock() < self._until
+
+    def refuses_requests(self, kind: str = "model") -> bool:
+        """Whether a request of this kind should not go out at all right now.
+
+        Only the failing kind is refused: a chat model that is gone must not
+        take recall's embedding calls down with it.
+        """
+        with self._lock:
+            return (
+                kind in self._failing
+                and self._failures >= REFUSE_IN_FLIGHT_AFTER
+                and self._clock() < self._until
+            )
+
+    def allowance(self, *, kind: str | None = None) -> int | None:
+        """How many matching provider jobs may be claimed now.
+
+        0 while paused; once the pause is over, one probe at a time until it
+        reports or `PROBE_HOLD_SECONDS` pass. ``kind`` keeps a failed chat
+        model from pausing raw-only work that needs embeddings, while an
+        embedding outage still paces that work.
+        """
+        now = self._clock()
+        with self._lock:
+            if self._failures == 0 or (kind is not None and kind not in self._failing):
+                return None
+            if now < self._until or now < self._probe_until:
+                return 0
+            self._probe_until = now + PROBE_HOLD_SECONDS
+            return 1
+
+    def state(self) -> ModelBackoffState:
+        now = self._clock()
+        with self._lock:
+            remaining = self._until - now if self._failures else 0.0
+            return ModelBackoffState(
+                until=(
+                    self._wall_clock() + timedelta(seconds=remaining) if remaining > 0 else None
+                ),
+                failures=self._failures,
+                last_error=self._last_error,
+                profile_id=self._profile_id,
+            )
+
+
+def next_retry_at(app: Any, state: str, own: str | None) -> str | None:
+    """When a queued job is tried next: its own retry wait, or the provider's pause.
+
+    While the breaker pauses, nothing is claimed at all, so the pause holds
+    every queued job, whatever it last failed with.
+    """
+    if state not in {"accepted", "pending"}:
+        return None
+    backoff = getattr(getattr(app, "state", None), "model_backoff", None)
+    until = backoff.state().until if isinstance(backoff, ModelBackoff) else None
+    paused = until.isoformat() if until is not None else None
+    candidates = [value for value in (own, paused) if value]
+    return max(candidates) if candidates else None
+
+
+class BackedOffModelTransport(httpx.AsyncBaseTransport):
+    """Report each provider exchange to the breaker; refuse while it confirms a pause."""
+
+    def __init__(
+        self,
+        backoff: ModelBackoff,
+        *,
+        profile_id: str,
+        inner: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self.backoff = backoff
+        self.profile_id = profile_id
+        self.inner = inner or httpx.AsyncHTTPTransport(retries=0, trust_env=False)
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        kind = request_kind(request)
+        if self.backoff.refuses_requests(kind):
+            self.backoff.record_refusal()
+            raise ModelBackoffRefusal("model_backoff_active", request=request)
+        try:
+            response = await self.inner.handle_async_request(request)
+        except ModelBackoffRefusal:
+            raise
+        except httpx.TransportError as error:
+            self.backoff.record_failure(transport_failure_code(error), self.profile_id, kind)
+            raise
+        code = failure_code(response.status_code)
+        if code is not None:
+            self.backoff.record_failure(code, self.profile_id, kind)
+        elif response.status_code < 400:
+            self.backoff.record_success(self.profile_id, kind)
+        return response
+
+    async def aclose(self) -> None:
+        await self.inner.aclose()
@@ -26,6 +26,7 @@ if TYPE_CHECKING:
 _operation: ContextVar[tuple["ModelProbeOperations", str] | None] = ContextVar(
    "model_probe_operation", default=None
 )
+_dispatch_started: ContextVar[bool] = ContextVar("model_probe_dispatch_started", default=False)


 class ProbeCode(StrEnum):
@@ -113,16 +114,26 @@ class ModelProber:
        if existing is not None:
            return existing
        token = _operation.set((operations, request.operation_id))
+        dispatch_token = _dispatch_started.set(False)
        try:
            await self._probe(profile_id)
        except ProbeOperationConflict:
            await asyncio.to_thread(
                operations.fail, request.operation_id, "model_probe_profile_changed"
            )
-        except Exception:
-            # Unknown dispatch/storage outcomes stay reserved, including across restart.
-            raise ProbeOperationUnavailable("model_probe_operation_unavailable") from None
+        except Exception as exc:
+            if _dispatch_started.get():
+                # Once a request may have reached the provider, preserve the
+                # reservation so a retry cannot duplicate a possibly billed call.
+                raise ProbeOperationUnavailable("model_probe_operation_unavailable") from None
+            logging.getLogger(__name__).warning(
+                "model probe failed before dispatch: %s", type(exc).__name__
+            )
+            await asyncio.to_thread(
+                operations.fail, request.operation_id, "model_probe_execution_failed"
+            )
        finally:
+            _dispatch_started.reset(dispatch_token)
            _operation.reset(token)
        return await asyncio.to_thread(operations.lookup, request.operation_id)

@@ -317,6 +328,8 @@ class ModelProber:
        listing_optional: bool = False,
    ) -> ProbeStage:
        await self._check_operation()
+        if _operation.get() is not None:
+            _dispatch_started.set(True)
        started = monotonic()
        try:
            response = await client.request(
@@ -4,9 +4,10 @@ from collections.abc import Iterator
 from contextlib import contextmanager
 from datetime import UTC, datetime
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
+from uuid import UUID

-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field, field_validator

 from one_memory.database import (
    take_the_write_lock_first,
@@ -14,11 +15,25 @@ from one_memory.database import (
 from one_memory.database_access import main_database

 #: Schema owned by `memory_server.migrations` (migration 12). No local copy.
-from one_memory.memory_server.migrations import onboarding_state_ddl
-from one_memory.memory_server.sql_compat import execute, is_mysql
+from one_memory.memory_server.migrations import (
+    onboarding_progress_ddl,
+    onboarding_state_ddl,
+)
+from one_memory.memory_server.sql_compat import execute, is_mysql, row_to_dict
 from one_memory.memory_server.store_binding import store_for

 SCHEMA = onboarding_state_ddl("sqlite")
+ONBOARDING_COLUMNS = (
+    "singleton",
+    "status",
+    "selected_source_ids_json",
+    "started_at",
+    "completed_at",
+    "updated_at",
+    "mode_intent",
+    "setup_step",
+    "model_profile_id",
+)

 #: The start/complete upserts, per engine.
 #:
@@ -51,11 +66,13 @@ START_MYSQL = """
        updated_at = VALUES(updated_at)
 """
 COMPLETE_UPDATE_SQLITE = (
-    "UPDATE onboarding_state SET status = 'completed', completed_at = ?, updated_at = ? "
+    "UPDATE onboarding_state SET status = 'completed', completed_at = ?, updated_at = ?, "
+    "mode_intent = NULL, setup_step = NULL, model_profile_id = NULL "
    "WHERE singleton = 1"
 )
 COMPLETE_UPDATE_MYSQL = (
-    "UPDATE onboarding_state SET status = 'completed', completed_at = %s, updated_at = %s "
+    "UPDATE onboarding_state SET status = 'completed', completed_at = %s, updated_at = %s, "
+    "mode_intent = NULL, setup_step = NULL, model_profile_id = NULL "
    "WHERE singleton = 1"
 )
 COMPLETE_INSERT_SQLITE = (
@@ -71,13 +88,27 @@ COMPLETE_INSERT_MYSQL = (
 RESET_UPDATE_SQLITE = (
    "UPDATE onboarding_state SET status = 'not_started', "
    "selected_source_ids_json = '[]', started_at = NULL, completed_at = NULL, "
+    "mode_intent = NULL, setup_step = NULL, model_profile_id = NULL, "
    "updated_at = ? WHERE singleton = 1"
 )
 RESET_UPDATE_MYSQL = (
    "UPDATE onboarding_state SET status = 'not_started', "
    "selected_source_ids_json = '[]', started_at = NULL, completed_at = NULL, "
+    "mode_intent = NULL, setup_step = NULL, model_profile_id = NULL, "
    "updated_at = %s WHERE singleton = 1"
 )
+ENSURE_PROGRESS_SQLITE = (
+    "INSERT INTO onboarding_state ("
+    "singleton,status,selected_source_ids_json,started_at,completed_at,updated_at"
+    ") VALUES (1,'not_started','[]',NULL,NULL,?) "
+    "ON CONFLICT(singleton) DO NOTHING"
+)
+ENSURE_PROGRESS_MYSQL = (
+    "INSERT INTO onboarding_state ("
+    "singleton,status,selected_source_ids_json,started_at,completed_at,updated_at"
+    ") VALUES (1,'not_started','[]',NULL,NULL,%s) "
+    "ON DUPLICATE KEY UPDATE singleton=VALUES(singleton)"
+)


 class OnboardingState(BaseModel):
@@ -87,6 +118,35 @@ class OnboardingState(BaseModel):
    selected_source_ids: tuple[str, ...]
    started_at: datetime | None
    completed_at: datetime | None
+    mode_intent: Literal["lite", "pro", "ultra"] | None
+    setup_step: Literal["review", "mode", "model"] | None
+    model_profile_id: str | None
+
+
+class OnboardingProgressUpdate(BaseModel):
+    """Only non-sensitive, resumable choices accepted from the onboarding UI."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    mode_intent: Literal["lite", "pro", "ultra"] | None = None
+    setup_step: Literal["review", "mode", "model"] | None = None
+    model_profile_id: str | None = Field(default=None, min_length=36, max_length=36)
+
+    @field_validator("model_profile_id")
+    @classmethod
+    def validate_model_profile_id(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        try:
+            if str(UUID(value)) != value:
+                raise ValueError
+        except (ValueError, TypeError, AttributeError):
+            raise ValueError("invalid_model_profile_id") from None
+        return value
+
+
+class OnboardingCompletedError(RuntimeError):
+    pass


 class OnboardingStore:
@@ -103,12 +163,31 @@ class OnboardingStore:
        """
        with self._connect(initialize=True) as connection:
            execute(connection, is_mysql(self._store), SCHEMA)
+            if not is_mysql(self._store):
+                existing = {
+                    str(row[1]) for row in connection.execute("PRAGMA table_info(onboarding_state)")
+                }
+                statements = tuple(
+                    statement.strip()
+                    for statement in onboarding_progress_ddl("sqlite").split(";")
+                    if statement.strip()
+                )
+                for column, statement in zip(
+                    ("mode_intent", "setup_step", "model_profile_id"),
+                    statements,
+                    strict=True,
+                ):
+                    if column not in existing:
+                        connection.execute(statement)

    def get(self) -> OnboardingState:
        mysql = is_mysql(self._store)
        with self._connect() as connection:
            row = execute(
-                connection, mysql, "SELECT * FROM onboarding_state WHERE singleton = 1"
+                connection,
+                mysql,
+                "SELECT " + ", ".join(ONBOARDING_COLUMNS) + " "
+                "FROM onboarding_state WHERE singleton = 1",
            ).fetchone()
        if row is None:
            return OnboardingState(
@@ -116,8 +195,11 @@ class OnboardingStore:
                selected_source_ids=(),
                started_at=None,
                completed_at=None,
+                mode_intent=None,
+                setup_step=None,
+                model_profile_id=None,
            )
-        return self._to_state(row)
+        return self._to_state(row, mysql=mysql)

    def start(self, source_ids: tuple[str, ...]) -> OnboardingState:
        now = datetime.now(UTC).isoformat()
@@ -150,6 +232,43 @@ class OnboardingStore:
                )
        return self.get()

+    def update_progress(self, update: OnboardingProgressUpdate) -> OnboardingState:
+        fields = tuple(
+            field
+            for field in ("mode_intent", "setup_step", "model_profile_id")
+            if field in update.model_fields_set
+        )
+        if not fields:
+            state = self.get()
+            if state.status == "completed":
+                raise OnboardingCompletedError("onboarding_completed")
+            return state
+        mysql = is_mysql(self._store)
+        placeholder = "%s" if mysql else "?"
+        assignments = [f"{field} = {placeholder}" for field in fields]
+        assignments.append(f"updated_at = {placeholder}")
+        values = [getattr(update, field) for field in fields]
+        now = datetime.now(UTC).isoformat()
+        values.append(now)
+        with self._connect(writing=True) as connection:
+            execute(
+                connection,
+                mysql,
+                ENSURE_PROGRESS_MYSQL if mysql else ENSURE_PROGRESS_SQLITE,
+                (now,),
+            )
+            updated = execute(
+                connection,
+                mysql,
+                "UPDATE onboarding_state SET "
+                + ", ".join(assignments)
+                + " WHERE singleton = 1 AND status != 'completed'",
+                tuple(values),
+            )
+            if updated.rowcount != 1:
+                raise OnboardingCompletedError("onboarding_completed")
+        return self.get()
+
    def reset(self) -> OnboardingState:
        """Return onboarding to its first-run state, touching nothing else.

@@ -207,33 +326,53 @@ class OnboardingStore:
            yield connection

    @staticmethod
-    def _to_state(row: Any) -> OnboardingState:
-        """Read the row by position, so it works for `sqlite3.Row` and tuples.
-
-        `SELECT *` makes the column order part of the contract here, which is
-        why the query is `SELECT *` and the indices are named: relying on
-        `row["..."]` would only work on SQLite, and relying on position alone
-        without saying which column is which would be unreadable.
-
-        Timestamps are a further engine difference: SQLite hands back the stored
-        string, MySQL hands back a `datetime`. Accepting both is not padding —
-        parsing a `datetime` raises, and treating a string as one would be
-        silently wrong.
-        """
-        # singleton, status, selected_source_ids_json, started_at, completed_at, updated_at
-        raw_ids = json.loads(row[2])
+    def _to_state(row: Any, *, mysql: bool) -> OnboardingState:
+        """Map SQLite rows and MySQL tuples through the shared database adapter."""
+        if mysql:
+            if not isinstance(row, tuple):
+                raise ValueError("onboarding_row_shape_invalid")
+        elif not isinstance(row, sqlite3.Row):
+            raise ValueError("onboarding_row_shape_invalid")
+        if len(row) != len(ONBOARDING_COLUMNS):
+            raise ValueError("onboarding_row_shape_invalid")
+        if mysql:
+            values = dict(zip(ONBOARDING_COLUMNS, tuple(row), strict=True))
+        else:
+            values = row_to_dict(row, ONBOARDING_COLUMNS, mysql=False)
+            if set(values) != set(ONBOARDING_COLUMNS):
+                raise ValueError("onboarding_row_shape_invalid")
+        _as_datetime(values["updated_at"], mysql=mysql, nullable=False)
+        raw_ids = json.loads(values["selected_source_ids_json"])
        return OnboardingState(
-            status=row[1],
+            status=values["status"],
            selected_source_ids=tuple(value for value in raw_ids if isinstance(value, str)),
-            started_at=_as_datetime(row[3]),
-            completed_at=_as_datetime(row[4]),
+            started_at=_as_datetime(values["started_at"], mysql=mysql),
+            completed_at=_as_datetime(values["completed_at"], mysql=mysql),
+            mode_intent=values["mode_intent"],
+            setup_step=values["setup_step"],
+            model_profile_id=values["model_profile_id"],
        )


-def _as_datetime(value: object) -> datetime | None:
-    """SQLite stores these as text; MySQL returns `datetime` objects."""
-    if value is None or value == "":
+def _as_datetime(
+    value: object,
+    *,
+    mysql: bool,
+    nullable: bool = True,
+) -> datetime | None:
+    """Validate the engine's timestamp shape and normalize it to UTC."""
+    if value is None:
+        if not nullable:
+            raise ValueError("onboarding_datetime_invalid")
        return None
-    if isinstance(value, datetime):
-        return value
-    return datetime.fromisoformat(str(value))
+    if mysql:
+        if not isinstance(value, datetime):
+            raise ValueError("onboarding_datetime_invalid")
+        parsed = value
+    else:
+        if not isinstance(value, str) or value == "":
+            raise ValueError("onboarding_datetime_invalid")
+        parsed = datetime.fromisoformat(value)
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC)
@@ -0,0 +1,123 @@
+"""Turn-level read projection for SDK raw batches.
+
+HY keeps several complete conversation turns in one L1 raw node so model
+writes stay batched. Product readers must not expose that storage batch as
+one conversation item: this module gives every contained turn a stable
+identity while retaining the parent raw id for traceability.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass
+
+from one_memory.hy_sdk_types import HySdkRawRecord, raw_turn_messages
+
+
+@dataclass(frozen=True)
+class RawDisplayTurn:
+    turn_id: str
+    turn_index: int
+    turn_count: int
+    content: str
+    messages: tuple[tuple[str, str], ...]
+
+
+def raw_display_turns(record: HySdkRawRecord) -> tuple[RawDisplayTurn, ...]:
+    """Split one stored raw batch into user-opened turns.
+
+    A user message opens a new turn; assistant/tool/system messages stay with
+    that user message until the next user message. Legacy content with no user
+    marker remains one turn so it never disappears from the product.
+    """
+    messages = raw_turn_messages(record.content)
+    grouped: list[list[tuple[str, str]]] = []
+    for message in messages:
+        role, _ = message
+        has_user = bool(grouped) and any(item[0] == "user" for item in grouped[-1])
+        if not grouped or (role == "user" and has_user):
+            grouped.append([message])
+        else:
+            grouped[-1].append(message)
+    if not grouped:
+        grouped = [[("", record.content)]]
+
+    digest = hashlib.sha256(record.raw_id.encode("utf-8")).hexdigest()
+    count = len(grouped)
+    return tuple(
+        RawDisplayTurn(
+            turn_id=f"raw-turn:{digest}:{index}",
+            turn_index=index,
+            turn_count=count,
+            content=_turn_content(turn),
+            messages=tuple(turn),
+        )
+        for index, turn in enumerate(grouped)
+    )
+
+
+def _turn_content(messages: list[tuple[str, str]]) -> str:
+    return "\n".join(f"[{role}]: {content}" if role else content for role, content in messages)
+
+
+def raw_prefix_added(
+    cached: tuple[tuple[str, str | None], ...],
+    current: tuple[tuple[str, str | None], ...],
+    cached_total: int,
+    current_total: int,
+) -> int | None:
+    """How many raws were only put on top of a cached newest-first listing.
+
+    `cached` and `current` are the (raw id, status) of the first page of each
+    listing. The answer is a count when the current page is the cached one
+    with new raws before it and nothing else changed; None when anything else
+    happened (a delete, a status change, a raw dated into the middle), which
+    needs a full re-listing.
+    """
+    added = current_total - cached_total
+    if added <= 0 or added > len(current):
+        return None
+    kept = current[added:]
+    if not kept and cached_total:
+        return None
+    if kept != cached[: len(kept)]:
+        return None
+    return added
+
+
+_WORD = re.compile(r"\w+")
+
+
+def _query_terms(query: str) -> frozenset[str]:
+    """Words of the query, plus character bigrams of unspaced (CJK) words."""
+    terms: set[str] = set()
+    for word in _WORD.findall(query.casefold()):
+        terms.add(word)
+        if not word.isascii() and len(word) > 1:
+            terms.update(word[index : index + 2] for index in range(len(word) - 1))
+    return frozenset(terms)
+
+
+def turns_for_hit(turns: tuple[RawDisplayTurn, ...], query: str) -> tuple[RawDisplayTurn, ...]:
+    """The turns one semantic raw hit shows, never none while it has turns.
+
+    The SDK embeds a whole raw batch, so a vector hit cannot say which of its
+    turns matched. Every turn containing the query text is shown; when none
+    does, the turn sharing the most query terms (the earliest on a tie) stands
+    for the hit. A semantic hit is never dropped for lacking the literal query.
+    """
+    if not turns:
+        return ()
+    needle = query.casefold().strip()
+    if needle:
+        lexical = tuple(turn for turn in turns if needle in turn.content.casefold())
+        if lexical:
+            return lexical
+    terms = _query_terms(query)
+
+    def overlap(turn: RawDisplayTurn) -> tuple[int, int]:
+        content = turn.content.casefold()
+        return (sum(1 for term in terms if term in content), -turn.turn_index)
+
+    return (max(turns, key=overlap),)
@@ -135,6 +135,8 @@ class RecallReceipt(BaseModel):
    #: exists yet (`fallback_reason`). Raw hits are excerpts, not memories.
    mode: Literal["memory", "raw"] = "memory"
    fallback_reason: Literal["model_unavailable", "no_memories"] | None = None
+    #: Whose memories were searched: the request's `user_id`, else `local`.
+    user_id: str = DEFAULT_USER_ID


 class RecallTarget(Protocol):
@@ -11,6 +11,7 @@ instead: plain retrieval over what was imported, the same lane
 from __future__ import annotations

 import asyncio
+import re
 import time
 from collections.abc import Awaitable, Callable
 from datetime import UTC, datetime
@@ -32,6 +33,63 @@ FallbackReason = Literal["model_unavailable", "no_memories"]
 #: caller). An empty set means the caller may read no raw conversation.
 RawSources = frozenset[str] | None

+#: What the whole recall request may take beyond the caller's own
+#: `timeout_ms`: the search keeps to that budget, but the checks around it
+#: (is a model configured, is the library empty, which raw sources) and the
+#: raw fallback need a little room of their own. Well under the broker's 15 s
+#: wait on Core, so a slow Core answers 504 before the broker gives up.
+RECALL_TOTAL_GRACE_SECONDS = 3.0
+RECALL_TOTAL_CEILING_SECONDS = 12.0
+
+
+def recall_total_timeout_seconds(timeout_ms: int) -> float:
+    """The most one recall request may take from start to answer."""
+    return min(timeout_ms / 1_000 + RECALL_TOTAL_GRACE_SECONDS, RECALL_TOTAL_CEILING_SECONDS)
+
+
+def _bounded_raw_excerpt(content: str, query: str, limit: int) -> str:
+    """Fit one raw hit without discarding the highest-ranked candidate.
+
+    Prefer the literal query, then its longest matching word. A semantic hit
+    with no lexical anchor keeps its beginning: that is also the part the
+    embedding service preserves when an input exceeds its own token limit.
+    """
+    if len(content) <= limit:
+        return content
+    if limit <= 2:
+        return content[:limit]
+
+    anchor = 0
+    needle = query.strip()
+    if needle:
+        exact = re.search(re.escape(needle), content, re.IGNORECASE)
+        if exact is not None:
+            anchor = exact.start()
+        else:
+            terms = sorted(re.findall(r"\w+", needle), key=len, reverse=True)
+            match = next(
+                (
+                    found
+                    for term in terms
+                    if (found := re.search(re.escape(term), content, re.IGNORECASE)) is not None
+                ),
+                None,
+            )
+            if match is not None:
+                anchor = match.start()
+
+    payload = limit
+    while True:
+        start = max(0, min(anchor - payload // 3, len(content) - payload))
+        end = min(len(content), start + payload)
+        adjusted = limit - int(start > 0) - int(end < len(content))
+        if adjusted == payload:
+            break
+        payload = adjusted
+    prefix = "…" if start > 0 else ""
+    suffix = "…" if end < len(content) else ""
+    return f"{prefix}{content[start:end]}{suffix}"
+

 async def recall_with_fallback(
    request: RecallRequest,
@@ -110,6 +168,9 @@ async def _raw_recall(
        )
    except TimeoutError:
        return receipt(truncated_by=TruncationBudget.TIMEOUT)
+    current_sources = await raw_sources()
+    if sources is not None:
+        sources &= current_sources or frozenset()
    hits: list[RecallHit] = []
    used = 0
    truncated_by: TruncationBudget | None = None
@@ -124,13 +185,23 @@ async def _raw_recall(
                truncated_by=truncated_by,
                unexamined=len(found) - index,
            )
-        if used + len(hit.content) > request.character_budget:
+        remaining = request.character_budget - used
+        if remaining <= 0:
+            truncated_by = TruncationBudget.CHARACTER
+            return receipt(
+                tuple(hits),
+                used=used,
+                truncated_by=truncated_by,
+                unexamined=len(found) - index,
+            )
+        content = hit.content
+        if len(content) > remaining:
+            content = _bounded_raw_excerpt(content, request.query, remaining)
            truncated_by = TruncationBudget.CHARACTER
-            continue
        hits.append(
            RecallHit(
                memory_id=hit.raw_id,
-                content=hit.content,
+                content=content,
                kind="raw",
                scopes=(),
                evidence_ids=(),
@@ -145,5 +216,5 @@ async def _raw_recall(
                session_id=hit.session_id,
            )
        )
-        used += len(hit.content)
+        used += len(content)
    return receipt(tuple(hits), used=used, truncated_by=truncated_by)
@@ -113,6 +113,37 @@ def inspect_runtime(
    )


+@dataclass(frozen=True)
+class CoreEndpoint:
+    host: Literal["127.0.0.1"]
+    port: int
+    token: str
+
+
+def core_endpoint(
+    data_dir: Path,
+    *,
+    alive: Callable[[int], bool] = process_is_alive,
+) -> CoreEndpoint | None:
+    """Where this home's Core listens and the token it accepts, from files alone.
+
+    The receipt and token checks `inspect_runtime` makes, without its identity
+    round trip: a caller that only has to hand something over quickly lets the
+    authenticated request itself be the proof. None when no live Core is named.
+    """
+    try:
+        raw = (data_dir / "runtime.json").read_text(encoding="utf-8")
+        receipt = _receipt(json.loads(raw))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return None
+    if receipt is None or not alive(receipt.pid):
+        return None
+    token = _runtime_token(data_dir)
+    if token is None:
+        return None
+    return CoreEndpoint(host=receipt.host, port=receipt.port, token=token)
+
+
 def _receipt(value: object) -> RuntimeReceipt | None:
    if not isinstance(value, dict):
        return None
@@ -33,7 +33,7 @@ from one_memory.model_profiles import (
 )
 from one_memory.sdk_search_options import SdkSearchFilters, SearchLane
 from one_memory.secrets import SecretStore, SecretStoreUnavailableError
-from one_memory.user_scope import owns
+from one_memory.user_scope import DEFAULT_USER_ID, owns

 _NO_GROUNDING = "现有记忆不足以回答这个问题。"
 _GROUNDING_LIMIT = 6
@@ -62,6 +62,8 @@ class SdkMemoryAnswer(BaseModel):
    answer: str
    memories: tuple[SdkAskMemory, ...]
    mode: Literal["generated", "extractive", "empty"]
+    #: Whose memories answered: the request's `user_id`, else `local`.
+    user_id: str = DEFAULT_USER_ID


 class _PromptMemory:
@@ -25,7 +25,7 @@ from one_memory.hy_runtime_config import HY_MEMORY_READER
 from one_memory.hy_sdk_runtime import SdkClientHandle, sdk_relevance_floor
 from one_memory.hy_sdk_types import HySdkError, parse_sdk_search
 from one_memory.memory_queue import ExtractionWindowPreset, QueueDepths
-from one_memory.memory_server.durable_queue import COMPLETED, DurableWriteQueue
+from one_memory.memory_server.durable_queue import WAITING_FOR_MODEL, DurableWriteQueue
 from one_memory.sdk_write_processor import SdkWriteCoordinator
 from one_memory.semantic_deadline import SemanticMemoryHit

@@ -34,6 +34,10 @@ _STABLE_CODE = re.compile(r"[a-z][a-z0-9_]{0,95}")

 logger = logging.getLogger(__name__)

+#: Jobs not yet run that a suspended source holds back.
+_WAITING_STATES = frozenset({"pending", "waiting_for_model", "waiting_for_permission"})
+_WAITING_SQL = ",".join(f"'{state}'" for state in sorted(_WAITING_STATES))
+

 class SdkMemoryRuntime:
    """Product services that remain after legacy task/governance writes retire."""
@@ -48,12 +52,19 @@ class SdkMemoryRuntime:
        data_dir: Path,
        memory_mode: Callable[[], str] = lambda: "pro",
        writes_open: Callable[[], bool] = lambda: True,
+        source_active: Callable[[str], bool] = lambda _source_key: True,
    ) -> None:
        self.coordinator = coordinator
        #: The SDK mode, for the graph store's path (`hy_graph_admin`).
        self.memory_mode = memory_mode
        #: False while an embedding switch pauses model writes.
        self.writes_open = writes_open
+        #: Whether a queue lane's source may still become memories: the same
+        #: question the drain's claim asks of it. A lane that is off (the
+        #: user turned the source off, or its grant was revoked) has its
+        #: waiting jobs suspended: kept, never claimed, and not counted as
+        #: pending until the source is on again.
+        self.source_active = source_active
        self.read_handle = read_handle
        self.write_queue = write_queue
        self.extraction_settings = extraction_settings
@@ -241,22 +252,11 @@ class SdkMemoryRuntime:
        now = datetime.now(UTC)
        fresh_since = (now - timedelta(days=7)).isoformat()
        with main_database(self.write_queue.database_path).read() as database:
-            fresh = int(
-                database.execute(
-                    "SELECT COUNT(*) FROM memory_write_jobs "
-                    "WHERE state IN ('pending','waiting_for_model','waiting_for_permission') "
-                    "AND event_at>=?",
-                    (fresh_since,),
-                ).fetchone()[0]
-            )
-            backlog = int(
-                database.execute(
-                    "SELECT COUNT(*) FROM memory_write_jobs "
-                    "WHERE state IN ('pending','waiting_for_model','waiting_for_permission') "
-                    "AND event_at<?",
-                    (fresh_since,),
-                ).fetchone()[0]
-            )
+            rows = database.execute(
+                "SELECT source_key,event_at>=? AS fresh,COUNT(*) FROM memory_write_jobs "
+                f"WHERE state IN ({_WAITING_SQL}) GROUP BY source_key,fresh",
+                (fresh_since,),
+            ).fetchall()
            recent = tuple(
                datetime.fromisoformat(str(row[0]))
                for row in database.execute(
@@ -264,6 +264,9 @@ class SdkMemoryRuntime:
                    "ORDER BY updated_at DESC LIMIT 8"
                )
            )
+        active = self._active_lanes({str(row[0]) for row in rows})
+        fresh = sum(int(row[2]) for row in rows if str(row[0]) in active and row[1])
+        backlog = sum(int(row[2]) for row in rows if str(row[0]) in active and not row[1])
        return QueueDepths(fresh=fresh, backlog=backlog, recent_completions=recent)

    def active_depths(self) -> tuple[int, int]:
@@ -276,13 +279,27 @@ class SdkMemoryRuntime:
        return running, running

    def status_counts(self) -> dict[str, int]:
+        """Jobs per state, with a suspended source's waiting jobs as `suspended`.
+
+        Those jobs keep their state in the table: suspension is the source's
+        switch, not the row's, so turning the source back on is all it takes
+        for the drain to claim them again, and nothing is moved or deleted.
+        """
        with main_database(self.write_queue.database_path).read() as database:
-            return {
-                str(row[0]): int(row[1])
-                for row in database.execute(
-                    "SELECT state,COUNT(*) FROM memory_write_jobs GROUP BY state"
-                )
-            }
+            rows = database.execute(
+                "SELECT source_key,state,COUNT(*) FROM memory_write_jobs GROUP BY source_key,state"
+            ).fetchall()
+        active = self._active_lanes({str(row[0]) for row in rows if str(row[1]) in _WAITING_STATES})
+        counts: dict[str, int] = {}
+        for source_key, state, count in rows:
+            name = str(state)
+            if name in _WAITING_STATES and str(source_key) not in active:
+                name = "suspended"
+            counts[name] = counts.get(name, 0) + int(count)
+        return counts
+
+    def _active_lanes(self, lanes: set[str]) -> set[str]:
+        return {lane for lane in lanes if self.source_active(lane)}

    def manual_batch_progress(self) -> tuple[int, int]:
        return 0, 0
@@ -291,33 +308,11 @@ class SdkMemoryRuntime:
        del task_ids
        return []

-    async def reconcile_unknown_outputs(
-        self,
-        *,
-        limit: int = 128,
-        exclude_error_codes: tuple[str, ...] = (),
-    ) -> int:
-        reconciled = 0
-        for job in await asyncio.to_thread(
-            self.write_queue.unknown_jobs,
-            limit=limit,
-            exclude_error_codes=exclude_error_codes,
-        ):
-            receipt = await self.coordinator.inquire_write_outcome(job.request_id)
-            if receipt is None:
-                continue
-            await asyncio.to_thread(
-                self.write_queue.settle,
-                job.job_id,
-                state=COMPLETED,
-                sdk_raw_ids=receipt.raw_ids,
-                sdk_memory_ids=receipt.memory_ids,
-            )
-            reconciled += 1
-        return reconciled
-
    async def resume_allowed(self) -> None:
-        await asyncio.to_thread(self.write_queue.readmit_parked)
+        await asyncio.to_thread(
+            self.write_queue.readmit_parked,
+            states=(WAITING_FOR_MODEL,),
+        )

    def accepted_backfill_status(self) -> None:
        return None
@@ -288,4 +288,3 @@ def verify_readback(
        productivity_readable=sum(1 for memory_id in legacy.productivity if readable(memory_id)),
        chat_missing_before_migration=chat_missing_before_migration,
    )
-
@@ -29,6 +29,7 @@ from collections.abc import Callable
 from pathlib import Path
 from typing import Any

+from one_memory.background_work import in_sdk_read
 from one_memory.embedding_health import EmbeddingGuardedClient, EmbeddingHealth
 from one_memory.embedding_spaces import (
    EmbeddingSpace,
@@ -93,6 +94,11 @@ class ActiveProfileReadHandle(SdkClientHandle):
        handle = await self.current_handle()
        return self._guarded(handle, await handle.client())

+    async def client_for_mode(self, mode: str) -> Any:
+        """Build/read with the caller's one mode snapshot, without rereading it."""
+        handle = await self.current_handle(mode=mode)
+        return self._guarded(handle, await handle.client())
+
    def _guarded(self, handle: SdkClientHandle, client: Any) -> Any:
        """A remote embedding's searches report `embedding_unavailable` (no fallback)."""
        profile = getattr(handle, "profile", None)
@@ -110,15 +116,15 @@ class ActiveProfileReadHandle(SdkClientHandle):
            ),
        )

-    async def current_handle(self) -> SdkClientHandle:
+    async def current_handle(self, *, mode: str | None = None) -> SdkClientHandle:
        """The handle of the live space, held for the asking task."""
-        space, identity = await asyncio.to_thread(self._resolve)
-        mode, features = self.memory_mode(), self.current_features()
+        space, identity = await in_sdk_read(self._resolve)
+        selected_mode, features = mode or self.memory_mode(), self.current_features()
        language = self.current_language()
        key = (
            space.space_id if space is not None else "",
            *identity,
-            mode,
+            selected_mode,
            features,
            language,
        )
@@ -127,8 +133,8 @@ class ActiveProfileReadHandle(SdkClientHandle):
            if handle is None:
                # Only on a change of space or profile: resolving a key can
                # reach the system keychain, so it is not done on every read.
-                handle = await asyncio.to_thread(
-                    self._build, space, identity, mode, features, language
+                handle = await in_sdk_read(
+                    self._build, space, identity, selected_mode, features, language
                )
                self._handles[key] = handle
            self._retired.update(value for name, value in self._handles.items() if name != key)
@@ -3,12 +3,15 @@
 from __future__ import annotations

 import asyncio
+import re
+import threading
 from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from datetime import datetime
 from typing import Any

+from one_memory.background_work import in_sdk_write
 from one_memory.embedding_spaces import (
    EmbeddingSpace,
    EmbeddingSpaceStore,
@@ -20,14 +23,70 @@ from one_memory.hy_sdk_runtime import (
    SdkClientHandle,
    builtin_retrieval_snapshot,
    language_kwargs,
+    retrieval_view,
 )
 from one_memory.imports.models import EvidenceContentKind, EvidenceOrigin, EvidenceRecord
 from one_memory.input_sanitization import sanitize_model_input
 from one_memory.memory_features import FeatureOverrides
-from one_memory.model_profiles import ModelProfileSnapshot, ModelProfileStore
+from one_memory.model_profiles import ModelProfileSnapshot, ModelProfileStore, ProviderKind
 from one_memory.secrets import SecretStore, SecretStoreUnavailableError

 PRODUCT_AGENT_ID = "all-apps"
+
+#: SDK request ids whose write call is running on a thread right now. A write
+#: the drain gave up on (its work ceiling, a lost lease) keeps running on its
+#: thread; it must not be re-run beside itself (`recover_unknown`).
+_IN_FLIGHT: set[str] = set()
+_IN_FLIGHT_LOCK = threading.Lock()
+
+
+def sdk_write_in_flight(request_id: str) -> bool:
+    with _IN_FLIGHT_LOCK:
+        return request_id in _IN_FLIGHT
+
+
+class _Tracked:
+    """One SDK write call, held in `_IN_FLIGHT` from submission until it ends.
+
+    If the wait for it is cancelled before a thread picked it up, it is
+    abandoned: it will not start, and it leaves `_IN_FLIGHT` at once.
+    """
+
+    def __init__(self, request_id: str, work: Callable[..., Any]) -> None:
+        self.request_id = request_id
+        self.work = work
+        self.started = False
+        self.abandoned = False
+        with _IN_FLIGHT_LOCK:
+            _IN_FLIGHT.add(request_id)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        with _IN_FLIGHT_LOCK:
+            if self.abandoned:
+                raise RuntimeError("hy_memory_write_abandoned")
+            self.started = True
+        try:
+            return self.work(*args, **kwargs)
+        finally:
+            with _IN_FLIGHT_LOCK:
+                _IN_FLIGHT.discard(self.request_id)
+
+    def abandon(self) -> None:
+        with _IN_FLIGHT_LOCK:
+            if not self.started:
+                self.abandoned = True
+                _IN_FLIGHT.discard(self.request_id)
+
+
+async def _write(tracked_id: str, work: Callable[..., Any], /, *args: Any, **kwargs: Any) -> Any:
+    call = _Tracked(tracked_id, work)
+    try:
+        return await in_sdk_write(call, *args, **kwargs)
+    except asyncio.CancelledError:
+        call.abandon()
+        raise
+
+
 _MESSAGE_ROLES = frozenset({"user", "assistant", "tool"})
 _CONVERSATION_ROLES = frozenset({"user", "assistant"})

@@ -54,7 +113,7 @@ class SdkWriteProcessor:
        records: tuple[EvidenceRecord, ...],
        *,
        request_id: str,
-        before_hy_invocation: Callable[[], Awaitable[None]],
+        before_hy_invocation: Callable[[bool], Awaitable[None]],
    ) -> SdkWriteReceipt:
        if not records:
            raise RuntimeError("hy_memory_task_without_inputs")
@@ -81,8 +140,9 @@ class SdkWriteProcessor:

        if extracted and not self._lite:
            contents = [sanitize_model_input(record.verbatim) for record in records]
-            await before_hy_invocation()
-            result = await asyncio.to_thread(
+            await before_hy_invocation(True)
+            result = await _write(
+                request_id,
                client.add_extracted,
                contents,
                user_id=scope.user_id,
@@ -108,8 +168,9 @@ class SdkWriteProcessor:
            ]
            if not messages:
                raise RuntimeError("hy_memory_task_without_inputs")
-            await before_hy_invocation()
-            result = await asyncio.to_thread(
+            await before_hy_invocation(not self._lite)
+            result = await _write(
+                request_id,
                client.add,
                messages,
                user_id=scope.user_id,
@@ -130,7 +191,7 @@ class SdkWriteProcessor:
        if not request_id:
            raise ValueError("request_id is required")
        client = await self._client_handle.client()
-        outcome = await asyncio.to_thread(client.get_write_outcome, request_id)
+        outcome = await in_sdk_write(client.get_write_outcome, request_id)
        if outcome is None:
            return None
        if not isinstance(outcome, Mapping):
@@ -223,10 +284,8 @@ class SdkWriteCoordinator:
        records: tuple[EvidenceRecord, ...],
        *,
        request_id: str,
-        before_hy_invocation: Callable[[], Awaitable[None]],
+        before_hy_invocation: Callable[[bool], Awaitable[None]],
    ) -> SdkWriteReceipt:
-        if not self.sedimentation_enabled():
-            raise RuntimeError("model_sedimentation_disabled")
        if not self.writes_open():
            # An embedding switch paused writes: the drain puts the job back.
            raise RuntimeError("embedding_switch_in_progress")
@@ -237,9 +296,8 @@ class SdkWriteCoordinator:
        self._writing[user_id] = self._writing.get(user_id, 0) + 1
        try:
            async with self._active_handle() as handle:
-                return await SdkWriteProcessor(
-                    handle, lite=getattr(handle, "mode", None) == "lite"
-                ).process_sdk_job(
+                lite = getattr(handle, "mode", None) == "lite"
+                return await SdkWriteProcessor(handle, lite=lite).process_sdk_job(
                    records,
                    request_id=request_id,
                    before_hy_invocation=before_hy_invocation,
@@ -406,24 +464,27 @@ class SdkWriteCoordinator:
            return (builtin.profile_id, builtin.revision), builtin, None, space
        identity = (space.profile_id, space.profile_revision)
        profile = self.profiles.snapshot(*identity)
-        try:
-            secret = self.profiles.resolve_snapshot_secret(*identity, self.secrets)
-        except SecretStoreUnavailableError:
-            raise RuntimeError("secure_storage_unavailable") from None
-        if profile.has_api_key and secret is None:
-            raise RuntimeError("model_secret_unavailable")
-        return identity, profile, secret, space
+        view = retrieval_view(profile)
+        secret: str | None = None
+        if view.embedding_provider_kind is ProviderKind.OPENAI_COMPATIBLE:
+            try:
+                secret = self.profiles.resolve_snapshot_secret(*identity, self.secrets)
+            except SecretStoreUnavailableError:
+                raise RuntimeError("secure_storage_unavailable") from None
+            if secret is None:
+                raise RuntimeError("model_secret_unavailable")
+        return identity, view, secret, space

    def _read_active_credentials(
        self,
        mode: str = "pro",
    ) -> tuple[tuple[str, int], ModelProfileSnapshot, str | None, EmbeddingSpace | None]:
+        if mode == "lite":
+            # A lite write is an embedding-only view of the live space. Never
+            # resolve or inject the generation model endpoint or its secret.
+            return self._lite_credentials()
        identity = self.profiles.active_identity()
        if identity is None:
-            if mode == "lite":
-                # lite stores raw turns with one embedding and calls no model:
-                # the live space's own, so they land where reads look.
-                return self._lite_credentials()
            raise RuntimeError("model_profile_not_active")
        profile = self.profiles.snapshot(*identity)
        space = self._live_space() if self.spaces is not None else None
@@ -509,11 +570,36 @@ def _is_extracted_content(record: EvidenceRecord) -> bool:
    )


+#: The SDK's stable failure codes are upper snake case (`RECONCILE_FAILED`).
+_SDK_FAILURE_CODE = re.compile(r"[A-Z][A-Z0-9_]{0,47}")
+
+
+def sdk_write_failure_code(value: Mapping[object, object]) -> str:
+    """The job's `error_code` for a failed SDK write: the SDK's own cause if it gave one.
+
+    hy-memory 2.0.13 names why a write failed: `agent_error_code`
+    (`LLM_ERROR`, `EMPTY_RESPONSE`, `JSON_PARSE_FAILED`, `EMBEDDING_FAILED`,
+    `RECONCILE_FAILED`) and, for a failed reconcile, `reconcile_error_code`
+    (`LLM_UNAVAILABLE`, `EMPTY_RESPONSE`, `JSON_PARSE_FAILED`,
+    `RECONCILE_EXCEPTION`). They become `hy_sdk_reconcile_empty_response`,
+    `hy_sdk_llm_error`, ... Without a recognisable code it stays
+    `hy_sdk_write_failed`. Only the code is kept, never the SDK's message.
+    """
+    reconcile = value.get("reconcile_error_code")
+    if isinstance(reconcile, str) and _SDK_FAILURE_CODE.fullmatch(reconcile):
+        cause = reconcile.removeprefix("RECONCILE_") or "FAILED"
+        return f"hy_sdk_reconcile_{cause.lower()}"
+    agent = value.get("agent_error_code")
+    if isinstance(agent, str) and _SDK_FAILURE_CODE.fullmatch(agent):
+        return f"hy_sdk_{agent.lower()}"
+    return "hy_sdk_write_failed"
+
+
 def _receipt_from_result(value: object) -> SdkWriteReceipt:
    if not isinstance(value, Mapping):
        raise RuntimeError("hy_sdk_write_receipt_shape_invalid")
    if value.get("success") is not True:
-        raise RuntimeError("hy_sdk_write_failed")
+        raise RuntimeError(sdk_write_failure_code(value))

    # Read only documented public receipt fields. ``variant`` identifies the
    # productivity namespace; IDs from both variants are canonical memory IDs.
@@ -0,0 +1,283 @@
+"""Stable UI projections over the HY SDK's mode-specific storage shapes."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from datetime import UTC, datetime
+from typing import Any, Literal, cast
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from one_memory.hy_sdk_types import (
+    HySdkMemoryPage,
+    HySdkMemoryRecord,
+    HySdkRawPage,
+    HySdkRawRecord,
+    raw_turn_messages,
+)
+from one_memory.imports.sources.parsing import unwrap_host_envelope_with_positions
+
+MemoryMode = Literal["lite", "pro", "ultra"]
+TimeBasis = Literal["conversation", "import", "write", "update"]
+ProjectionDisplayState = Literal["empty", "excerpt", "no_user_excerpt", "no_displayable_memory"]
+RAW_STATUSES = ("active", "shadow")
+HOME_PROJECTION_CANDIDATES = 10
+HOME_EXCERPT_CODEPOINTS = 200
+
+_SPACE = re.compile(r"\s+")
+_CONTROL_ONLY = re.compile(
+    r"^(?:"
+    r"<<?\s*(?:image|attachment|system[_-]?reminder|no[_ -]?content)\s*>>?"
+    r"|\[\s*(?:image|attachment|system[_ -]?reminder|no[_ -]?content)\s*\]"
+    r")$",
+    re.IGNORECASE,
+)
+
+
+class HomeProjectionCapabilities(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    content_plane: Literal["raw", "memory"]
+    generation_required: bool
+    graph_enabled: bool
+    evolve_available: bool
+
+
+class _HomeLatest(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    time: datetime | None
+    time_basis: TimeBasis | None
+    excerpt: str
+    truncated: bool
+    source_id: str
+
+
+class HomeRawLatest(_HomeLatest):
+    type: Literal["raw"] = "raw"
+    raw_id: str
+    session_id: str
+    display_state: Literal["excerpt", "no_user_excerpt"]
+
+
+class HomeMemoryLatest(_HomeLatest):
+    type: Literal["memory"] = "memory"
+    memory_id: str
+    scene: Literal["chat", "working", "coding"]
+    # scene=all lists chat rows and productivity experiences; facts are not
+    # part of that page or its total.
+    kind: Literal["chat", "experience"]
+    variant: Literal["working", "coding"] | None
+
+
+class HomeProjectionV1(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    projection_version: Literal[1] = 1
+    user_id: str
+    effective_mode: MemoryMode
+    capabilities: HomeProjectionCapabilities
+    visible_count: int = Field(ge=0)
+    display_state: ProjectionDisplayState
+    latest: HomeRawLatest | HomeMemoryLatest | None
+    observed_at: datetime
+
+
+def raw_list_filters(statuses: list[str] | tuple[str, ...] | None = None) -> dict[str, list[str]]:
+    """The one kept-raw definition shared by `/raw` and the home projection."""
+    return {
+        "layers": ["l1_raw"],
+        "statuses": list(statuses or RAW_STATUSES),
+    }
+
+
+def home_capabilities(mode: MemoryMode) -> HomeProjectionCapabilities:
+    return HomeProjectionCapabilities(
+        content_plane="raw" if mode == "lite" else "memory",
+        generation_required=mode != "lite",
+        graph_enabled=mode == "ultra",
+        evolve_available=mode == "ultra",
+    )
+
+
+def raw_user_excerpt(content: str, *, limit: int = HOME_EXCERPT_CODEPOINTS) -> tuple[str, bool]:
+    """Return only displayable user text from one SDK raw turn.
+
+    Role selection happens before wrapper removal, so assistant/system content
+    can never become a homepage excerpt after sanitization.
+    """
+    candidates: list[str] = []
+    for role, text in raw_turn_messages(content):
+        if role != "user":
+            continue
+        envelope = unwrap_host_envelope_with_positions(text)
+        if envelope.status == "ambiguous":
+            # An uncertain host envelope may contain system context. Showing
+            # nothing is safer than guessing which bytes the person authored.
+            continue
+        cleaned = envelope.text or ""
+        cleaned = _SPACE.sub(" ", cleaned).strip()
+        if not cleaned or _CONTROL_ONLY.fullmatch(cleaned):
+            continue
+        candidates.append(cleaned)
+    joined = " ".join(candidates)
+    return joined[:limit], len(joined) > limit
+
+
+def _epoch(value: int | None) -> datetime | None:
+    return datetime.fromtimestamp(value, tz=UTC) if value is not None else None
+
+
+def _raw_time(record: HySdkRawRecord) -> tuple[datetime | None, TimeBasis | None]:
+    if record.memory_at is not None:
+        return _epoch(record.memory_at), "conversation"
+    if record.gmt_created is not None:
+        return _epoch(record.gmt_created), "import"
+    return None, None
+
+
+def _memory_time(record: HySdkMemoryRecord) -> tuple[datetime | None, TimeBasis | None]:
+    # Exactly the scene=all merge key. `memory_at` is event time and does not
+    # decide which row list_memories returns first.
+    if record.sort_updated_at is not None:
+        return _epoch(record.sort_updated_at), "update"
+    written = record.gmt_created if record.scene == "chat" else record.created_at
+    if written is not None:
+        return _epoch(written), "write"
+    return None, None
+
+
+def _bounded(text: str) -> tuple[str, bool]:
+    flattened = _SPACE.sub(" ", text).strip()
+    return flattened[:HOME_EXCERPT_CODEPOINTS], len(flattened) > HOME_EXCERPT_CODEPOINTS
+
+
+def project_raw_latest(records: tuple[HySdkRawRecord, ...]) -> HomeRawLatest | None:
+    if not records:
+        return None
+    for record in records:
+        excerpt, truncated = raw_user_excerpt(record.content)
+        if excerpt:
+            at, basis = _raw_time(record)
+            return HomeRawLatest(
+                raw_id=record.raw_id,
+                session_id=record.session_id,
+                display_state="excerpt",
+                time=at,
+                time_basis=basis,
+                excerpt=excerpt,
+                truncated=truncated,
+                source_id=record.source,
+            )
+    newest = records[0]
+    at, basis = _raw_time(newest)
+    return HomeRawLatest(
+        raw_id=newest.raw_id,
+        session_id=newest.session_id,
+        display_state="no_user_excerpt",
+        time=at,
+        time_basis=basis,
+        excerpt="",
+        truncated=False,
+        source_id=newest.source,
+    )
+
+
+def project_memory_latest(
+    records: tuple[HySdkMemoryRecord, ...],
+) -> HomeMemoryLatest | None:
+    record = next(
+        (
+            item
+            for item in records
+            if item.kind in {"chat", "experience"}
+            and (
+                (item.kind == "chat" and item.scene == "chat" and item.variant is None)
+                or (
+                    item.kind == "experience"
+                    and item.scene in {"working", "coding"}
+                    and item.variant == item.scene
+                )
+            )
+        ),
+        None,
+    )
+    if record is None:
+        return None
+    excerpt, truncated = _bounded(record.content)
+    at, basis = _memory_time(record)
+    return HomeMemoryLatest(
+        memory_id=record.memory_id,
+        scene=record.scene,
+        kind=cast(Literal["chat", "experience"], record.kind),
+        variant=record.variant,
+        time=at,
+        time_basis=basis,
+        excerpt=excerpt,
+        truncated=truncated,
+        source_id=record.source or "",
+    )
+
+
+async def read_home_projection(
+    client: Any,
+    *,
+    user_id: str,
+    mode: MemoryMode,
+) -> HomeProjectionV1:
+    """Read one authoritative projection; any SDK/shape failure escapes."""
+    client_mode = getattr(client, "mode", mode)
+    if client_mode != mode:
+        raise RuntimeError("home_projection_mode_mismatch")
+    if mode == "lite":
+        raw = await asyncio.to_thread(
+            client.list_memories,
+            user_id=user_id,
+            **raw_list_filters(),
+            limit=HOME_PROJECTION_CANDIDATES,
+            offset=0,
+            order="desc",
+        )
+        raw_page = HySdkRawPage.from_memory_list(raw, limit=HOME_PROJECTION_CANDIDATES, offset=0)
+        visible_count = raw_page.total
+        raw_latest = project_raw_latest(raw_page.raw)
+        latest: HomeRawLatest | HomeMemoryLatest | None = raw_latest
+        display_state: ProjectionDisplayState = (
+            "empty"
+            if visible_count == 0
+            else raw_latest.display_state
+            if raw_latest is not None
+            else "no_user_excerpt"
+        )
+    else:
+        raw = await asyncio.to_thread(
+            client.list_memories,
+            user_id=user_id,
+            scene="all",
+            statuses=["active"],
+            limit=HOME_PROJECTION_CANDIDATES,
+            offset=0,
+            order="desc",
+        )
+        memory_page, _skipped = HySdkMemoryPage.from_sdk_skipping_invalid(
+            raw, limit=HOME_PROJECTION_CANDIDATES, offset=0
+        )
+        visible_count = memory_page.total
+        latest = project_memory_latest(memory_page.memories)
+        display_state = (
+            "empty"
+            if visible_count == 0
+            else "excerpt"
+            if latest is not None
+            else "no_displayable_memory"
+        )
+    return HomeProjectionV1(
+        user_id=user_id,
+        effective_mode=mode,
+        capabilities=home_capabilities(mode),
+        visible_count=visible_count,
+        display_state=display_state,
+        latest=latest,
+        observed_at=datetime.now(UTC),
+    )
@@ -25,6 +25,7 @@
 | `test_c1_cross_source_session_isolation.py` | `contract` | Same session name in two sources must stay two conversations. |
 | `test_c1_damage_per_source.py` | `contract` | Damage and unknown schema, per source: a bad record must not sink the import. |
 | `test_c1_deepseek_profiles.py` | `contract` | DeepSeek Harness has two profiles; only the headless session form is importable. |
+| `test_c1_deepseek_versioned_sessions.py` | `contract` | DeepSeek Harness versions its session file names; every generation must import. |
 | `test_c1_import_event_matrix.py` | `contract` | C1 owned matrix: existing history, new file, append, truncate/replace, restart, revoke. |
 | `test_c1_import_failure_injection.py` | `contract` | C1 failure injection: atomic receipt, disk-full, read-only source, rotation. |
 | `test_c1_import_instrumentation.py` | `contract` | Instrumented import accounting: bytes read, opens, hashes, jobs, duplicates. |
@@ -110,6 +111,7 @@
 | `test_health.py` | `contract` | 覆盖 a backfill that fails says so rather than disappearing、a failed catch up leaves a traceback behind、configured model without content consent does not start backfill 等 15 个场景。 |
 | `test_hermes_gateway_injection.py` | `contract` | Hermes gateway text in `user` rows: notices are skipped, relayed messages unwrapped. |
 | `test_history_listing_rotation.py` | `contract` | 覆盖 history listing alternates started and untouched files、history listing drains whichever cohort is longer 场景。 |
+| `test_home_projection.py` | `contract` | 覆盖 memory projection covers pro and ultra、memory projection preserves productivity namespace、project raw latest uses import time without conversation time 等 7 个场景。 |
 | `test_host_capabilities.py` | `unit` | A plugin does not become realtime on every host or every unknown version. |
 | `test_hourly_c1_peak_replay_contract.py` | `contract` | Guard the package peak-replay probe's error accounting. |
 | `test_hourly_c1_recall_stage_probe_contract.py` | `contract` | Guard the packaged recall stage probe's command and error semantics. |
@@ -121,6 +123,7 @@
 | `test_import_api.py` | `integration` | 覆盖 resume during cleanup returns conflict without internal error、authorize detect import and revoke api flow、protected api rejects missing token and foreign origin 等 5 个场景。 |
 | `test_import_control_races_review.py` | `contract` | Read-only review repro: real runner/store, synthetic delayed adapter cleanup. |
 | `test_import_evidence_atomicity.py` | `contract` | 覆盖 counter failure rolls back evidence versions and cursor、same identity cursor rewind is blocked and logged、replaced identity may reset checkpoint 等 20 个场景。 |
+| `test_import_job_retention.py` | `integration` | `import_jobs` stays bounded, and the questions asked of it are SQL, not scans. |
 | `test_import_oversized_verbatim.py` | `contract` | 覆盖 normal verbatim is unchanged、oversized verbatim is truncated instead of rejected 场景。 |
 | `test_import_runner.py` | `contract` | 覆盖 job transitions are explicit、runner keeps per record errors and continues、sync slices reuse the same source listing 等 22 个场景。 |
 | `test_import_skip_batching.py` | `contract` | 覆盖 batch limit and tail use fewer commits、batched skips keep their order against the next write、flushes before every nonmatching event 等 14 个场景。 |
@@ -135,7 +138,7 @@
 | `test_internal_preset.py` | `contract` | The optional model preset a configured build carries. |
 | `test_jsonl_snapshot_tail.py` | `contract` | Bounded EOF handling on synthetic files only, never original host history. |
 | `test_library_search_window.py` | `unit` | The library search window store and the unified record/keyword parsing. |
-| `test_live_capture.py` | `integration` | Visible hook text lands in Evidence before the transcript file is flushed. |
+| `test_live_capture.py` | `integration` | Hooks hand visible text to Core, which stages it once, without Evidence. |
 | `test_live_sync.py` | `contract` | 覆盖 live sync preempts a reader batch before it emits work、live sync cuts in front of a running history import、live sync does not resume a history import the user paused 等 24 个场景。 |
 | `test_live_sync_file_incremental.py` | `contract` | 覆盖 unchanged file metadata avoids a job and content read、changed file content is read once by the import job、workbuddy first live poll baselines history then imports only append 等 6 个场景。 |
 | `test_live_sync_job_coalescing.py` | `contract` | A poll that finds nothing must not leave an import job behind. |
@@ -189,6 +192,7 @@
 | `test_memory_write_registry.py` | `contract` | A3-01: acceptance and outcome recording for the unified write path. |
 | `test_memory_write_routes.py` | `integration` | A3-01: the HTTP write entry, tested against a real FastAPI app. |
 | `test_migrate_off_sqlite.py` | `contract` | A1-06: the migration is only done when reconciliation agrees. |
+| `test_model_backoff.py` | `contract` | A broken model configuration must not turn a backlog into a request storm (#245). |
 | `test_model_creation_api.py` | `integration` | Normal protected model creation routes with temporary data and in-memory secrets. |
 | `test_model_creation_operations.py` | `contract` | 覆盖 lookup without table is read only and legacy create does not initialize、operation commits with profile and version without autoactivation、any replay conflicts before secret put 等 21 个场景。 |
 | `test_model_creation_validation_boundary.py` | `integration` | Real ASGI validation must precede creation reservation and secret writes. |
@@ -210,6 +214,7 @@
 | `test_onboarding_profile.py` | `integration` | R-09：首次安装引导把画像录下来，不问用户一句话。 |
 | `test_oversized_file_guard.py` | `contract` | One pass over a source file is bounded by a byte budget, not skipped. |
 | `test_parent_watchdog.py` | `integration` | A Core that outlives its launcher makes the next launch impossible. |
+| `test_pinned_sdk_raw_search.py` | `integration` | MemHub's raw search against the hy-memory wheel it pins, not the repo source. |
 | `test_policy_api_wiring.py` | `integration` | 覆盖 global model permission off does not backfill、backfill puts history on write jobs without scheduling memory tasks、source pause skips history until the source is reenabled 场景。 |
 | `test_policy_production_entry.py` | `contract` | 覆盖 production serve passes only supported app options、maintenance serve does not own the runtime 场景。 |
 | `test_precipitation_concurrency_setting.py` | `contract` | Rule 2/9: precipitation concurrency is configurable, not hardcoded to 1. |
@@ -318,4 +323,4 @@
 | `test_workspace_recall.py` | `contract` | Workspace memories were unreachable from every host; these pin the way in. |
 | `test_write_queue_lease_renewal.py` | `contract` | Rule 8: a lease must outlive the work it covers, and be renewed while it runs. |

-共 313 个测试文件。
+共 318 个测试文件。
@@ -14,8 +14,8 @@ from pathlib import Path
 import pytest

 PRIMARY_MARKERS = ("unit", "contract", "integration", "performance", "live")
-EXPECTED_TEST_FILE_COUNT = 313
-EXPECTED_TEST_FILES_SHA256 = "dcada5d5421767196a79e415dd47c2b6c6d67681972dbe81481b31867d318928"
+EXPECTED_TEST_FILE_COUNT = 318
+EXPECTED_TEST_FILES_SHA256 = "df8752566a0bf9e540f68b4948f3f5dbc409bd6836707b1330206e2349d70940"

 # Pure transformations, validation models, parity checks and state machines.
 # This list is intentionally small: uncertain files default to contract.
@@ -70,6 +70,7 @@ INTEGRATION_FILES = frozenset(
        "test_file_import_operations.py",
        "test_graph_width_endpoint.py",
        "test_import_api.py",
+        "test_import_job_retention.py",
        "test_live_capture.py",
        "test_live_watch_grants.py",
        "test_log_privacy.py",
@@ -93,6 +94,7 @@ INTEGRATION_FILES = frozenset(
        "test_model_profile_context_reset.py",
        "test_onboarding_profile.py",
        "test_parent_watchdog.py",
+        "test_pinned_sdk_raw_search.py",
        "test_policy_api_wiring.py",
        "test_recall_scope_control.py",
        "test_retrieval_lifespan.py",
@@ -39,8 +39,7 @@ def kuzu_graph_with_embedding_width(db_path: Path, width: int) -> None:
    database = kuzu.Database(str(db_path))
    connection = kuzu.Connection(database)
    connection.execute(
-        f"CREATE NODE TABLE Memory("
-        f"node_id STRING, embedding FLOAT[{width}], PRIMARY KEY(node_id))"
+        f"CREATE NODE TABLE Memory(node_id STRING, embedding FLOAT[{width}], PRIMARY KEY(node_id))"
    )
    del connection
    del database
@@ -29,7 +29,6 @@ from one_memory.imports.sources.registry import (
    build_source_catalog,
 )
 from one_memory.imports.supervisor import ImportSupervisor
-from one_memory.live_capture import capture_hook

 FREEZE_THRESHOLD_SECONDS = 1.0

@@ -228,31 +227,17 @@ async def _run(

        hook_text = "realtime hook while history import is running"
        hook_started = time.monotonic()
-        result["hook_accepted"] = await asyncio.to_thread(
-            capture_hook,
-            "workbuddy",
-            {
+        # A hook hands its turn to Core over loopback; it no longer writes the
+        # database itself. What is measured is that hand-off under import load.
+        handed = await client.post(
+            "/api/v1/live-capture/workbuddy",
+            json={
                "hook_event_name": "UserPromptSubmit",
                "session_id": "pressure-live-session",
                "prompt": hook_text,
            },
-            app.state.evidence_store.database_path,
        )
-        hook_deadline = hook_started + 10
-        hook_stored = False
-        while time.monotonic() < hook_deadline:
-            with sqlite3.connect(app.state.evidence_store.database_path) as connection:
-                hook_stored = (
-                    connection.execute(
-                        "SELECT 1 FROM evidence WHERE source_id='workbuddy' AND verbatim=?",
-                        (hook_text,),
-                    ).fetchone()
-                    is not None
-                )
-            if hook_stored:
-                break
-            await asyncio.sleep(0.01)
-        result["hook_stored"] = hook_stored
+        result["hook_accepted"] = handed.status_code == 202
        result["hook_visible_ms"] = round((time.monotonic() - hook_started) * 1000, 1)

        during, during_unavailable, sampled_terminal = await _measure_recall_until(
@@ -104,9 +104,7 @@ SDK_PRIVATE_ATTRIBUTES = frozenset(
    }
 )
 SDK_PRIVATE_ACCESS_EXCEPTIONS = {
-    f"{PACKAGE_LABEL}/hy_graph_projection.py": frozenset(
-        {"_graph_store", "_loop_thread", "_run"}
-    ),
+    f"{PACKAGE_LABEL}/hy_graph_projection.py": frozenset({"_graph_store", "_loop_thread", "_run"}),
    # Startup migration runs while Runtime writers are stopped. It is the one
    # non-runtime path allowed to manipulate SDK storage directly so that
    # migration-only mechanics never become public HyMemoryClient methods.
@@ -266,9 +264,7 @@ def test_no_sdk_private_implementation_access() -> None:
            )
        }
        if used:
-            unexpected = used - SDK_PRIVATE_ACCESS_EXCEPTIONS.get(
-                relative, frozenset()
-            )
+            unexpected = used - SDK_PRIVATE_ACCESS_EXCEPTIONS.get(relative, frozenset())
            if unexpected:
                offenders.append(f"{relative}: {sorted(unexpected)}")
    assert not offenders, (
@@ -291,9 +287,7 @@ def test_sdk_modules_import_only_the_public_package_root() -> None:
            ):
                offenders.append(relative)
                break
-            if isinstance(node, ast.ImportFrom) and (
-                node.module or ""
-            ).startswith("hy_memory."):
+            if isinstance(node, ast.ImportFrom) and (node.module or "").startswith("hy_memory."):
                offenders.append(relative)
                break
            if (
@@ -324,3 +324,48 @@ def test_saturated_raw_reads_do_not_delay_memory_reads() -> None:
    finally:
        release_raw.set()
        shutdown_bulk_pool()
+
+
+def test_recall_reads_answer_while_every_sdk_write_thread_is_stuck() -> None:
+    """A write that hangs in the SDK keeps its thread, not recall's (#231)."""
+    from one_memory.background_work import SDK_WRITE_WORKERS, in_sdk_read, in_sdk_write
+
+    stuck = threading.Barrier(SDK_WRITE_WORKERS + 1)
+    release = threading.Event()
+
+    def hung_write() -> None:
+        stuck.wait(timeout=2)
+        assert release.wait(5)
+
+    async def scenario() -> tuple[float, int]:
+        writes = [asyncio.create_task(in_sdk_write(hung_write)) for _ in range(SDK_WRITE_WORKERS)]
+        # One more than the pool holds: it waits for a write thread, as the
+        # drain's next write would.
+        queued = asyncio.create_task(in_sdk_write(lambda: None))
+        await asyncio.to_thread(stuck.wait, 2)
+        started = time.monotonic()
+        answer = await asyncio.wait_for(in_sdk_read(lambda: 7), 1)
+        elapsed = time.monotonic() - started
+        assert not queued.done()
+        release.set()
+        await asyncio.gather(*writes, queued)
+        return elapsed, answer
+
+    try:
+        elapsed, answer = asyncio.run(scenario())
+        assert answer == 7
+        assert elapsed < 0.2
+    finally:
+        release.set()
+        shutdown_bulk_pool()
+
+
+def test_sdk_writes_run_on_their_own_bounded_threads() -> None:
+    from one_memory.background_work import SDK_WRITE_WORKERS, in_sdk_write, sdk_write_pool
+
+    try:
+        name = asyncio.run(in_sdk_write(lambda: threading.current_thread().name))
+        assert name.startswith("one-memory-sdk-write")
+        assert sdk_write_pool()._max_workers == SDK_WRITE_WORKERS
+    finally:
+        shutdown_bulk_pool()
@@ -0,0 +1,246 @@
+"""DeepSeek Harness versions its session file names; every generation must import.
+
+The first format writes `<session>/session.jsonl[.zstd]`; v3 and v4 write
+`session.v3.jsonl.zstd` / `session.v4.jsonl.zstd`. Discovery used to match only
+the two unversioned names, so every v3/v4 session was invisible to the import
+job — `discovered 0` while the files sat on disk. These tests pin the file-name
+contract, the header gate that keeps an unknown future version out of the
+database, and the upgrade path where a library imported before the fix picks up
+the versioned files on its next scan.
+"""
+
+import json
+from pathlib import Path
+
+import pytest
+import zstandard
+
+from one_memory.imports.adapters import ScanFailure, ScanIssueCode
+from one_memory.imports.sources import deepseek_harness
+from one_memory.imports.sources.deepseek_harness import (
+    DEEPSEEK_HARNESS_DESCRIPTOR,
+    create_deepseek_harness_adapter,
+)
+from tests.test_secondary_source_adapters import (
+    _cursors,
+    _evidence,
+    _evidence_text,
+    _grant,
+    _scan,
+    _skip_codes,
+)
+
+
+def _write_session(directory: Path, name: str, records: list[dict[str, object]]) -> None:
+    directory.mkdir(parents=True, exist_ok=True)
+    payload = "".join(f"{json.dumps(record)}\n" for record in records).encode()
+    (directory / name).write_bytes(zstandard.ZstdCompressor().compress(payload))
+
+
+def _conversation(version: int | None, *, directory: str = "run-a") -> list[dict[str, object]]:
+    header: dict[str, object] = {
+        "type": "session",
+        "version": version,
+        "id": directory,
+        "cwd": "/private/versioned-project",
+    }
+    return [
+        header,
+        {
+            "type": "user/message",
+            "seq": 1,
+            "data": {
+                "id": "human",
+                "role": "user",
+                "source": {"kind": "user"},
+                "content": [{"type": "text", "text": "visible human"}],
+            },
+        },
+        {
+            "type": "assistant/message",
+            "seq": 2,
+            "data": {
+                "message": {
+                    "id": "assistant",
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": "visible assistant"}],
+                }
+            },
+        },
+    ]
+
+
+def _session_adapter(tmp_path: Path):
+    root = tmp_path / "dsh"
+    root.mkdir(parents=True, exist_ok=True)
+    return root, create_deepseek_harness_adapter(
+        _grant(DEEPSEEK_HARNESS_DESCRIPTOR.source_id, root, tmp_path)
+    )
+
+
+def test_versioned_v4_session_file_is_discovered_and_imported(tmp_path: Path) -> None:
+    root, adapter = _session_adapter(tmp_path)
+    session = root / "run-v4"
+    records = _conversation(4, directory="run-v4")
+    records.append(
+        {
+            "type": "tool/result",
+            "seq": 3,
+            "time": 1793341068763,
+            "data": {
+                "callId": "call-1",
+                "message": {"role": "tool", "content": [{"type": "text", "text": "tool output"}]},
+            },
+        }
+    )
+    _write_session(session, "session.v4.jsonl.zstd", records)
+    # A rotated backup next to the live file must not be imported as a second copy.
+    (session / "session.v4.jsonl.zstd.orig-20261027").write_bytes(
+        zstandard.ZstdCompressor().compress(b'{"type":"session","version":4}\n')
+    )
+
+    events = _scan(adapter)
+
+    assert _evidence_text(events) == ["visible human", "visible assistant", "tool output"]
+    evidence = _evidence(events)
+    assert {event.evidence.project for event in evidence} == {"versioned-project"}
+    assert {event.evidence.conversation_id for event in evidence} == {"run-v4"}
+
+
+def test_versioned_v3_session_file_is_discovered_and_imported(tmp_path: Path) -> None:
+    root, adapter = _session_adapter(tmp_path)
+    _write_session(root / "run-v3", "session.v3.jsonl.zstd", _conversation(3))
+
+    events = _scan(adapter)
+
+    assert _evidence_text(events) == ["visible human", "visible assistant"]
+
+
+def _tool_result(content: list[dict[str, object]]) -> dict[str, object]:
+    return {
+        "type": "tool/result",
+        "seq": 3,
+        "data": {"callId": "call-1", "message": {"role": "tool", "content": content}},
+    }
+
+
+def test_tool_output_imports_in_either_block_shape(tmp_path: Path) -> None:
+    """`tool/result` output written as `text` blocks used to be dropped.
+
+    Only `tool-result` blocks were read, so a session that writes plain `text`
+    blocks lost every tool output. Both shapes must arrive, in any generation.
+    """
+    root, adapter = _session_adapter(tmp_path)
+    v3 = _conversation(3, directory="run-v3-text")
+    v3.append(_tool_result([{"type": "text", "text": "v3 text output"}]))
+    _write_session(root / "run-v3-text", "session.v3.jsonl.zstd", v3)
+    v0 = _conversation(0, directory="run-v0-block")
+    v0.append(_tool_result([{"type": "tool-result", "content": "v0 block output"}]))
+    _write_session(root / "run-v0-block", "session.jsonl.zstd", v0)
+
+    texts = _evidence_text(_scan(adapter))
+
+    assert "v3 text output" in texts
+    assert "v0 block output" in texts
+
+
+def test_text_tool_output_is_scrubbed_like_block_output(tmp_path: Path) -> None:
+    root, adapter = _session_adapter(tmp_path)
+    secret = "sk-" + "a" * 40
+    records = _conversation(4, directory="run-secret")
+    records.append(_tool_result([{"type": "text", "text": f"token {secret} " + "x" * 5000}]))
+    _write_session(root / "run-secret", "session.v4.jsonl.zstd", records)
+
+    tool = _evidence_text(_scan(adapter))[-1]
+
+    assert secret not in tool
+    assert len(tool) < 2000
+
+
+def test_session_file_names_outside_the_contract_are_not_imported(tmp_path: Path) -> None:
+    root, adapter = _session_adapter(tmp_path)
+    for name in (
+        "session.v4.jsonl.zstd.orig-20261027",
+        "session.vx.jsonl.zstd",
+        "other.v4.jsonl.zstd",
+        "session.v4.json",
+    ):
+        _write_session(root / name.replace(".", "-"), name, _conversation(4))
+
+    assert _evidence(_scan(adapter)) == []
+
+
+def test_unknown_future_session_version_imports_nothing(tmp_path: Path) -> None:
+    root, adapter = _session_adapter(tmp_path)
+    records = _conversation(5)
+    records.append(
+        {
+            "type": "user/message",
+            "seq": 9,
+            "data": {
+                "id": "future",
+                "role": "user",
+                "source": {"kind": "user"},
+                "content": [{"type": "text", "text": "future generation payload"}],
+            },
+        }
+    )
+    _write_session(root / "run-v5", "session.v5.jsonl.zstd", records)
+
+    events = _scan(adapter)
+
+    assert _evidence(events) == []
+    assert ScanIssueCode.UNSUPPORTED_SCHEMA in _skip_codes(events)
+
+
+def test_unknown_session_version_is_reported_and_read_once_supported(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Not importing a future format yet must stay "yet".
+
+    A cursor left behind by the refused scan would put the whole session behind
+    the checkpoint, so the release that learns the format would read nothing.
+    """
+    root, adapter = _session_adapter(tmp_path)
+    _write_session(root / "run-v5", "session.v5.jsonl.zstd", _conversation(5))
+
+    refused = _scan(adapter)
+
+    assert _cursors(refused) == {}
+    assert [event.reason_code for event in refused if isinstance(event, ScanFailure)] == [
+        ScanIssueCode.UNSUPPORTED_SCHEMA
+    ]
+
+    monkeypatch.setattr(deepseek_harness, "SUPPORTED_SESSION_VERSIONS", frozenset({0, 3, 4, 5}))
+    _, upgraded = _session_adapter(tmp_path)
+
+    assert _evidence_text(_scan(upgraded, cursors=_cursors(refused))) == [
+        "visible human",
+        "visible assistant",
+    ]
+
+
+def test_upgrade_scan_rediscovers_versioned_files_already_on_disk(tmp_path: Path) -> None:
+    """A library imported before this fix must pick up the files on its next scan.
+
+    The first scan sees only the unversioned session that the old predicate
+    matched; after the upgrade, the versioned file next to it is discovered by
+    the next scan while the already imported session stays deduplicated by the
+    cursor it left behind.
+    """
+    root, adapter = _session_adapter(tmp_path)
+    old = root / "run-old"
+    _write_session(old, "session.jsonl.zstd", _conversation(0, directory="run-old"))
+    first_scan = _scan(adapter)
+    assert _evidence_text(first_scan) == ["visible human", "visible assistant"]
+    assert _evidence(first_scan)[0].evidence.conversation_id == "run-old"
+
+    versioned = root / "run-v4"
+    _write_session(versioned, "session.v4.jsonl.zstd", _conversation(4, directory="run-v4"))
+    cursors = _cursors(first_scan)
+    assert cursors  # the old session left a cursor behind
+
+    upgrade_scan = _scan(adapter, cursors=cursors)
+
+    assert _evidence_text(upgrade_scan) == ["visible human", "visible assistant"]
+    assert {event.evidence.conversation_id for event in _evidence(upgrade_scan)} == {"run-v4"}
@@ -131,3 +131,24 @@ def test_run_as_the_entry_it_ends_itself_while_still_importing(tmp_path) -> None
        _reap([process])
    assert process.returncode == -signal.SIGALRM
    assert time.monotonic() - started < 10
+
+
+def test_with_no_core_a_real_capture_exits_at_once_and_writes_nothing(tmp_path) -> None:
+    # The process a host actually starts: no Core is running for this home,
+    # so the turn is dropped. Nothing may fall back to writing the database.
+    data_dir = tmp_path / "data"
+    env = {
+        key: value for key, value in os.environ.items() if key != "ONE_MEMORY_CAPTURE_DEADLINE_S"
+    }
+    env.update(HOME=str(tmp_path), ONE_MEMORY_DATA_DIR=str(data_dir))
+    payload = b'{"hook_event_name": "UserPromptSubmit", "session_id": "s", "prompt": "hi"}'
+    result = subprocess.run(
+        [sys.executable, "-m", "one_memory.cli", "capture", "workbuddy"],
+        input=payload,
+        capture_output=True,
+        env=env,
+        timeout=60,
+        check=False,
+    )
+    assert (result.returncode, result.stdout, result.stderr) == (0, b"", b"")
+    assert not (data_dir / "one-memory.sqlite3").exists()
@@ -16,6 +16,8 @@ def database(tmp_path):
    path = tmp_path / "context.sqlite3"
    with closing(sqlite3.connect(path)) as db, db:
        db.execute("CREATE TABLE source_grants(user_id TEXT, source_id TEXT, revoked_at TEXT)")
+        db.execute("INSERT INTO source_grants VALUES('local','cursor',NULL)")
+        db.execute("INSERT INTO source_grants VALUES('local','codex',NULL)")
        db.execute("INSERT INTO source_grants VALUES('local','revoked','2026-09-19')")
        db.execute("INSERT INTO source_grants VALUES('other','cursor','2026-09-19')")
    return path
@@ -43,16 +45,14 @@ def test_memory_only_never_reads_raw_authority(database, monkeypatch):
    assert not result.raw_allowed and result.raw_sources == frozenset()


-def test_raw_permission_does_not_grant_memory_and_removes_revoked_sources(database):
-    result = resolve(
-        database, access(["om_conversations"], ["all-apps", "source:cursor", "source:revoked"])
-    )
-    assert result.raw_allowed and result.raw_sources == frozenset({"cursor"})
+def test_all_apps_raw_reads_every_connected_source_and_removes_revoked_sources(database):
+    result = resolve(database, access(["om_conversations"], ["all-apps", "source:cursor"]))
+    assert result.raw_allowed and result.raw_sources == frozenset({"cursor", "codex"})
    assert not result.memory_allowed


-@pytest.mark.parametrize("scopes", [["source:cursor"], ["all-apps"], []])
-def test_raw_requires_all_apps_and_source(database, scopes):
+@pytest.mark.parametrize("scopes", [["source:cursor"], []])
+def test_raw_requires_all_apps(database, scopes):
    with pytest.raises(HTTPException) as error:
        resolve(database, access(["om_conversations"], scopes))
    assert error.value.status_code == 403
@@ -80,9 +80,7 @@ def test_explicit_raw_filter_must_be_currently_authorized(database, source):
    with pytest.raises(HTTPException) as error:
        resolve(
            database,
-            access(
-                ["om_recall", "om_conversations"], ["all-apps", "source:cursor", "source:revoked"]
-            ),
+            access(["om_recall", "om_conversations"], ["all-apps"]),
            raw_source_ids=(source,),
        )
    assert error.value.status_code == 403
@@ -104,10 +102,19 @@ def test_filters_do_not_change_memory_scope(database):
    assert result.raw_sources == frozenset({"cursor"})


-def test_implicit_revoked_raw_path_can_be_reported_beside_allowed_memory(database):
+def test_explicit_raw_filter_accepts_any_connected_source_under_all_apps(database):
    result = resolve(
-        database, access(["om_recall", "om_conversations"], ["all-apps", "source:revoked"])
+        database,
+        access(["om_conversations"], ["all-apps", "source:cursor"]),
+        raw_source_ids=("codex",),
    )
+    assert result.raw_allowed and result.raw_sources == frozenset({"codex"})
+
+
+def test_no_connected_raw_source_can_be_reported_beside_allowed_memory(database):
+    with closing(sqlite3.connect(database)) as db, db:
+        db.execute("UPDATE source_grants SET revoked_at='2026-09-20' WHERE user_id='local'")
+    result = resolve(database, access(["om_recall", "om_conversations"], ["all-apps"]))
    assert result.memory_allowed and not result.raw_allowed


@@ -124,7 +131,7 @@ def test_expired_deadline_does_not_open_database(database, monkeypatch):
    with pytest.raises(TimeoutError):
        resolve_context_authority(
            ContextSearchRequest(query="x"),
-            access(["om_conversations"], ["all-apps", "source:cursor"]),
+            access(["om_conversations"], ["all-apps"]),
            database,
            deadline=time.monotonic() - 1,
        )
@@ -263,6 +263,48 @@ def test_a_switch_over_the_api_pauses_writes_and_keeps_intake(tmp_path, backend)
    asyncio.run(scenario())


+def test_graph_backfill_blocks_starting_an_embedding_switch(tmp_path, backend):
+    backend.store.put(
+        builtin_base(),
+        512,
+        {"m1": ("memory", "local")},
+        model="bge-small-zh-v1.5",
+    )
+
+    async def scenario():
+        app = application(tmp_path)
+        async with app.router.lifespan_context(app), client_for(app) as client:
+            await recovered(client)
+            profile = remote_profile(app)
+            plan = (
+                await client.post(
+                    "/api/v1/embedding-switches/plan",
+                    json={"profile_id": profile.profile_id},
+                )
+            ).json()
+            hold = asyncio.Event()
+            task = asyncio.create_task(hold.wait())
+            app.state.memory_graph_backfill._task = task
+            try:
+                response = await client.post(
+                    "/api/v1/embedding-switches",
+                    json={
+                        "profile_id": profile.profile_id,
+                        "expected_revision": profile.revision,
+                        "plan_token": plan["plan_token"],
+                    },
+                )
+                assert response.status_code == 409
+                assert response.json()["detail"] == "memory_lifecycle_busy"
+                assert app.state.embedding_switch.writes_open() is True
+            finally:
+                task.cancel()
+                await asyncio.gather(task, return_exceptions=True)
+                app.state.memory_graph_backfill._task = None
+
+    asyncio.run(scenario())
+
+
 def test_cancel_over_the_api(tmp_path, backend):
    backend.store.put(builtin_base(), 512, {f"m{i}": (f"m {i}", "local") for i in range(4)})

@@ -53,8 +53,8 @@ def test_external_marker_is_not_an_installation_grant(tmp_path):
                "/api/v2/memories/ask", json={"question": "history"}, headers=headers()
            )
            assert denied_tool.status_code == 403
-            # om_conversations reaches Core only as the v2 raw lane, and only
-            # with a source grant: all-apps alone opens no raw source.
+            # om_conversations reaches Core only as the v2 raw lane. all-apps
+            # has nothing to open because this fresh home has no connected source.
            no_raw = await client.post(
                "/api/v2/context/search",
                json={"query": "history", "kinds": ["raw"]},
@@ -193,7 +193,7 @@ def _qwenwork() -> Harness:

 def _deepseek() -> Harness:
    def write(path: Path, turns: list[Turn]) -> None:
-        # deepseek only accepts a file literally named session.jsonl, and nests
+        # deepseek only accepts files named session[.vN].jsonl[.zstd], and nests
        # the turn under "data".
        lines: list[dict] = [{"type": "session", "version": 0, "id": "s1", "cwd": "/w"}]
        for index, (role, text, _session) in enumerate(turns):
@@ -225,7 +225,7 @@ def _deepseek() -> Harness:

    from one_memory.imports.sources.deepseek_harness import create_deepseek_harness_adapter

-    # deepseek accepts only a file literally named session.jsonl.
+    # deepseek accepts only session[.vN].jsonl[.zstd]; the first format is used here.
    return Harness(
        "deepseek-harness",
        write,
@@ -150,7 +150,18 @@ def test_lifespan_content_backfill_failure_is_visible(tmp_path, monkeypatch) ->

    async def scenario() -> None:
        async with app.router.lifespan_context(app):
-            health = await _get_json(app, "/api/v1/health")
+            # The rebuild is released when post-ready recovery finishes, and
+            # recovery now resumes imports off the loop, so it can still be
+            # running at the first request.
+            for _ in range(500):
+                if app.state.recovery in {"done", "failed"}:
+                    break
+                await asyncio.sleep(0.01)
+            for _ in range(500):
+                health = await _get_json(app, "/api/v1/health")
+                if health["content_candidate_backfill"] != "running":
+                    break
+                await asyncio.sleep(0.01)
            assert health["content_candidate_backfill"] == "failed"
            assert health["content_candidate_backfill_failure"] == "database_locked"