fix(memhub): make the embedding switch work on real graphs and SDK services

Reviewing the switch against the real SDK, Kuzu and EmbedService found what the in-memory backend could not: - Verifying the graph ran beside live clients, and the SDK refuses a graph one holds open, so an ultra switch failed whenever a read landed after the copy. Clients are closed for the verify too. - The graph was only re-embedded in ultra, so a pro home's graph from its ultra days went with the old space. It moves in every mode now. - The re-embed built a full client config, which needs the generation key; an Ollama embedding has none resolved. It uses the retrieval view. - The scan opened Chroma outside the first-open lock, the race that once lost a clean install's first write. It takes the client-construction lock. - A live space whose profile was deleted raised KeyError on every read. It now answers `embedding_space_profile_missing`. Also tests the legacy-collection blocker and the real startup migration on a home mid-switch. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
feat(memhub-cli): embedding switch commands and the App contract
2026-11-01 21:19:01 +08:00 · 2026-11-01 20:49:23 +08:00 · 2026-11-01 20:49:12 +08:00 · 2026-11-01 20:48:55 +08:00 · 2026-11-01 20:34:32 +08:00 · 2026-11-01 19:54:44 +08:00
377 changed files with 46371 additions and 12165 deletions
@@ -40,6 +40,7 @@ MEMORY_EMBEDDING_DIMS=1024
 # MEMORY_EMBEDDER_TIMEOUT=15
 # MEMORY_EMBEDDER_MAX_RETRIES=2
 # MEMORY_EMBEDDER_RETRY_DELAY=0.3
+# MEMORY_EMBEDDER_BATCH_SIZE=64
 # MEMORY_EMBEDDER_EXTRA_HEADERS={}
 # MEMORY_EMBEDDER_EXTRA_BODY={}

@@ -4,15 +4,108 @@ Hy Memory and MemHub are versioned and released independently.

 ## Unreleased

+## Hy Memory 2.0.10 — 2026-11-01
+
+- Published
+  [`hy-memory==2.0.10`](https://pypi.org/project/hy-memory/2.0.10/).
+- New `hy_memory.reembed` module for switching the embedding
+  model. Writers must be paused for the whole run. Nothing is derived from
+  the provider or endpoint: source and target are named explicitly, and the
+  identity of a space is the model name plus the width (`space_identity`).
+  Only Chroma and Kuzu are supported.
+  - `vector_space_names(config, base_name=None)` returns every physical
+    collection a client opens for the six vector roles: memory, entities,
+    coding keys and working facts, each in the working and coding variants.
+  - `reembed_vector_space(source, target, embedding=...)` pages every raw
+    source collection, covering all users and all layers including L1_RAW. It
+    embeds the text the write path embedded (`reembed_text`: the canonical
+    state's `state_retrieval_text`, a schema's `retrieval_text`, otherwise the
+    document). It then writes each record into the target with the same id,
+    document and metadata. Each batch's widths are checked before anything is
+    written. A cancel stops at a batch boundary (`ReembedCancelled`). A rerun
+    skips the ids the target already holds, so it resumes, and a merge never
+    overwrites the target. The source is never written.
+  - `plan_reembed`, `verify_reembed` and `drop_vector_space` complete the
+    vector side. `verify_reembed` checks ids, metadata, per-user counts and
+    the width, and runs a self-recall sample. `drop_vector_space` refuses
+    collections that a live client in this process holds open.
+  - `scan_vector_spaces(persist_directory)` is read-only. It lists every
+    space on disk with its roles, counts, stored width, per-user counts and
+    the models recorded in metadata. `diff_spaces(source, target)` returns the
+    ids that the source holds and the target lacks, whatever their status.
+  - `reembed_graph(source_path, target_path, embedding=..., target_dims=...)`
+    builds a new Kuzu graph at the new width. It copies every node and edge
+    and recomputes `Memory.embedding`, `Memory.beh_embedding`, and the Topic
+    and HierarchyTopic embeddings, then rebuilds the HNSW index. The source
+    graph is opened read-only and kept for rollback. A run that fails or is
+    cancelled leaves no target behind, and a rerun starts over.
+    `verify_graph_reembed` and `drop_graph` complete the graph side.
+- `EmbedService.embed_batch` now splits large batches into
+  requests of `embedder.batch_size` texts each (`MEMORY_EMBEDDER_BATCH_SIZE`,
+  default 64); before, it sent them all in one request. On a 429 it waits for
+  the `Retry-After` time plus jitter, capped at 60 s. It takes a per-call
+  `max_retries`. A returned vector whose width differs from the configured
+  `embedding_dims` now raises `EmbeddingDimensionMismatchError` and is not
+  retried.
+- Raw conversations are stored already trimmed. MemHub now keeps every raw
+  forever and lite mode stores nothing else, so tool output and long pasted
+  logs no longer stay in full. One rule (`hy_memory/utils/raw_trim.py`) is
+  applied to each message when the raw is written:
+  - `user` and `system` turns are kept in full;
+  - `assistant` turns and other speakers (`[John]:`) longer than 500
+    characters, after stripping, are cut to the first 500 plus `...`. This is
+    the limit history injection used before;
+  - `tool` turns keep their head and tail, and the middle becomes
+    `[...N bytes omitted by truncate...]`, with the coding limit
+    `coding.tool_result_max_bytes` (`MEMORY_CODING_TOOL_RESULT_MAX_BYTES`,
+    default 2048).
+
+  The rule is idempotent. It covers chat `L1_RAW` in lite, pro and ultra (lite
+  keeps tool turns, because it has no coding route) and the `memory_history`
+  ADD record. The coding/working `coding_trace` was already trimmed when it
+  was written. Its tool and assistant truncations are now idempotent, so
+  reading the history back no longer rewrites the omitted-count markers. The
+  text embedded for `L1_RAW` is the trimmed text. New raws carry
+  `custom.raw_trimmed=true`.
+- Extractor history ("last k messages") now joins the stored raws directly
+  and does not trim them again. Raws written before this change have no
+  `raw_trimmed` flag, so they are still trimmed with the same rule when they
+  are read. The extractor still receives the current batch in full (tool
+  turns are still removed on the chat route).
+
+## MemHub 1.0.5 — 2026-10-28
+
+Build 36, on `hy-memory==2.0.8`. Linux x64/arm64 Runtime and macOS arm64
+App and Runtime. Upgrading from 1.0.4 migrates the existing library to SDK
+authority on first launch.
+
+- MemHub turns off the HY pipeline log and trace at every diagnostic level
+  (hy-memory 2.0.8 `MEMORY_PIPELINE_LOG_ENABLED=false`,
+  `MEMORY_PIPELINE_TRACE_ENABLED=false`), so the per-step JSONL files under
+  `hy-memory/governed-v2/logs/` and the `pipeline_logs` rows stop growing.
+  The Debug panel no longer shows the HY pipeline section. Existing files are
+  left in place.
+- HY SDK text logs are written once, to `hy_memory.log`. They are no longer
+  copied to `service.log` and `service-error.log` through the SDK's
+  stdout/stderr streams. SDK warnings and errors also go to `core.log`, so the
+  Debug panel still shows them. A live switch of the diagnostic level now also
+  changes the level of `hy_memory.log`.
+
+- MemHub shows when working and coding experiences were talked about. After
+  the SDK upgrade every one of them read "时间未知" (time unknown) because the
+  SDK never stored their conversation time; hy-memory 2.0.7 stores it and
+  Core now passes it through the memory list, detail, search and home
+  summary. An experience stored before 2.0.7 shows its write time, labelled
+  "写入于" / "写入时间", instead of "时间未知". Metadata repair also writes
+  the conversation time it recovers from the migration bundle into the SDK's
+  coding/working stores when they already have the column.
+- The SDK migration no longer fails its first run on a home with legacy
+  vectors: reattaching them left a Chroma instance open with its own settings,
+  and the readback that followed could not open the same store
+  ("An instance of Chroma already exists ... with different settings").
 - MemHub "添加记忆" (add a memory) no longer waits behind unprocessed history.
  Notes are claimed ahead of the event-time window that keeps history strictly
  old to new; they still run one at a time and in order within their session.
- SDK reconcile keeps time order. Both reconcile prompts now state that only
-  `memory_at` decides which memory is newer, that an older memory must never
-  supersede or overwrite a newer one, and that an unknown time is not newer;
-  the Chinese prompt now lists `memory_at` among the new-memory fields. The
-  reconciler also enforces this in code: a SUPERSEDE or UPDATE aimed at a memory
-  with a later `memory_at` becomes an ADD, so the newer memory stays current.
 - The SDK memory page now reads its list, count, source and time labels and
  graph from one page response for one source filter, so rows, totals and the
  map no longer disagree. Memories with no recorded source are shown and
@@ -70,6 +163,121 @@ Hy Memory and MemHub are versioned and released independently.
  `hy_node_permissions` proof table. Evidence, governed memories, model
  profiles, SDK stores, and source/host grants are preserved.

+## Hy Memory 2.0.9 — 2026-11-01
+
+- Published
+  [`hy-memory==2.0.9`](https://pypi.org/project/hy-memory/2.0.9/).
+- Placeholder values no longer overwrite the user's basic profile (L0). A
+  small extraction model filled `basic_info` with `{"name": "用户"}`,
+  `The user` or `N/A` when the user had said nothing about themselves, and
+  each placeholder superseded the real value, so the L0 chain read
+  费天翔 → Fei → 用户 → The user. Two defences:
+  - `upsert_basic_profile` drops placeholder values: empty, `用户`,
+    `the user`, `user`, `n/a`, `na`, `none`, `null`, `unknown`, `未提供`,
+    `未知`, `不详`, `-`, `?` and the field's own name, compared
+    case-insensitively with whitespace and punctuation stripped. When nothing
+    is left it writes no new version and no new L0 head. Placeholders already
+    stored in the chain no longer override earlier real values when the
+    profile is assembled, so `get_user_profile` of an affected user shows the
+    last real value again without any migration. This also stops an
+    assistant quoting an old memory ("The user's name is 用户.") from being
+    written back.
+  - The extraction prompts (zh and en) state the rule: only what the user
+    said in a `user` turn, never the field name or a placeholder, `{}`
+    otherwise, with a small-talk counter-example.
+
+## Hy Memory 2.0.8 — 2026-10-28
+
+- Published
+  [`hy-memory==2.0.8`](https://pypi.org/project/hy-memory/2.0.8/).
+- New `MEMORY_PIPELINE_LOG_ENABLED` (default `true`) turns the pipeline JSONL
+  log (`{MEMORY_LOG_DIR}/<subdir>/<date>.log`) off. With `false` no JSONL
+  file or directory is written. When `MEMORY_PIPELINE_TRACE_ENABLED` is also
+  `false`, `store_pipeline_log` becomes a no-op that returns `True` at once:
+  no timing, redaction, background task or database write. The init log line
+  now states whether the JSONL log is on or off.
+- Conversation and memory text no longer appears in INFO or WARNING logs. The
+  `[add]` input, search queries and rewrites, coding experience tasks, fact
+  statements and subjects, reconcile op details, extracted info, embedding
+  inputs and unparsable model output moved to DEBUG. INFO lines keep ids,
+  counts and character lengths; parse-failure warnings remain but report only
+  the length of the output, e.g. `failed to parse output (812 chars)`. The
+  `[embed]` INFO line now carries `request.input_chars` instead of
+  `request.input`. The `JSON_PARSE_FAILED` error message from extraction no
+  longer embeds the model output either.
+
+## Hy Memory 2.0.7 — 2026-10-28
+
+- Published
+  [`hy-memory==2.0.7`](https://pypi.org/project/hy-memory/2.0.7/).
+- Coding and working experiences and facts now keep their conversation time.
+  `add(..., memory_at=...)` reached only the chat path before; the
+  productivity path dropped it, so every experience had only its write time
+  and MemHub showed them as "时间未知" (time unknown). `coding_memory_meta`
+  and `working_fact` gain a nullable `memory_at` column (epoch seconds) in
+  both the working and coding stores; existing databases get it on open, and
+  their old rows stay `None`. Without `memory_at` a write uses the time the
+  request arrived, as chat does. When an experience is updated by a later
+  conversation it keeps the later of the two times.
+- `list_memories` (`scene="coding"`, `"working"` and `"all"`), `get` and
+  `search` return `memory_at` for experiences and facts in the same field and
+  format as chat (epoch seconds, `None` when unknown). Experience search
+  results now also carry `created_at`.
+
+## Hy Memory 2.0.6 — 2026-10-27
+
+- Published
+  [`hy-memory==2.0.6`](https://pypi.org/project/hy-memory/2.0.6/).
+- `search(..., rerank=False)` skips every reranking stage for that one
+  call (the local cross-encoder, the memory-graph rerank, and the BM25 rerank of
+  working/coding facts), so results come back in retrieval-score order. The
+  flag travels on the read request, so concurrent searches do not affect each
+  other. The default (`True`) keeps current behavior; `/api/v1/search` accepts
+  it too.
+- MMR diversity selection now runs only when the requested `limit` is
+  below 20 (`MMR_MAX_TOP_K`) and is skipped for larger limits, where its
+  quadratic token-overlap pass is slow and gains little. Previously it ran for
+  every limit. `MEMORY_HYBRID_V2_MMR_LAMBDA` still sets the weight.
+  Near-duplicate demotion follows the same gate: it compares each candidate
+  with every earlier non-duplicate, which is quadratic in a pool that grows
+  with `limit`, and large result pages should show similar items anyway.
+- `search(scene="all")` searches chat, working and coding at the same time
+  and merges them with Reciprocal Rank Fusion (k=60) over each scene's own
+  ranking, so no scene is crowded out by the other scenes' score scales. Each
+  result says which scene and kind it came from. A scene that fails or is turned
+  off is reported in `errors` and does not fail the search. Source filters apply
+  to all three.
+- `list_memories(scene="all")` lists chat, working and coding memories
+  together, newest update first, with `limit`/`offset` paging over the merged
+  order and `total` summing all three. `scene="coding"` and `"working"` now
+  honor `include_sources` / `exclude_sources`, and `total` counts only the
+  filtered memories.
+- `update()` and `delete()` now work on working/coding experiences and
+  facts, not just chat memories. They take the same optional `kind` / `variant`
+  as `get()`, and an ID found in more than one place raises
+  `AmbiguousMemoryIdError` instead of guessing. Updating an experience replaces
+  its solution and keeps its task, unless a new `task=` is also passed; updating
+  a fact replaces its statement. Deleting removes the stored row and its vectors.
+- `list_memories(scene="chat" | "coding" | "working")` lists one kind of
+  memory. `coding` and `working` list that scene's whole store, newest update
+  first (`workspace_id` still narrows it), and `total` is now the real count
+  rather than the page size. The new `memory_stats()` returns the count and the
+  latest created/updated time for each scene and their total, without reading
+  any memory text. Previously coding and working memories could not be listed
+  or counted without a workspace, so a library of 45 memories listed 22.
+- Reconcile keeps time order. Both reconcile prompts now state that only
+  `memory_at` decides which memory is newer, that an older memory must never
+  supersede or overwrite a newer one, and that an unknown time is not newer;
+  the Chinese prompt now lists `memory_at` among the new-memory fields. The
+  reconciler also enforces this in code: a SUPERSEDE or UPDATE aimed at a memory
+  with a later `memory_at` becomes an ADD, so the newer memory stays current.
+- The HTTP server returns 409 `ambiguous_memory_id` and 400 for a bad
+  `kind`/`variant` instead of 500, passes `kind`/`variant` (and `task` on PUT)
+  to get/update/delete, and no longer reads a PUT/DELETE query string as part
+  of the memory id.
+- `memory_stats()` reads working/coding times, which are stored as naive UTC,
+  as UTC rather than local time.
+
 ## Hy Memory 2.0.5 — 2026-10-22

 - Published
@@ -33,6 +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-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)**!
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **Open-sourced** **[Hy-Memory-30B-A3B](https://huggingface.co/tencent/Hy-Memory-30B-A3B)** on Hugging Face along with its [technical report](https://arxiv.org/abs/2610.22196) on attributed reinforcement learning for long-term memory writing!
@@ -33,6 +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-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)**！
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **模型开源** 在 Hugging Face 发布 **[Hy-Memory-30B-A3B](https://huggingface.co/tencent/Hy-Memory-30B-A3B)** 长期记忆写入模型及[技术报告](https://arxiv.org/abs/2610.22196)！
@@ -48,6 +48,7 @@
 | `MEMORY_EMBEDDER_TIMEOUT` | `15` | 单次超时，秒 |
 | `MEMORY_EMBEDDER_MAX_RETRIES` | `2` | 最大重试次数 |
 | `MEMORY_EMBEDDER_RETRY_DELAY` | `0.3` | 重试间隔，秒 |
+| `MEMORY_EMBEDDER_BATCH_SIZE` | `64` | `embed_batch` 单次请求最多发送的文本条数，超出按此切块 |
 | `MEMORY_EMBEDDER_EXTRA_HEADERS` | — | JSON object，附加 HTTP headers |
 | `MEMORY_EMBEDDER_EXTRA_BODY` | — | JSON object，附加请求 body |

@@ -191,6 +192,7 @@ SDK 不设置 Rerank Search 并发上限。开启后模型在 `HyMemoryClient`
 | `MEMORY_LOG_FORMAT` | `text` | `text` / `json` |
 | `MEMORY_LOG_DIR` | — | 统一日志根目录 |
 | `MEMORY_TRACE_LOG_DIR` | — | JSONL 日志目录的兼容旧名；优先使用 `MEMORY_LOG_DIR` |
+| `MEMORY_PIPELINE_LOG_ENABLED` | `true` | 是否写 pipeline JSONL 日志（`{MEMORY_LOG_DIR}/<subdir>/<date>.log`）；`false` 完全不写 |
 | `MEMORY_PIPELINE_TRACE_ENABLED` | `true` | 是否写入 cache 的 pipeline trace 表 |
 | `MEMORY_MEMORY_OPERATIONS_ENABLED` | `false` | 是否写入 memory operation 审计记录 |
 | `MEMORY_HISTORY_ENABLE` | `true` | 是否启用历史记录 |
@@ -55,6 +55,33 @@ except Exception:
 from .client import HyMemoryClient
 from .inspector import MemoryInspector
 from .runtime import SharedRuntime
+from .reembed import (
+    EmbeddingSpaceIdentity,
+    GraphReembedPlan,
+    GraphReembedProgress,
+    GraphReembedReport,
+    GraphVerification,
+    ReembedCancelled,
+    ReembedPlan,
+    ReembedProgress,
+    ReembedReport,
+    ReembedVerification,
+    ScannedSpace,
+    SpaceDiff,
+    VectorSpace,
+    diff_spaces,
+    drop_graph,
+    drop_vector_space,
+    plan_reembed,
+    reembed_graph,
+    reembed_text,
+    reembed_vector_space,
+    scan_vector_spaces,
+    space_identity,
+    vector_space_names,
+    verify_graph_reembed,
+    verify_reembed,
+)
 from .snapshot import (
    DataPlaneRestore,
    DataPlaneSnapshot,
@@ -129,6 +156,32 @@ __all__ = [
    "DataPlaneSnapshotRejected",
    "restore_local_data_plane",
    "snapshot_local_data_plane",
+    # 换 embedding 模型：把向量库和图重新 embed 进新的 embedding 空间
+    "EmbeddingSpaceIdentity",
+    "GraphReembedPlan",
+    "GraphReembedProgress",
+    "GraphReembedReport",
+    "GraphVerification",
+    "ReembedCancelled",
+    "ReembedPlan",
+    "ReembedProgress",
+    "ReembedReport",
+    "ReembedVerification",
+    "ScannedSpace",
+    "SpaceDiff",
+    "VectorSpace",
+    "diff_spaces",
+    "drop_graph",
+    "drop_vector_space",
+    "plan_reembed",
+    "reembed_graph",
+    "reembed_text",
+    "reembed_vector_space",
+    "scan_vector_spaces",
+    "space_identity",
+    "vector_space_names",
+    "verify_graph_reembed",
+    "verify_reembed",
    # 配置
    "MemoryConfig",
    # 公共扩展协议 / 精确读取类型
@@ -682,6 +682,23 @@ Output:
 ```
 John's occupation and location are HIS attributes, so they go into `memory` with "John" as the subject. They must NEVER land in `basic_info.occupation` / `basic_info.location` — `basic_info` is exclusively the user's own profile. Only `name` (Tim, from the user message's `name` field) belongs there.

+## Example 11 — Counter-example: small talk has no basic_info
+
+New Messages:
+[{"role": "user", "content": "Hi"},
+ {"role": "assistant", "content": "Hello! The user's name is The user. How can I help?"}]
+Memory Date: 2025-09-03
+
+Output:
+```json
+{
+  "memory": [],
+  "intentions": [],
+  "basic_info": {}
+}
+```
+The user stated nothing about themselves. The assistant's line is not a user turn, and "The user" is a placeholder, not a name. Output `{}` — never `{"name": "The user"}` or `{"name": "user"}`.
+
 ---
 """

@@ -749,6 +766,14 @@ Rules:
  fields (e.g. name, age, location, occupation, employer) **explicitly stated**
  in the NEW user messages. Never infer, never invent. If no field is explicitly
  stated, output `{{}}`.
+  * HARD RULE: fill a field ONLY if the user stated it in a `user` turn.
+    Anything said only by the assistant (including the assistant quoting an
+    earlier memory such as "The user's name is X") does NOT count. If nothing
+    qualifies, output `"basic_info": {{}}`.
+  * NEVER write the field name itself or a placeholder as a value ("user",
+    "The user", "用户", "name", "N/A", "unknown", "none", "-"). Omit the field.
+  * Negative example: small talk such as `[user]: Hi` / `[assistant]: How can
+    I help?`, or `[user]: Reply with exactly: PONG` → `"basic_info": {{}}`.
  * Exception for `name`: the `name` field on the user's own message, or a leading
    line "The user's name is X" / "用户名叫X", is an authoritative source for
    `name` — even though the user never said it out loud.
@@ -817,6 +842,14 @@ Rules:
  fields (e.g. name, age, location, occupation, employer) **explicitly stated**
  in the NEW user messages. Never infer, never invent. If no field is explicitly
  stated, output `{{}}`.
+  * HARD RULE: fill a field ONLY if the user stated it in a `user` turn.
+    Anything said only by the assistant (including the assistant quoting an
+    earlier memory such as "The user's name is X") does NOT count. If nothing
+    qualifies, output `"basic_info": {{}}`.
+  * NEVER write the field name itself or a placeholder as a value ("user",
+    "The user", "用户", "name", "N/A", "unknown", "none", "-"). Omit the field.
+  * Negative example: small talk such as `[user]: Hi` / `[assistant]: How can
+    I help?`, or `[user]: Reply with exactly: PONG` → `"basic_info": {{}}`.
  * Exception for `name`: the `name` field on the user's own message, or a leading
    line "The user's name is X" / "用户名叫X", is an authoritative source for
    `name` — even though the user never said it out loud.
@@ -1177,7 +1210,7 @@ class Extractor:
                        if not tc_id:
                            logger.error(
                                f"[extractor] tool_call_id is empty! "
-                                f"raw tc: {json.dumps(tc_raw, ensure_ascii=False, default=str)[:500]}"
+                                f"raw_keys={list(tc_raw.keys())}"
                            )
                        try:
                            t_res = await tool_registry.dispatch(
@@ -1311,11 +1344,12 @@ class Extractor:
                if parsed is None:
                    if not all_tool_calls:
                        logger.warning(
-                            f"[extractor] JSON parse failed: {raw_text[:200]}"
+                            f"[extractor] JSON parse failed ({len(raw_text)} chars)"
                        )
+                        logger.debug(f"[extractor] unparsable output: {raw_text[:200]!r}")
                        return ExtractResult(
                            success=False,
-                            error=f"JSON parse failed: {raw_text[:200]}",
+                            error=f"JSON parse failed ({len(raw_text)} chars)",
                            error_code="JSON_PARSE_FAILED",
                            raw_response=raw_text,
                            tokens_used=total_tokens,
@@ -129,8 +129,7 @@ def _parse_tool_calls_list(raw_calls: list, _json) -> List[Dict[str, Any]]:
        tc_id = tc.get("id") or ""
        if not tc_id:
            logger.error(
-                f"[llm] tool_call missing 'id'! raw: "
-                f"{_json.dumps(tc, ensure_ascii=False, default=str)[:500]}"
+                f"[llm] tool_call missing 'id'! keys={list(tc.keys())}"
            )

        # 保留原始 tc 完整结构，只规范化 arguments
@@ -234,7 +234,7 @@ class MemAgent:
                    f"identity={len(identity)} facts={len(facts)} "
                    f"basic_info={basic_field_count}fields"
                )
-                logger.info(f"MemAgent: extracted_info={extract_result.info}")
+                logger.debug(f"MemAgent: extracted_info={extract_result.info}")

            # 3. 冲突检测（如果有已有记忆）
            if mode == ProcessMode.FULL and existing_memories:
@@ -365,6 +365,13 @@ EXTRACT_PROMPT_ZH = """## 最近 k 条消息
 * basic_info：**只装用户本人的画像**。
  仅当 NEW user messages 中**明确**陈述稳定画像字段（如 姓名、年龄、所在地、职业、雇主）时才填写。
  绝不推断、绝不编造。没有任何字段被明确陈述时输出 `{{}}`。
+  * **硬性规则**：只有用户在 `user` 回合里**明确说出**的字段才能填写。只在
+    assistant 回合出现的内容（包括 assistant 引用旧记忆，如"The user's name is X"
+    / "用户名是X"）一律不算。没有符合条件的字段时，必须输出 `"basic_info": {{}}`。
+  * **绝不**把字段名本身或占位符当值写入（"用户"、"The user"、"user"、"name"、
+    "姓名"、"N/A"、"unknown"、"未知"、"未提供"、"-"），宁可省略该字段。
+  * 负例：寒暄如 `[user]: 你好` / `[assistant]: 我可以帮你。`，或
+    `[user]: Reply with exactly: PONG` → `"basic_info": {{}}`。
  * `name` 的例外：用户自己那条消息上的 `name` 字段，或文首形如
    "用户名叫X" / "The user's name is X" 的那一行，都是 `name` 的权威来源
    ——即使用户本人从未开口自报姓名。
@@ -440,6 +447,13 @@ EXTRACT_PROMPT_ZH_NO_INTENTION = """## 最近 k 条消息
 * basic_info：**只装用户本人的画像**。
  仅当 NEW user messages 中**明确**陈述稳定画像字段（如 姓名、年龄、所在地、职业、雇主）时才填写。
  绝不推断、绝不编造。没有任何字段被明确陈述时输出 `{{}}`。
+  * **硬性规则**：只有用户在 `user` 回合里**明确说出**的字段才能填写。只在
+    assistant 回合出现的内容（包括 assistant 引用旧记忆，如"The user's name is X"
+    / "用户名是X"）一律不算。没有符合条件的字段时，必须输出 `"basic_info": {{}}`。
+  * **绝不**把字段名本身或占位符当值写入（"用户"、"The user"、"user"、"name"、
+    "姓名"、"N/A"、"unknown"、"未知"、"未提供"、"-"），宁可省略该字段。
+  * 负例：寒暄如 `[user]: 你好` / `[assistant]: 我可以帮你。`，或
+    `[user]: Reply with exactly: PONG` → `"basic_info": {{}}`。
  * `name` 的例外：用户自己那条消息上的 `name` 字段，或文首形如
    "用户名叫X" / "The user's name is X" 的那一行，都是 `name` 的权威来源
    ——即使用户本人从未开口自报姓名。
@@ -669,6 +683,23 @@ Memory Date：2025-09-02
 ```
 职业和所在地是 **John 的**属性，所以进 `memory` 并以"John"作主体，**绝不能**落到 `basic_info` 的 `occupation` / `location` —— `basic_info` 专属于用户本人。只有 `name`（Tim，来自用户消息的 `name` 字段）才该放进去。注意输出语言随输入语言（此例为英文）。

+## 示例 11 —— 反例：寒暄没有 basic_info
+
+新消息：
+[{"role": "user", "content": "你好"},
+ {"role": "assistant", "content": "你好！我可以帮你。之前记得 The user's name is 用户."}]
+Memory Date：2025-09-03
+
+输出：
+```json
+{
+  "memory": [],
+  "intentions": [],
+  "basic_info": {}
+}
+```
+用户没有说任何关于自己的信息。assistant 那句不是 user 回合，"用户" 也是占位符而不是名字。必须输出 `{}`——**绝不能**输出 `{"name": "用户"}`。
+
 ---
 """

@@ -50,7 +50,7 @@ def is_canonical_state_node(node: Any) -> bool:


 def _log_ops_detail(ops: List["ReconcileOp"]) -> None:
-    """以单条 INFO（JSON list）输出 reconcile 的逐条结果，便于线上 debug。"""
+    """以单条 DEBUG（JSON list）输出 reconcile 的逐条结果；含记忆正文，不进 INFO。"""
    if not ops:
        return
    view = [
@@ -68,7 +68,7 @@ def _log_ops_detail(ops: List["ReconcileOp"]) -> None:
        }
        for o in ops
    ]
-    logger.info(
+    logger.debug(
        f"[reconciler] ops detail: {json.dumps(view, ensure_ascii=False, default=str)}"
    )

@@ -1514,9 +1514,10 @@ class MemoryReconciler:
                logger.warning(
                    f"[reconciler] RECONCILE JSON parse failed "
                    f"(attempt {_attempt+1}/{_MAX_PARSE_ATTEMPTS}), "
-                    f"retrying: raw="
-                    f"{raw_response[:200] if _log_llm_content_enabled() else '<redacted>'}"
+                    f"retrying: raw({len(raw_response or '')} chars)"
                )
+                if _log_llm_content_enabled():
+                    logger.debug(f"[reconciler] unparsable raw={raw_response[:200]!r}")

            recon_elapsed = (_time.perf_counter() - t_recon) * 1000

@@ -1528,8 +1529,8 @@ class MemoryReconciler:
                    error_code = "LLM_UNAVAILABLE"
                elif raw_response.strip():
                    error_msg = (
-                        f"RECONCILE JSON parse failed after {_n_attempts} attempts: "
-                        f"{raw_response[:200] if _log_llm_content_enabled() else '<redacted>'}"
+                        f"RECONCILE JSON parse failed after {_n_attempts} attempts "
+                        f"({len(raw_response)} chars)"
                    )
                    error_code = "JSON_PARSE_FAILED"
                else:
@@ -1806,7 +1807,8 @@ class MemoryReconciler:
                except Exception as _re:
                    logger.debug(f"[reconciler] json_repair failed: {_re}")
            if data is None:
-                logger.warning(f"[reconciler] failed to parse ops JSON: {text[:200]}")
+                logger.warning(f"[reconciler] failed to parse ops JSON ({len(text)} chars)")
+                logger.debug(f"[reconciler] unparsable ops output: {text[:200]!r}")
                return []

        if not isinstance(data, list):
@@ -2018,11 +2020,11 @@ class MemoryReconciler:
                if clash is not None:
                    logger.warning(
                        f"[reconciler] memory_id {clash} already touched by '{touched[clash]}', "
-                        f"current op '{op.op} ({op.reason[:60]})' dropped"
+                        f"current op '{op.op}' dropped"
                    )
                    continue
                for t in target_ids:
-                    touched[t] = f"{op.op}({op.reason[:40]})"
+                    touched[t] = op.op
            validated.append(op)

        return validated
@@ -211,7 +211,9 @@ def parse_tool_calls_from_json(raw: Any) -> List[ToolCall]:
                try:
                    args = json.loads(args_raw) if args_raw.strip() else {}
                except json.JSONDecodeError:
-                    logger.warning(f"[tools] failed to parse arguments as JSON: {args_raw[:120]}")
+                    logger.warning(
+                        f"[tools] failed to parse arguments as JSON ({len(args_raw)} chars)"
+                    )
                    args = {}
            elif isinstance(args_raw, dict):
                args = args_raw
@@ -26,6 +26,8 @@ from __future__ import annotations

 import asyncio
 import logging
+import re
+import unicodedata
 import uuid
 import weakref
 from dataclasses import dataclass
@@ -208,6 +210,76 @@ def _sanitize_kv(
    return result


+# ================================================================
+# 占位符守卫（P0-1）
+# ================================================================
+# 弱模型（如 qwen3.5-2b）在用户什么都没说时，会把 schema 字段说明里的词当值
+# 填进 basic_info：{"name": "用户"} / "The user" / "N/A"。每个占位符都会
+# supersede 掉真实值，演化链变成 费天翔 → Fei → 用户 → The user。
+# 规则：占位符永远不入库；读侧组装 KV 时占位符也不覆盖已有真实值。
+
+_PLACEHOLDER_VALUES = frozenset({
+    "用户", "该用户", "本用户", "用户本人",
+    "the user", "the user's", "user", "a user", "this user",
+    "n/a", "na", "none", "null", "nil", "unknown", "unspecified",
+    "not provided", "not specified", "not mentioned",
+    "未提供", "未知", "不详", "未说明", "未提及", "无",
+    "-", "?",
+})
+
+# 内置字段的中文标签：弱模型也会把字段说明的中文词当值。
+_FIELD_LABELS: Dict[str, tuple] = {
+    "name": ("姓名", "名字", "用户名", "用户姓名", "用户名字"),
+    "age": ("年龄", "用户年龄"),
+    "location": ("所在地", "地点", "城市", "用户所在地"),
+    "occupation": ("职业", "工作", "用户职业"),
+    "employer": ("雇主", "公司", "用户雇主"),
+}
+
+# 去掉标点/符号后再比较，让 "The user." / "用户。" / "N/A" 都命中。
+# "-" / "?" 本身就是纯标点，剥完为空串，同样判为占位符。
+_PUNCT_RE = re.compile(r"[\s\.,;:!?'\"`~()\[\]{}<>/\\|_\-\u3000-\u303f\uff00-\uff0f\uff1a-\uff20]+")
+
+
+def _placeholder_key(value: str) -> str:
+    s = unicodedata.normalize("NFKC", str(value or "")).strip().lower()
+    s = s.replace("\u2019", "'")
+    s = _PUNCT_RE.sub(" ", s)
+    return " ".join(s.split())
+
+
+_PLACEHOLDER_KEYS = frozenset(_placeholder_key(v) for v in _PLACEHOLDER_VALUES)
+
+
+def is_placeholder_value(field_name: str, value: Any) -> bool:
+    """value 是否为占位符（空 / 用户 / The user / N/A / 字段名本身 等）。
+
+    大小写不敏感、首尾空白与标点不敏感。数字（如 age=30）永远不是占位符。
+    """
+    if value is None:
+        return True
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, (int, float)):
+        return False
+    key = _placeholder_key(value)
+    if not key:
+        return True
+    if key in _PLACEHOLDER_KEYS:
+        return True
+    field_key = _placeholder_key(field_name)
+    if field_key and key in (field_key, field_key.replace("_", " ")):
+        return True
+    for label in _FIELD_LABELS.get(field_name, ()):
+        if key == _placeholder_key(label):
+            return True
+    return False
+
+
+def _drop_placeholders(kv: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in kv.items() if not is_placeholder_value(k, v)}
+
+
 # ================================================================
 # 公共入口：upsert_basic_profile
 # ================================================================
@@ -287,6 +359,8 @@ async def _upsert_basic_profile_unlocked(
    # L0 Basic Info 从输入、唯一性到落盘都只属于 user_id。

    new_kv = _sanitize_kv(kv or {}, allowed_fields=allowed_fields)
+    # 单调性守卫：占位符永远不覆盖已有值，过滤后为空就不写新版本、不产生新链头。
+    new_kv = _drop_placeholders(new_kv)
    if not new_kv:
        return BasicProfileUpsertResult(
            success=True, changed=False, reason="no valid fields after sanitize"
@@ -513,5 +587,8 @@ def _assemble_full_kv_from_nodes(
        for k, v in kv.items():
            if allowed_set is not None and k not in allowed_set:
                continue
+            # 历史上已落盘的占位符版本（如 name=用户）不覆盖更早的真实值。
+            if is_placeholder_value(k, v):
+                continue
            full_kv[k] = v
    return full_kv
@@ -1166,7 +1166,10 @@ class CodingMemoryExtractor:
                    obj = None

        if not isinstance(obj, dict):
-            logger.warning(f"[coding-extract] failed to parse output: {text!r}")
+            logger.warning(
+                f"[coding-extract] failed to parse output ({len(text or '')} chars)"
+            )
+            logger.debug(f"[coding-extract] unparsable output: {text!r}")
            return [], []

        # "memories" 是双层化之前的 key，老 prompt 缓存 / 旧模型可能还这么回
@@ -454,9 +454,10 @@ class WorkingFactReconciler:
        workspace_id: Optional[str] = None,
        branch: Optional[str] = None,
        source: str = "default",
+        memory_at: Optional[datetime] = None,
    ) -> Tuple[List[WorkingFact], List[FactReconcileOp]]:
        """
-        执行 reconcile + 持久化。
+        执行 reconcile + 持久化。memory_at 是这段对话的时间，记到新事实上。

        Returns:
            (真正落库的新事实, 执行过的 ops)。LLM 挂掉时退化为全 INSERT 不覆盖，
@@ -493,6 +494,7 @@ class WorkingFactReconciler:
            workspace_id=workspace_id,
            branch=branch,
            source=source,
+            memory_at=memory_at,
        )
        logger.info(
            f"[fact-reconcile] drafts={len(drafts)} inserted={len(facts)} "
@@ -568,9 +570,12 @@ class WorkingFactReconciler:
                    kept.append(fact)
            if blocked:
                logger.info(
-                    f"[fact-reconcile] subject gate blocked {len(blocked)} candidate(s) "
-                    f"for subject={draft.subject!r}: "
-                    + ", ".join(f"{f.fact_id}({f.subject!r})" for f in blocked)
+                    f"[fact-reconcile] subject gate blocked {len(blocked)} candidate(s): "
+                    + ", ".join(f.fact_id for f in blocked)
+                )
+                logger.debug(
+                    f"[fact-reconcile] subject gate: draft subject={draft.subject!r} "
+                    f"blocked subjects={[f.subject for f in blocked]!r}"
                )
            result.append(kept)
        return result
@@ -743,7 +748,10 @@ class WorkingFactReconciler:
                    obj = None

        if not isinstance(obj, dict):
-            logger.warning(f"[fact-reconcile] failed to parse ops output: {text!r}")
+            logger.warning(
+                f"[fact-reconcile] failed to parse ops output ({len(text or '')} chars)"
+            )
+            logger.debug(f"[fact-reconcile] unparsable ops output: {text!r}")
            return {}
        ops_raw = obj.get("ops")
        if not isinstance(ops_raw, list):
@@ -781,6 +789,7 @@ class WorkingFactReconciler:
        workspace_id: Optional[str],
        branch: Optional[str] = None,
        source: str = "default",
+        memory_at: Optional[datetime] = None,
    ) -> Tuple[List[WorkingFact], List[FactReconcileOp]]:
        inserted: List[WorkingFact] = []
        ops: List[FactReconcileOp] = []
@@ -801,6 +810,7 @@ class WorkingFactReconciler:
                subject=draft.subject,
                details=draft.details,
                status="active",
+                memory_at=memory_at,
            )

            allowed = {c.fact_id for c in (candidates[idx] if idx < len(candidates) else [])}
@@ -831,8 +841,11 @@ class WorkingFactReconciler:
                # 别的主体的状态不是。闸门关掉时这道复查一并跳过，否则闸门就没关干净。
                if self.subject_gate and _subject_conflict(draft.subject, old.subject):
                    logger.warning(
-                        f"[fact-reconcile] refused cross-subject SUPERSEDE: "
-                        f"{old.fact_id}({old.subject!r}) by draft subject {draft.subject!r}"
+                        f"[fact-reconcile] refused cross-subject SUPERSEDE: {old.fact_id}"
+                    )
+                    logger.debug(
+                        f"[fact-reconcile] cross-subject: old subject={old.subject!r} "
+                        f"draft subject={draft.subject!r}"
                    )
                    continue
                try:
@@ -195,8 +195,10 @@ async def classify_messages_scene(
        result = _parse_scene_json(resp.content)
        if result is None:
            logger.warning(
-                f"[coding-judge] failed to parse classify_messages output: {resp.content!r}; defaulting to chat"
+                f"[coding-judge] failed to parse classify_messages output "
+                f"({len(resp.content or '')} chars); defaulting to chat"
            )
+            logger.debug(f"[coding-judge] unparsable classify_messages output: {resp.content!r}")
            await _store_coding_log(
                cache, request_id=request_id, user_id=user_id, agent_id=agent_id,
                session_id=session_id, step="CODING_JUDGE", prompt=prompt,
@@ -207,9 +209,8 @@ async def classify_messages_scene(
            return "chat"
        scene = result["scene"]
        parsed = {**result, "is_coding": scene != "chat"}
-        logger.info(
-            f"[coding-judge] scene={scene} reason={result.get('reason', '')!r}"
-        )
+        logger.info(f"[coding-judge] scene={scene}")
+        logger.debug(f"[coding-judge] scene={scene} reason={result.get('reason', '')!r}")
        await _store_coding_log(
            cache, request_id=request_id, user_id=user_id, agent_id=agent_id,
            session_id=session_id, step="CODING_JUDGE", prompt=prompt,
@@ -295,8 +296,10 @@ async def classify_queries_scene(
        result = _parse_scene_json(resp.content)
        if result is None:
            logger.warning(
-                f"[coding-judge] failed to parse classify_queries output: {resp.content!r}; defaulting to chat"
+                f"[coding-judge] failed to parse classify_queries output "
+                f"({len(resp.content or '')} chars); defaulting to chat"
            )
+            logger.debug(f"[coding-judge] unparsable classify_queries output: {resp.content!r}")
            return "chat"
        scene = result["scene"]
        logger.info(f"[coding-judge] queries scene={scene}")
@@ -422,15 +425,18 @@ async def classify_and_rewrite_queries(
    scene = _parse_scene_label(head)
    if scene is None:
        logger.warning(
-            f"[coding-judge] classify_and_rewrite unrecognized head={head!r}; falling back to chat"
+            f"[coding-judge] classify_and_rewrite unrecognized head "
+            f"({len(head)} chars); falling back to chat"
        )
+        logger.debug(f"[coding-judge] classify_and_rewrite unrecognized head={head!r}")
        return {"scene": "chat", "is_coding": False, "rewrite_query": rewrite, "ok": False}
    is_coding = scene != "chat"

    logger.info(
        f"[coding-judge] classify_and_rewrite scene={scene} "
-        f"rewrite={rewrite!r}"
+        f"rewrite({len(rewrite)} chars)"
    )
+    logger.debug(f"[coding-judge] classify_and_rewrite rewrite={rewrite!r}")
    return {"scene": scene, "is_coding": is_coding, "rewrite_query": rewrite, "ok": True}


@@ -569,8 +575,9 @@ async def analyze_queries(
        parsed_scene = _parse_scene_label(head)
        if parsed_scene is None:
            logger.warning(
-                f"[coding-judge] analyze_queries unrecognized head={head!r}; ok=False"
+                f"[coding-judge] analyze_queries unrecognized head ({len(head)} chars); ok=False"
            )
+            logger.debug(f"[coding-judge] analyze_queries unrecognized head={head!r}")
            return {**fallback, "since_raw": ""}
        scene = parsed_scene
        idx = 1
@@ -589,9 +596,10 @@ async def analyze_queries(
    created_after = _since_to_created_after(since_raw, current_time)

    logger.info(
-        f"[coding-judge] analyze scene={scene} rewrite={rewrite!r} "
+        f"[coding-judge] analyze scene={scene} rewrite({len(rewrite)} chars) "
        f"since={since_raw!r} created_after={created_after}"
    )
+    logger.debug(f"[coding-judge] analyze rewrite={rewrite!r}")
    return {
        "scene": scene, "is_coding": scene != "chat", "rewrite_query": rewrite,
        "created_after": created_after, "since_raw": since_raw, "ok": True,
@@ -614,7 +622,10 @@ def _since_to_created_after(since_raw: str, current_time: str) -> Optional[float
            return dt.timestamp()
        except (ValueError, TypeError):
            continue
-    logger.warning(f"[coding-judge] analyze_queries unparsable SINCE={since_raw!r}")
+    logger.warning(
+        f"[coding-judge] analyze_queries unparsable SINCE ({len(since_raw)} chars)"
+    )
+    logger.debug(f"[coding-judge] analyze_queries unparsable SINCE={since_raw!r}")
    return None


@@ -11,6 +11,7 @@ Coding Memory 预处理工具（规则，零 LLM）
 使用方式与 scene 路由见 docs/scene_coding_usage.md。
 """

+import re
 from typing import Any, Dict, List, Optional, Tuple

 from ..pipelines.base import ChatMessage
@@ -63,6 +64,13 @@ DEFAULT_MAX_TOOL_RESULT_BYTES = 2048
 DEFAULT_HEAD_BYTES = 1024
 DEFAULT_TAIL_BYTES = 512

+# 本模块自己产出的省略标记。截断结果会再次经过截断（落库前一次、读历史时又一次），
+# 认出自己的标记才能保证幂等：已截断的文本再截一次原样返回，而不是把省略计数改写。
+_TOOL_OMIT_MARKER_RE = re.compile(r"\n\n\[\.\.\.\d+ bytes omitted by truncate\.\.\.\]\n\n")
+# 标记本身的字节数上限（数字位数有限），用于判断「已截断且只超出一个标记的长度」。
+_TOOL_OMIT_MARKER_MAX_BYTES = 128
+_ASSISTANT_OMIT_MARKER_RE = re.compile(r" \[\.\.\.\d+ chars omitted\.\.\.\] ")
+

 def truncate_tool_result_text(
    text: str,
@@ -81,6 +89,12 @@ def truncate_tool_result_text(
    raw = text.encode("utf-8")
    if len(raw) <= max_bytes:
        return text
+    # 已截断过（max_bytes 很小时标记本身会让结果略超上限）：原样返回，保证幂等。
+    if (
+        len(raw) <= max_bytes + _TOOL_OMIT_MARKER_MAX_BYTES
+        and _TOOL_OMIT_MARKER_RE.search(text)
+    ):
+        return text
    # 自定义 max_bytes 可能小于默认 head+tail（1024+512）。按原比例缩放内容窗口，
    # 给省略标记预留空间，不能因为窗口和过大而把超限原文直接返回。
    marker_budget = min(96, max(24, max_bytes // 4))
@@ -161,6 +175,10 @@ def truncate_assistant_text(
        text = "" if text is None else str(text)
    if len(text) <= head_chars + tail_chars:
        return text
+    # 已截断过：中段恰好是本函数的省略标记 → 原样返回，保证幂等（否则会把
+    # 省略计数改写成标记自身的长度）。
+    if _ASSISTANT_OMIT_MARKER_RE.fullmatch(text[head_chars:len(text) - tail_chars]):
+        return text
    omitted = len(text) - head_chars - tail_chars
    return (
        text[:head_chars]
@@ -388,7 +388,10 @@ class CodingMemoryReconciler:
                    obj = None

        if not obj or not isinstance(obj, dict):
-            logger.warning(f"[coding-reconcile] failed to parse ops output: {text!r}")
+            logger.warning(
+                f"[coding-reconcile] failed to parse ops output ({len(text or '')} chars)"
+            )
+            logger.debug(f"[coding-reconcile] unparsable ops output: {text!r}")
            return []
        ops_raw = obj.get("ops") or []
        if not isinstance(ops_raw, list):
@@ -441,10 +444,10 @@ class CodingMemoryReconciler:
        for op in ops:
            if op.action == "ADD":
                if op.draft_idx is None or not (0 <= op.draft_idx < len(drafts)):
-                    logger.warning(f"[coding-reconcile] drop invalid ADD: {op.to_dict()}")
+                    logger.warning(f"[coding-reconcile] drop invalid ADD: {_op_ref(op)}")
                    continue
                if op.draft_idx in consumed:
-                    logger.warning(f"[coding-reconcile] drop ADD on consumed draft: {op.to_dict()}")
+                    logger.warning(f"[coding-reconcile] drop ADD on consumed draft: {_op_ref(op)}")
                    continue
                d = drafts[op.draft_idx]
                memory = self._draft_to_new_memory(d)
@@ -458,18 +461,18 @@ class CodingMemoryReconciler:

            elif op.action == "UPDATE":
                if op.draft_idx is None or not (0 <= op.draft_idx < len(drafts)):
-                    logger.warning(f"[coding-reconcile] drop invalid UPDATE: {op.to_dict()}")
+                    logger.warning(f"[coding-reconcile] drop invalid UPDATE: {_op_ref(op)}")
                    continue
                if not op.target_experience_id:
-                    logger.warning(f"[coding-reconcile] drop UPDATE missing target: {op.to_dict()}")
+                    logger.warning(f"[coding-reconcile] drop UPDATE missing target: {_op_ref(op)}")
                    continue
                if not self._target_was_offered(op, candidates_per_draft):
                    logger.warning(
-                        f"[coding-reconcile] drop UPDATE outside authority scope: {op.to_dict()}"
+                        f"[coding-reconcile] drop UPDATE outside authority scope: {_op_ref(op)}"
                    )
                    continue
                if op.draft_idx in consumed:
-                    logger.warning(f"[coding-reconcile] drop UPDATE on consumed draft: {op.to_dict()}")
+                    logger.warning(f"[coding-reconcile] drop UPDATE on consumed draft: {_op_ref(op)}")
                    continue
                d = drafts[op.draft_idx]
                memory = self._draft_to_new_memory(d, experience_id=op.target_experience_id)
@@ -488,17 +491,17 @@ class CodingMemoryReconciler:

            elif op.action == "DELETE":
                if not op.target_experience_id:
-                    logger.warning(f"[coding-reconcile] drop DELETE missing target: {op.to_dict()}")
+                    logger.warning(f"[coding-reconcile] drop DELETE missing target: {_op_ref(op)}")
                    continue
                if not self._target_was_offered(op, candidates_per_draft):
                    logger.warning(
-                        f"[coding-reconcile] drop DELETE outside authority scope: {op.to_dict()}"
+                        f"[coding-reconcile] drop DELETE outside authority scope: {_op_ref(op)}"
                    )
                    continue
                # DELETE 需要知道 user_id；通过 draft_idx（如有）或第一个 draft 推断
                user_id = self._infer_user_id(op, drafts)
                if not user_id:
-                    logger.warning(f"[coding-reconcile] drop DELETE no user_id context: {op.to_dict()}")
+                    logger.warning(f"[coding-reconcile] drop DELETE no user_id context: {_op_ref(op)}")
                    continue
                try:
                    ok = await self.store.delete(op.target_experience_id, user_id=user_id)
@@ -577,6 +580,7 @@ class CodingMemoryReconciler:
            confidence=d.confidence,
            source=d.source,
            extraction_source=d.extraction_source,
+            memory_at=d.memory_at,
        )


@@ -584,6 +588,14 @@ class CodingMemoryReconciler:
 # Helpers
 # ================================================================

+def _op_ref(op: ReconcileOp) -> str:
+    """op 的日志引用：只带动作与编号，不带 LLM 写的 reason。"""
+    return (
+        f"action={op.action} draft_idx={op.draft_idx} "
+        f"target={op.target_experience_id}"
+    )
+
+
 def _truncate(s: str, n: int) -> str:
    if not s:
        return ""
@@ -86,6 +86,7 @@ CREATE TABLE IF NOT EXISTS coding_memory_meta (
    confidence       REAL NOT NULL DEFAULT 0.7,
    source           TEXT NOT NULL DEFAULT 'default',
    extraction_source TEXT NOT NULL DEFAULT 'auto_extract',
+    memory_at        INTEGER,
    created_at       TEXT NOT NULL,
    updated_at       TEXT NOT NULL
 );
@@ -109,6 +110,7 @@ CREATE TABLE IF NOT EXISTS working_fact (
    derived_experience_ids TEXT NOT NULL DEFAULT '[]',
    status                 TEXT NOT NULL DEFAULT 'active',
    fact_chain_summary     TEXT NOT NULL DEFAULT '',
+    memory_at              INTEGER,
    created_at             TEXT NOT NULL
 );
 -- 反查前驱（谁的 fact_link 指向我）走这个索引，写演变总结时要顺着链往回走
@@ -164,6 +166,8 @@ _ADDED_COLUMNS = {
    "coding_memory_meta": {
        "source_fact_ids": "TEXT NOT NULL DEFAULT '[]'",
        "extraction_source": "TEXT NOT NULL DEFAULT 'auto_extract'",
+        # 对话时间，秒级 epoch（同 chat）。老库里的行是 NULL：那时没存过。
+        "memory_at": "INTEGER",
    },
    # 早期版本存过一列 fact_chain（机械累积的历代说法），已废弃：同样的信息顺着
    # fact_link 反查就有。老库里那一列留着不管，有默认值不影响插入。
@@ -177,6 +181,7 @@ _ADDED_COLUMNS = {
        "subject": "TEXT NOT NULL DEFAULT ''",
        "details": "TEXT NOT NULL DEFAULT ''",
        "source": "TEXT NOT NULL DEFAULT 'default'",
+        "memory_at": "INTEGER",
    },
 }

@@ -217,6 +222,21 @@ def _in_clause(column: str, values: Optional[List[str]]) -> Tuple[str, List[Any]
    return f"{column} IN ({placeholders})", list(values)


+def _source_where(
+    include_sources: Optional[List[str]], exclude_sources: Optional[List[str]],
+) -> Tuple[str, List[Any]]:
+    """Caller-source filter as SQL (``1`` when unfiltered); exclusion wins."""
+    clauses: List[str] = []
+    params: List[Any] = []
+    if include_sources:
+        clauses.append(f"source IN ({','.join('?' for _ in include_sources)})")
+        params.extend(include_sources)
+    if exclude_sources:
+        clauses.append(f"source NOT IN ({','.join('?' for _ in exclude_sources)})")
+        params.extend(exclude_sources)
+    return (" AND ".join(clauses) or "1"), params
+
+
 def _scope_matches(
    row_workspace_id: Optional[str],
    row_branch: Optional[str],
@@ -275,6 +295,29 @@ def _parse_dt(s: Optional[str]) -> Optional[datetime]:
        return None


+def _from_epoch(value: Any) -> Optional[datetime]:
+    """memory_at 列（秒级 epoch）→ datetime；NULL 或坏值返回 None。"""
+    if value is None:
+        return None
+    try:
+        return datetime.fromtimestamp(int(value))
+    except Exception:
+        return None
+
+
+def _to_epoch(value: Optional[datetime]) -> Optional[int]:
+    return int(value.timestamp()) if isinstance(value, datetime) else None
+
+
+def _later(a: Optional[datetime], b: Optional[datetime]) -> Optional[datetime]:
+    """两个对话时间取较晚的；一边缺就取另一边。"""
+    if a is None:
+        return b
+    if b is None:
+        return a
+    return a if _to_epoch(a) >= _to_epoch(b) else b
+
+
 def _row_to_memory(row: sqlite3.Row) -> CodingMemory:
    """SQLite row → CodingMemory"""
    return CodingMemory(
@@ -293,6 +336,7 @@ def _row_to_memory(row: sqlite3.Row) -> CodingMemory:
        confidence=row["confidence"],
        source=row["source"],
        extraction_source=row["extraction_source"],
+        memory_at=_from_epoch(row["memory_at"]),
        created_at=_parse_dt(row["created_at"]),
        updated_at=_parse_dt(row["updated_at"]),
    )
@@ -319,6 +363,7 @@ def _row_to_fact(row: sqlite3.Row) -> WorkingFact:
        # 老库刚 ADD COLUMN 时可能取不到这一列，用 keys() 兜一下
        fact_chain_summary=(row["fact_chain_summary"] or ""
                            if "fact_chain_summary" in row.keys() else ""),
+        memory_at=_from_epoch(row["memory_at"]),
        created_at=_parse_dt(row["created_at"]),
    )

@@ -560,7 +605,11 @@ class CodingMemoryStore:
        await self._upsert_vec_keys(memory)
        logger.info(
            f"[coding-store] inserted experience_id={memory.experience_id} "
-            f"task={memory.task!r} keys={1 + len(memory.search_keys)}"
+            f"keys={1 + len(memory.search_keys)}"
+        )
+        logger.debug(
+            f"[coding-store] inserted experience_id={memory.experience_id} "
+            f"task={memory.task!r}"
        )

    async def update(self, memory: CodingMemory) -> None:
@@ -582,6 +631,8 @@ class CodingMemoryStore:
        memory.updated_at = datetime.utcnow()
        if memory.created_at is None:
            memory.created_at = prev.created_at
+        # 合并后的经验讲的是两段对话，对话时间取较晚的那段
+        memory.memory_at = _later(prev.memory_at, memory.memory_at)
        await _run_in_pool(self._upsert_sql_sync, memory)
        # 删旧 VDB
        await self._delete_vec_keys_by_count(memory.experience_id, prev_key_count)
@@ -603,6 +654,86 @@ class CodingMemoryStore:
        logger.info(f"[coding-store] deleted experience_id={experience_id}")
        return True

+    async def edit_experience(
+        self,
+        experience_id: str,
+        *,
+        user_id: Optional[str] = None,
+        task: Optional[str] = None,
+        solution: Optional[str] = None,
+        search_keys: Optional[List[str]] = None,
+    ) -> Optional[CodingMemory]:
+        """调用方手动改一条经验（client.update 用）。返回改后的经验；不存在返回 None。
+
+        与 update() 的区别：update 是写入链路的覆盖式重写，带写授权校验（同
+        agent/session/workspace 才能改）；这里是用户对已有条目的直接编辑，只动
+        给定的字段，其余原样保留，因此不做授权校验。
+
+        向量行只嵌 task + search_keys（solution 不进向量），所以只改 solution 时
+        不重嵌、不碰向量库；改了 task / search_keys 才删旧 key 行重写。
+        updated_at 总是刷新。
+        """
+        prev = await self.get_by_id(experience_id, user_id=user_id)
+        if prev is None:
+            return None
+        updated = deepcopy(prev)
+        if task is not None:
+            updated.task = task
+        if solution is not None:
+            updated.solution = solution
+        if search_keys is not None:
+            updated.search_keys = list(search_keys)
+        updated.updated_at = datetime.utcnow()
+        await _run_in_pool(self._upsert_sql_sync, updated)
+        if updated.task != prev.task or updated.search_keys != prev.search_keys:
+            await self._delete_vec_keys_by_count(experience_id, 1 + len(prev.search_keys))
+            await self._upsert_vec_keys(updated)
+        logger.info(f"[coding-store] edited experience_id={experience_id}")
+        return updated
+
+    async def edit_fact(
+        self,
+        fact_id: str,
+        *,
+        statement: str,
+        user_id: Optional[str] = None,
+    ) -> Optional[WorkingFact]:
+        """调用方手动改一条事实的 statement。返回改后的事实；不存在返回 None。
+
+        statement 是事实层的检索文本，所以 active 事实会重嵌并覆盖它那一行向量
+        （node_id 就是 fact_id，upsert 即覆盖）。superseded 事实的向量行早已撤掉，
+        这里不把它加回去，否则会让过期结论重新占召回名额。
+        """
+        prev = await self.get_fact(fact_id, user_id=user_id)
+        if prev is None:
+            return None
+        updated = deepcopy(prev)
+        updated.statement = statement
+        await _run_in_pool(self._upsert_fact_sql_sync, updated)
+        if updated.status == "active":
+            await self._upsert_fact_vec(updated)
+        logger.info(f"[coding-store] edited fact_id={fact_id}")
+        return updated
+
+    async def delete_fact(self, fact_id: str, user_id: Optional[str] = None) -> bool:
+        """物理删除一条事实（SQLite 行 + 事实向量行），返回是否真有删到。
+
+        别处留下的引用（经验的 source_fact_ids、后继事实的 fact_link）不清：
+        召回侧本来就按存在性过滤死链（get_many / get_facts 查不到自然掉队）。
+        """
+        prev = await self.get_fact(fact_id, user_id=user_id)
+        if prev is None:
+            logger.info(f"[coding-store] delete fact skipped (not found): {fact_id}")
+            return False
+        if self._fact_vec is not None:
+            try:
+                await self._fact_vec.delete(fact_id)
+            except Exception as e:
+                logger.debug(f"[coding-store] delete fact vec {fact_id} ignored: {e}")
+        await _run_in_pool(self._delete_fact_sql_sync, fact_id, prev.user_id)
+        logger.info(f"[coding-store] deleted fact_id={fact_id}")
+        return True
+
    # ------------------------------------------------------------
    # 读取
    # ------------------------------------------------------------
@@ -687,29 +818,84 @@ class CodingMemoryStore:
        branch: Optional[str] = None,
        limit: int = 100,
        offset: int = 0,
+        include_sources: Optional[List[str]] = None,
+        exclude_sources: Optional[List[str]] = None,
    ) -> List["CodingMemory"]:
        """按 workspace_id（+可选 branch）纯过滤列出该 user 的完整 coding memory。

        作用域规则见 _scope_where（与 search 路径共用同一套）。无语义排序，按
-        updated_at 倒序（最近修改优先）。
+        updated_at 倒序（最近修改优先）。include_sources / exclude_sources 按
+        source 列在 SQL 里过滤（排除优先），所以 LIMIT/OFFSET 在过滤之后生效。
        """
        return await _run_in_pool(
-            self._list_by_workspace_sync, user_id, workspace_id, branch, limit, offset
+            self._list_by_workspace_sync, user_id, workspace_id, branch, limit, offset,
+            include_sources, exclude_sources,
        )

    def _list_by_workspace_sync(
        self, user_id: str, workspace_id: str, branch: Optional[str],
        limit: int, offset: int,
+        include_sources: Optional[List[str]] = None,
+        exclude_sources: Optional[List[str]] = None,
    ) -> List["CodingMemory"]:
        scope_sql, scope_params = _scope_where(workspace_id, branch)
+        source_sql, source_params = _source_where(include_sources, exclude_sources)
        with self._lock:
            assert self._conn is not None
            sql = (f"SELECT * FROM coding_memory_meta WHERE user_id = ? AND {scope_sql} "
-                   f"ORDER BY updated_at DESC LIMIT ? OFFSET ?")
-            params: List[Any] = [user_id] + scope_params + [limit, offset]
+                   f"AND {source_sql} "
+                   f"ORDER BY updated_at DESC, experience_id ASC LIMIT ? OFFSET ?")
+            params: List[Any] = ([user_id] + scope_params + source_params
+                                 + [limit, offset])
            cur = self._conn.execute(sql, params)
            return [_row_to_memory(r) for r in cur.fetchall()]

+    async def stats(
+        self,
+        user_id: str,
+        workspace_id: Optional[str] = None,
+        branch: Optional[str] = None,
+        include_sources: Optional[List[str]] = None,
+        exclude_sources: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """经验数、最新创建/修改时间、active 事实数。纯聚合，不读正文。
+
+        作用域与 list_by_workspace 相同：workspace_id 为空表示该 user 全部；
+        来源过滤同样与 list_by_workspace 一致，count 因此恒等于分页可翻到的总数。
+        """
+        return await _run_in_pool(
+            self._stats_sync, user_id, workspace_id, branch,
+            include_sources, exclude_sources,
+        )
+
+    def _stats_sync(
+        self, user_id: str, workspace_id: Optional[str], branch: Optional[str],
+        include_sources: Optional[List[str]] = None,
+        exclude_sources: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        scope_sql, scope_params = _scope_where(workspace_id, branch)
+        source_sql, source_params = _source_where(include_sources, exclude_sources)
+        with self._lock:
+            assert self._conn is not None
+            row = self._conn.execute(
+                f"SELECT COUNT(*) AS n, MAX(created_at) AS created, "
+                f"MAX(updated_at) AS updated FROM coding_memory_meta "
+                f"WHERE user_id = ? AND {scope_sql} AND {source_sql}",
+                [user_id] + scope_params + source_params,
+            ).fetchone()
+            facts = self._conn.execute(
+                f"SELECT COUNT(*) AS n FROM working_fact "
+                f"WHERE user_id = ? AND status = 'active' AND {scope_sql} "
+                f"AND {source_sql}",
+                [user_id] + scope_params + source_params,
+            ).fetchone()
+        return {
+            "count": int(row["n"] or 0),
+            "latest_created_at": _parse_dt(row["created"]) if row["created"] else None,
+            "latest_updated_at": _parse_dt(row["updated"]) if row["updated"] else None,
+            "facts": int(facts["n"] or 0),
+        }
+
    # ------------------------------------------------------------
    # 召回
    # ------------------------------------------------------------
@@ -820,7 +1006,8 @@ class CodingMemoryStore:
            fact.created_at = datetime.utcnow()
        await _run_in_pool(self._upsert_fact_sql_sync, fact)
        await self._upsert_fact_vec(fact)
-        logger.info(
+        logger.info(f"[coding-store] inserted fact_id={fact.fact_id}")
+        logger.debug(
            f"[coding-store] inserted fact_id={fact.fact_id} "
            f"statement={fact.statement!r}"
        )
@@ -1049,8 +1236,8 @@ class CodingMemoryStore:
                    experience_id, user_id, agent_id, task, search_keys, solution,
                    boundary_envs, workspace_id, branch, session_id,
                    files, source_fact_ids, confidence, source, extraction_source,
-                    created_at, updated_at
-                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    memory_at, created_at, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                ON CONFLICT(experience_id) DO UPDATE SET
                    user_id         = excluded.user_id,
                    agent_id        = excluded.agent_id,
@@ -1066,6 +1253,7 @@ class CodingMemoryStore:
                    confidence      = excluded.confidence,
                    source          = excluded.source,
                    extraction_source = excluded.extraction_source,
+                    memory_at       = excluded.memory_at,
                    updated_at      = excluded.updated_at
                """,
                (
@@ -1076,6 +1264,7 @@ class CodingMemoryStore:
                    json.dumps(memory.files, ensure_ascii=False),
                    json.dumps(memory.source_fact_ids, ensure_ascii=False),
                    memory.confidence, memory.source, memory.extraction_source,
+                    _to_epoch(memory.memory_at),
                    (memory.created_at or datetime.utcnow()).isoformat(),
                    (memory.updated_at or datetime.utcnow()).isoformat(),
                ),
@@ -1088,6 +1277,14 @@ class CodingMemoryStore:
                (experience_id, user_id),
            )

+    def _delete_fact_sql_sync(self, fact_id: str, user_id: str) -> None:
+        with self._lock:
+            assert self._conn is not None
+            self._conn.execute(
+                "DELETE FROM working_fact WHERE fact_id = ? AND user_id = ?",
+                (fact_id, user_id),
+            )
+
    def _get_by_id_sync(
        self, experience_id: str, user_id: Optional[str]
    ) -> Optional[CodingMemory]:
@@ -1208,8 +1405,8 @@ class CodingMemoryStore:
                    fact_id, user_id, agent_id, session_id, workspace_id, branch,
                    source, statement, files, subject, details,
                    fact_link, derived_experience_ids,
-                    status, fact_chain_summary, created_at
-                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    status, fact_chain_summary, memory_at, created_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                ON CONFLICT(fact_id) DO UPDATE SET
                    user_id                = excluded.user_id,
                    agent_id               = excluded.agent_id,
@@ -1224,7 +1421,8 @@ class CodingMemoryStore:
                    fact_link              = excluded.fact_link,
                    derived_experience_ids = excluded.derived_experience_ids,
                    status                 = excluded.status,
-                    fact_chain_summary     = excluded.fact_chain_summary
+                    fact_chain_summary     = excluded.fact_chain_summary,
+                    memory_at              = excluded.memory_at
                """,
                (
                    fact.fact_id, fact.user_id, fact.agent_id,
@@ -1237,6 +1435,7 @@ class CodingMemoryStore:
                    json.dumps(fact.derived_experience_ids, ensure_ascii=False),
                    fact.status,
                    fact.fact_chain_summary or "",
+                    _to_epoch(fact.memory_at),
                    (fact.created_at or datetime.utcnow()).isoformat(),
                ),
            )
@@ -25,6 +25,11 @@ FactStatus = Literal["active", "superseded"]
 MAX_FACT_CHAIN_ENTRIES = 8


+def _epoch(value: Optional[datetime]) -> Optional[int]:
+    """memory_at 对外是秒级 epoch，与 chat 一致。"""
+    return int(value.timestamp()) if isinstance(value, datetime) else None
+
+
 # ================================================================
 # 草稿（LLM extract 阶段输出）
 # ================================================================
@@ -53,6 +58,8 @@ class CodingMemoryDraft:
    files: List[str] = field(default_factory=list)
    source: str = "default"
    extraction_source: str = "auto_extract"
+    # 对话时间（SDK 注入，同 chat 的 memory_at）
+    memory_at: Optional[datetime] = None

    def __post_init__(self) -> None:
        from ..utils.source_filter import normalize_source
@@ -73,6 +80,7 @@ class CodingMemoryDraft:
            "files": list(self.files),
            "source": self.source,
            "extraction_source": self.extraction_source,
+            "memory_at": _epoch(self.memory_at),
        }


@@ -111,6 +119,9 @@ class CodingMemory:
    extraction_source: str = "auto_extract"

    # 时间
+    # memory_at 是对话时间（同 chat），created_at / updated_at 是写库时间。
+    # UPDATE 合并时取两者中较晚的那个对话时间，见 store.update。
+    memory_at: Optional[datetime] = None
    created_at: Optional[datetime] = None
    updated_at: Optional[datetime] = None

@@ -135,6 +146,7 @@ class CodingMemory:
            "confidence": self.confidence,
            "source": self.source,
            "extraction_source": self.extraction_source,
+            "memory_at": _epoch(self.memory_at),
            "created_at": self.created_at.isoformat() if self.created_at else None,
            "updated_at": self.updated_at.isoformat() if self.updated_at else None,
        }
@@ -249,6 +261,7 @@ class WorkingFact:
    fact_chain_summary: str = ""

    # 时间
+    memory_at: Optional[datetime] = None   # 对话时间（同 chat），没传时是收到请求的时间
    created_at: Optional[datetime] = None  # 产生时间，新的优先

    def __post_init__(self) -> None:
@@ -272,6 +285,7 @@ class WorkingFact:
            "derived_experience_ids": list(self.derived_experience_ids),
            "status": self.status,
            "fact_chain_summary": self.fact_chain_summary,
+            "memory_at": _epoch(self.memory_at),
            "created_at": self.created_at.isoformat() if self.created_at else None,
        }

@@ -18,6 +18,7 @@ CodingWriter - 写入端协调器
 import logging
 import time
 import uuid
+from datetime import datetime
 from typing import Any, Dict, List, Optional

 from ..agent.llm_provider import LLMProvider
@@ -79,9 +80,11 @@ class CodingWriter:
        session_id: Optional[str] = None,
        request_id: Optional[str] = None,
        source: str = "default",
+        memory_at: Optional[datetime] = None,
    ) -> Dict[str, Any]:
        """
-        working/coding 段写入端到端。返回响应 dict（兼容 client.add 返回结构）：
+        working/coding 段写入端到端。memory_at 是对话时间，记到这次写出的经验和
+        事实上；不传则用收到请求的时间（与 chat 链路一致）。返回响应 dict（兼容 client.add 返回结构）：
            {
                "success": True,
                "scene": "productivity",
@@ -101,6 +104,8 @@ class CodingWriter:
        """
        request_id = request_id or str(uuid.uuid4())
        t0 = time.perf_counter()
+        if memory_at is None:
+            memory_at = datetime.now()

        if not messages:
            return self._empty_response(request_id, t0)
@@ -172,6 +177,7 @@ class CodingWriter:
        # extractor 只负责内容；调用来源由 SDK 入口注入，不能交给 LLM 生成。
        for draft in drafts:
            draft.source = source
+            draft.memory_at = memory_at

        # 3. 经验层 reconcile + 持久化
        ops: List[ReconcileOp] = (
@@ -197,6 +203,7 @@ class CodingWriter:
                workspace_id=workspace_id,
                branch=branch,
                source=source,
+                memory_at=memory_at,
            )

        experience_ids = [op.target_experience_id for op in ops
@@ -260,6 +260,7 @@ class EmbedderConfig:
    max_retries: int = None  # 最大重试次数
    retry_delay: float = None  # 重试间隔（秒）
    timeout: int = None  # 请求超时（秒）
+    batch_size: int = None  # 单次 HTTP 请求最多带多少条 input（embed_batch 按此切块）

    # 内部平台扩展（extra_headers / extra_body 会透传给 OpenAI client）
    extra_headers: Optional[Dict[str, str]] = None
@@ -294,6 +295,10 @@ class EmbedderConfig:
            # 请求切断并制造重试风暴。SDK 内层重试已关闭，15s 是每个显式 attempt
            # 的真实上限；部署可通过 MEMORY_EMBEDDER_TIMEOUT 覆盖。
            self.timeout = _get_env_int("MEMORY_EMBEDDER_TIMEOUT", 15)
+        if self.batch_size is None:
+            # 大批量（如重新 embed 整个库）不能一次 HTTP 发几千条：多数服务对
+            # input 数组有上限，超了直接 400。按 batch_size 切块逐块发送。
+            self.batch_size = _get_env_int("MEMORY_EMBEDDER_BATCH_SIZE", 64)
        if self.extra_headers is None:
            val = os.getenv("MEMORY_EMBEDDER_EXTRA_HEADERS")
            if val:
@@ -38,10 +38,12 @@ import importlib.util
 import json
 from json import JSONDecodeError
 import logging
+import random
 import threading
 import time

 from ..config import MemoryConfig
+from ..embedding import EmbeddingDimensionMismatchError
 from .workload import embedding_slot
 from ..utils.log_setup import get_request_id

@@ -80,7 +82,7 @@ def _count_tokens(text: str) -> int:
    try:
        import tiktoken

-        return len(tiktoken.get_encoding("cl100k_base").encode(text))
+        return len(tiktoken.get_encoding("cl100k_base").encode(text, disallowed_special=()))
    except Exception:
        return len(text) // _CHARS_PER_TOKEN_FALLBACK + 1

@@ -98,7 +100,8 @@ def _truncate_for_embedding(text: str, limit: int = _EMBED_MAX_TOKENS) -> str:
        import tiktoken

        enc = tiktoken.get_encoding("cl100k_base")
-        ids = enc.encode(text)
+        # Input is ordinary user text, not a tokenizer control-token stream.
+        ids = enc.encode(text, disallowed_special=())
        if len(ids) <= limit:
            return text
        dropped = len(ids) - limit
@@ -186,6 +189,41 @@ def _redact_headers(headers: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any
    return out


+# Retry-After 的上限：服务端给出超长等待（或恶意值）时不让单次调用挂几十分钟。
+_RETRY_AFTER_MAX_S = 60.0
+
+
+def _retry_after_seconds(exc: Exception) -> Optional[float]:
+    """从 429 异常的响应头里取 Retry-After（秒数或 HTTP 日期），取不到返回 None。"""
+    response = getattr(exc, "response", None)
+    headers = getattr(response, "headers", None)
+    if not headers:
+        return None
+    try:
+        raw = headers.get("retry-after") or headers.get("Retry-After")
+    except Exception:
+        return None
+    if raw is None:
+        return None
+    raw = str(raw).strip()
+    try:
+        seconds = float(raw)
+    except ValueError:
+        try:
+            from email.utils import parsedate_to_datetime
+            from datetime import datetime, timezone
+
+            when = parsedate_to_datetime(raw)
+            if when.tzinfo is None:
+                when = when.replace(tzinfo=timezone.utc)
+            seconds = (when - datetime.now(timezone.utc)).total_seconds()
+        except Exception:
+            return None
+    if seconds != seconds:  # NaN
+        return None
+    return min(max(0.0, seconds), _RETRY_AFTER_MAX_S)
+
+
 def _embeddings_api_url(base_url: str) -> str:
    """OpenAI SDK posts to ``{base_url}/embeddings`` (base_url usually ends with /v1)."""
    base = (base_url or "").rstrip("/")
@@ -204,7 +242,8 @@ class EmbedServiceConfig:
    api_key: str = ""
    base_url: str = ""
    embedding_dims: int = 1536
-    batch_size: int = 100
+    # embed_batch 单次 HTTP 最多带多少条 input；超出按块顺序发送
+    batch_size: int = 64
    enable_cache: bool = True
    cache_size: int = 10000
    max_retries: int = 5
@@ -286,6 +325,7 @@ class EmbedService:
            max_retries=embedder.max_retries if embedder.max_retries is not None else 5,
            retry_delay=embedder.retry_delay if embedder.retry_delay is not None else 3.0,
            timeout=embedder.timeout if embedder.timeout is not None else 60,
+            batch_size=max(1, int(getattr(embedder, "batch_size", None) or 64)),
            queue_batch_size=int(os.getenv("MEMORY_EMBED_BATCH_SIZE", "8")),
            queue_batch_window_ms=float(os.getenv("MEMORY_EMBED_BATCH_WINDOW_MS", "100")),
            extra_headers=embedder.extra_headers,
@@ -639,6 +679,8 @@ class EmbedService:
        self,
        texts: List[str],
        use_cache: bool = True,
+        *,
+        max_retries: Optional[int] = None,
    ) -> List[List[float]]:
        """
        批量向量化
@@ -646,17 +688,23 @@ class EmbedService:
        Args:
            texts: 文本列表
            use_cache: 是否使用缓存
+            max_retries: 本次调用的重试次数；None 用配置值。长批量任务（重新
+                embed 整个库）可以给更宽的重试预算，不影响在线路径。
        
        Returns:
            向量列表
        """
-        vectors, _metas = await self.embed_batch_with_meta(texts, use_cache=use_cache)
+        vectors, _metas = await self.embed_batch_with_meta(
+            texts, use_cache=use_cache, max_retries=max_retries,
+        )
        return vectors

    async def embed_batch_with_meta(
        self,
        texts: List[str],
        use_cache: bool = True,
+        *,
+        max_retries: Optional[int] = None,
    ) -> Tuple[List[List[float]], List[Dict[str, Any]]]:
        """批量向量化，同时返回每条的 provider metadata（非 vector）。"""
        if not texts:
@@ -681,7 +729,12 @@ class EmbedService:
            indices_to_embed.append(i)

        if texts_to_embed:
-            vectors, batch_metas = await self._embed_texts_with_meta(texts_to_embed)
+            # max_retries 只在显式给出时透传：保持 `_embed_texts_with_meta(texts)`
+            # 这个既有调用形状不变（测试与下游替身按它打桩）。
+            retry_kwargs = {} if max_retries is None else {"max_retries": max_retries}
+            vectors, batch_metas = await self._embed_texts_with_meta(
+                texts_to_embed, **retry_kwargs,
+            )

            for j, vector in enumerate(vectors):
                idx = indices_to_embed[j]
@@ -699,9 +752,9 @@ class EmbedService:
        return results, metas
    
    async def _embed_texts_with_meta(
-        self, texts: List[str]
+        self, texts: List[str], *, max_retries: Optional[int] = None,
    ) -> Tuple[List[List[float]], List[Dict[str, Any]]]:
-        """实际的向量化调用：**一次 HTTP 带走整批**；返回 (vectors, metas)。
+        """实际的向量化调用：**一次 HTTP 带走一块**；返回 (vectors, metas)。

        早期实现是 `for text in texts: await _embed_openai([text])` 逐条串行，
        原意是"避免 batch size 限制"，但代价极大：线上一批 8 条 × ~5.6s 串行
@@ -718,21 +771,34 @@ class EmbedService:
        截断在这里做（发送前逐条过 `_truncate_for_embedding`）：所有 embedding
        路径（embed / embed_batch / embed_queued / *_with_meta）最终都落到这个
        方法 —— 放在各入口会漏。理由与阈值见模块头部 `_EMBED_MAX_TOKENS`。
+
+        切块：一次带走整批只适用于小批。几千条的 input 数组会被多数服务直接
+        400（input 上限），所以按 `batch_size`（默认 64）切块，块之间顺序发送。
+        不超过一块时行为与切块前逐字相同（`batch_mode="single_request"`）。
        """
        if not texts:
            return [], []

        safe_texts = [_truncate_for_embedding(t) for t in texts]
-        vectors, meta = await self._embed_openai(safe_texts)
-        base_meta = dict(meta or {})
-        base_meta["batch_mode"] = "single_request"
-        base_meta["batch_input_count"] = len(safe_texts)
-
+        chunk = max(1, int(self._embed_config.batch_size or 64))
+        vectors: List[List[float]] = []
        all_metas: List[Dict[str, Any]] = []
-        for idx in range(len(safe_texts)):
-            m = dict(base_meta)
-            m["batch_index"] = idx
-            all_metas.append(m)
+        chunk_count = (len(safe_texts) + chunk - 1) // chunk
+        for start in range(0, len(safe_texts), chunk):
+            part = safe_texts[start:start + chunk]
+            retry_kwargs = {} if max_retries is None else {"max_retries": max_retries}
+            part_vectors, meta = await self._embed_openai(part, **retry_kwargs)
+            base_meta = dict(meta or {})
+            base_meta["batch_mode"] = "single_request" if chunk_count == 1 else "chunked"
+            base_meta["batch_input_count"] = len(part)
+            if chunk_count > 1:
+                base_meta["batch_chunk_index"] = start // chunk
+                base_meta["batch_chunk_count"] = chunk_count
+            for idx in range(len(part)):
+                m = dict(base_meta)
+                m["batch_index"] = start + idx
+                all_metas.append(m)
+            vectors.extend(part_vectors)

        self._last_embed_meta = all_metas[-1] if all_metas else {}
        return vectors, all_metas
@@ -753,16 +819,22 @@ class EmbedService:
        """
        打一条 INFO 级 embedding 请求日志（含 request_id / provider / model / api / 入参 / 出参）。

-        出参只含 vector 维度，不含向量数值。request_id 同时写入 message，
+        出参只含 vector 维度，不含向量数值。入参的 input 是待向量化的原文
+        （对话 / 记忆 / 查询），INFO 只记每条的字符数（input_chars），原文仅在
+        DEBUG 单独输出。request_id 同时写入 message，
        并依赖 log formatter 的 %(request_id)s（setup_logging 后生效）。
        """
+        texts = request_payload.get("input")
+        info_request = {k: v for k, v in request_payload.items() if k != "input"}
+        if isinstance(texts, list):
+            info_request["input_chars"] = [len(str(t)) for t in texts]
        payload = {
            "request_id": get_request_id(),
            "status": status,
            "provider": self._embed_config.provider,
            "model": self._embed_config.model,
            "api": api_url,
-            "request": request_payload,
+            "request": info_request,
            "response": response_payload,
        }
        try:
@@ -770,9 +842,13 @@ class EmbedService:
        except Exception:
            body = str(payload)
        logger.info(f"[embed] {body}")
+        if texts is not None and logger.isEnabledFor(logging.DEBUG):
+            logger.debug(
+                f"[embed] input: {json.dumps(texts, ensure_ascii=False, default=str)}"
+            )

    async def _embed_openai(
-        self, texts: List[str]
+        self, texts: List[str], *, max_retries: Optional[int] = None,
    ) -> Tuple[List[List[float]], Dict[str, Any]]:
        """
        使用 OpenAI 兼容接口向量化
@@ -862,7 +938,9 @@ class EmbedService:
            "endpoint_overridden": bool(_ov),
        }

-        _max_retries = max(0, int(self._embed_config.max_retries or 0))
+        _max_retries = max(0, int(
+            (self._embed_config.max_retries or 0) if max_retries is None else max_retries
+        ))
        _retry_delay = max(0.0, float(self._embed_config.retry_delay or 0.0))
        last_exc: Optional[Exception] = None

@@ -908,6 +986,17 @@ class EmbedService:
                        f"got={len(vectors)}"
                    )
                dims = [len(v) for v in vectors]
+                expected_dims = self._embed_config.embedding_dims
+                if expected_dims:
+                    bad = [d for d in dims if d != int(expected_dims)]
+                    if bad:
+                        # 宽度不对的向量写进集合会把集合的维度钉死在错误值上（Chroma
+                        # 首次 add 定维），或在已有集合上整批失败。确定性错误，不重试。
+                        raise EmbeddingDimensionMismatchError(
+                            "embedding dimension mismatch: "
+                            f"expected={int(expected_dims)} got={bad[0]} "
+                            f"model={self._embed_config.model}"
+                        )
                meta = {
                    "http_status": raw.status_code,
                    "response_headers": resp_headers,
@@ -943,6 +1032,8 @@ class EmbedService:
                    },
                )
                return vectors, meta
+            except EmbeddingDimensionMismatchError:
+                raise
            except Exception as e:
                last_exc = e
                _err_name = type(e).__name__
@@ -976,12 +1067,18 @@ class EmbedService:
                if _retryable and attempt < _max_retries:
                    # 逐出可能卡死的 client,下个 attempt 重建干净连接(恢复原防御语义)
                    self._evict_client(_eff_base_url, _eff_api_key, _eff_timeout)
+                    _delay = _retry_delay
+                    _retry_after = _retry_after_seconds(e) if _status == 429 else None
+                    if _retry_after is not None:
+                        # 限流时服务端明确告诉了要等多久：按它等，再加一点抖动，
+                        # 避免多个 worker 在同一时刻一起醒来再次撞限流。
+                        _delay = max(_delay, _retry_after) + random.uniform(0, 0.25 * _retry_after)
                    logger.warning(
                        f"[embed] attempt {attempt + 1}/{_max_retries + 1} failed "
-                        f"({_err_name}): {_err_msg[:200]}; retry in {_retry_delay}s"
+                        f"({_err_name}): {_err_msg[:200]}; retry in {_delay:.2f}s"
                    )
-                    if _retry_delay > 0:
-                        await asyncio.sleep(_retry_delay)
+                    if _delay > 0:
+                        await asyncio.sleep(_delay)
                    continue
                self._log_embed_call(
                    status="error",
@@ -22,6 +22,7 @@ import logging
 import json
 import threading
 import time
+import weakref

 from ..models.memory import MemoryNode, MemoryLayer, MemoryStatus
 from ..config import MemoryConfig
@@ -77,6 +78,21 @@ async def _run_in_kuzu_pool(func, *args, **kwargs):
    return await run_in_executor_guarded(_kuzu_executor, _measured)


+# 本进程里已打开、尚未 close 的 store。drop_graph 据此拒绝删掉一个正被
+# 活着的 client 使用的图库。WeakSet：store 被回收后自动消失。
+_LIVE_STORES: "weakref.WeakSet[KuzuGraphStore]" = weakref.WeakSet()
+
+
+def open_graph_paths() -> List[str]:
+    """Real paths of the graph databases live stores in this process hold open."""
+    import os
+    return [
+        os.path.realpath(str(store._db_path))
+        for store in list(_LIVE_STORES)
+        if store._db is not None
+    ]
+
+
 def kuzu_executor_snapshot() -> Dict[str, Any]:
    with _kuzu_stats_lock:
        return {
@@ -350,6 +366,7 @@ class KuzuGraphStore(GraphStoreBase):
            )
            self._db = db
            self._conn = conn
+            _LIVE_STORES.add(self)
        except asyncio.TimeoutError:
            logger.warning(
                f"GraphStore init timed out after 5s (Kuzu file lock contention). "
@@ -2441,6 +2458,7 @@ class KuzuGraphStore(GraphStoreBase):
    async def close(self) -> None:
        """关闭连接"""
        conn, db = self._conn, self._db
+        _LIVE_STORES.discard(self)
        self._conn = None
        self._db = None
        self._available = False
@@ -89,6 +89,17 @@ def passes_created_after(
 logger = logging.getLogger(__name__)


+def physical_collection_name(base_name: Optional[str], dims: Optional[int]) -> str:
+    """The collection name a store opens for ``base_name`` at ``dims``.
+
+    The dims suffix keeps two embedding widths from sharing one collection.
+    `hy_memory.reembed.vector_space_names` uses this too, so callers never
+    re-derive the rule.
+    """
+    base = base_name or "agent_memories"
+    return f"{base}_{dims}" if dims else base
+
+
 class VectorStoreBase(ABC):
    """
    向量存储抽象基类
@@ -98,13 +109,10 @@ class VectorStoreBase(ABC):

    def __init__(self, config: MemoryConfig):
        self.config = config
-        base_name = config.vector_store.collection_name or "agent_memories"
-        dims = config.vector_store.embedding_dims
        # 自动拼接维度后缀，避免不同 embedding 模型写入同一 collection 导致维度冲突
-        if dims:
-            self._collection_name = f"{base_name}_{dims}"
-        else:
-            self._collection_name = base_name
+        self._collection_name = physical_collection_name(
+            config.vector_store.collection_name, config.vector_store.embedding_dims,
+        )

    _supports_retrieval_clauses: bool = False
    _supports_narrow_episode_queries: bool = False
@@ -9,10 +9,12 @@ Agent Memory V2 - VectorStore (Chroma)
 - 同步 API → _run_in_vdb_pool() 包装为异步
 """

-from typing import Optional, List, Dict, Any
+from typing import Optional, List, Dict, Any, Set, Tuple
 import concurrent.futures
 import functools
 import logging
+import os
+import weakref

 from ..models.memory import (
    MemoryNode, MemoryLayer, MemoryStatus,
@@ -33,6 +35,30 @@ _vdb_executor = concurrent.futures.ThreadPoolExecutor(
 )


+# 本进程里已 initialize、尚未 close 的 store。drop_vector_space 据此拒绝删掉
+# 一个正被活着的 client 使用的集合。WeakSet：store 被回收后自动消失。
+_LIVE_STORES: "weakref.WeakSet[ChromaVectorStore]" = weakref.WeakSet()
+
+
+def _location_key(vs_config) -> Tuple[str, str]:
+    if getattr(vs_config, "host", None):
+        return ("http", f"{vs_config.host}:{vs_config.port or 8000}")
+    return ("local", os.path.realpath(str(vs_config.persist_directory or "")))
+
+
+def open_collection_names(location: Tuple[str, str]) -> Set[str]:
+    """Collections that live stores in this process hold open at ``location``."""
+    names: Set[str] = set()
+    for store in list(_LIVE_STORES):
+        if store._client is None or _location_key(store.config.vector_store) != location:
+            continue
+        names.add(store._collection_name)
+        if store._entity_collection is not None:
+            from ..pipelines._retrieval.config import entity_collection_name
+            names.add(entity_collection_name(store._collection_name))
+    return names
+
+
 async def _run_in_vdb_pool(func, *args, **kwargs):
    """Run a synchronous Chroma call in the dedicated VDB executor."""
    call = functools.partial(func, *args, **kwargs) if args or kwargs else func
@@ -88,6 +114,7 @@ class ChromaVectorStore(VectorStoreBase):
            return client, collection

        self._client, self._collection = await _run_in_vdb_pool(_init)
+        _LIVE_STORES.add(self)
        logger.debug(f"VectorStore initialized (Chroma), collection={self._collection_name}")

    # ================================================================
@@ -561,6 +588,7 @@ class ChromaVectorStore(VectorStoreBase):
    async def close(self) -> None:
        """关闭客户端"""
        # Chroma PersistentClient 无需显式关闭
+        _LIVE_STORES.discard(self)
        self._client = None
        self._collection = None
        self._entity_collection = None
@@ -160,6 +160,28 @@ def near_dup_demote(
    return out


+# MMR 只在调用方请求的 top-k（search 的 limit）小于这个值时自动启用。
+# mmr_select 的贪心是 O(k^2 * pool) 次 Jaccard，k 大时代价陡增，而大 k 本身已
+# 足够容纳多样性，收益很小。权重仍由 MEMORY_HYBRID_V2_MMR_LAMBDA 控制。
+MMR_MAX_TOP_K = 20
+
+
+def mmr_applies(top_k: int, lambda_: float) -> bool:
+    """本次检索是否走 MMR：λ 在有效区间内，且 top_k < MMR_MAX_TOP_K。"""
+    return 0.0 < float(lambda_) < 0.999 and int(top_k) < MMR_MAX_TOP_K
+
+
+def near_dup_applies(top_k: int) -> bool:
+    """本次检索是否走近重复降权：与 MMR 同一个 top-k 门槛。
+
+    near_dup_demote 让每个候选和此前所有"非重复"候选两两算 Jaccard，候选
+    互不相似时是 O(pool^2)；池子随 limit 放大（约 max(3*limit, 30) + 关键词
+    命中），limit 达到 MMR_MAX_TOP_K 时代价同样陡增。大 k 的调用方（如记忆
+    面板翻页）要的是全部相关项，相似项也应照常出现，降权没有收益。
+    """
+    return int(top_k) < MMR_MAX_TOP_K
+
+
 def mmr_select(
    hits: Sequence[Dict[str, Any]],
    limit: int,
@@ -115,11 +115,16 @@ class ReconcileHybridRetriever:
        fused_max = max(fused_all) if fused_all else 0.0

        base = (
-            f"[reconcile-hybrid][{req}] pool={pool_size} q_terms={q_terms!r} "
+            f"[reconcile-hybrid][{req}] pool={pool_size} q_terms={len(q_terms)} "
            f"raw_bm25 max={raw_max:.4f} nonzero={raw_nonzero}/{len(raw_bm25)} "
            f"bm25_norm max={norm_max:.4f} nonzero={norm_nonzero}/{len(bm25_norms)} "
            f"sem_max={sem_max:.4f} fused_max={fused_max:.4f} "
            f"kept={kept}/{len(fused_all)} min_score={self._cfg.min_score} "
+            f"query({len(query_text or '')} chars)"
+        )
+        # query 是待对账的新记忆原文，词项与预览只进 DEBUG
+        logger.debug(
+            f"[reconcile-hybrid][{req}] q_terms={q_terms!r} "
            f"query={q_preview!r} lemmatized={lem_preview!r}"
        )

@@ -401,6 +401,11 @@ class ReadRequest:
    intention_limit: int = 0           # Intention 路的 topk，默认 0 关闭


+    # 重排开关（按次生效）。False 时跳过全部重排阶段：本地 cross-encoder
+    # (recall.local_rerank_enabled) 与记忆关系图重排 (_apply_graph_rerank)，
+    # 结果按召回分排序。走请求对象而非环境变量，并发请求互不影响。
+    rerank: bool = True
+
    # 时间过滤
    created_after: Optional[float] = None  # Unix timestamp (float)，只返回 gmt_created >= 此值的记忆

@@ -692,9 +692,10 @@ class CrossDomainSweeper:
                )

            logger.info(
-                f"[sweeper] Created L6 core {core_id[:12]}: '{core_content[:60]}' "
+                f"[sweeper] Created L6 core {core_id[:12]} "
                f"from {len(cluster_ids)} basics, evidence_inherited={len(inherited_evidence_ids)}"
            )
+            logger.debug(f"[sweeper] L6 core {core_id[:12]} content={core_content[:60]!r}")
            return 1, 0, [core_id]

        except Exception as e:
@@ -57,7 +57,9 @@ from ._retrieval.ner import (
    memory_matches_time_hints,
 )
 from ._retrieval.diversity import (
+    near_dup_applies,
    near_dup_demote,
+    mmr_applies,
    mmr_select,
    social_boilerplate_demote,
    pool_df_demote,
@@ -1279,7 +1281,10 @@ class BaseReadPipeline(ReadPipeline):
            SAME_SERIES_TIMELINE_ON = bool(
                getattr(self.config.recall, "same_series_timeline_enabled", False)
            )
-            LOCAL_RERANK_ON = bool(
+            # 按次的重排开关（search(rerank=False)）：关掉本地 cross-encoder 与图重排，
+            # 结果按召回分排序。只读请求对象，不碰共享状态，并发请求互不影响。
+            RERANK_ON = bool(getattr(request, "rerank", True))
+            LOCAL_RERANK_ON = RERANK_ON and bool(
                getattr(self.config.recall, "local_rerank_enabled", False)
            )
            LOCAL_RERANK_POOL_FACTOR = max(1, int(
@@ -1431,6 +1436,11 @@ class BaseReadPipeline(ReadPipeline):
            MIN_SCORE = _resolve_normal_min_score(request.min_score)

            final_limit = request.limit if request.limit > 0 else 10
+            # MMR 只在调用方的 top-k（final_limit，即 search 的 limit）< MMR_MAX_TOP_K
+            # 时启用；池子（LOCAL_RERANK 下是 final_limit 的若干倍）不参与判定。
+            MMR_ON = mmr_applies(final_limit, MMR_LAMBDA)
+            # 近重复降权同样是候选两两比较，用同一个 top-k 门槛。
+            NEAR_DUP_ON = near_dup_applies(final_limit)
            vdb_sem_limit = max(final_limit * 3, 30)
            vdb_kw_limit = max(final_limit * 5, 80)
            graph_limit = max(
@@ -2462,7 +2472,7 @@ class BaseReadPipeline(ReadPipeline):
            # 只把已选出的 top-N 换个顺序收益很小。
            relation_paths: List[Dict[str, Any]] = []
            _graph_stats: Dict[str, Any] = {}
-            if self._expansion_on():
+            if RERANK_ON and self._expansion_on():
                _t_graph = datetime.now()
                _pool_before = len(normal_results)
                normal_results, relation_paths, _graph_stats = await self._apply_graph_rerank(
@@ -2525,7 +2535,7 @@ class BaseReadPipeline(ReadPipeline):
                        df_thr=POOL_DF_THR,
                        penalty=POOL_DF_PENALTY,
                    )
-                if NEAR_DUP_THR > 0 and NEAR_DUP_PENALTY > 0:
+                if NEAR_DUP_ON and NEAR_DUP_THR > 0 and NEAR_DUP_PENALTY > 0:
                    normal_results = near_dup_demote(
                        normal_results,
                        jaccard_thr=NEAR_DUP_THR,
@@ -2538,7 +2548,7 @@ class BaseReadPipeline(ReadPipeline):
                    ))
                    if LOCAL_RERANK_ON else final_limit
                )
-                if 0.0 < MMR_LAMBDA < 0.999 and len(normal_results) > _pre_rerank_limit:
+                if MMR_ON and len(normal_results) > _pre_rerank_limit:
                    normal_results = mmr_select(
                        normal_results,
                        _pre_rerank_limit,
@@ -2715,7 +2725,7 @@ class BaseReadPipeline(ReadPipeline):
                        reverse=True,
                    )
                    if (
-                        0.0 < MMR_LAMBDA < 0.999
+                        MMR_ON
                        and len(multi_seed_pool) > _pre_rerank_limit
                    ):
                        multi_seed_pool = mmr_select(
@@ -3544,6 +3554,9 @@ class BaseReadPipeline(ReadPipeline):
                "episode_capsule_render_mode": EPISODE_CAPSULE_RENDER_MODE,
                "same_series_timeline_enabled": SAME_SERIES_TIMELINE_ON,
                "local_rerank_enabled": LOCAL_RERANK_ON,
+                "rerank": RERANK_ON,
+                "mmr_applied": MMR_ON,
+                "near_dup_applied": NEAR_DUP_ON,
                "local_rerank_model": getattr(
                    self.config.recall,
                    "local_rerank_model",
@@ -3574,8 +3587,9 @@ class BaseReadPipeline(ReadPipeline):
                f"hidden_l0={len(hidden_l0_hits)} fwd_l6={len(forward_l6)} rev_l6={len(reverse_l6)} "
                f"fused_l6={len(fused_l6)} graph_intent={len(graph_intention_hits)} "
                f"returned={len(final_results)} "
-                f"query='{request.query[:80]}'"
+                f"query({len(request.query or '')} chars)"
            )
+            logger.debug(f"[read/{self.VERSION}] query={request.query[:80]!r}")

            response.success = True

@@ -2516,7 +2516,8 @@ def _parse_operations_json(text: str) -> Optional[List[Dict[str, Any]]]:
            return result
        return None
    except json.JSONDecodeError:
-        logger.warning(f"[S2-agent] JSON parse failed: {json_str[:200]}")
+        logger.warning(f"[S2-agent] JSON parse failed ({len(json_str)} chars)")
+        logger.debug(f"[S2-agent] unparsable output: {json_str[:200]!r}")
        return None


@@ -280,6 +280,22 @@ class MemoryWriter(WritePipeline):
            custom["source_raw_memory_ids"] = source_ids
        return custom

+    def _flat_trimmed_raw(self, request: WriteRequest) -> str:
+        """把 request.messages 按 raw 统一规则裁剪后拼成 L1_RAW 文本。
+
+        只裁落库副本；request.messages 不动（本次 extractor 输入仍用完整 messages）。
+        """
+        import copy as _copy
+        from ..utils.raw_trim import trim_raw_messages
+
+        _coding_cfg = getattr(getattr(self, "config", None), "coding", None)
+        _trimmed_req = _copy.copy(request)
+        _trimmed_req.messages = trim_raw_messages(
+            request.messages,
+            tool_max_bytes=getattr(_coding_cfg, "tool_result_max_bytes", None),
+        )
+        return _trimmed_req.get_flat_content()
+
    @staticmethod
    def _attach_client_meta(custom: Dict[str, Any], request: Optional[WriteRequest]) -> None:
        """给新建节点挂上调用方 meta（单份 list）。
@@ -2554,9 +2570,14 @@ class MemoryWriter(WritePipeline):
        try:
            # 参数校验
            content = request.content
+            # raw 在写入时就按统一规则裁好（见 utils/raw_trim.py）：工具输出、长
+            # assistant 回复不再原样长期存储；历史拼接直接用存下来的文本，不再二次裁剪。
+            # request.messages 保持原样——本次 extractor 输入仍是完整 messages。
+            _raw_trimmed = False
            if not content and request.has_messages():
-                content = request.get_flat_content()
+                content = self._flat_trimmed_raw(request)
                request.content = content
+                _raw_trimmed = True

            if not content:
                response.error_code = 400
@@ -2627,6 +2648,9 @@ class MemoryWriter(WritePipeline):
                    vector_store = await self._get_vector_store()
                    layer_enum = MemoryLayer.from_string(suggested_layer)
                    _raw_custom: Dict[str, Any] = {}
+                    if _raw_trimmed:
+                        from ..utils.raw_trim import RAW_TRIMMED_KEY
+                        _raw_custom[RAW_TRIMMED_KEY] = True
                    self._attach_client_meta(_raw_custom, request)
                    mem_node = MemoryNode(
                        user_id=request.user_id,
@@ -2929,13 +2953,16 @@ class MemoryWriter(WritePipeline):
        agent_id: Optional[str] = None,
        exclude_memory_id: str = "",
        max_turns: int = 20,
-        max_chars_assistant: int = 500,
+        max_chars_assistant: Optional[int] = None,
    ) -> str:
        """
        获取该用户最近的 L1_RAW 对话记录，按轮次拆分后拼成 history context。

        每条 L1_RAW 的 content 是多轮对话（[user]: ...\n[assistant]: ...）。
-        拆成单条 message 后，user 消息完整保留，assistant 消息截取前 max_chars_assistant 字符。
+        raw 在写入时已按 utils/raw_trim.py 的规则裁好（custom[RAW_TRIMMED_KEY]），
+        这里拆成单条 message 后直接拼接，不再二次裁剪。该规则之前写入的旧 raw
+        没有这个标记，仍按同一（幂等）规则裁剪后再拼，避免旧的长回复 / 工具输出
+        撑大 prompt。max_chars_assistant 只作用于这些旧 raw，默认同写入规则。
        最终取最近 max_turns 条 message（注意单位是 message 条数，非对话轮数；
        调用方按 k 轮 × 2 传入）。

@@ -2977,23 +3004,33 @@ class MemoryWriter(WritePipeline):
            # 避免把正文里形如 "[注]: xxx" 的普通文本误判成消息边界。
            import re as _re
            from .base import parse_user_name_line
-            _KNOWN_ROLES = {"user", "assistant", "system", "tool"}
            # 带方括号的任意 label（含对方真人名字）
            _labeled_prefix = _re.compile(r"^\[([^\]\n]{1,32})\]:\s?")
            # 无方括号的已知 role（历史数据容错，沿用旧正则的 `\[?...\]?` 宽容度）
            _bare_role_prefix = _re.compile(r"^(user|assistant|system|tool):\s?")

-            # (label, content) 元组列表；label 为 role 或对方真人名字
-            parsed: List[Tuple[str, str]] = []
+            from ..utils.raw_trim import (
+                DEFAULT_RAW_ASSISTANT_MAX_CHARS,
+                RAW_TRIMMED_KEY,
+                trim_raw_body,
+            )
+            if max_chars_assistant is None:
+                max_chars_assistant = DEFAULT_RAW_ASSISTANT_MAX_CHARS
+            _coding_cfg = getattr(getattr(self, "config", None), "coding", None)
+            _tool_max_bytes = getattr(_coding_cfg, "tool_result_max_bytes", None)
+
+            # (label, content, 是否旧 raw 需兼容裁剪) 元组列表；label 为 role 或对方真人名字
+            parsed: List[Tuple[str, str, bool]] = []
            user_name: str = ""
            for node in nodes:
                content = node.content or ""
+                _legacy = not bool((node.custom or {}).get(RAW_TRIMMED_KEY))
                for _line_idx, line in enumerate(content.split("\n")):
                    m = _labeled_prefix.match(line) or _bare_role_prefix.match(line)
                    if m:
                        label = m.group(1)
                        body = line[m.end():]
-                        parsed.append((label, body))
+                        parsed.append((label, body, _legacy))
                        continue
                    # 名字行只可能是每个 node content 的第一行（get_flat_content 插在文首）。
                    # 逐 node 判断而非用 `not parsed`：parsed 跨 node 累积，第二个 node
@@ -3006,18 +3043,18 @@ class MemoryWriter(WritePipeline):
                            continue
                    if parsed:
                        # 续行：拼回上一条 message（保留换行）
-                        prev_label, prev_body = parsed[-1]
-                        parsed[-1] = (prev_label, prev_body + "\n" + line)
+                        prev_label, prev_body, prev_legacy = parsed[-1]
+                        parsed[-1] = (prev_label, prev_body + "\n" + line, prev_legacy)
                    else:
                        # 开头就是无前缀行（异常/老数据）：当成 user 消息兜底
-                        parsed.append(("user", line))
+                        parsed.append(("user", line, _legacy))

            # 取最近 max_turns 条 message（按 message 截断，绝不从消息中间切开）
            recent = parsed[-max_turns:] if len(parsed) > max_turns else parsed
            if not recent:
                return ""

-            # 格式化：非 user 侧整条截断（含对方真人），user 完整保留
+            # 格式化：新 raw 直接拼接；旧 raw 按写入同一规则兼容裁剪
            all_messages: List[str] = []
            if user_name:
                from .base import render_user_name_line
@@ -3025,17 +3062,18 @@ class MemoryWriter(WritePipeline):

                _name_line = render_user_name_line(
                    user_name,
-                    is_chinese("\n".join(b for _, b in recent)),
+                    is_chinese("\n".join(b for _, b, _ in recent)),
                )
                if _name_line:
                    all_messages.append(_name_line)
-            for label, body in recent:
+            for label, body, legacy in recent:
+                if legacy:
+                    body = trim_raw_body(
+                        label, body,
+                        assistant_max_chars=max_chars_assistant,
+                        tool_max_bytes=_tool_max_bytes,
+                    )
                body = body.strip()
-                # 截断口径：assistant + 对方真人（非已知 role 的 label）。
-                # user 完整保留；system / tool 沿用历史行为（不截断）。
-                _truncate = label == "assistant" or label not in _KNOWN_ROLES
-                if _truncate and len(body) > max_chars_assistant:
-                    body = body[:max_chars_assistant] + "..."
                all_messages.append(f"[{label}]: {body}")

            return "\n".join(all_messages)
@@ -33,9 +33,28 @@ import threading
 from datetime import datetime
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from typing import Any, Dict, Optional
+from urllib.parse import parse_qs, urlparse
+
+from .retrieval import AmbiguousMemoryIdError

 logger = logging.getLogger("hy_memory.server")

+
+def _namespace_args(values: Dict[str, Any]) -> Dict[str, Any]:
+    """kind / variant from a query string (lists) or a JSON body (scalars).
+
+    They disambiguate an id that exists in more than one namespace (chat,
+    experience, fact; working or coding). Absent means "resolve it".
+    """
+    args: Dict[str, Any] = {}
+    for key in ("kind", "variant"):
+        value = values.get(key)
+        if isinstance(value, list):
+            value = value[0] if value else None
+        if value:
+            args[key] = str(value)
+    return args
+
 # Lazy-init global client
 _client = None
 _client_lock = None
@@ -148,7 +167,6 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
            if path == "/api/v1/metrics":
                minutes = 5
                if "?" in self.path:
-                    from urllib.parse import parse_qs, urlparse
                    qs = parse_qs(urlparse(self.path).query)
                    minutes = int(qs.get("minutes", ["5"])[0])
                client = _get_client()
@@ -161,7 +179,8 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
            if m:
                memory_id = m.group(1)
                client = _get_client()
-                result = client.get(memory_id)
+                query = parse_qs(urlparse(self.path).query)
+                result = client.get(memory_id, **_namespace_args(query))
                if result is None:
                    _json_response(self, 404, {"error": "not_found", "memory_id": memory_id})
                else:
@@ -170,6 +189,10 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):

            _json_response(self, 404, {"error": "not_found", "path": path})

+        except AmbiguousMemoryIdError as e:
+            _json_response(self, 409, {"error": "ambiguous_memory_id", "detail": str(e)})
+        except ValueError as e:
+            _json_response(self, 400, {"error": str(e)})
        except Exception as e:
            logger.error(f"[server] GET {path} error: {e}", exc_info=True)
            _json_response(self, 500, {"error": str(e)})
@@ -213,7 +236,7 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
            _json_response(self, 500, {"error": str(e)})

    def do_PUT(self):
-        path = self.path.rstrip("/")
+        path = self.path.split("?")[0].rstrip("/")
        body = _read_json_body(self)
        if body is None:
            _json_response(self, 400, {"error": "invalid JSON body"})
@@ -228,29 +251,43 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
                    _json_response(self, 400, {"error": "content is required"})
                    return
                client = _get_client()
-                result = client.update(memory_id, content)
+                result = client.update(
+                    memory_id,
+                    content,
+                    **_namespace_args(body),
+                    **({"task": body["task"]} if body.get("task") else {}),
+                )
                _json_response(self, 200, result)
                return

            _json_response(self, 404, {"error": "not_found", "path": path})

+        except AmbiguousMemoryIdError as e:
+            _json_response(self, 409, {"error": "ambiguous_memory_id", "detail": str(e)})
+        except ValueError as e:
+            _json_response(self, 400, {"error": str(e)})
        except Exception as e:
            logger.error(f"[server] PUT {path} error: {e}", exc_info=True)
            _json_response(self, 500, {"error": str(e)})

    def do_DELETE(self):
-        path = self.path.rstrip("/")
+        path = self.path.split("?")[0].rstrip("/")
        try:
            m = re.match(r"^/api/v1/memories/([^/]+)$", path)
            if m:
                memory_id = m.group(1)
                client = _get_client()
-                result = client.delete(memory_id)
+                query = parse_qs(urlparse(self.path).query)
+                result = client.delete(memory_id, **_namespace_args(query))
                _json_response(self, 200, result)
                return

            _json_response(self, 404, {"error": "not_found", "path": path})

+        except AmbiguousMemoryIdError as e:
+            _json_response(self, 409, {"error": "ambiguous_memory_id", "detail": str(e)})
+        except ValueError as e:
+            _json_response(self, 400, {"error": str(e)})
        except Exception as e:
            logger.error(f"[server] DELETE {path} error: {e}", exc_info=True)
            _json_response(self, 500, {"error": str(e)})
@@ -455,7 +492,8 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
            if key in body:
                kwargs[key] = body[key]

-        for key in ("limit", "min_score", "schema_min_score", "schema_limit", "reader"):
+        for key in ("limit", "min_score", "schema_min_score", "schema_limit", "reader",
+                    "rerank"):
            if key in body:
                kwargs[key] = body[key]

@@ -4,6 +4,7 @@ from __future__ import annotations

 import asyncio
 import concurrent.futures
+import contextvars
 import functools
 from concurrent.futures import Executor
 from typing import Any, Callable, Optional
@@ -39,7 +40,9 @@ async def run_in_executor_guarded(

 async def to_thread_guarded(func: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
    """Guarded equivalent of ``asyncio.to_thread`` using the default pool."""
-    return await run_in_executor_guarded(None, func, *args, **kwargs)
+    context = contextvars.copy_context()
+    call = functools.partial(func, *args, **kwargs)
+    return await run_in_executor_guarded(None, context.run, call)


 def concurrent_result_guarded(
@@ -1,6 +1,7 @@
 # -*- coding: utf-8 -*-
 """
-Pipeline Log Writer — 环节级 JSONL 日志（始终开启，与 SQLite Trace 分离）。
+Pipeline Log Writer — 环节级 JSONL 日志（默认开启，MEMORY_PIPELINE_LOG_ENABLED=false 关闭；
+与 SQLite Trace 分离）。

 目录: {log_dir}/{subdir}/{date}.log
 每行: request_id, namespace, user_id, agent_id, step, prompt, content, parsed,
@@ -1,16 +1,20 @@
 # -*- coding: utf-8 -*-
 """
-Pipeline 可观测性：Log（文件 JSONL，始终开启）与 Trace（SQLite pipeline_logs，可关闭）。
+Pipeline 可观测性：Log（文件 JSONL，默认开启，可关闭）与 Trace（SQLite pipeline_logs，可关闭）。

 - Log：运维 tail/grep，每个环节即时一行，不依赖后续步骤成功与否。
 - Trace：Inspector / 调试，落库 pipeline_logs（需 MEMORY_CACHE_BACKEND=sqlite 等持久化后端）。

 环境变量：
+  MEMORY_PIPELINE_LOG_ENABLED    — Log 写 JSONL 文件，默认 true；false 时完全不写
  MEMORY_PIPELINE_TRACE_ENABLED  — Trace 落库，默认 true；OpenClaw C 端可设 false
  MEMORY_MEMORY_OPERATIONS_ENABLED — memory_operations 审计表落库，默认 false
  MEMORY_LOG_DIR                 — Log 目录（优先）
  MEMORY_TRACE_LOG_DIR           — Log 目录（兼容旧名）

+Log 与 Trace 都关闭时不包装 store_pipeline_log，而是换成立即返回 True 的
+空操作：热路径不做任何计时、脱敏或后台任务，也不写库。
+
 子目录（{log_dir}/{subdir}/{date}.log）由 PipelineLogWriter 从每条记录的
 user_id 前缀（第一个 "__" 左侧）切分；无前缀回落 "default"。该前缀是
 通用 namespace，可用于项目、部署或数据分桶。
@@ -94,6 +98,16 @@ def is_pipeline_trace_enabled() -> bool:
    )


+def is_pipeline_log_enabled() -> bool:
+    """是否把 pipeline step 写成 JSONL 文件（{log_dir}/<subdir>/<date>.log）。默认开启。"""
+    return os.getenv("MEMORY_PIPELINE_LOG_ENABLED", "true").strip().lower() in (
+        "true",
+        "1",
+        "yes",
+        "on",
+    )
+
+
 def is_memory_operations_enabled() -> bool:
    """是否将知识库变动写入 memory_operations 审计表。默认关闭（false）。"""
    return os.getenv("MEMORY_MEMORY_OPERATIONS_ENABLED", "false").lower() in (
@@ -125,7 +139,7 @@ def redact_content(value: str) -> str:

 def resolve_pipeline_log_dir() -> str:
    """
-    JSONL pipeline log 根目录（始终使用，有默认值）。
+    JSONL pipeline log 根目录（MEMORY_PIPELINE_LOG_ENABLED 开启时使用，有默认值）。

    优先级: MEMORY_LOG_DIR > MEMORY_TRACE_LOG_DIR > {MEMORY_DATA_DIR}/logs/pipeline
    """
@@ -228,6 +242,7 @@ def wrap_store_pipeline_log(
 ) -> Callable[..., Any]:
    """包装 cache.store_pipeline_log：计时同步、JSONL/DB 异步落盘，不堵主请求。

+    - log_writer 为 None 时不写 JSONL（MEMORY_PIPELINE_LOG_ENABLED=false）
    - step-to-step elapsed_ms / event_at_ms 在调用瞬间打点（与业务墙钟对齐）
    - event_at_ms：调用方传入非 0 值则直接复用（App 已在自己被调用的那一刻
      同步打点，比这里更接近真实事件时刻）；传 0 / 不传才用本地 time.time()
@@ -410,7 +425,8 @@ def wrap_store_pipeline_log(
        try:
            loop = asyncio.get_running_loop()
            # JSONL 用线程池，与 loop 无亲和，留在当前 loop。
-            _track_task(loop.create_task(_persist_jsonl()))
+            if log_writer is not None:
+                _track_task(loop.create_task(_persist_jsonl()))
            # DB trace 用 cache pool（可能 aiomysql，绑定 owner_loop）。若当前不在
            # owner_loop（如 search 走独立 loop），派发回 owner_loop 执行，避免跨 loop。
            if trace_enabled:
@@ -446,25 +462,26 @@ def wrap_store_pipeline_log(
                        )
        except RuntimeError:
            # 无 running loop（极少见）：退化为同步写，保证不丢日志
-            try:
-                log_writer.write_step(
-                    request_id=request_id,
-                    user_id=user_id,
-                    agent_id=agent_id,
-                    session_id=session_id,
-                    step=step,
-                    prompt=prompt,
-                    response=response,
-                    parsed=parsed,
-                    memory_ids=mem_ids,
-                    elapsed_ms=step_elapsed_ms,
-                    prompt_tokens=prompt_tokens,
-                    completion_tokens=completion_tokens,
-                    total_tokens=total_tokens,
-                    event_at_ms=event_at_ms,
-                )
-            except Exception:
-                pass
+            if log_writer is not None:
+                try:
+                    log_writer.write_step(
+                        request_id=request_id,
+                        user_id=user_id,
+                        agent_id=agent_id,
+                        session_id=session_id,
+                        step=step,
+                        prompt=prompt,
+                        response=response,
+                        parsed=parsed,
+                        memory_ids=mem_ids,
+                        elapsed_ms=step_elapsed_ms,
+                        prompt_tokens=prompt_tokens,
+                        completion_tokens=completion_tokens,
+                        total_tokens=total_tokens,
+                        event_at_ms=event_at_ms,
+                    )
+                except Exception:
+                    pass
            if trace_enabled:
                try:
                    result = original_store(
@@ -496,6 +513,11 @@ def wrap_store_pipeline_log(
    return _store_pipeline_observability


+async def _noop_store_pipeline_log(*args: Any, **kwargs: Any) -> bool:
+    """Log 与 Trace 都关闭时的 store_pipeline_log：不计时、不写文件、不写库。"""
+    return True
+
+
 def install_pipeline_observability(
    cache: Any,
    *,
@@ -503,6 +525,9 @@ def install_pipeline_observability(
 ) -> None:
    """给 cache 安装 JSONL + Trace 包装（fire-and-forget）。

+    MEMORY_PIPELINE_LOG_ENABLED=false 时不写 JSONL；若 Trace 也关闭，
+    store_pipeline_log 被换成空操作（不包装、不写库）。
+
    在 cache 所属 loop（write loop / _LoopThread）上调用，本函数会捕获该 loop
    作为 owner_loop 传给包装器：search 走独立 loop 后，从 search loop 触发的 DB
    落库会被派发回这个 owner_loop，避免跨 loop 用 aiomysql 污染连接池。
@@ -514,15 +539,31 @@ def install_pipeline_observability(
    except RuntimeError:
        owner_loop = None

-    log_dir = resolve_pipeline_log_dir()
-    log_writer = PipelineLogWriter(log_dir)
+    log_enabled = is_pipeline_log_enabled()
    trace_enabled = is_pipeline_trace_enabled()
-    logger.info(
-        f"[{log_label}] Pipeline log (JSONL) enabled: {log_dir}/<subdir>/<date>.log "
-        f"(subdir from user_id prefix before '__', else default) ; "
-        f"pipeline trace (DB)={'on' if trace_enabled else 'off'} ; "
-        f"persist=async(fire-and-forget)"
-    )
+    if not log_enabled and not trace_enabled:
+        logger.info(
+            f"[{log_label}] Pipeline log (JSONL) disabled ; pipeline trace (DB)=off ; "
+            f"store_pipeline_log=no-op"
+        )
+        cache.store_pipeline_log = _noop_store_pipeline_log
+        return
+
+    log_writer = None
+    if log_enabled:
+        log_dir = resolve_pipeline_log_dir()
+        log_writer = PipelineLogWriter(log_dir)
+        logger.info(
+            f"[{log_label}] Pipeline log (JSONL) enabled: {log_dir}/<subdir>/<date>.log "
+            f"(subdir from user_id prefix before '__', else default) ; "
+            f"pipeline trace (DB)={'on' if trace_enabled else 'off'} ; "
+            f"persist=async(fire-and-forget)"
+        )
+    else:
+        logger.info(
+            f"[{log_label}] Pipeline log (JSONL) disabled ; "
+            f"pipeline trace (DB)=on ; persist=async(fire-and-forget)"
+        )
    cache.store_pipeline_log = wrap_store_pipeline_log(
        cache.store_pipeline_log,
        log_writer=log_writer,
@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+"""
+原始对话（raw）落库前的统一裁剪规则（规则，零 LLM）。
+
+raw 会被长期保存（MemHub 已取消 raw 的保留期限；lite 模式下 raw 是唯一存储），
+不裁剪会把工具输出、大段粘贴日志原样存下来。因此 raw 在**写入时**就裁好，
+读取方（extractor 的「最近 k 条」历史注入）直接拼接，不再二次裁剪。
+
+规则按说话人标签（ChatMessage.speaker_label() / L1_RAW 里的 ``[label]``）：
+
+- ``user``：完整保留；
+- ``system``：完整保留（与历史注入原口径一致）；
+- ``tool``：头尾保留、中段替换为 ``[...N bytes omitted by truncate...]``，
+  上限为 ``coding.tool_result_max_bytes``（env ``MEMORY_CODING_TOOL_RESULT_MAX_BYTES``，
+  默认 2048），与 coding 链路同一个函数；
+- 其余（``assistant``、对方真人名字等非已知 role 的 label）：strip 后超过
+  ``assistant_max_chars``（默认 500，即历史注入原来的 ``max_chars_assistant``）
+  时截成前 N 个字符 + ``...``。
+
+所有规则确定且幂等：对已裁剪的文本再裁一次结果不变。
+"""
+
+from typing import List, Optional
+
+from ..pipelines.base import ChatMessage
+
+# 历史注入原 `_get_recent_history(max_chars_assistant=500)` 的默认值，现为唯一来源。
+DEFAULT_RAW_ASSISTANT_MAX_CHARS = 500
+
+# L1_RAW 节点 custom 上的标记：内容已按本模块规则在写入时裁剪。
+# 历史拼接据此区分「新 raw 直接拼接」与「本规则之前写入的旧 raw 需兼容裁剪」。
+RAW_TRIMMED_KEY = "raw_trimmed"
+
+# 不裁剪的标签（tool 单独处理）
+_KEEP_LABELS = frozenset({"user", "system"})
+
+
+def trim_raw_body(
+    label: str,
+    body: str,
+    *,
+    assistant_max_chars: int = DEFAULT_RAW_ASSISTANT_MAX_CHARS,
+    tool_max_bytes: Optional[int] = None,
+) -> str:
+    """按说话人标签裁剪单条消息正文。幂等。"""
+    if not isinstance(body, str):
+        body = "" if body is None else str(body)
+    if label in _KEEP_LABELS:
+        return body
+    if label == "tool":
+        from ..coding.preproc import (
+            DEFAULT_MAX_TOOL_RESULT_BYTES,
+            truncate_tool_result_text,
+        )
+
+        return truncate_tool_result_text(
+            body, max_bytes=int(tool_max_bytes or DEFAULT_MAX_TOOL_RESULT_BYTES),
+        )
+    stripped = body.strip()
+    if len(stripped) > assistant_max_chars:
+        return stripped[:assistant_max_chars] + "..."
+    return body
+
+
+def trim_raw_messages(
+    messages: List[ChatMessage],
+    *,
+    assistant_max_chars: int = DEFAULT_RAW_ASSISTANT_MAX_CHARS,
+    tool_max_bytes: Optional[int] = None,
+) -> List[ChatMessage]:
+    """返回裁剪后的新列表；不修改入参（messages 仍要原样给 extractor）。"""
+    out: List[ChatMessage] = []
+    for m in messages:
+        new_content = trim_raw_body(
+            m.speaker_label(),
+            m.content,
+            assistant_max_chars=assistant_max_chars,
+            tool_max_bytes=tool_max_bytes,
+        )
+        if new_content == m.content:
+            out.append(m)
+            continue
+        out.append(ChatMessage(
+            role=m.role,
+            content=new_content,
+            name=m.name,
+            tool_calls=list(m.tool_calls),
+            tool_call_id=m.tool_call_id,
+            tool_name=m.tool_name,
+        ))
+    return out
@@ -36,7 +36,8 @@ def count_tokens(text: str) -> int:
    enc = _get_encoder()
    if enc:
        try:
-            return len(enc.encode(text))
+            # Quoted control-token spellings are ordinary input text.
+            return len(enc.encode(text, disallowed_special=()))
        except Exception as e:
            logger.debug(f"[token_count] encode failed, char fallback: {e}")
    return max(1, len(text) // 4)
@@ -13,8 +13,8 @@
   接口先补 SDK。Runtime writers 停止后的 App 启动迁移可直接操作底层存储，
   但不得把迁移专用方法加入公共 Client。
 3. MemHub **不存 memory 实体**；**可以存 `memory_id`** 做组织/回执。原文进入 **SDK raw**。
-4. SDK raw 只保留滚动三天；一条 raw 对应一个完整 turn，只含真人 user 与
-   assistant，tool 不持久化。提取后的高层 memory 不受该窗口影响。
+4. SDK raw 全部保留，任何模式（lite / pro / ultra）都不删除；一条 raw 对应一个
+   完整 turn，只含真人 user 与 assistant，tool 不持久化。
 5. `source_raw_ids` 是 SDK 内部溯源关系，不是产品 Evidence 合同；记忆详情不提供
   “原始依据”或按 raw ID 展开原文的入口。

@@ -172,6 +172,20 @@ result = client.add_extracted(
 该入口仍走 SDK reconcile/持久化；MemHub 只做管理面门禁与可选
 `memory_id` 记录。

+应用的「添加记忆」、MCP `MemHub_write`（经 broker `POST /memories` 以本机可信身份转发）
+共用同一个本机 HTTP 合同，直接新增一条记忆：
+
+```text
+POST /api/v2/memories                         {request_id, text, scope: "all-apps"}
+GET  /api/v2/memories/additions/{request_id}  # 该次新增的状态
+```
+
+两者返回同一回执（`evidence_id`、`text`、`scope`、`created_at`、`state`、`task_id`、
+`memory_ids`、`error`）。同一 `request_id` 重放返回原回执；内容不同返回 409
+`memory_add_conflict`，未知 `request_id` 返回 404 `memory_add_not_found`。新增走持久
+写入队列的优先通道，最终调用 `add_extracted` + reconcile。带外部读取信封的请求
+一律拒绝（403 `external_endpoint_denied`）。
+
 ## Search：搜索记忆

 ```python
@@ -29,10 +29,12 @@ prompt/response、密钥、访问令牌或完整本地路径。结构化日志
 文件。详细合同见
 [`docs/contracts/diagnostic-logging.md`](docs/contracts/diagnostic-logging.md)。

-用户显式把诊断级别切换为 `debug` 时，Core 会启用 HY pipeline trace，并将
-`MEMORY_LOG_LLM_CONTENT` 设为 `true`。该模式会把完整模型 prompt/response 写入本地调试
-日志，其中可能包含获授权的对话正文和模型输出；它只应用于有意识的故障排查，不应长期
-开启，也不应在未经检查和脱敏时分享相关日志。切回 `info` 会停止后续正文记录，但不会
+HY pipeline 日志与 trace 在任何级别下都关闭。HY SDK 的文本日志只写入
+`hy-memory/governed-v2/logs/hy_memory.log`，其中的 WARNING 及以上同时写入 `core.log`；
+SDK 不在 INFO 及以上级别记录对话或记忆正文。用户显式把诊断级别切换为 `debug` 时，Core 将
+`MEMORY_LOG_LLM_CONTENT` 设为 `true`。该模式会把完整模型 prompt/response 写入
+`hy_memory.log` 的 DEBUG 行，其中可能包含获授权的对话正文和模型输出；它只应用于有意识的
+故障排查，不应长期开启，也不应在未经检查和脱敏时分享相关日志。切回 `info` 会停止后续正文记录，但不会
 自动删除此前已写入的调试文件。

 具体行为以当前源码、网络请求实现和发布说明为准。发现实现与本说明不一致时，请按
@@ -18,13 +18,13 @@ If you run into a problem, please open an Issue with the version, platform,repro

 ## 发行与平台合同

-源码当前固定使用公开 PyPI 正式版 `hy-memory==2.0.5`。MemHub 源码版本为 `1.0.5`
-（build 14），GitHub 仓库为
+源码当前固定使用公开 PyPI 正式版 `hy-memory==2.0.10`。MemHub 源码版本为 `1.0.5`
+（build 36），GitHub 仓库为
 [`Tencent-Hunyuan/Hy-Memory`](https://github.com/Tencent-Hunyuan/Hy-Memory)，npm 包名为
 `memhub-cli`。当前代码架构见
 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。

-`v1.0.5` 的发行目标是 Linux x64/arm64 Runtime 与 macOS arm64/x64 App 和 Runtime。
+`v1.0.5` 的发行目标是 Linux x64/arm64 Runtime 与 macOS arm64 App 和 Runtime。
 Linux 制品由 GitHub Actions 在原生架构 runner 上构建并完成生命周期验收；macOS
 制品由发行流水线完成 Developer ID 签名、公证和验收后手动上传。Windows 不支持。
 只有同时出现在 GitHub Release 与 `release-manifest.json` 中、且通过公开校验的制品才属于
@@ -109,15 +109,16 @@ Node、Host Bridge 或模型。用户显式执行 `memhub install` 后，CLI 才
 Python Core 和运行所需的 Python 依赖位于 MemHub 受管 Runtime，不写入系统 Python。
 MemHub 的 SQLite 数据默认位于 `~/.one-memory`，不在 npm 包或 Runtime 版本目录中。
 `npm uninstall` 只移除 npm CLI；`memhub uninstall` 移除服务、受管 Runtime 和 CLI 链接，
-默认保留 Memory。只有独立的 `memhub delete-data` 在 Runtime 停止且二次确认精确路径后
-才会删除数据。
+默认保留 Memory。只有独立的 `memhub delete-data` 在 Runtime 停止、显式加 `--yes` 并用
+`--confirm <数据目录>` 再写一遍同一个目录后才会删除数据（不加参数只预览要删除的目录）。`memhub stop` 停止受管服务时也会关闭
+登录自动启动，再次 `memhub start` 会恢复。

 当前平台能力和安装边界以源码、CI 与发布说明为准。未完成真机验收的平台不会仅凭跨平台
 测试宣称可用。

 ## Hy Memory

-SDK 依赖固定为公开 PyPI 正式版 `hy-memory==2.0.5`。SDK 配置、权限边界及 search
+SDK 依赖固定为公开 PyPI 正式版 `hy-memory==2.0.10`。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.5",
+      "versionInfo": "2.0.10",
      "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.5
+## hy-memory 2.0.10

 License: Apache-2.0

@@ -30,9 +30,7 @@ const REQUIRED_COMMAND_SURFACE = [
  "sync",
  "memories",
  "profile",
-  "calls",
-  "notes",
-  "graph",
+  "graph-width",
  "models",
  "host",
  "doctor",
@@ -50,19 +48,17 @@ const REQUIRED_COMMAND_SURFACE = [
  "uninstall",
  "delete-data",
  "recall",
-  "setup",
  "scan",
  "progress",
  "jobs",
-  "path",
+  "scan-roots",
  "adapter",
  "write",
-  "task",
  "serve",
 ];

 const REQUIRED_MARKERS = [
-  "backup_restore_confirmation_required",
+  "backup_restore_confirmation_mismatch",
  "backup_restore_runtime_state_unknown",
  "backup_restore_maintenance_identity_invalid",
  "runtime_service_activation_unverified",
@@ -79,16 +75,18 @@ const REQUIRED_MARKERS = [
 * exact literal the catalog usage string contains.
 */
 const REQUIRED_SUBCOMMANDS = [
-  { command: "calls", marker: "memhub calls clear" },
-  { command: "notes", marker: "memhub notes add" },
-  { command: "notes", marker: "memhub notes process" },
+  { command: "memories", marker: "memhub memories add" },
+  { command: "memories", marker: "memhub memories add-status" },
  { command: "memories", marker: "memhub memories update" },
  { command: "memories", marker: "memhub memories delete" },
  { command: "write", marker: "memhub write submit" },
  { command: "write", marker: "memhub write status" },
-  { command: "graph", marker: "memhub graph width" },
+  { command: "graph-width", marker: "memhub graph-width --decision" },
+  { command: "models", marker: "memhub models add" },
+  { command: "models", marker: "memhub models test" },
  { command: "models", marker: "memhub models edit" },
  { command: "models", marker: "memhub models activate" },
+  { command: "sources", marker: "memhub sources connect" },
  { command: "jobs", marker: "memhub jobs start" },
  { command: "jobs", marker: "memhub jobs <pause|resume|cancel>" },
 ];
@@ -100,57 +98,30 @@ const REQUIRED_SUBCOMMANDS = [
 * counterexamples on the packaged Runtime") had no machine-checkable probe.
 * These run without `--lifecycle`, so they are safe against any package.
 */
+const PROFILE_ID = "44444444-4444-4444-8444-444444444444";
 const STOPPED_DESTRUCTIVE_PROBES = [
+  { name: "memories_add", args: ["memories", "add", "synthetic memory"] },
  {
-    name: "calls_clear_preview",
-    args: ["calls", "clear", "--event", "11111111-1111-4111-8111-111111111111"],
-  },
-  {
-    name: "calls_clear_apply",
-    args: [
-      "calls",
-      "clear",
-      "--event",
-      "11111111-1111-4111-8111-111111111111",
-      "--confirm",
-    ],
-  },
-  {
-    name: "calls_clear_all_apply",
-    args: ["calls", "clear", "--all", "--confirm"],
-  },
-  {
-    name: "notes_process_apply",
-    args: [
-      "notes",
-      "process",
-      "33333333-3333-4333-8333-333333333333",
-      "--confirm",
-    ],
+    name: "memories_delete_apply",
+    args: ["memories", "delete", "m-1", "--yes"],
  },
  {
    name: "graph_width_apply",
-    args: ["graph", "width", "--decision", "keep_existing", "--confirm"],
+    args: ["graph-width", "--decision", "keep_existing"],
  },
  {
-    name: "models_activate_apply",
-    args: [
-      "models",
-      "activate",
-      "44444444-4444-4444-8444-444444444444",
-      "--confirm",
-    ],
+    name: "graph_width_rebuild_apply",
+    args: ["graph-width", "--decision", "rebuild_with_new", "--yes"],
+  },
+  { name: "models_activate_apply", args: ["models", "activate", PROFILE_ID] },
+  { name: "models_test", args: ["models", "test", PROFILE_ID] },
+  {
+    name: "models_remove_apply",
+    args: ["models", "remove", PROFILE_ID, "--yes"],
  },
  {
-    name: "models_edit_apply",
-    args: [
-      "models",
-      "edit",
-      "44444444-4444-4444-8444-444444444444",
-      "--config-file",
-      "/nonexistent/patch.json",
-      "--confirm",
-    ],
+    name: "sources_connect_import",
+    args: ["sources", "connect", "codex", "--import"],
  },
 ];

@@ -119,6 +119,7 @@ describe("A19 batch execution", () => {
      readerFor([]),
      operations,
      planned.notFound,
+      { confirmOverrides: false },
    );
    // Exactly one request for two sources — the batch endpoint, per contract.
    expect(post).toHaveBeenCalledTimes(1);
@@ -165,6 +166,7 @@ describe("A19 batch execution", () => {
      readerFor([]),
      operations,
      planned.notFound,
+      { confirmOverrides: false },
    );
    expect(document.state).toBe("partial");
    const byId = Object.fromEntries(
@@ -206,6 +208,7 @@ describe("A19 batch execution", () => {
      readerFor([]),
      operations,
      [],
+      { confirmOverrides: false },
    );
    expect(document.sources.every((row) => row.status === "failed")).toBe(true);
    expect(
@@ -249,6 +252,7 @@ describe("A19 batch execution", () => {
      readerFor([]),
      operations,
      [],
+      { confirmOverrides: false },
    );
    const busy = document.sources.find((row) => row.source_id === "cursor");
    expect(document.state).toBe("partial");
@@ -288,6 +292,7 @@ describe("A19 batch execution", () => {
      readerFor([]),
      operations,
      planned.notFound,
+      { confirmOverrides: false },
    );
    const notFoundRow = document.sources.find(
      (row) => row.source_id === "cursor",
@@ -296,3 +301,82 @@ describe("A19 batch execution", () => {
    expect(document.not_found_source_ids).toContain("cursor");
  });
 });
+
+describe("environment-override sources need --confirm-overrides", () => {
+  it("leaves them out and names them unless confirmed", async () => {
+    const planned = await planBatchImport(
+      readerFor([
+        found("codex"),
+        found("dsh", {
+          candidate_kind: "environment_override",
+          requires_override_confirmation: true,
+        }),
+      ]),
+    );
+    if (planned.state !== "preview") throw new Error("expected preview");
+    const post = vi.fn(
+      async (_path: string, body: Record<string, unknown>) => ({
+        state: "committed" as const,
+        data: {
+          request_id: body.request_id,
+          accepted_source_ids: body.source_ids,
+          failed_sources: {},
+          jobs: [],
+        },
+      }),
+    );
+    const operations = { post } as unknown as CoreOperations;
+    const skipped = await executeBatchImport(
+      planned.candidates,
+      readerFor([]),
+      operations,
+      planned.notFound,
+      { confirmOverrides: false },
+    );
+    expect(post.mock.calls[0]![1]).toMatchObject({
+      source_ids: ["codex"],
+      confirm_environment_overrides: false,
+    });
+    expect(skipped.override_required_source_ids).toEqual(["dsh"]);
+    expect(renderBatchScanText(skipped)).toContain("--confirm-overrides");
+
+    const confirmed = await executeBatchImport(
+      planned.candidates,
+      readerFor([]),
+      operations,
+      planned.notFound,
+      { confirmOverrides: true },
+    );
+    expect(post.mock.calls[1]![1]).toMatchObject({
+      source_ids: ["codex", "dsh"],
+      confirm_environment_overrides: true,
+    });
+    expect(confirmed.override_required_source_ids).toBeUndefined();
+  });
+
+  it("refuses without a request when every detected source needs confirmation", async () => {
+    const planned = await planBatchImport(
+      readerFor([
+        found("dsh", {
+          candidate_kind: "environment_override",
+          requires_override_confirmation: true,
+        }),
+      ]),
+    );
+    if (planned.state !== "preview") throw new Error("expected preview");
+    const post = vi.fn();
+    const document = await executeBatchImport(
+      planned.candidates,
+      readerFor([]),
+      { post } as unknown as CoreOperations,
+      planned.notFound,
+      { confirmOverrides: false },
+    );
+    expect(post).not.toHaveBeenCalled();
+    expect(document).toMatchObject({
+      state: "rejected",
+      code: "environment_override_confirmation_required",
+    });
+    expect(batchScanExitCode(document)).toBe(1);
+  });
+});
@@ -1,4 +1,5 @@
-/** A19: one-shot scan/import of every *detected* source.
+/** A19: one-shot connect/import of every *detected* source
+ * (`sources connect --all-detected --import`).
 *
 * The engine already takes many sources in a single `POST /api/v1/sources/connect`
 * (`source_ids` is a 1..32 tuple) and answers per source. The CLI used to reject
@@ -37,13 +38,16 @@ export interface BatchSourceRow {
 export interface BatchScanDocument {
  schema_version: 1;
  product: string;
-  command: "scan" | "init";
+  command: "sources connect";
  state: "committed" | "partial" | "rejected" | "unknown" | "no_sources";
  request_id: string | null;
  accepted_source_ids: string[];
  sources: BatchSourceRow[];
  /** `location_state != found` rows are listed so the user can see what was skipped. */
  not_found_source_ids: string[];
+  /** Detected sources whose location comes from an environment override and
+   * that were left out because `--confirm-overrides` was not given. */
+  override_required_source_ids?: string[];
  code?: string;
 }

@@ -118,12 +122,39 @@ export async function planBatchImport(reader: CoreReader): Promise<

 /** Run the batch connect once and fold the per-source receipt into rows. */
 export async function executeBatchImport(
-  candidates: readonly SourceConnectionCandidate[],
+  detected: readonly SourceConnectionCandidate[],
  reader: CoreReader,
  operations: CoreOperations,
  notFound: readonly string[],
+  options: { confirmOverrides: boolean },
 ): Promise<BatchScanDocument> {
  const requestId = randomUUID();
+  // An environment-override location is a choice the user has to confirm:
+  // without `--confirm-overrides` those sources are left out and named.
+  const skipped = options.confirmOverrides
+    ? []
+    : detected
+        .filter((candidate) => candidate.requires_override_confirmation)
+        .map((candidate) => candidate.source_id);
+  const overrideFields =
+    skipped.length > 0 ? { override_required_source_ids: skipped } : {};
+  const candidates = detected.filter(
+    (candidate) => !skipped.includes(candidate.source_id),
+  );
+  if (candidates.length === 0) {
+    return {
+      schema_version: 1,
+      product: PRODUCT,
+      command: "sources connect",
+      state: "rejected",
+      request_id: null,
+      accepted_source_ids: [],
+      sources: [],
+      not_found_source_ids: [...notFound],
+      ...overrideFields,
+      code: "environment_override_confirmation_required",
+    };
+  }
  // Same shared builder as the single-source import and the Web console, so a
  // batch connect cannot drift from either.
  const request = buildSourceImportRequest({
@@ -141,9 +172,9 @@ export async function executeBatchImport(
          : [[candidate.source_id, candidate.candidate_revision]],
      ),
    ),
-    confirmEnvironmentOverrides: candidates.some(
-      (candidate) => candidate.requires_override_confirmation,
-    ),
+    confirmEnvironmentOverrides:
+      options.confirmOverrides &&
+      candidates.some((candidate) => candidate.requires_override_confirmation),
    fullRescan: false,
    onboarding: true,
    enableSync: true,
@@ -154,7 +185,7 @@ export async function executeBatchImport(
    return {
      schema_version: 1,
      product: PRODUCT,
-      command: "scan",
+      command: "sources connect",
      state: result.state,
      request_id: requestId,
      accepted_source_ids: [],
@@ -168,6 +199,7 @@ export async function executeBatchImport(
        failure_reason: result.code,
      })),
      not_found_source_ids: [...notFound],
+      ...overrideFields,
      code: result.code,
    };
  }
@@ -254,7 +286,7 @@ export async function executeBatchImport(
  return {
    schema_version: 1,
    product: PRODUCT,
-    command: "scan",
+    command: "sources connect",
    state:
      failedCount === 0
        ? "committed"
@@ -270,6 +302,7 @@ export async function executeBatchImport(
    accepted_source_ids: accepted,
    sources: rows,
    not_found_source_ids: [...notFound],
+    ...overrideFields,
  };
 }

@@ -301,5 +334,10 @@ export function renderBatchScanText(document: BatchScanDocument): string {
      : document.state === "partial"
        ? `部分完成：${document.accepted_source_ids.length} 个成功，其余见上方`
        : `未完成：${document.code ?? "unknown"}`;
-  return `${summary}\n${lines.join("\n")}\n`;
+  const overrides = document.override_required_source_ids ?? [];
+  const hint =
+    overrides.length > 0
+      ? `\n未接入（目录来自环境变量覆盖，需确认）：${overrides.join("、")}\n确认目录无误后加 --confirm-overrides 重新运行。`
+      : "";
+  return `${summary}\n${lines.join("\n")}${hint}\n`;
 }
@@ -0,0 +1,373 @@
+// Contract fixes from the CLI review: exit codes, where JSON goes, the global
+// `--data-dir`, and the write idempotency key.
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { run } from "./cli.js";
+import { COMMANDS } from "./command-catalog.js";
+
+const transport = vi.hoisted(() => ({
+  get: vi.fn(),
+  post: vi.fn(),
+  put: vi.fn(),
+  patch: vi.fn(),
+  delete: vi.fn(),
+  request: vi.fn(),
+}));
+vi.mock("axios", () => ({
+  default: {
+    create: vi.fn(() => transport),
+    get: transport.get,
+    post: transport.post,
+    request: transport.request,
+    isAxiosError: () => false,
+  },
+}));
+
+const runtime = vi.hoisted(() => ({
+  inspectRuntimeStatus: vi.fn(),
+  discoverRuntimeAttachment: vi.fn(),
+  inspectBackgroundHealth: vi.fn(),
+}));
+vi.mock("@one-memory/runtime-control", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@one-memory/runtime-control")>()),
+  ...runtime,
+}));
+
+const ATTACHED = {
+  instanceId: "instance-1",
+  apiToken: "synthetic-runtime-token",
+  host: "127.0.0.1",
+  port: 8765,
+  servicePid: 4242,
+  health: {
+    status: "ok",
+    service: "one-memory-core",
+    version: "1.2.3",
+    instance_id: "instance-1",
+  },
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  for (const method of Object.values(transport)) method.mockReset();
+  runtime.inspectRuntimeStatus.mockResolvedValue({
+    state: "running",
+    code: "runtime_verified",
+    instanceId: "instance-1",
+    host: "127.0.0.1",
+    port: 8765,
+    version: "1.2.3",
+  });
+  runtime.discoverRuntimeAttachment.mockResolvedValue(ATTACHED);
+  runtime.inspectBackgroundHealth.mockResolvedValue(null);
+});
+
+describe("--data-dir is a global option", () => {
+  it("points a Runtime-attached command at that data directory", async () => {
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: { request_id: "r", profile: null, elapsed_ms: 1 },
+    });
+    const result = await capturedRun(
+      ["profile", "--data-dir", "/synthetic/other", "--json"],
+      { ONE_MEMORY_DATA_DIR: "/synthetic/default" },
+    );
+    expect(result.code).toBe(0);
+    expect(runtime.inspectRuntimeStatus).toHaveBeenCalledWith(
+      expect.objectContaining({ dataDir: "/synthetic/other" }),
+    );
+  });
+
+  it("is accepted by every command the catalog used to advertise it on", async () => {
+    runtime.inspectRuntimeStatus.mockResolvedValue({
+      state: "stopped",
+      code: "runtime_not_running",
+    });
+    runtime.discoverRuntimeAttachment.mockResolvedValue(null);
+    for (const argv of [
+      ["profile"],
+      ["scan-roots", "list"],
+      ["adapter", "list"],
+      ["scan", "--source", "codex"],
+      ["write", "status", "r-1"],
+      ["backup", "create", "--target", "/synthetic/data/backups/a"],
+      ["memories", "list"],
+    ]) {
+      const result = await capturedRun([
+        ...argv,
+        "--data-dir",
+        "/synthetic/other",
+        "--json",
+      ]);
+      expect(result.code, argv.join(" ")).toBe(3);
+    }
+  });
+
+  it("refuses a relative or repeated --data-dir", async () => {
+    for (const argv of [
+      ["profile", "--data-dir", "relative"],
+      ["profile", "--data-dir", "/a", "--data-dir", "/b"],
+      ["profile", "--data-dir"],
+    ]) {
+      expect((await capturedRun(argv)).code).toBe(2);
+    }
+    expect(runtime.inspectRuntimeStatus).not.toHaveBeenCalled();
+  });
+});
+
+describe("Core failures are exit 1, not usage errors", () => {
+  it("adapter probe reports a Core refusal with its code on stdout", async () => {
+    transport.request.mockResolvedValue({
+      status: 409,
+      data: { detail: "source_not_authorized" },
+    });
+    const result = await capturedRun([
+      "adapter",
+      "probe",
+      "--source",
+      "codex",
+      "--json",
+    ]);
+    expect(result.code).toBe(1);
+    expect(result.stderr).toBe("");
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      command: "adapter probe",
+      state: "failed",
+      code: "source_not_authorized",
+      exit_code: 1,
+    });
+  });
+
+  it("adapter probe prints readable text without --json", async () => {
+    transport.request.mockResolvedValue({
+      status: 200,
+      data: { source: "codex", available: true },
+    });
+    const result = await capturedRun(["adapter", "probe", "--source", "codex"]);
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain("来源 codex 的探测结果");
+    expect(result.stdout).toContain("available: true");
+  });
+
+  it("scan-roots add posts directly and reports a refusal as exit 1", async () => {
+    transport.request.mockResolvedValue({
+      status: 409,
+      data: { detail: "scan_root_conflict" },
+    });
+    const result = await capturedRun([
+      "scan-roots",
+      "add",
+      "--root",
+      "/synthetic/root",
+      "--source",
+      "codex",
+      "--json",
+    ]);
+    expect(result.code).toBe(1);
+    expect(transport.request).toHaveBeenCalledWith(
+      expect.objectContaining({
+        method: "post",
+        url: "http://127.0.0.1:8765/api/v1/scan-roots",
+        data: { root: "/synthetic/root", source: "codex", recursive: true },
+      }),
+    );
+    expect(JSON.parse(result.stdout).code).toBe("scan_root_conflict");
+  });
+
+  it("the old `path add` spelling still works", async () => {
+    transport.request.mockResolvedValue({ status: 200, data: { ok: true } });
+    const result = await capturedRun([
+      "path",
+      "remove",
+      "--root",
+      "/synthetic/root",
+      "--yes",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.request.mock.calls[0][0]).toMatchObject({
+      method: "delete",
+      data: { root: "/synthetic/root" },
+    });
+  });
+
+  it("scan --source runs directly", async () => {
+    transport.post.mockResolvedValue({
+      status: 200,
+      data: { job_id: "j1", source_id: "codex", status: "pending" },
+    });
+    const result = await capturedRun(["scan", "--source", "codex", "--json"]);
+    expect(result.code).toBe(0);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      command: "scan",
+      state: "committed",
+      scan: { job_id: "j1" },
+    });
+    // A scan without a source is a usage error, not a preview.
+    expect((await capturedRun(["scan"])).code).toBe(2);
+  });
+});
+
+describe("write submit keeps its idempotency key", () => {
+  async function messagesFile(): Promise<string> {
+    const directory = await mkdtemp(path.join(tmpdir(), "memhub-write-"));
+    const file = path.join(directory, "messages.json");
+    await writeFile(file, JSON.stringify([{ role: "user", content: "hi" }]));
+    return file;
+  }
+
+  it("generates a request id, sends it and prints it with a retry hint", async () => {
+    transport.post.mockImplementation(
+      async (_url: string, body: { request_id: string }) => ({
+        status: 200,
+        data: {
+          request_id: body.request_id,
+          state: "accepted",
+          created_at: "T",
+          updated_at: "T",
+        },
+      }),
+    );
+    const result = await capturedRun([
+      "write",
+      "submit",
+      "--session",
+      "s1",
+      "--messages-file",
+      await messagesFile(),
+    ]);
+    expect(result.code).toBe(0);
+    const sent = transport.post.mock.calls[0][1].request_id as string;
+    expect(sent).toMatch(/^[0-9a-f-]{36}$/);
+    expect(result.stdout).toContain(`request_id: ${sent}`);
+    expect(result.stdout).toContain(`--request-id ${sent}`);
+  });
+
+  it("reports a 409 conflict as JSON on stdout with the request id", async () => {
+    transport.post.mockResolvedValue({
+      status: 409,
+      data: { detail: "memory_write_conflict" },
+    });
+    const result = await capturedRun([
+      "write",
+      "submit",
+      "--session",
+      "s1",
+      "--messages-file",
+      await messagesFile(),
+      "--request-id",
+      "req-1",
+      "--json",
+    ]);
+    expect(result.code).toBe(1);
+    expect(result.stderr).toBe("");
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      command: "write submit",
+      state: "rejected",
+      request_id: "req-1",
+      code: "memory_write_conflict",
+    });
+  });
+
+  it("write status of an unknown id is exit 1 with state not_found", async () => {
+    transport.get.mockResolvedValue({ status: 404, data: {} });
+    const error = Object.assign(new Error("404"), {
+      response: { status: 404 },
+    });
+    transport.get.mockRejectedValue(error);
+    const result = await capturedRun(["task", "--id", "nope", "--json"]);
+    // `axios.isAxiosError` is mocked false, so the read error surfaces as a
+    // failed read; either way it is exit 1, never a silent exit 0.
+    expect(result.code).toBe(1);
+  });
+});
+
+describe("doctor and ui use exit 3 for a stopped Runtime", () => {
+  it("doctor exits 3 when the Runtime is stopped", async () => {
+    runtime.inspectRuntimeStatus.mockResolvedValue({
+      state: "stopped",
+      code: "runtime_not_running",
+    });
+    const result = await capturedRun(["doctor", "--json"]);
+    expect(result.code).toBe(3);
+    expect(JSON.parse(result.stdout).schema_version).toBe(1);
+  });
+});
+
+describe("catalog exit codes", () => {
+  it("lists exit 2 for every command, since every parser can reject", () => {
+    for (const command of COMMANDS) {
+      expect(command.exit_codes, command.name).toContain(2);
+    }
+  });
+
+  it("lists exit 3 for every command that attaches to the Runtime", () => {
+    for (const name of [
+      "status",
+      "doctor",
+      "init",
+      "sources",
+      "sync",
+      "progress",
+      "jobs",
+      "models",
+      "memories",
+      "profile",
+      "settings",
+      "evolve",
+      "graph-width",
+      "host",
+      "recall",
+      "scan-roots",
+      "adapter",
+      "scan",
+      "write",
+      "backup",
+      "ui",
+      "onboarding",
+    ]) {
+      const command = COMMANDS.find((entry) => entry.name === name);
+      expect(command?.exit_codes, name).toContain(3);
+    }
+  });
+
+  it("does not claim exit 3 or 4 for lifecycle commands that never return them", () => {
+    for (const name of ["start", "stop", "restart"]) {
+      const command = COMMANDS.find((entry) => entry.name === name);
+      expect(command?.exit_codes).toEqual([0, 1, 2]);
+    }
+  });
+
+  it("says stop turns login auto-start off for a managed service", () => {
+    const stop = COMMANDS.find((entry) => entry.name === "stop");
+    expect(stop?.summary).toContain("登录时也不会自动启动");
+  });
+});
+
+async function capturedRun(
+  arguments_: string[],
+  environment: NodeJS.ProcessEnv = { ONE_MEMORY_DATA_DIR: "/synthetic/data" },
+) {
+  let stdout = "";
+  let stderr = "";
+  const stdoutSpy = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation((chunk) => {
+      stdout += String(chunk);
+      return true;
+    });
+  const stderrSpy = vi
+    .spyOn(process.stderr, "write")
+    .mockImplementation((chunk) => {
+      stderr += String(chunk);
+      return true;
+    });
+  try {
+    return { code: await run(arguments_, environment), stdout, stderr };
+  } finally {
+    stdoutSpy.mockRestore();
+    stderrSpy.mockRestore();
+  }
+}
@@ -162,10 +162,54 @@ it("never emits a secret from a malformed manually written event", async () => {
    command: "logs",
    state: "empty",
    events: 0,
-    invalid_lines: 1,
+    invalid_lines: 0,
+    unrecognized_lines: 1,
  });
 });

+// After an upgrade the files still hold an older build's records. They are
+// whole JSON lines the reader leaves out, not damage, so the text output must
+// not warn about them; only a line that is not JSON is called damaged.
+it("warns only about lines that are not JSON, not about older records", async () => {
+  const dataDir = await fixture();
+  const older = {
+    schema_version: 0,
+    service: "desktop",
+    component: "desktop.lifecycle",
+    event: "desktop.started",
+  };
+  await writeFile(
+    path.join(dataDir, "logs", "diagnostic-desktop.jsonl"),
+    `${JSON.stringify(older)}\n${JSON.stringify({ ...older, schema_version: 1 })}\n`,
+    { mode: 0o600 },
+  );
+  let stdout = "";
+  let stderr = "";
+  vi.spyOn(process.stdout, "write").mockImplementation((value) => {
+    stdout += String(value);
+    return true;
+  });
+  vi.spyOn(process.stderr, "write").mockImplementation((value) => {
+    stderr += String(value);
+    return true;
+  });
+
+  expect(await run(["logs"], { ONE_MEMORY_DATA_DIR: dataDir })).toBe(0);
+  expect(stdout).toContain("core.start_failed");
+  expect(stdout).not.toContain("损坏");
+  expect(stderr).toBe("");
+
+  await writeFile(
+    path.join(dataDir, "logs", "diagnostic-cli.jsonl"),
+    '{"schema_version": 1, "event": \n',
+    { mode: 0o600 },
+  );
+  stdout = "";
+  expect(await run(["logs"], { ONE_MEMORY_DATA_DIR: dataDir })).toBe(0);
+  expect(stdout).toContain("跳过 1 行损坏的诊断记录。");
+  expect(stderr).toBe("memhub: 跳过 1 行损坏的诊断记录。\n");
+});
+
 it("rejects invalid filters without touching the log directory", async () => {
  const dataDir = path.join(
    await mkdtemp(path.join(os.tmpdir(), "om-cli-no-log-")),
@@ -1,8 +1,16 @@
-import { mkdtemp, readdir, readFile, realpath, rm } from "node:fs/promises";
+import {
+  mkdir,
+  mkdtemp,
+  readdir,
+  readFile,
+  realpath,
+  rm,
+} from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import {
  claimRuntimeServiceForApp,
+  clearSdkMigrationBlock,
  readRuntimeServiceOwner,
  recordSdkMigrationBlock,
  resolveRuntimeCliConfig,
@@ -922,6 +930,38 @@ describe("public One Memory CLI", () => {
      target_path: "/tmp/install/current/bin/one-memory",
    };

+    it("says the data was restored when a failed migration put it back", async () => {
+      vi.clearAllMocks();
+      runtimeMocks.planCliLink.mockResolvedValueOnce(presentCliLink);
+      runtimeMocks.runSdkMigration.mockResolvedValueOnce({
+        state: "deferred",
+        code: "sdk_migration_memory_unreadable",
+        dataRestored: true,
+      } as never);
+      const streams = captureStreams();
+      let code: number;
+      try {
+        code = await run(
+          upgradeArguments,
+          {},
+          { waitForRuntimeReady: async () => true },
+        );
+      } finally {
+        streams.restore();
+      }
+      expect(code!).toBe(1);
+      const failure = JSON.parse(streams.stderr());
+      expect(failure).toMatchObject({
+        code: "sdk_migration_memory_unreadable",
+        data_restored: true,
+        log_file: "/tmp/custom data/logs/sdk-migration.log",
+      });
+      expect(failure.message).toContain("记忆数据已恢复到升级前的状态。");
+      expect(failure.message).toContain(
+        "/tmp/custom data/logs/sdk-migration.log",
+      );
+    });
+
    it("migrates the home with the new Core before restarting the Runtime", async () => {
      vi.clearAllMocks();
      runtimeMocks.planCliLink.mockResolvedValueOnce(presentCliLink);
@@ -1971,16 +2011,11 @@ describe("stopped Runtime is exit 3, not a usage error", () => {
    ["path", "list", "--json"],
    ["adapter", "list", "--json"],
    ["task", "--id", "nope", "--json"],
-    [
-      "write",
-      "submit",
-      "--session",
-      "s",
-      "--messages-file",
-      "/tmp/messages.json",
-      "--json",
-    ],
-    ["backup", "create", "--target", "/tmp/x", "--yes", "--json"],
+    ["write", "status", "nope", "--json"],
+    ["backup", "create", "--target", "/tmp/x", "--json"],
+    ["scan-roots", "add", "--root", "/tmp/x", "--json"],
+    ["scan", "--source", "codex", "--json"],
+    ["onboarding", "reset", "--json"],
  ])("%s ... --json exits 3 with runtime_not_running", async (...argv) => {
    const streams = captureStreams();
    let code: number;
@@ -1990,7 +2025,9 @@ describe("stopped Runtime is exit 3, not a usage error", () => {
      streams.restore();
    }
    expect(code!).toBe(3);
-    const document = JSON.parse(streams.stderr());
+    // A result, not an error: on stdout like every other --json document.
+    expect(streams.stderr()).toBe("");
+    const document = JSON.parse(streams.stdout());
    expect(document).toMatchObject({
      code: "runtime_not_running",
      exit_code: 3,
@@ -1999,6 +2036,48 @@ describe("stopped Runtime is exit 3, not a usage error", () => {
    expect(document.status).not.toBe("usage_error");
  });

+  it("write submit validates its messages file before attaching, then exits 3", async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), "memhub-write-"));
+    const file = path.join(directory, "messages.json");
+    await import("node:fs/promises").then(({ writeFile }) =>
+      writeFile(file, JSON.stringify([{ role: "user", content: "hi" }])),
+    );
+    const streams = captureStreams();
+    let missing: number;
+    let code: number;
+    try {
+      missing = await run(
+        [
+          "write",
+          "submit",
+          "--session",
+          "s",
+          "--messages-file",
+          path.join(directory, "absent.json"),
+          "--json",
+        ],
+        {},
+      );
+      code = await run(
+        [
+          "write",
+          "submit",
+          "--session",
+          "s",
+          "--messages-file",
+          file,
+          "--json",
+        ],
+        {},
+      );
+    } finally {
+      streams.restore();
+      await rm(directory, { recursive: true, force: true });
+    }
+    expect(missing!).toBe(2);
+    expect(code!).toBe(3);
+  });
+
  it.each(["pause", "resume"] as const)(
    "parses sync %s as the direct sync-set command",
    async (action) => {
@@ -2134,6 +2213,94 @@ describe("lifecycle commands report a migration block", () => {
    expect(output.value()).not.toContain("runtime_not_ready_within_budget");
  });

+  it("restart on a frozen home retries the migration in the foreground first", async () => {
+    const dataDir = await mkdtemp(path.join(tmpdir(), "memhub-frozen-"));
+    await recordSdkMigrationBlock(
+      dataDir,
+      "sdk_migration_memory_unreadable",
+      "desktop",
+      { frozen: { service_was_enabled: true }, data_restored: true },
+    );
+    const controls = {
+      ...blockedControls(),
+      migrateSdkData: vi.fn(async () => ({
+        state: "deferred" as const,
+        code: "sdk_migration_memory_unreadable",
+        dataRestored: true,
+      })),
+    };
+    const output = captureStdout();
+    let code: number;
+    try {
+      code = await run(
+        ["restart", "--json"],
+        { ONE_MEMORY_DATA_DIR: dataDir },
+        controls,
+      );
+    } finally {
+      output.restore();
+      await rm(dataDir, { recursive: true, force: true });
+    }
+    expect(code!).toBe(1);
+    expect(controls.migrateSdkData).toHaveBeenCalledWith(
+      expect.objectContaining({ dataDir, caller: "cli-restart" }),
+    );
+    // Still frozen: the service is not started to retry on its own.
+    expect(controls.restartManagedRuntime).not.toHaveBeenCalled();
+    expect(controls.ensureRuntime).not.toHaveBeenCalled();
+    expect(JSON.parse(output.value())).toMatchObject({
+      command: "restart",
+      state: "blocked",
+      code: "sdk_migration_memory_unreadable",
+      data_restored: true,
+    });
+  });
+
+  it("restart on a frozen home restarts the Runtime once the retry succeeds", async () => {
+    const dataDir = await mkdtemp(path.join(tmpdir(), "memhub-frozen-"));
+    await recordSdkMigrationBlock(
+      dataDir,
+      "sdk_migration_memory_unreadable",
+      "desktop",
+      { frozen: { service_was_enabled: false } },
+    );
+    const order: string[] = [];
+    const migrateSdkData = vi.fn(async () => {
+      order.push("migrate");
+      await clearSdkMigrationBlock(dataDir);
+      return { state: "cutover" as const };
+    });
+    const output = captureStreams();
+    let code: number;
+    try {
+      code = await run(
+        ["restart", "--json"],
+        { ONE_MEMORY_DATA_DIR: dataDir },
+        {
+          migrateSdkData,
+          waitForRuntimeReady: vi.fn(async () => true),
+          restartManagedRuntime: vi.fn(async () => {
+            order.push("restart");
+            return "restarted" as const;
+          }),
+          stopRuntime: vi.fn(async () => "stopped" as const),
+          ensureRuntime: vi.fn(async () => {
+            order.push("restart");
+            return { pid: 1 } as never;
+          }),
+        },
+      );
+    } finally {
+      output.restore();
+      await rm(dataDir, { recursive: true, force: true });
+    }
+    expect(code!).toBe(0);
+    expect(migrateSdkData).toHaveBeenCalledWith(
+      expect.objectContaining({ caller: "cli-restart" }),
+    );
+    expect(order).toEqual(["migrate", "restart"]);
+  });
+
  it("restart in text mode names the log file and GitHub issues", async () => {
    const dataDir = await blockedHome();
    const output = captureStdout();
@@ -2583,7 +2750,8 @@ describe("ui wires the Core session contract without token leakage", () => {
    } finally {
      output.restore();
    }
-    expect(code!).toBe(4);
+    // A stopped Runtime is exit 3, like every other command.
+    expect(code!).toBe(3);
    const document = JSON.parse(output.value());
    expect(document).toMatchObject({
      schema_version: 1,
@@ -2612,6 +2780,120 @@ describe("ui wires the Core session contract without token leakage", () => {
 // refuse while the Runtime owns the data dir, stop+call Core from a
 // maintenance process, and never report success from a malformed response.
 describe("backup restore drives the Core managed-restore contract", () => {
+  it("previews without --yes, exits 0 and starts nothing", async () => {
+    const maintenance = vi.fn();
+    const output = captureStdout();
+    let code: number;
+    try {
+      code = await run(
+        ["backup", "restore", "--source", "/tmp/x", "--json"],
+        {},
+        { runMaintenanceRestore: maintenance },
+      );
+    } finally {
+      output.restore();
+    }
+    expect(code!).toBe(0);
+    expect(maintenance).not.toHaveBeenCalled();
+    expect(JSON.parse(output.value())).toMatchObject({
+      command: "backup restore",
+      state: "preview",
+      target: "/tmp/x",
+      applied: false,
+      next_step: "memhub backup restore --source /tmp/x --yes --confirm /tmp/x",
+    });
+  });
+
+  it("deletes data only when --confirm repeats the data directory", async () => {
+    const home = await mkdtemp(path.join(tmpdir(), "memhub-delete-home-"));
+    const dataDir = path.join(home, ".one-memory");
+    await mkdir(path.join(dataDir, "logs"), { recursive: true });
+    const deleteData = async (...extra: string[]) => {
+      const output = captureStdout();
+      try {
+        const code = await run(
+          ["delete-data", "--data-dir", dataDir, ...extra, "--json"],
+          { HOME: home },
+        );
+        return { code, document: JSON.parse(output.value()) };
+      } finally {
+        output.restore();
+      }
+    };
+    try {
+      const refused = await deleteData("--yes");
+      expect(refused.code).toBe(4);
+      expect(refused.document).toMatchObject({
+        state: "blocked",
+        code: "data_deletion_confirmation_required",
+      });
+      expect(await readdir(dataDir)).toEqual(["logs"]);
+
+      const deleted = await deleteData("--yes", "--confirm", dataDir);
+      expect(deleted.code).toBe(0);
+      expect(await readdir(dataDir).catch(() => [])).toEqual([]);
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
+  it("refuses --yes without repeating the backup path", async () => {
+    const maintenance = vi.fn();
+    const output = captureStdout();
+    let code: number;
+    try {
+      code = await run(
+        ["backup", "restore", "--source", "/tmp/x", "--yes", "--json"],
+        {},
+        { runMaintenanceRestore: maintenance },
+      );
+    } finally {
+      output.restore();
+    }
+    expect(code!).toBe(4);
+    expect(maintenance).not.toHaveBeenCalled();
+    expect(JSON.parse(output.value())).toMatchObject({
+      state: "rejected",
+      code: "backup_restore_confirmation_required",
+      next_step:
+        "恢复需要再写一遍备份路径：memhub backup restore --source /tmp/x --yes --confirm /tmp/x",
+    });
+  });
+
+  it("restores with --yes and the repeated backup path", async () => {
+    const maintenance = vi.fn(async () => ({
+      state: "restored" as const,
+      result: {
+        state: "restored" as const,
+        restoredBytes: 1,
+        previousBackupPath: "/tmp/pre.sqlite3",
+        sourceSchemaVersion: 34,
+      },
+    }));
+    const output = captureStdout();
+    let code: number;
+    try {
+      code = await run(
+        [
+          "backup",
+          "restore",
+          "--source",
+          "/tmp/x",
+          "--yes",
+          "--confirm",
+          "/tmp/x",
+          "--json",
+        ],
+        {},
+        { runMaintenanceRestore: maintenance },
+      );
+    } finally {
+      output.restore();
+    }
+    expect(code!).toBe(0);
+    expect(maintenance).toHaveBeenCalledTimes(1);
+  });
+
  it("rejects while the Runtime is running, with a distinct exit code", async () => {
    runtimeMocks.inspectRuntimeStatus.mockResolvedValueOnce({
      state: "running",
@@ -2728,7 +3010,7 @@ describe("backup restore drives the Core managed-restore contract", () => {
    });
  });

-  it("requires --confirm to repeat the exact source path", async () => {
+  it("refuses a legacy --confirm that does not repeat the source path", async () => {
    const maintenance = vi.fn();
    const output = captureStdout();
    let code: number;
@@ -2756,7 +3038,7 @@ describe("backup restore drives the Core managed-restore contract", () => {
      command: "backup",
      verb: "restore",
      state: "rejected",
-      code: "backup_restore_confirmation_required",
+      code: "backup_restore_confirmation_mismatch",
    });
  });

@@ -2908,7 +3190,7 @@ describe("init onboarding", () => {

  // Boolean flags were idempotent, but accepting them twice hid a duplicated
  // argv fragment that could also have duplicated a value-bearing flag.
-  it.each(["--import", "--full-rescan", "--confirm-overrides", "--dry-run"])(
+  it.each(["--import", "--confirm-overrides"])(
    "refuses a repeated init %s flag",
    async (flag) => {
      expect(await run(["init", "--source", "codex", flag, flag], {})).toBe(2);
@@ -2981,12 +3263,25 @@ describe("init onboarding", () => {
    },
  );

-  it("accepts --dry-run together with --import", async () => {
-    // Parsing must accept the pair; it stops at the Runtime check, which is
-    // not a usage failure.
-    expect(
-      await run(["init", "--source", "codex", "--import", "--dry-run"], {}),
-    ).not.toBe(2);
+  // `--dry-run` and `--full-rescan` never did anything (P0-2/P0-3): they are
+  // gone rather than accepted as no-ops.
+  it.each(["--dry-run", "--full-rescan"])(
+    "refuses the removed no-op %s flag",
+    async (flag) => {
+      expect(
+        await run(["init", "--source", "codex", "--import", flag], {}),
+      ).toBe(2);
+    },
+  );
+
+  it("still parses the old `init --source --import` spelling", async () => {
+    // It stops at the Runtime check (exit 3), which is not a usage failure.
+    const streams = captureStreams();
+    try {
+      expect(await run(["init", "--source", "codex", "--import"], {})).toBe(3);
+    } finally {
+      streams.restore();
+    }
  });
 });

@@ -58,10 +58,22 @@ const CONFIRM_OPTION: CommandOption = {
  flag: "--yes",
  summary: "确认执行；不加该参数时只输出计划，不做任何改动。",
 };
+/** The one confirmation convention, for irreversible operations only. */
+const DESTRUCTIVE_CONFIRM_OPTION: CommandOption = {
+  flag: "--yes",
+  summary:
+    "确认这次不可逆操作；不加时只说明将要做什么，不做任何改动，exit 0。（旧的 --confirm 仍作为别名接受。）",
+};
 const JSON_OPTION: CommandOption = {
  flag: "--json",
  summary: "以 JSON 输出到 stdout，供脚本与 Agent 消费。",
 };
+/** Global to the memory commands: whose memories are read or written. */
+const USER_ID_OPTION: CommandOption = {
+  flag: "--user-id <id>",
+  summary:
+    "读写哪个用户的记忆，默认 local（App 用的就是 local）。1–64 位字母、数字、点、下划线或连字符；其他用户的记忆来自用 sources connect hermes --user-id 接入的 Hermes profile。",
+};
 const WATCH_OPTION: CommandOption = {
  flag: "--watch",
  summary: "串行持续刷新；Ctrl-C 只停止观察，不停止 Runtime。",
@@ -70,21 +82,6 @@ const INTERVAL_OPTION: CommandOption = {
  flag: "--interval <seconds>",
  summary: "刷新间隔，默认 5 秒，范围 1..300；必须与 --watch 一起使用。",
 };
-const PLAN_FILE_OPTION: CommandOption = {
-  flag: "--plan-file <path>",
-  summary: "读取先前 --json 保存的有界计划文件。",
-};
-const EXPLICIT_CONFIRM_OPTION: CommandOption = {
-  flag: "--confirm",
-  summary: "确认执行计划文件逐字描述的操作；缺少时绝不写入。",
-};
-// Same flag, but for commands that name their target directly instead of
-// going through a saved plan file; the plan-file wording would be wrong here.
-const DIRECT_CONFIRM_OPTION: CommandOption = {
-  flag: "--confirm",
-  summary: "确认执行上面预览的这次操作；缺少时绝不写入。",
-};
-
 const SERVICE_OPTIONS: readonly CommandOption[] = [
  PLATFORM_OPTION,
  HOME_OPTION,
@@ -154,55 +151,77 @@ const INSTALL_OPTIONS: readonly CommandOption[] = [
 const INSTALL_USAGE =
  "[--source <path> | --release-manifest-url <https-url>] [--channel <stable|prerelease>] [--install-root <path>] [--home <path>] [--bin-dir <path>] [--data-dir <path>] [--uid <id>] [--xdg-config-home <path>] [--no-shell-path] [--shell-profile <path>] [--preserve-data-dir] [--allow-downgrade] [--yes]";

+const USAGE_EXITS = [EXIT_OK, EXIT_FAILED, EXIT_USAGE] as const;
+const RUNTIME_EXITS = [
+  EXIT_OK,
+  EXIT_FAILED,
+  EXIT_USAGE,
+  EXIT_RUNTIME_STOPPED,
+] as const;
+
+const KIND_OPTION: CommandOption = {
+  flag: "--kind <chat|experience|fact>",
+  summary:
+    "记忆所在的命名空间；工作/编码场景的经验和事实需要同时给 --variant。list 输出里每条都带 kind/variant。",
+};
+const VARIANT_OPTION: CommandOption = {
+  flag: "--variant <working|coding>",
+  summary:
+    "经验或事实属于工作还是编码场景；必须和 --kind experience|fact 一起用。",
+};
+
 export const COMMANDS: readonly CommandDescriptor[] = [
  {
    name: "serve",
    summary: "在前台启动完整 Runtime（Core 与 Host Gateway），不注册系统服务。",
    usage: "memhub serve",
    options: [],
-    exit_codes: [EXIT_OK, EXIT_FAILED],
+    exit_codes: USAGE_EXITS,
  },
  {
    name: "start",
-    summary: "启动本机 Runtime；已有通过身份校验的实例时只连接，不重复启动。",
+    summary:
+      "启动本机 Runtime；已有通过身份校验的实例时只连接，不重复启动。受管服务会同时恢复登录时自动启动。",
    usage: "memhub start [--json]",
    options: [JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_RUNTIME_STOPPED],
+    exit_codes: USAGE_EXITS,
  },
  {
    name: "stop",
-    summary: "停止通过身份校验的本机 Runtime；身份不明确时不发送信号。",
+    summary:
+      "停止通过身份校验的本机 Runtime；身份不明确时不发送信号。受管服务（launchd/systemd、App）停止后登录时也不会自动启动，直到再次运行 memhub start。",
    usage: "memhub stop [--json]",
    options: [JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED],
+    exit_codes: USAGE_EXITS,
  },
  {
    name: "restart",
    summary: "先停止再启动本机 Runtime，两步串行执行。",
    usage: "memhub restart [--json]",
    options: [JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED],
+    exit_codes: USAGE_EXITS,
  },
  {
    name: "status",
    summary: "只读查询 Runtime 运行状态；不启动服务、不迁移数据、不改配置。",
    usage: "memhub status [--watch] [--interval <seconds>] [--json]",
    options: [WATCH_OPTION, INTERVAL_OPTION, JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "doctor",
-    summary: "按诊断口径做同样的只读检查；默认不修复任何东西。",
+    summary:
+      "按诊断口径做只读检查并给出修复建议；默认不修复任何东西。Runtime 未运行时 exit 3。",
    usage: "memhub doctor [--json]",
    options: [JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "logs",
    summary:
-      "读取本机脱敏诊断日志；logs export 会把排查包直接存到下载目录。默认显示最近一次会话的 200 条事件。",
+      "读取本机脱敏诊断日志；logs export 会把排查包（含系统崩溃报告）直接存到下载目录。默认显示最近一次会话的 200 条事件。",
    usage:
-      "memhub logs export [--json]\nmemhub logs [--since <15m|2h|7d|RFC3339>] [--session <id>] [--trace <id>] [--incident <id>] [--operation <id>] [--request <id>] [--job <id>] [--task <id>] [--component <name>] [--event <name>] [--errors-only] [--tail <1..5000>] [--follow] [--json]",
+      "memhub logs export [--json]\n            memhub logs [--since <15m|2h|7d|RFC3339>] [--session <id>] [--trace <id>] [--incident <id>] [--operation <id>] [--request <id>] [--job <id>] [--task <id>] [--component <name>] [--event <name>] [--errors-only] [--tail <1..5000>] [--follow] [--json]",
    options: [
      {
        flag: "--since <time>",
@@ -226,64 +245,56 @@ export const COMMANDS: readonly CommandDescriptor[] = [
          "以 NDJSON 输出到 stdout（每行一个脱敏事件；非单 JSON 文档），供脚本与 Agent 消费。",
      },
    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE],
+    exit_codes: USAGE_EXITS,
  },
  {
    name: "init",
    summary:
-      "首次接入：选择来源 → 选择是否导入历史。接入即开启该 Harness 的处理；后续可用 sync pause/resume 冻结或恢复。在终端且不带 --source 时进入交互引导（默认全选）；非终端或加 --json 时不读 stdin、只列出可用来源和下一步。--all-detected 一次接入所有已检测来源。",
+      "首次接入引导。在终端里（未加 --json）进入交互向导：选择来源 → 是否开启处理 → 配置模型。非终端或加 --json 时不读 stdin，只列出可接入的来源和下一步命令。脚本接入请用 sources connect。",
+    usage: "memhub init [--json]",
+    options: [JSON_OPTION],
+    exit_codes: RUNTIME_EXITS,
+  },
+  {
+    name: "sources",
+    summary:
+      "列出来源，直接接入来源，或按 request id 查接入回执。connect 不加 --import 只授权（处理保持冻结：不导入历史、不扫描新会话）；加 --import 同时导入历史并开启持续同步，返回 request id。目录来自环境变量覆盖的来源必须加 --confirm-overrides。Hermes 的每个 profile 是一个独立用户：用 --user-id 和 --root 接入，授权并导入历史（会自动排除 ~/.hermes/profiles/**，各用户互不读取）。",
    usage:
-      "memhub init [--json]\n            memhub init --source <id> [--source <id> ...] [--import] [--dry-run] [--full-rescan] [--confirm-overrides] [--json]\n            memhub init --all-detected [--import] [--dry-run] [--json]",
+      "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: [
      {
-        flag: "--source <id>",
-        summary: "要接入的来源，可重复；终端下不给则进入交互引导。",
+        flag: "--import",
+        summary:
+          "接入后立即导入历史会话并开启持续同步；不加时只授权，处理保持冻结。",
+      },
+      {
+        flag: "--user-id <id>",
+        summary:
+          "只用于 hermes：这条接入属于哪个用户（默认 local）。和 --root 一起接入一个 Hermes profile，例如 --user-id wife --root ~/.hermes/profiles/wife；其他来源只能是 local。",
+      },
+      {
+        flag: "--root <path>",
+        summary:
+          "只用于 hermes：读取的根目录（~ 会展开为主目录）。默认是 Hermes 自己的目录 ~/.hermes。",
      },
      {
        flag: "--all-detected",
        summary:
-          "接入并（加 --import 时）导入全部 location_state=found 的来源。",
-      },
-      {
-        flag: "--import",
-        summary: "接入后立即导入该来源的历史会话（默认只接入不导入）。",
-      },
-      {
-        flag: "--dry-run",
-        summary: "只出计划，不接入也不导入；用于先看会做什么。",
-      },
-      {
-        flag: "--full-rescan",
-        summary: "导入时忽略既有游标做全量重扫。",
+          "接入全部已检测到（location_state=found）的来源；与具体来源互斥。",
      },
      {
        flag: "--confirm-overrides",
-        summary: "确认接受环境覆盖类来源（如 DSH_HOME 指定的目录）。",
+        summary:
+          "确认接受目录来自环境变量覆盖的来源（如 DSH_HOME 指定的目录）；不加时这些来源被拒绝（指定来源时）或跳过并列出（--all-detected 时）。",
      },
-      JSON_OPTION,
-    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
-  },
-  {
-    name: "setup",
-    summary: "生成无头首次导入计划；只读取已有来源，不探测目录、不写授权。",
-    usage: "memhub setup plan --source <id> [--source <id> ...] [--json]",
-    options: [
      {
-        flag: "--source <id>",
-        summary: "计划导入的来源，可重复 1..32 次。",
+        flag: "--request-id <uuid>",
+        summary:
+          "--import 的幂等键；用同一个 id 重试只会读回第一次的回执，不会重复导入。",
      },
      JSON_OPTION,
    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
-  },
-  {
-    name: "sources",
-    summary: "列出来源、执行已确认的导入计划。",
-    usage:
-      "memhub sources list [--json]\n            memhub sources import --plan-file <path> --confirm [--json]\n            memhub sources receipt <request-id> [--json]",
-    options: [PLAN_FILE_OPTION, EXPLICIT_CONFIRM_OPTION, JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "sync",
@@ -297,7 +308,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
      },
      JSON_OPTION,
    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "progress",
@@ -318,17 +329,17 @@ export const COMMANDS: readonly CommandDescriptor[] = [
      INTERVAL_OPTION,
      JSON_OPTION,
    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "jobs",
    summary:
-      "启动或控制单个导入任务：start 创建 history/sync 作业；pause/resume/cancel 控制已有作业。所有写操作先出计划，必须显式 --confirm；list/show 为只读。",
+      "查看或控制导入任务：start 创建 history/sync 任务；pause/resume/cancel 控制已有任务。都直接执行。",
    usage:
      "memhub jobs list [--json]\n" +
      "            memhub jobs show <job-id> [--json]\n" +
-      "            memhub jobs start --source <id> [--operation <history|sync>] [--confirm] [--json]\n" +
-      "            memhub jobs <pause|resume|cancel> --job <id> [--confirm] [--json]",
+      "            memhub jobs start --source <id> [--operation <history|sync>] [--json]\n" +
+      "            memhub jobs <pause|resume|cancel> --job <id> [--json]",
    options: [
      {
        flag: "--source <id>",
@@ -336,123 +347,186 @@ export const COMMANDS: readonly CommandDescriptor[] = [
      },
      {
        flag: "--operation <history|sync>",
-        summary: "start 的导入类型，默认 history。",
+        summary:
+          "start 的导入类型，默认 history；sync 与 scan --source 相同，立即增量同步一次。",
      },
      {
        flag: "--job <id>",
        summary: "pause/resume/cancel 的目标导入任务。",
      },
-      DIRECT_CONFIRM_OPTION,
      JSON_OPTION,
    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "models",
    summary:
-      "交互配置模型，或生成配置/探测计划、执行已确认操作与查询回执；脚本模式的凭据只从受控文件读取。",
+      "管理生成模型配置。add/test 直接提交并返回操作 ID（异步，用 receipt 查结果）；edit 直接执行；activate 换了向量模型（模型或维度）时先显示切换计划，需 --yes 确认后重新生成全部向量，switch 查看或取消、spaces 查看或清理旧向量数据；remove 不可逆，需 --yes。<profile-id>/<operation-id> 都是 UUID；脚本模式的凭据只从受控文件读取。",
    usage:
-      "memhub models list [--json]\n            memhub models show <profile-id> [--json]\n            memhub models plan --config-file <path> [--json]\n            memhub models configure --plan-file <path> --confirm [--api-key-file <path>] [--json]\n            memhub models receipt <operation-id> [--json]\n            memhub models edit <profile-id> --config-file <path> [--confirm] [--api-key-file <path>] [--json]\n            memhub models activate <profile-id> [--confirm] [--json]\n            memhub models probe-plan <profile-id> [--json]\n            memhub models probe --plan-file <path> --confirm [--json]\n            memhub models probe-receipt <operation-id> [--json]\n            memhub models remove <profile-id> [--confirm] [--json]",
+      "memhub models list [--json]\n            memhub models show <profile-id> [--json]\n            memhub models add --config-file <path> [--api-key-file <path>] [--activate [--yes] [--wait|--no-wait]] [--json]\n            memhub models test <profile-id> [--json]\n            memhub models receipt <operation-id> [--json]\n            memhub models edit <profile-id> --config-file <path> [--api-key-file <path>] [--json]\n            memhub models activate <profile-id> [--yes] [--wait|--no-wait] [--json]\n            memhub models switch <status|cancel> [--json]\n            memhub models spaces [--cleanup <space-id> --yes] [--json]\n            memhub models remove <profile-id> [--yes] [--json]",
    alternative_usage: "memhub models setup",
    options: [
      {
        flag: "--config-file <path>",
-        summary: "不含 api_key 的有界 JSON 模型配置。",
+        summary:
+          "有界 JSON 模型配置，不能含 api_key；edit 的补丁必须带 expected_revision。",
      },
-      PLAN_FILE_OPTION,
-      EXPLICIT_CONFIRM_OPTION,
      {
        flag: "--api-key-file <path>",
-        summary: "从 regular file 读取凭据；内容不进入参数、输出或错误。",
+        summary: "从属主专用的普通文件读取凭据；内容不进入参数、输出或错误。",
      },
+      {
+        flag: "--activate",
+        summary:
+          "add 成功后先探测，再按 activate 的规则设为当前使用（向量模型变化时同样要确认切换）。",
+      },
+      {
+        flag: "--wait | --no-wait",
+        summary:
+          "activate 开始向量模型切换后是否跟随进度；终端里默认跟随，Ctrl-C 只停止显示。",
+      },
+      {
+        flag: "--cleanup <space-id>",
+        summary: "spaces：立即删除一个已停用的向量空间（不可恢复，需 --yes）。",
+      },
+      DESTRUCTIVE_CONFIRM_OPTION,
      JSON_OPTION,
    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "memories",
-    summary: "通过 SDK 数据面列出、查看、修改或物理删除记忆。",
+    summary:
+      "列出、搜索、查看、添加、修改或物理删除记忆（对话、工作、编码三个场景）。add 和 App 的「添加记忆」是同一个入口；delete 不可逆，需 --yes。",
    usage:
-      "memhub memories list [--status <state>] [--offset <n>] [--limit <n>] [--json]\n            memhub memories show <memory-id> [--json]\n            memhub memories update <memory-id> --content-file <path> [--confirm] [--json]\n            memhub memories delete <memory-id> [--confirm] [--json]",
+      "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: [
+      {
+        flag: "--scene <all|chat|working|coding>",
+        summary: "只列一个场景，默认 all。working/coding 列的是该场景的经验。",
+      },
+      { flag: "--source <id>", summary: "只列某个来源写入的记忆。" },
+      {
+        flag: "--query <text>",
+        summary:
+          "关键词搜索（只搜 active 记忆，在最相关的一批里匹配所有关键词，输出 search_window 时表示可能少计）。",
+      },
      {
        flag: "--status <state>",
-        summary: `记忆状态，取值 ${MEMORY_STATUSES.join("、")}。`,
+        summary: `记忆状态，取值 ${MEMORY_STATUSES.join("、")}，默认 active。`,
      },
      { flag: "--offset <n>", summary: "跳过前 n 条，默认 0。" },
      {
        flag: "--limit <n>",
        summary: "本页最多返回多少条，默认 100，上限 500。",
      },
+      KIND_OPTION,
+      VARIANT_OPTION,
      {
        flag: "--content-file <path>",
        summary:
-          "从有界普通文件读取 update 的新正文；预览只显示摘要，--confirm 时才写入。",
+          "从有界普通文件读取正文：add 的新记忆（≤12000 字），或 update 的新内容（经验为 solution）。",
      },
-      DIRECT_CONFIRM_OPTION,
+      {
+        flag: "--task <text>",
+        summary: "update 经验（--kind experience）时同时改写 task。",
+      },
+      {
+        flag: "--request-id <uuid>",
+        summary:
+          "add 的幂等键；用同一个 id 重试只会读回第一次的结果，不会重复添加。不给时自动生成并输出。",
+      },
+      DESTRUCTIVE_CONFIRM_OPTION,
+      USER_ID_OPTION,
      JSON_OPTION,
    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "profile",
-    summary: "读取 SDK 组装后的用户长期画像（L0 + 已启用的长期画像补充）。",
-    usage: "memhub profile [--json]",
-    options: [DATA_DIR_OPTION, JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
-  },
-  {
-    name: "calls",
    summary:
-      "清除本机调用记录；不可逆删除，默认只出计划，必须显式 --confirm 才执行。",
-    usage:
-      "memhub calls clear --event <id> [--event <id> ...] [--confirm] [--json]\n            memhub calls clear --all [--confirm] [--json]",
+      "读取 SDK 组装后的用户长期画像（L0 + 已启用的长期画像补充）；--versions 列出 L0 画像的版本链（最新在前，* 为当前版本）。",
+    usage: "memhub profile [--versions] [--user-id <id>] [--json]",
    options: [
      {
-        flag: "--event <id>",
-        summary: "要清除的调用记录事件 ID，可重复，最多 100 条。",
+        flag: "--versions",
+        summary:
+          "列出 L0 基本信息的版本链（get_user_basic_info），用于找出覆盖了正确值的错误版本。",
      },
-      {
-        flag: "--all",
-        summary: "清除全部调用记录；与 --event 互斥。",
-      },
-      DIRECT_CONFIRM_OPTION,
+      USER_ID_OPTION,
      JSON_OPTION,
    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
  },
  {
-    name: "notes",
+    name: "settings",
    summary:
-      "端内新增记忆（memory-notes）：从普通文件新增，或显式确认后处理已有笔记。",
+      "查看或切换记忆模式（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 恢复默认值。",
    usage:
-      "memhub notes add --content-file <path> [--json]\n            memhub notes apply --plan-file <path> --content-file <path> --confirm [--json]\n            memhub notes process <note-id> [--confirm] [--json]",
+      "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 reset [<name> ...] [--json]",
    options: [
      {
-        flag: "--content-file <path>",
-        summary: "从有界普通文件读取新增正文；计划只保存摘要，执行时重新校验。",
+        flag: "mode [lite|pro|ultra]",
+        summary: "不带模式只显示当前模式；带模式时先显示切换计划。",
      },
-      PLAN_FILE_OPTION,
-      DIRECT_CONFIRM_OPTION,
+      {
+        flag: "features set <name>=<true|false>",
+        summary:
+          "开关一个或多个 SDK 功能；功能在当前模式下不生效时会注明原因（例如 graph_rerank 需要 ultra）。",
+      },
+      {
+        flag: "features reset [<name> ...]",
+        summary: "把指定功能（不写则全部）恢复为 SDK 默认值。",
+      },
+      CONFIRM_OPTION,
      JSON_OPTION,
    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
  },
  {
-    name: "graph",
-    summary: "图谱宽度不匹配时的用户决定；默认只出计划，--confirm 后才执行。",
+    name: "evolve",
+    summary:
+      "立即为一个用户运行记忆进化（System 2，仅 ultra 模式）。在后台运行并返回运行 ID；--wait 等待结果。同一用户同时只运行一次；每晚的自动进化由 Runtime 按设置安排。",
    usage:
-      "memhub graph width --decision <keep_existing|rebuild_with_new|export_first> [--confirm] [--json]",
+      "memhub evolve [--user-id <id>] [--agent-id <id>] [--max-batches <n>] [--wait] [--json]",
+    options: [
+      USER_ID_OPTION,
+      {
+        flag: "--agent-id <id>",
+        summary:
+          "进化哪个 agent 的记忆，默认 all-apps（MemHub 写入记忆用的 agent）。",
+      },
+      {
+        flag: "--max-batches <n>",
+        summary: "每轮最多处理的批次数（1–1000），默认由 SDK 决定。",
+      },
+      { flag: "--wait", summary: "等待这次进化结束再返回。" },
+      JSON_OPTION,
+    ],
+    exit_codes: RUNTIME_EXITS,
+  },
+  {
+    name: "graph-width",
+    summary:
+      "嵌入维度变化、图谱宽度不匹配时的处置决定。keep_existing 与 export_first 直接执行；rebuild_with_new 会归档旧图谱并重建，需 --yes。",
+    usage:
+      "memhub graph-width --decision <keep_existing|export_first|rebuild_with_new> [--yes] [--json]",
    options: [
      {
        flag: "--decision <decision>",
        summary:
-          "keep_existing（保持）、export_first（先导出）、rebuild_with_new（导出后重建）。",
+          "keep_existing（保持现有图谱）、export_first（先导出）、rebuild_with_new（导出后归档旧图谱并按新维度重建）。",
+      },
+      {
+        ...DESTRUCTIVE_CONFIRM_OPTION,
+        summary: "rebuild_with_new 必须加；其它决定不需要。",
      },
-      DIRECT_CONFIRM_OPTION,
      JSON_OPTION,
    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "host",
@@ -480,14 +554,14 @@ export const COMMANDS: readonly CommandDescriptor[] = [
      },
      JSON_OPTION,
    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "recall",
    summary:
-      "从当前授权的原文与已沉淀记忆统一检索上下文；本地只读，不调用模型、不触发补索引。",
+      "从原始对话与已沉淀记忆统一检索上下文；本地只读，不调用模型、不触发补索引。文本输出标明每条是「原始对话摘录」还是「记忆」（JSON 里是 kind: raw|memory）。",
    usage:
-      "memhub recall <query> [--kind <raw|memory>] [--source <id>] [--limit <n>] [--character-budget <n>] [--timeout-ms <n>] [--json]\n            memhub recall --query-file <path> [...]\n            memhub recall --stdin [...]",
+      "memhub recall <query> [--kind <raw|memory>] [--source <id>] [--limit <n>] [--character-budget <n>] [--timeout-ms <n>] [--user-id <id>] [--json]\n            memhub recall --query-file <path> [...]\n            memhub recall --stdin [...]",
    options: [
      {
        flag: "--query-file <path>",
@@ -514,23 +588,24 @@ export const COMMANDS: readonly CommandDescriptor[] = [
        flag: "--timeout-ms <n>",
        summary: "Core 查询时限 50..30000 毫秒，默认 2000。",
      },
+      USER_ID_OPTION,
      JSON_OPTION,
    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "service-plan",
    summary: "生成用户级服务计划；只输出计划，不写文件也不执行命令。",
    usage: `memhub service-plan ${SERVICE_USAGE}`,
    options: SERVICE_OPTIONS,
-    exit_codes: [EXIT_OK, EXIT_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_PLAN_BLOCKED],
  },
  {
    name: "service-install",
    summary: "预览用户级服务安装；只有 --yes 才写入服务文件并注册。",
    usage: `memhub service-install ${SERVICE_USAGE} [--yes]`,
    options: [...SERVICE_OPTIONS, CONFIRM_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
  },
  {
    name: "service-uninstall",
@@ -538,15 +613,15 @@ export const COMMANDS: readonly CommandDescriptor[] = [
      "预览用户级服务卸载；只有 --yes 才注销并删除逐字匹配的受管服务文件，不删数据。",
    usage: `memhub service-uninstall ${SERVICE_USAGE} [--yes]`,
    options: [...SERVICE_OPTIONS, CONFIRM_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
  },
  {
    name: "install",
    summary:
-      "预览发行目录安装、memhub/memhub-cli/one-memory 短链接、PATH 条目与用户服务计划；只有 --yes 才执行并在失败时回滚。",
+      "预览发行目录安装、memhub/memhub-cli/one-memory 短链接、PATH 条目与用户服务计划；只有 --yes 才执行。记忆数据迁移开始前失败会回滚；迁移开始后失败保留新版本、拒绝启动，并输出迁移日志与反馈地址。",
    usage: `memhub install ${INSTALL_USAGE}`,
    options: INSTALL_OPTIONS,
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
  },
  {
    name: "uninstall",
@@ -559,24 +634,31 @@ export const COMMANDS: readonly CommandDescriptor[] = [
  {
    name: "upgrade",
    summary:
-      "预览升级；只有 --yes 才切换受管版本并重启服务，失败时恢复旧版本，不删数据。",
+      "预览升级；只有 --yes 才切换受管版本并重启服务，不删数据。记忆数据迁移开始前失败会恢复旧版本；迁移开始后失败保留新版本、拒绝启动，并输出迁移日志与反馈地址（不会回滚到旧版本）。",
    usage: `memhub upgrade ${INSTALL_USAGE}`,
    options: INSTALL_OPTIONS,
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
  },
  {
    name: "delete-data",
    summary:
-      "独立、二次确认地删除 One Memory Home（数据）。这是唯一会删除数据的命令；uninstall 不会。默认只出预览；需 Runtime 已停止，并显式 --confirm <path> 复述该目录。",
+      "删除 MemHub 数据目录（记忆、来源、配置），不可逆。这是唯一会删除数据的命令；uninstall 不会。需要 Runtime 已停止；不加参数时只预览要删除的目录；删除需要 --yes 并用 --confirm 再写一遍同一个目录。",
    usage:
      "memhub delete-data [--data-dir <path>] [--yes --confirm <path>] [--json]",
    options: [
-      DATA_DIR_OPTION,
-      CONFIRM_OPTION,
+      {
+        flag: "--data-dir <path>",
+        summary: "要删除的数据目录绝对路径；默认当前使用的数据目录。",
+      },
+      {
+        ...DESTRUCTIVE_CONFIRM_OPTION,
+        summary:
+          "删除时必须加，且要同时给出 --confirm <path>；不加时只预览，exit 0。",
+      },
      {
        flag: "--confirm <path>",
        summary:
-          "第二次确认：逐字复述预览里的数据目录；缺少它时即使 --yes 也不删除。",
+          "删除时必须加：再写一遍要删除的数据目录，与预览中的目录完全一致才执行。",
      },
      JSON_OPTION,
    ],
@@ -588,113 +670,150 @@ export const COMMANDS: readonly CommandDescriptor[] = [
      "onboarding reset 回到首次运行的引导流程。只清除引导完成状态：不删记忆数据，也不需要卸载重装。",
    usage: "memhub onboarding reset [--json]",
    options: [JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "help",
    summary: "显示总帮助或单个命令的用法。",
    usage: "memhub help [command] [--json]",
    options: [JSON_OPTION],
-    exit_codes: [EXIT_OK],
+    exit_codes: [EXIT_OK, EXIT_USAGE],
  },
  {
    name: "version",
    summary: "显示 CLI 版本。",
    usage: "memhub version [--json]",
    options: [JSON_OPTION],
-    exit_codes: [EXIT_OK],
+    exit_codes: [EXIT_OK, EXIT_USAGE],
  },
  {
-    name: "path",
+    name: "scan-roots",
    summary:
-      "查看或登记被扫描的目录（scan roots）。list 只读；add/remove 预览后加 --yes 才提交；均已接入 Runtime 的 scan-roots 端点。",
+      "查看或登记被扫描的目录（scan roots）。add/remove 直接执行。（旧名 path 仍可用。）",
    usage:
-      "memhub path list [--json]\n" +
-      "            memhub path add --root <path> [--source <id>] [--no-recursive] [--yes]\n" +
-      "            memhub path remove --root <path> [--yes]",
-    options: [DATA_DIR_OPTION, JSON_OPTION, CONFIRM_OPTION],
-    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED, EXIT_PLAN_BLOCKED],
+      "memhub scan-roots list [--json]\n" +
+      "            memhub scan-roots add --root <path> [--source <id>] [--no-recursive] [--json]\n" +
+      "            memhub scan-roots remove --root <path> [--json]",
+    options: [
+      { flag: "--root <path>", summary: "要登记或移除的目录。" },
+      {
+        flag: "--source <id>",
+        summary: "把目录绑定到某个来源；不给时由 Runtime 自动识别。",
+      },
+      { flag: "--no-recursive", summary: "只扫描该目录本身，不进入子目录。" },
+      JSON_OPTION,
+    ],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "adapter",
    summary:
-      "查看 Harness Adapter 的就绪状态与最近一次探测结果（list），或现场探测某个来源（probe --source <id>）；两者均为只读，已接入 Runtime 的 adapters/探测端点。",
+      "查看 Harness Adapter 的就绪状态与最近一次探测结果（list），或现场探测某个来源（probe --source <id>）；两者均为只读。",
    usage:
      "memhub adapter list [--json]\n" +
      "            memhub adapter probe --source <id> [--json]",
-    options: [DATA_DIR_OPTION, JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED],
+    options: [
+      { flag: "--source <id>", summary: "probe 的目标来源。" },
+      JSON_OPTION,
+    ],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "scan",
    summary:
-      "立即扫描；默认只输出计划，加 --yes 才真正执行。指定 --source 扫描单个来源，--all 一次扫描/导入全部已检测来源（Runtime 按来源寻址，不接受裸路径）。",
-    usage:
-      "memhub scan [--source <id>] [--full] [--yes] [--json]\n            memhub scan --all [--yes] [--json]",
+      "立即增量扫描一个已连接并开启同步的来源，返回导入任务（与 jobs start --operation sync 相同）。接入全部来源请用 sources connect --all-detected --import。",
+    usage: "memhub scan --source <id> [--json]",
    options: [
      {
        flag: "--source <id>",
-        summary: "按单个来源扫描；与 --all 互斥。",
+        summary: "要扫描的来源。",
      },
-      {
-        flag: "--all",
-        summary:
-          "处理全部 location_state=found 的来源，按来源逐条回执；部分成功返回非 0。",
-      },
-      {
-        flag: "--full",
-        summary: "忽略既有游标做全量重扫；默认只读取增量。",
-      },
-      DATA_DIR_OPTION,
      JSON_OPTION,
-      CONFIRM_OPTION,
    ],
-    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED, EXIT_PLAN_BLOCKED],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "write",
-    summary: "提交 OpenAI messages 到 SDK 写入队列，或按 request id 查询状态。",
-    usage:
-      "memhub write submit --messages-file <path> --session <id> [--source <id>] [--request-id <id>] [--memory-at <RFC3339>] [--live] [--json]\n            memhub write status --id <request-id> [--json]",
-    options: [DATA_DIR_OPTION, JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED],
-  },
-  {
-    name: "task",
    summary:
-      "兼容别名：按 request id 查询写入状态；新脚本请使用 write status。",
-    usage: "memhub task --id <request-id> [--json]",
-    options: [DATA_DIR_OPTION, JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED],
+      "提交一段 OpenAI 格式的对话（messages）到写入队列，异步加工成记忆；或按 request id 查询状态。request id 是幂等键：不给时自动生成并输出，重试请带上同一个。新增一条结论式记忆请用 memories add。",
+    usage:
+      "memhub write submit --messages-file <path> --session <id> [--source <id>] [--request-id <id>] [--memory-at <RFC3339>] [--live] [--user-id <id>] [--json]\n            memhub write status <request-id> [--user-id <id>] [--json]",
+    options: [
+      {
+        flag: "--messages-file <path>",
+        summary:
+          "OpenAI messages 数组（或 {messages:[…]}），1..200 条，role 为 user/assistant/tool，至少一条 user。",
+      },
+      { flag: "--session <id>", summary: "会话 ID。" },
+      { flag: "--source <id>", summary: "来源应用，默认 memhub-cli。" },
+      {
+        flag: "--request-id <id>",
+        summary:
+          "幂等键：同 id 同内容不会重复入队，同 id 不同内容被拒绝（409）。",
+      },
+      { flag: "--memory-at <RFC3339>", summary: "对话发生时间，必须带时区。" },
+      { flag: "--live", summary: "优先处理。" },
+      USER_ID_OPTION,
+      JSON_OPTION,
+    ],
+    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "backup",
    summary:
-      "备份与恢复 MemHub 数据（两阶段）。create 调用 Runtime 的备份端点；restore 会覆盖现有数据，要求 Runtime 已停止且 `--confirm` 逐字重复 `--source`，随后由非 Runtime 维护态 Core 完成受管校验、保护性备份和原子替换。",
+      "备份与恢复主库（来源、写入队列、配置）。注意：不包含记忆本身——SDK 记忆库 hy-memory/ 不在备份里，restore 也不会替换它。create 的目标要放在 <数据目录>/backups/ 下才能被 restore 使用；restore 覆盖现有主库，需 Runtime 已停止，并加 --yes 与 --confirm <同一个备份路径>。",
    usage:
-      "memhub backup create --target <path> [--yes] [--json]\n" +
-      "            memhub backup restore --source <path> --yes --confirm <path> [--json]",
+      "memhub backup create --target <path> [--json]\n" +
+      "            memhub backup restore --source <path> [--yes --confirm <path>] [--json]",
    options: [
-      DATA_DIR_OPTION,
-      JSON_OPTION,
-      CONFIRM_OPTION,
+      {
+        flag: "--target <path>",
+        summary: "create 的备份文件路径，必须在数据目录内。",
+      },
+      {
+        flag: "--source <path>",
+        summary:
+          "restore 的备份文件，必须是 <数据目录>/backups/ 下的受管备份。",
+      },
+      {
+        ...DESTRUCTIVE_CONFIRM_OPTION,
+        summary:
+          "restore 必须加，且要同时给出 --confirm <path>；create 不需要。",
+      },
      {
        flag: "--confirm <path>",
-        summary: "restore 要求逐字重复 --source 路径；不一致时不做任何改动。",
+        summary:
+          "restore 必须加：再写一遍 --source 的备份路径，完全一致才执行。",
      },
+      JSON_OPTION,
    ],
-    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED, EXIT_PLAN_BLOCKED],
+    exit_codes: [...RUNTIME_EXITS, EXIT_PLAN_BLOCKED],
  },
  {
    name: "ui",
    summary:
-      "用系统默认浏览器打开 Runtime 托管的 Web Console：先向 Core 换取一次性 loopback 登录码，再交给系统浏览器由 Core 置 HttpOnly/SameSite=Strict session；CLI 不向浏览器暴露裸 Core token。Core 未提供该合同时如实返回 ui_session_contract_unavailable（exit 4）。",
+      "用系统默认浏览器打开 Runtime 托管的 Web Console：先向 Core 换取一次性 loopback 登录码，再交给系统浏览器由 Core 置 HttpOnly/SameSite=Strict session；CLI 不向浏览器暴露裸 Core token。Runtime 未运行时 exit 3；Core 未提供该合同时如实返回 ui_session_contract_unavailable（exit 4）。",
    usage: "memhub ui [--json]",
    options: [JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
+    exit_codes: [...RUNTIME_EXITS, EXIT_PLAN_BLOCKED],
  },
 ];

+/** Old names that still run but are not listed: `path` → `scan-roots`,
+ * `task` → `write status`, `graph width` → `graph-width`. */
+export const HIDDEN_COMMAND_ALIASES: Readonly<Record<string, string>> = {
+  path: "scan-roots",
+  task: "write",
+  graph: "graph-width",
+};
+
 export function findCommand(name: string): CommandDescriptor | undefined {
  return COMMANDS.find((command) => command.name === name);
 }
+
+/** A listed command, or the command a hidden alias now runs as. */
+export function findCommandOrAlias(
+  name: string,
+): CommandDescriptor | undefined {
+  return findCommand(HIDDEN_COMMAND_ALIASES[name] ?? name);
+}
@@ -69,7 +69,6 @@ const COMMANDS = [
  "doctor",
  "logs",
  "init",
-  "setup",
  "sources",
  "sync",
  "progress",
@@ -77,10 +76,9 @@ const COMMANDS = [
  "models",
  "memories",
  "profile",
-  // C6 App BLOCK (25f4ecf): UI write operations that had no CLI equivalent.
-  "calls",
-  "notes",
-  "graph",
+  "settings",
+  "evolve",
+  "graph-width",
  "host",
  "recall",
  "service-plan",
@@ -93,19 +91,20 @@ const COMMANDS = [
  "onboarding",
  "help",
  "version",
-  // A6 product commands. Appended, not inserted: the catalog is a stable
-  // contract, so existing names must not shift position.
-  "path",
+  "scan-roots",
  "adapter",
  "scan",
  "write",
-  "task",
  "backup",
-  // `ui` is declared but blocked on a Core session contract; it is listed so
-  // `help` documents it and the blocked shape is machine-readable.
  "ui",
 ] as const;

+/** Old names that still run and still answer `--help`, but are not listed. */
+const HIDDEN_ALIASES = [
+  ["path", "scan-roots"],
+  ["task", "write"],
+] as const;
+
 describe("CLI-22 shared output contract", () => {
  describe("help", () => {
    it.each([["help"], ["--help"], ["-h"]])(
@@ -146,6 +145,56 @@ describe("CLI-22 shared output contract", () => {
      },
    );

+    it.each(HIDDEN_ALIASES)(
+      "documents the hidden alias %s as %s and keeps it out of the listing",
+      async (alias, target) => {
+        const streams = captureStreams();
+        try {
+          expect(await run(["help", alias], {})).toBe(0);
+          expect(await run([alias, "--help"], {})).toBe(0);
+        } finally {
+          streams.restore();
+        }
+        expect(streams.stdout()).toContain(`${PRODUCT} ${target}`);
+        const listing = captureStreams();
+        try {
+          expect(await run(["help", "--json"], {})).toBe(0);
+        } finally {
+          listing.restore();
+        }
+        const names = JSON.parse(listing.stdout()).commands.map(
+          (entry: { name: string }) => entry.name,
+        );
+        expect(names).not.toContain(alias);
+      },
+    );
+
+    it("lists no removed command", async () => {
+      const streams = captureStreams();
+      try {
+        expect(await run(["help", "--json"], {})).toBe(0);
+      } finally {
+        streams.restore();
+      }
+      const catalog = streams.stdout();
+      for (const removed of [
+        '"name":"setup"',
+        '"name":"notes"',
+        '"name":"calls"',
+        '"name":"graph"',
+        "--plan-file",
+        "probe-plan",
+        "probe-receipt",
+        "models configure",
+        "sources import",
+        "--full-rescan",
+        "--dry-run",
+        "--full]",
+      ]) {
+        expect(catalog).not.toContain(removed);
+      }
+    });
+
    it("never executes the documented command", async () => {
      for (const command of COMMANDS) {
        for (const argv of [
@@ -201,27 +250,63 @@ describe("CLI-22 shared output contract", () => {
      expect(payload.commands).toBeUndefined();
    });

-    it("documents the destructive restore confirmation explicitly", async () => {
+    it("documents the one --yes convention for destructive commands", async () => {
+      const general = captureStreams();
+      try {
+        expect(await run(["help"], {})).toBe(0);
+      } finally {
+        general.restore();
+      }
+      expect(general.stdout()).toContain("确认约定");
+      for (const [command, usage] of [
+        [
+          "backup",
+          "memhub backup restore --source <path> [--yes --confirm <path>]",
+        ],
+        ["memories", "memhub memories delete <memory-id>"],
+        ["models", "memhub models remove <profile-id> [--yes]"],
+        [
+          "delete-data",
+          "memhub delete-data [--data-dir <path>] [--yes --confirm <path>]",
+        ],
+        ["graph-width", "[--yes]"],
+      ] as const) {
+        const streams = captureStreams();
+        try {
+          expect(await run(["help", command], {})).toBe(0);
+        } finally {
+          streams.restore();
+        }
+        expect(streams.stdout()).toContain(usage);
+        // Only the two commands with no way back repeat the target path.
+        if (command !== "backup" && command !== "delete-data") {
+          expect(streams.stdout()).not.toContain("--confirm <path>");
+        }
+      }
+    });
+
+    it("says backup does not include the memories themselves", async () => {
      const streams = captureStreams();
      try {
        expect(await run(["help", "backup"], {})).toBe(0);
      } finally {
        streams.restore();
      }
-      expect(streams.stdout()).toContain(
-        "memhub backup restore --source <path> --yes --confirm <path>",
-      );
-      expect(streams.stdout()).toContain("逐字重复 --source");
+      expect(streams.stdout()).toContain("不包含记忆本身");
    });

-    it("does not attach restore's confirmation flag to path", async () => {
-      const streams = captureStreams();
-      try {
-        expect(await run(["help", "path"], {})).toBe(0);
-      } finally {
-        streams.restore();
+    it("does not promise a rollback after the migration started", async () => {
+      for (const command of ["install", "upgrade"]) {
+        const streams = captureStreams();
+        try {
+          expect(await run(["help", command], {})).toBe(0);
+        } finally {
+          streams.restore();
+        }
+        expect(streams.stdout()).toContain("迁移开始后失败保留新版本");
+        expect(streams.stdout()).not.toContain("失败时恢复旧版本");
+        expect(streams.stdout()).not.toContain("失败时回滚");
      }
-      expect(streams.stdout()).not.toContain("--confirm <path>");
    });
  });

@@ -545,22 +630,25 @@ describe("documented commands", () => {
    models: [
      "list",
      "show",
-      "plan",
-      "configure",
+      "add",
+      "test",
      "receipt",
-      "probe-plan",
-      "probe",
-      "probe-receipt",
+      "edit",
+      "activate",
+      "switch",
+      "spaces",
      "remove",
    ],
    // Source processing is one Freeze/Thaw switch under `sync`; the obsolete
    // independent read/write `sources access` command must not return here.
-    sources: ["list", "import", "receipt"],
+    sources: ["list", "connect", "receipt"],
    jobs: ["list", "show", "start", "<pause|resume|cancel>"],
    // `sync <pause|resume>` is documented as one alternation, so it is
    // checked as an entry rather than as two literal subcommands.
    sync: ["status", "<pause|resume>"],
-    memories: ["list", "show", "update", "delete"],
+    memories: ["list", "show", "add", "add-status", "update", "delete"],
+    "scan-roots": ["list", "add", "remove"],
+    write: ["submit", "status"],
    host: ["list", "status", "install", "uninstall", "sync"],
  };

@@ -133,6 +133,20 @@ describe("unified context search", () => {
    expect(output).not.toMatch(/^- raw |memory-1|raw-1|采用状态/m);
  });

+  it("labels raw hits as original-conversation excerpts, not memories", async () => {
+    const streams = captureStreams();
+    try {
+      expect(await run(["recall", "synthetic question"])).toBe(0);
+    } finally {
+      streams.restore();
+    }
+    const output = streams.stdout();
+    expect(output).toContain(
+      "- [原始对话摘录 · codex] Synthetic raw citation.",
+    );
+    expect(output).toContain("- [记忆] Synthetic SDK memory.");
+  });
+
  it("queries the SDK context endpoint directly and preserves item ids", async () => {
    const streams = captureStreams();
    try {
@@ -10,6 +10,8 @@ export interface ContextSearchInput {
  limit: number;
  character_budget: number;
  timeout_ms: number;
+  /** Whose memories to search. Omitted for the default user (`local`). */
+  user_id?: string;
 }

 /** The CLI's JSON document mirrors Core's SDK-native context schema v2. */
@@ -23,6 +25,7 @@ export interface ContextSearchDocument {
    | "unavailable"
    | "denied"
    | "not_found"
+    | "rejected"
    | "invalid";
  code?: string;
  request_id?: string;
@@ -94,9 +97,17 @@ export function contextExitCode(document: ContextSearchDocument): number {
 }

 export function renderContextText(document: ContextSearchDocument): string {
-  if (document.state === "unavailable") return "暂时无法查记忆，请稍后重试。\n";
+  if (document.state === "unavailable") {
+    // No lexical fallback: without the embedding service nothing is searched.
+    return document.code === "embedding_unavailable"
+      ? "向量服务不可用，无法检索；请检查向量模型配置。\n"
+      : "暂时无法查记忆，请稍后重试。\n";
+  }
  if (document.state === "denied") return "当前应用没有查记忆权限。\n";
  if (document.state === "invalid") return "查记忆返回了无法识别的结果。\n";
+  if (document.state === "rejected") {
+    return `查记忆被拒绝（${document.code}），请检查参数。\n`;
+  }
  const lines = [
    document.state === "empty"
      ? "没有查到相关记忆。"
@@ -104,8 +115,14 @@ export function renderContextText(document: ContextSearchDocument): string {
        ? "查到以下内容，部分内容还在整理中："
        : "查到以下相关内容：",
  ];
+  // A raw hit is an excerpt of an original conversation, not a distilled
+  // memory; say which one each line is so it is not read as a conclusion.
  for (const item of document.items) {
-    lines.push(`- ${String(item.content)}`);
+    const label =
+      item.kind === "raw"
+        ? `[原始对话摘录 · ${String(item.source)}]`
+        : "[记忆]";
+    lines.push(`- ${label} ${String(item.content)}`);
  }
  if (document.truncated) lines.push("结果已按请求预算截断。");
  return `${lines.join("\n")}\n`;
@@ -8,16 +8,30 @@ import axios from "axios";
 */
 const READ_ONLY_PATHS = [
  "/api/v1/call-events",
+  // Read-only: the registry plus a scan of the vector store's collection names.
+  "/api/v1/embedding-spaces",
+  "/api/v1/embedding-switches/current",
  "/api/v1/import-jobs",
  "/api/v1/live-sync",
  "/api/v1/memory-processing",
  "/api/v1/model-profiles",
+  "/api/v1/source-grants",
  "/api/v1/sources",
  "/api/v2/home-summary",
  "/api/v2/memory-library",
  "/api/v2/user-profile",
+  "/api/v2/user-profile/versions",
+  "/api/v1/settings/memory-mode",
+  "/api/v1/settings/memory-features",
+  "/api/v2/evolve",
 ] as const;
+/** One evolve run's receipt (`memhub evolve --wait`). */
+const EVOLVE_RUN =
+  /^\/api\/v2\/evolve\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const SDK_MEMORY_DETAIL = /^\/api\/v2\/memories\/[A-Za-z0-9][\w.-]{0,127}$/;
+/** Status of one `POST /api/v2/memories` addition, by its request id. */
+const MEMORY_ADDITION =
+  /^\/api\/v2\/memories\/additions\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;

 /** Contract (C0, H25): the one-time loopback code exchange for `memhub ui`.
 * It is a POST because it mints a short-lived code; the CLI sends the bearer
@@ -79,9 +93,15 @@ export const RESERVED_MEMORY_SEGMENTS = ["ask", "graph"] as const;
 /** A response larger than this is refused before it is buffered. */
 const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;

+/** `rejected` is Core refusing the request itself (400/409/422: a bad filter,
+ * an ambiguous id). It is not "Core is busy" — only a transport failure or a
+ * 5xx is `unavailable`. */
 export type ReadOutcome<T> =
  | { state: "ok"; data: T }
-  | { state: "denied" | "unavailable" | "not_found"; code: string };
+  | {
+      state: "denied" | "unavailable" | "not_found" | "rejected";
+      code: string;
+    };

 export type CoreReader = <T>(
  path: string,
@@ -140,10 +160,40 @@ export function createCoreReader(attachment: {
    if (response.status === 404) {
      return { state: "not_found" as const, code: "http_404" };
    }
-    return { state: "unavailable" as const, code: `http_${response.status}` };
+    if ([400, 409, 422].includes(response.status)) {
+      return {
+        state: "rejected" as const,
+        code: detailCode(response.data, response.status),
+      };
+    }
+    return {
+      state: "unavailable" as const,
+      code: unavailableCode(response.data, response.status),
+    };
  };
 }

+/** A 503 that names `embedding_unavailable` keeps it: the search could not
+ * embed its query, which needs another fix than "try again later". */
+function unavailableCode(value: unknown, status: number): string {
+  return status === 503 && detailCode(value, status) === EMBEDDING_UNAVAILABLE
+    ? EMBEDDING_UNAVAILABLE
+    : `http_${status}`;
+}
+
+export const EMBEDDING_UNAVAILABLE = "embedding_unavailable";
+
+/** Core's stable `detail` code when it sent one, else the bare status. */
+function detailCode(value: unknown, status: number): string {
+  const detail =
+    value && typeof value === "object" && !Array.isArray(value)
+      ? (value as { detail?: unknown }).detail
+      : undefined;
+  return typeof detail === "string" && /^[a-z0-9_.:-]{1,128}$/.test(detail)
+    ? detail
+    : `http_${status}`;
+}
+
 /**
 * Context search is semantically read-only but intentionally uses POST so the
 * private query and filters are carried in a bounded body, never in a URL.
@@ -184,7 +234,10 @@ export function createCoreContextQuery(attachment: {
    if (response.status === 404) {
      return { state: "not_found" as const, code: "http_404" };
    }
-    return { state: "unavailable" as const, code: `http_${response.status}` };
+    return {
+      state: "unavailable" as const,
+      code: unavailableCode(response.data, response.status),
+    };
  };
 }

@@ -192,6 +245,8 @@ export function isReadOnlyPath(path: string): boolean {
  if ((READ_ONLY_PATHS as readonly string[]).includes(path)) return true;
  if (IMPORT_JOB.test(path)) return true;
  if (OPERATION_RECEIPT.test(path)) return true;
+  if (MEMORY_ADDITION.test(path)) return true;
+  if (EVOLVE_RUN.test(path)) return true;
  if (!SDK_MEMORY_DETAIL.test(path)) return false;
  const segment = path.slice("/api/v2/memories/".length);
  return !(RESERVED_MEMORY_SEGMENTS as readonly string[]).includes(segment);
@@ -199,8 +254,10 @@ export function isReadOnlyPath(path: string): boolean {

 /** A write accepted by the unified Memory Server entry.
 *
- * `request_id` is what the caller keeps and queries later. Retrying is unsafe:
- * HY has no idempotency key, so a resubmit duplicates the memory.
+ * `request_id` is the idempotency key: Core keys the write on it, so a retry
+ * with the same id and the same messages is answered from the first write, and
+ * the same id with different messages is refused (409). A retry without the
+ * original id is a new write.
 */
 export interface MemoryWriteReceipt {
  request_id: string;
@@ -267,6 +324,11 @@ function baseUrlOf(attachment: RuntimeAttachmentLike): string {
  return `http://${attachment.host}:${attachment.port}`;
 }

+export type MemoryWriteOutcome =
+  | { state: "accepted"; receipt: MemoryWriteReceipt }
+  | { state: "rejected"; code: string; http_status: number }
+  | { state: "unknown"; code: string };
+
 export async function submitMemoryWrite(
  attachment: RuntimeAttachmentLike,
  request: {
@@ -276,29 +338,54 @@ export async function submitMemoryWrite(
    messages: readonly OpenAIMessage[];
    memory_at?: string;
    priority?: "live" | "normal";
+    /** Whose memory this is. Omitted for the default user (`local`). */
+    user_id?: string;
  },
-): Promise<MemoryWriteReceipt> {
-  const response = await axios.post<MemoryWriteReceipt>(
-    `${baseUrlOf(attachment)}/api/v2/memory-writes`,
-    {
-      request_id: request.request_id,
-      session_id: request.session,
-      source_id: request.source,
-      messages: [...request.messages],
-      ...(request.memory_at === undefined
-        ? {}
-        : { memory_at: request.memory_at }),
-      ...(request.priority === undefined ? {} : { priority: request.priority }),
-    },
-    {
-      headers: { Authorization: `Bearer ${attachment.apiToken}` },
-      timeout: 15_000,
-      proxy: false,
-      maxRedirects: 0,
-      maxContentLength: MAX_RESPONSE_BYTES,
-    },
-  );
-  return response.data;
+): Promise<MemoryWriteOutcome> {
+  let response: { status: number; data: unknown };
+  try {
+    response = await axios.post<MemoryWriteReceipt>(
+      `${baseUrlOf(attachment)}/api/v2/memory-writes`,
+      {
+        request_id: request.request_id,
+        session_id: request.session,
+        source_id: request.source,
+        messages: [...request.messages],
+        ...(request.memory_at === undefined
+          ? {}
+          : { memory_at: request.memory_at }),
+        ...(request.priority === undefined
+          ? {}
+          : { priority: request.priority }),
+        ...(request.user_id === undefined || request.user_id === "local"
+          ? {}
+          : { user_id: request.user_id }),
+      },
+      {
+        headers: { Authorization: `Bearer ${attachment.apiToken}` },
+        timeout: 15_000,
+        proxy: false,
+        maxRedirects: 0,
+        maxContentLength: MAX_RESPONSE_BYTES,
+        validateStatus: () => true,
+      },
+    );
+  } catch {
+    // The request may or may not have reached Core; the same request id makes
+    // a retry safe.
+    return { state: "unknown", code: "transport_result_unknown" };
+  }
+  if (response.status >= 200 && response.status < 300) {
+    return { state: "accepted", receipt: response.data as MemoryWriteReceipt };
+  }
+  if (response.status >= 400 && response.status < 500) {
+    return {
+      state: "rejected",
+      code: detailCode(response.data, response.status),
+      http_status: response.status,
+    };
+  }
+  return { state: "unknown", code: `http_${response.status}_result_unknown` };
 }

 /** Ask Runtime to scan one source now, returning the import job it started.
@@ -415,11 +502,16 @@ export async function deleteModelProfile(
 export async function readMemoryWrite(
  attachment: RuntimeAttachmentLike,
  requestId: string,
+  /** A receipt belongs to the user that submitted it; omit for `local`. */
+  userId?: string,
 ): Promise<MemoryWriteReceipt | null> {
  try {
    const response = await axios.get<MemoryWriteReceipt>(
      `${baseUrlOf(attachment)}/api/v2/memory-writes/${encodeURIComponent(requestId)}`,
      {
+        ...(userId === undefined || userId === "local"
+          ? {}
+          : { params: { user_id: userId } }),
        headers: { Authorization: `Bearer ${attachment.apiToken}` },
        timeout: 10_000,
        proxy: false,
@@ -495,48 +587,52 @@ export async function readScanRoots(
  }
 }

+/** A direct Core write whose refusal carries Core's stable code. */
+export type CoreWriteResult =
+  | { ok: true; data: unknown }
+  | { ok: false; code: string };
+
+async function coreWrite(
+  attachment: RuntimeAttachmentLike,
+  method: "post" | "delete",
+  pathname: string,
+  body: Record<string, unknown>,
+  timeout = 10_000,
+): Promise<CoreWriteResult> {
+  let response: { status: number; data: unknown };
+  try {
+    response = await axios.request({
+      method,
+      url: `${baseUrlOf(attachment)}${pathname}`,
+      data: body,
+      headers: { Authorization: `Bearer ${attachment.apiToken}` },
+      timeout,
+      proxy: false,
+      maxRedirects: 0,
+      maxContentLength: MAX_RESPONSE_BYTES,
+      validateStatus: () => true,
+    });
+  } catch {
+    return { ok: false, code: "transport_failed" };
+  }
+  if (response.status >= 200 && response.status < 300) {
+    return { ok: true, data: response.data };
+  }
+  return { ok: false, code: detailCode(response.data, response.status) };
+}
+
 export async function addScanRoot(
  attachment: RuntimeAttachmentLike,
  body: { root: string; source?: string; recursive?: boolean },
-): Promise<unknown | null> {
-  try {
-    const response = await axios.post<unknown>(
-      `${baseUrlOf(attachment)}/api/v1/scan-roots`,
-      body,
-      {
-        headers: { Authorization: `Bearer ${attachment.apiToken}` },
-        timeout: 10_000,
-        proxy: false,
-        maxRedirects: 0,
-        maxContentLength: MAX_RESPONSE_BYTES,
-      },
-    );
-    return response.data;
-  } catch (error) {
-    return { _error: error instanceof Error ? error.message : String(error) };
-  }
+): Promise<CoreWriteResult> {
+  return coreWrite(attachment, "post", "/api/v1/scan-roots", body);
 }

 export async function removeScanRoot(
  attachment: RuntimeAttachmentLike,
  body: { root: string },
-): Promise<unknown | null> {
-  try {
-    const response = await axios.delete<unknown>(
-      `${baseUrlOf(attachment)}/api/v1/scan-roots`,
-      {
-        headers: { Authorization: `Bearer ${attachment.apiToken}` },
-        data: body,
-        timeout: 10_000,
-        proxy: false,
-        maxRedirects: 0,
-        maxContentLength: MAX_RESPONSE_BYTES,
-      },
-    );
-    return response.data;
-  } catch (error) {
-    return { _error: error instanceof Error ? error.message : String(error) };
-  }
+): Promise<CoreWriteResult> {
+  return coreWrite(attachment, "delete", "/api/v1/scan-roots", body);
 }

 export async function readAdapters(
@@ -562,21 +658,12 @@ export async function readAdapters(
 export async function probeAdapter(
  attachment: RuntimeAttachmentLike,
  source: string,
-): Promise<unknown | null> {
-  try {
-    const response = await axios.post<unknown>(
-      `${baseUrlOf(attachment)}/api/v1/adapters/probe`,
-      { source },
-      {
-        headers: { Authorization: `Bearer ${attachment.apiToken}` },
-        timeout: 15_000,
-        proxy: false,
-        maxRedirects: 0,
-        maxContentLength: MAX_RESPONSE_BYTES,
-      },
-    );
-    return response.data;
-  } catch (error) {
-    return { _error: error instanceof Error ? error.message : String(error) };
-  }
+): Promise<CoreWriteResult> {
+  return coreWrite(
+    attachment,
+    "post",
+    "/api/v1/adapters/probe",
+    { source },
+    15_000,
+  );
 }
@@ -4,9 +4,12 @@ const WRITE_PATHS = [
  "/api/v1/sources/connect",
  "/api/v1/model-profiles",
 ] as const;
-const MEMORY_WRITE_PATH =
-  /^\/api\/v1\/memories(?:\/[A-Za-z0-9][\w.-]{0,127}\/(?:correct|scopes|actions\/delete))?$/;
-const SDK_MEMORY_PATH = /^\/api\/v2\/memories\/[A-Za-z0-9][\w.-]{0,127}$/;
+/** `POST /api/v2/memories` adds one memory (the app's 添加记忆). */
+const MEMORY_ADD_PATH = "/api/v2/memories";
+/** One SDK memory; delete names its namespace, and a non-default user, in
+ * the query string. */
+const SDK_MEMORY_PATH =
+  /^\/api\/v2\/memories\/[A-Za-z0-9][\w.-]{0,127}(?:\?(?:kind=(?:chat|experience|fact)(?:&variant=(?:working|coding))?(?:&user_id=[A-Za-z0-9._-]{1,64})?|user_id=[A-Za-z0-9._-]{1,64}))?$/;
 const MODEL_PROBE_PATH =
  /^\/api\/v1\/model-profiles\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/probe$/;
 const MODEL_PROFILE_PATH =
@@ -22,24 +25,33 @@ const SOURCE_REVOKE_PATH =
 const SOURCE_IMPORT_JOB_PATH = "/api/v1/import-jobs";
 const IMPORT_JOB_ACTION_PATH =
  /^\/api\/v1\/import-jobs\/[A-Za-z0-9][\w.-]{0,127}\/(?:pause|resume|cancel)$/;
-const CALL_EVENTS_CLEAR_PATH = "/api/v1/call-events/clear";
-const CALL_EVENTS_CLEAR_ALL_PATH = "/api/v1/call-events/clear-all";
-const IMPORT_FILE_COMMIT =
-  /^\/api\/v1\/import-files\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/commit$/;
-const IMPORT_FILE =
-  /^\/api\/v1\/import-files\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
-const MEMORY_NOTES_PATH = "/api/v1/memory-notes";
-const MEMORY_NOTE_PROCESS =
-  /^\/api\/v1\/memory-notes\/[A-Za-z0-9][\w.:-]{0,127}\/process$/;
-const EXTRACTION_SETTINGS_PATH = "/api/v1/extraction-settings";
 const GRAPH_WIDTH_PATH = "/api/v1/graph-width";
-const MANUAL_EXTRACT_PATH = "/api/v1/memory-processing/manual-extract";
+/** `memhub evolve` starts a run; `memhub settings mode <m> --yes` sets the mode. */
+const EVOLVE_PATH = "/api/v2/evolve";
+const MEMORY_MODE_PATH = "/api/v1/settings/memory-mode";
+/** `memhub settings features set|reset` sets the SDK features. */
+const MEMORY_FEATURES_PATH = "/api/v1/settings/memory-features";
 const ONBOARDING_COMPLETE_PATH = "/api/v1/onboarding/complete";
+const EMBEDDING_SWITCH_PATHS = [
+  "/api/v1/embedding-switches",
+  "/api/v1/embedding-switches/plan",
+] as const;
+const EMBEDDING_SWITCH_CANCEL =
+  /^\/api\/v1\/embedding-switches\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/cancel$/;
+const EMBEDDING_SPACE_PATH =
+  /^\/api\/v1\/embedding-spaces\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const MAX_BYTES = 4 * 1024 * 1024;

 export type OperationOutcome<T> =
  | { state: "committed"; data: T }
-  | { state: "rejected"; code: string; http_status: number }
+  | {
+      state: "rejected";
+      code: string;
+      http_status: number;
+      /** Core's refusal body, when it carries more than the code (a switch
+       * plan rides along with `embedding_switch_required`). */
+      body?: unknown;
+    }
  | { state: "unknown"; code: string };

 export interface CoreOperations {
@@ -70,18 +82,6 @@ export interface CorePatchOperations {
  ): Promise<OperationOutcome<T>>;
 }

-export interface CoreUploadOperations {
-  uploadImportFile<T>(
-    input: {
-      bytes: Uint8Array;
-      filename: string;
-      inputKind: "raw_conversation" | "memory_content";
-      operationId: string;
-    },
-    signal?: AbortSignal,
-  ): Promise<OperationOutcome<T>>;
-}
-
 export function createCoreOperations(attachment: {
  host: string;
  port: number;
@@ -90,8 +90,7 @@ export function createCoreOperations(attachment: {
 }): CoreOperations &
  CoreDeleteOperations &
  CorePutOperations &
-  CorePatchOperations &
-  CoreUploadOperations {
+  CorePatchOperations {
  const client = axios.create({
    baseURL: `http://${attachment.host}:${attachment.port}`,
    headers: { Authorization: `Bearer ${attachment.apiToken}` },
@@ -102,18 +101,6 @@ export function createCoreOperations(attachment: {
    maxBodyLength: 128 * 1024,
    validateStatus: () => true,
  });
-  // Uploads carry up to 128 MiB of raw octet-stream, so they need a separate
-  // body limit and a deadline that leaves room for parsing on the Core side.
-  const uploadClient = axios.create({
-    baseURL: `http://${attachment.host}:${attachment.port}`,
-    headers: { Authorization: `Bearer ${attachment.apiToken}` },
-    timeout: 120_000,
-    proxy: false,
-    maxRedirects: 0,
-    maxContentLength: MAX_BYTES,
-    maxBodyLength: 128 * 1024 * 1024,
-    validateStatus: () => true,
-  });
  return {
    async post<T>(
      path: string,
@@ -123,20 +110,17 @@ export function createCoreOperations(attachment: {
      if (
        !(WRITE_PATHS as readonly string[]).includes(path) &&
        path !== SOURCE_IMPORT_JOB_PATH &&
-        !MEMORY_WRITE_PATH.test(path) &&
+        path !== MEMORY_ADD_PATH &&
        !MODEL_PROBE_PATH.test(path) &&
        !SOURCE_SYNC_PATH.test(path) &&
        !IMPORT_JOB_ACTION_PATH.test(path) &&
        !SOURCE_AUTHORIZE_PATH.test(path) &&
        !SOURCE_REVOKE_PATH.test(path) &&
-        path !== CALL_EVENTS_CLEAR_PATH &&
-        path !== CALL_EVENTS_CLEAR_ALL_PATH &&
-        !IMPORT_FILE_COMMIT.test(path) &&
-        path !== MEMORY_NOTES_PATH &&
-        !MEMORY_NOTE_PROCESS.test(path) &&
        path !== GRAPH_WIDTH_PATH &&
-        path !== MANUAL_EXTRACT_PATH &&
+        path !== EVOLVE_PATH &&
        path !== ONBOARDING_COMPLETE_PATH &&
+        !(EMBEDDING_SWITCH_PATHS as readonly string[]).includes(path) &&
+        !EMBEDDING_SWITCH_CANCEL.test(path) &&
        !MODEL_PROFILE_ACTIVATE.test(path)
      ) {
        throw new Error("core_operation_path_not_allowed");
@@ -154,11 +138,18 @@ export function createCoreOperations(attachment: {
      if (response.status >= 200 && response.status < 300) {
        return { state: "committed", data: response.data as T };
      }
-      if (response.status >= 400 && response.status < 500) {
+      if (
+        (response.status >= 400 && response.status < 500) ||
+        // Core answers a refusal it can name with 503 (`sdk_reembed_unavailable`)
+        // or 507 (`insufficient_disk_space`) on the switch routes.
+        ([503, 507].includes(response.status) &&
+          (EMBEDDING_SWITCH_PATHS as readonly string[]).includes(path))
+      ) {
        return {
          state: "rejected",
          code: safeErrorCode(response.data, response.status),
          http_status: response.status,
+          body: response.data,
        };
      }
      return {
@@ -171,7 +162,11 @@ export function createCoreOperations(attachment: {
      body: Record<string, unknown>,
      signal?: AbortSignal,
    ) {
-      if (path !== EXTRACTION_SETTINGS_PATH && !SDK_MEMORY_PATH.test(path)) {
+      if (
+        path !== MEMORY_MODE_PATH &&
+        path !== MEMORY_FEATURES_PATH &&
+        (!SDK_MEMORY_PATH.test(path) || path.includes("?"))
+      ) {
        throw new Error("core_operation_path_not_allowed");
      }
      let response: { status: number; data: unknown };
@@ -233,7 +228,11 @@ export function createCoreOperations(attachment: {
      };
    },
    async delete<T>(path: string, signal?: AbortSignal) {
-      if (!IMPORT_FILE.test(path) && !SDK_MEMORY_PATH.test(path)) {
+      if (
+        !SDK_MEMORY_PATH.test(path) &&
+        !MODEL_PROFILE_PATH.test(path) &&
+        !EMBEDDING_SPACE_PATH.test(path)
+      ) {
        throw new Error("core_operation_path_not_allowed");
      }
      let response: { status: number; data: unknown };
@@ -257,51 +256,6 @@ export function createCoreOperations(attachment: {
        code: `http_${response.status}_result_unknown`,
      };
    },
-    async uploadImportFile<T>(
-      input: {
-        bytes: Uint8Array;
-        filename: string;
-        inputKind: "raw_conversation" | "memory_content";
-        operationId: string;
-      },
-      signal?: AbortSignal,
-    ) {
-      const query = new URLSearchParams({
-        filename: input.filename,
-        input_kind: input.inputKind,
-        operation_id: input.operationId,
-      });
-      let response: { status: number; data: unknown };
-      try {
-        response = await uploadClient.post(
-          `/api/v1/import-files?${query.toString()}`,
-          input.bytes,
-          {
-            headers: {
-              "Content-Type": "application/octet-stream",
-              "Content-Length": String(input.bytes.byteLength),
-            },
-            ...(signal ? { signal } : {}),
-          },
-        );
-      } catch {
-        return { state: "unknown", code: "transport_result_unknown" };
-      }
-      if (response.status >= 200 && response.status < 300) {
-        return { state: "committed", data: response.data as T };
-      }
-      if (response.status >= 400 && response.status < 500) {
-        return {
-          state: "rejected",
-          code: safeErrorCode(response.data, response.status),
-          http_status: response.status,
-        };
-      }
-      return {
-        state: "unknown",
-        code: `http_${response.status}_result_unknown`,
-      };
-    },
  };
 }

@@ -0,0 +1,488 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { run } from "./cli.js";
+import { renderContextText } from "./context-search.js";
+import { describeEmbeddingSwitchSummary } from "./embedding-switch-flow.js";
+import { composeStatusReport, renderStatusText } from "./status-report.js";
+
+const transport = vi.hoisted(() => ({
+  get: vi.fn(),
+  post: vi.fn(),
+  put: vi.fn(),
+  patch: vi.fn(),
+  delete: vi.fn(),
+}));
+vi.mock("axios", () => ({
+  default: { create: vi.fn(() => transport), get: vi.fn() },
+}));
+
+const runtime = vi.hoisted(() => ({
+  inspectRuntimeStatus: vi.fn(),
+  discoverRuntimeAttachment: vi.fn(),
+}));
+vi.mock("@one-memory/runtime-control", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@one-memory/runtime-control")>()),
+  ...runtime,
+}));
+
+const PROFILE = "44444444-4444-4444-8444-444444444444";
+const JOB = "55555555-5555-4555-8555-555555555555";
+const SPACE = "66666666-6666-4666-8666-666666666666";
+
+function plan(overrides: Record<string, unknown> = {}) {
+  return {
+    needed: true,
+    reason: "embedding_identity_changed",
+    plan_token: "token-1",
+    source: {
+      space_id: "77777777-7777-4777-8777-777777777777",
+      model: "bge-small-zh-v1.5",
+      dims: 512,
+      collection_base: "memhub_aaaaaaaaaaaaaaaa",
+      vectors: 12480,
+    },
+    target: {
+      space_id: null,
+      model: "text-embedding-v3",
+      dims: 1024,
+      collection_base: "",
+    },
+    target_profile_id: PROFILE,
+    target_revision: 5,
+    target_provider_kind: "openai_compatible",
+    target_local: false,
+    sources: [],
+    total_vectors: 12480,
+    users: 2,
+    graph_vectors: null,
+    estimate_s: 120,
+    requests: 195,
+    disk_bytes_needed: 70 * 1024 * 1024,
+    disk_bytes_free: 10 * 1024 * 1024 * 1024,
+    retention_days: 14,
+    blockers: [],
+    ...overrides,
+  };
+}
+
+function job(
+  state: string,
+  percent: number,
+  extra: Record<string, unknown> = {},
+) {
+  return {
+    job_id: JOB,
+    kind: "switch",
+    state,
+    source: plan().source,
+    target: { ...plan().target, space_id: SPACE },
+    stray_space_ids: [],
+    target_profile_id: PROFILE,
+    target_revision: 5,
+    requested_by: "cli",
+    progress: {
+      phase: state === "reembedding" ? "vectors" : "prepare",
+      done: Math.round((12480 * percent) / 100),
+      total: 12480,
+      percent,
+      eta_s: 60,
+    },
+    cancel_requested: false,
+    error_code: null,
+    attempt: 1,
+    created_at: "T1",
+    updated_at: "T1",
+    finished_at: state === "done" ? "T2" : null,
+    ...extra,
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  for (const method of Object.values(transport)) method.mockReset();
+  runtime.inspectRuntimeStatus.mockResolvedValue({
+    state: "running",
+    code: "runtime_verified",
+    instanceId: "instance-1",
+    host: "127.0.0.1",
+    port: 8765,
+    version: "1.2.3",
+  });
+  runtime.discoverRuntimeAttachment.mockResolvedValue({
+    instanceId: "instance-1",
+    apiToken: "synthetic-runtime-token",
+    host: "127.0.0.1",
+    port: 8765,
+    servicePid: 4242,
+    health: {
+      status: "ok",
+      service: "one-memory-core",
+      version: "1.2.3",
+      instance_id: "instance-1",
+    },
+  });
+});
+
+describe("models activate with an embedding change", () => {
+  it("prints the plan and exits 2 without --yes on a non-terminal", async () => {
+    transport.post.mockImplementation(async (url: string) =>
+      url === "/api/v1/embedding-switches/plan"
+        ? { status: 200, data: plan() }
+        : { status: 404, data: {} },
+    );
+    const result = await capturedRun(["models", "activate", PROFILE]);
+    expect(result.code).toBe(2);
+    expect(result.stdout).toContain("将更换向量模型");
+    expect(result.stdout).toContain("bge-small-zh-v1.5（512 维）");
+    expect(result.stdout).toContain("text-embedding-v3（1024 维）");
+    expect(result.stdout).toContain("12,480");
+    expect(result.stdout).toContain("重新运行并加上 --yes 以确认");
+    expect(transport.post.mock.calls.map(([url]) => url)).toEqual([
+      "/api/v1/embedding-switches/plan",
+    ]);
+  });
+
+  it("starts the switch with --yes and emits JSON progress lines", async () => {
+    transport.post.mockImplementation(async (url: string) => {
+      if (url === "/api/v1/embedding-switches/plan") {
+        return { status: 200, data: plan() };
+      }
+      if (url === "/api/v1/embedding-switches") {
+        return { status: 202, data: job("preparing", 0) };
+      }
+      return { status: 404, data: {} };
+    });
+    const answers = [
+      {
+        phase: "running",
+        writes_paused: true,
+        job: job("reembedding", 50),
+        last_finished: null,
+      },
+      {
+        phase: "idle",
+        writes_paused: false,
+        job: null,
+        last_finished: job("done", 100),
+      },
+    ];
+    transport.get.mockImplementation(async (url: string) =>
+      url === "/api/v1/embedding-switches/current"
+        ? { status: 200, data: { schema_version: 1, ...answers.shift() } }
+        : { status: 404, data: {} },
+    );
+    const result = await capturedRun(
+      ["models", "activate", PROFILE, "--yes", "--wait", "--json"],
+      { watchWait: async () => undefined },
+    );
+    expect(result.code).toBe(0);
+    const lines = result.stdout
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line));
+    expect(lines.map((line) => line.state)).toEqual([
+      "preparing",
+      "reembedding",
+      "done",
+      "done",
+    ]);
+    expect(lines[1]).toMatchObject({ percent: 50, job_id: JOB });
+    expect(lines.at(-1)).toMatchObject({ result: "switched" });
+    expect(transport.post).toHaveBeenCalledWith(
+      "/api/v1/embedding-switches",
+      {
+        profile_id: PROFILE,
+        expected_revision: 5,
+        plan_token: "token-1",
+        requested_by: "cli",
+      },
+      undefined,
+    );
+  });
+
+  it("refuses a plan with blockers and starts nothing", async () => {
+    transport.post.mockResolvedValue({
+      status: 200,
+      data: plan({ blockers: ["sdk_reembed_unavailable"] }),
+    });
+    const result = await capturedRun([
+      "models",
+      "activate",
+      PROFILE,
+      "--yes",
+      "--json",
+    ]);
+    expect(result.code).toBe(1);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      state: "blocked",
+      code: "sdk_reembed_unavailable",
+    });
+    expect(transport.post).toHaveBeenCalledTimes(1);
+  });
+
+  it("says nothing is re-embedded when only generation changed", async () => {
+    transport.post.mockImplementation(async (url: string) =>
+      url === "/api/v1/embedding-switches/plan"
+        ? {
+            status: 200,
+            data: plan({ needed: false, reason: "same_embedding" }),
+          }
+        : { status: 200, data: profileResponse() },
+    );
+    const result = await capturedRun(["models", "activate", PROFILE]);
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain("向量模型未变化，无需重新生成向量。");
+  });
+
+  it("reads the plan carried by a 409 embedding_switch_required", async () => {
+    transport.post.mockImplementation(async (url: string) =>
+      url.endsWith("/activate")
+        ? {
+            status: 409,
+            data: { detail: "embedding_switch_required", plan: plan() },
+          }
+        : { status: 404, data: { detail: "Not Found" } },
+    );
+    const result = await capturedRun(["models", "activate", PROFILE, "--json"]);
+    expect(result.code).toBe(2);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      state: "confirmation_required",
+      code: "embedding_switch_required",
+    });
+  });
+});
+
+describe("models switch and spaces", () => {
+  it("reports no switch, then cancels the running one", async () => {
+    transport.get.mockResolvedValueOnce({
+      status: 200,
+      data: {
+        schema_version: 1,
+        phase: "idle",
+        writes_paused: false,
+        job: null,
+        last_finished: null,
+      },
+    });
+    const idle = await capturedRun(["models", "switch", "status"]);
+    expect(idle.code).toBe(0);
+    expect(idle.stdout).toContain("没有进行中的向量模型切换");
+
+    transport.get.mockResolvedValueOnce({
+      status: 200,
+      data: {
+        schema_version: 1,
+        phase: "running",
+        writes_paused: true,
+        job: job("reembedding", 20),
+        last_finished: null,
+      },
+    });
+    transport.post.mockResolvedValue({
+      status: 200,
+      data: job("reembedding", 20, { cancel_requested: true }),
+    });
+    const cancelled = await capturedRun([
+      "models",
+      "switch",
+      "cancel",
+      "--json",
+    ]);
+    expect(cancelled.code).toBe(0);
+    expect(transport.post).toHaveBeenCalledWith(
+      `/api/v1/embedding-switches/${JOB}/cancel`,
+      {},
+      undefined,
+    );
+    expect(JSON.parse(cancelled.stdout)).toMatchObject({
+      cancel_requested: true,
+    });
+  });
+
+  it("lists spaces and needs --yes before cleaning one up", async () => {
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: {
+        schema_version: 1,
+        live_space_id: "x",
+        spaces: [
+          {
+            space_id: SPACE,
+            state: "retired",
+            model: "bge-small-zh-v1.5",
+            dims: 512,
+            vectors: 10,
+            keep_until: "2026-11-15T00:00:00+00:00",
+          },
+          {
+            space_id: "88888888-8888-4888-8888-888888888888",
+            state: "dropped",
+            model: "m",
+            dims: 8,
+          },
+        ],
+        scanned: [],
+        scan_error: null,
+      },
+    });
+    const listed = await capturedRun(["models", "spaces"]);
+    expect(listed.code).toBe(0);
+    expect(listed.stdout).toContain("已停用");
+    expect(listed.stdout).toContain("保留到 2026-11-15");
+    expect(listed.stdout).not.toContain("88888888");
+
+    const preview = await capturedRun(["models", "spaces", "--cleanup", SPACE]);
+    expect(preview.code).toBe(0);
+    expect(preview.stdout).toContain("--yes");
+    expect(transport.delete).not.toHaveBeenCalled();
+
+    transport.delete.mockResolvedValue({
+      status: 200,
+      data: { schema_version: 1 },
+    });
+    const dropped = await capturedRun([
+      "models",
+      "spaces",
+      "--cleanup",
+      SPACE,
+      "--yes",
+    ]);
+    expect(dropped.code).toBe(0);
+    expect(transport.delete).toHaveBeenCalledWith(
+      `/api/v1/embedding-spaces/${SPACE}`,
+      undefined,
+    );
+  });
+});
+
+describe("status and search wording", () => {
+  it("shows the switch line in memhub status", async () => {
+    const reader = async (path: string) =>
+      path === "/api/v1/memory-processing"
+        ? {
+            state: "ok" as const,
+            data: {
+              pending: 3,
+              fresh_pending: 1,
+              backlog_pending: 2,
+              outside_window_pending: 0,
+              running: 0,
+              waiting_for_model: 0,
+              completed: 9,
+              failed: 0,
+              embedding_switch: {
+                job_id: JOB,
+                kind: "switch",
+                state: "reembedding",
+                percent: 50,
+                eta_s: 60,
+              },
+            },
+          }
+        : { state: "unavailable" as const, code: "http_503" };
+    const report = await composeStatusReport({
+      dataDir: "/synthetic/data",
+      runtime: {
+        state: "running",
+        code: "runtime_verified",
+        instanceId: "instance-1",
+        host: "127.0.0.1",
+        port: 8765,
+      } as never,
+      background: null,
+      reader: reader as never,
+    });
+    const text = renderStatusText(report, "MemHub");
+    expect(text).toContain("向量模型：切换中 50%，记忆整理已暂停");
+    expect(
+      describeEmbeddingSwitchSummary({
+        kind: "merge",
+        state: "reembedding",
+        percent: 30,
+      }),
+    ).toBe("正在合并旧向量数据 30%，记忆整理已暂停");
+    expect(
+      describeEmbeddingSwitchSummary({
+        kind: "merge",
+        state: "scanning",
+        percent: 0,
+      }),
+    ).toBe("正在检查向量数据…");
+  });
+
+  it("names an unavailable embedding service instead of 'try later'", () => {
+    expect(
+      renderContextText({
+        schema_version: 2,
+        product: "memhub",
+        state: "unavailable",
+        code: "embedding_unavailable",
+        items: [],
+      }),
+    ).toContain("向量服务不可用");
+  });
+});
+
+function profileResponse() {
+  return {
+    profile_id: PROFILE,
+    name: "Synthetic",
+    provider_kind: "openai_compatible",
+    base_url: "https://example.invalid/v1",
+    model: "synthetic-model-2",
+    embedding_model: "text-embedding-v3",
+    embedding_provider_kind: "openai_compatible",
+    embedding_base_url: "https://example.invalid/v1",
+    embedding_dimensions: 1024,
+    has_api_key: true,
+    credential_state: "available",
+    timeout_seconds: 30,
+    max_concurrency: 1,
+    context_window: null,
+    disable_thinking: true,
+    capabilities: {
+      endpoint_reachable: true,
+      model_available: true,
+      structured_output: true,
+      embedding_available: true,
+    },
+    revision: 5,
+    is_active: true,
+    created_at: "2026-09-19T00:00:00Z",
+    updated_at: "2026-09-19T00:00:00Z",
+  };
+}
+
+async function capturedRun(
+  arguments_: string[],
+  controls: Parameters<typeof run>[2] = {},
+) {
+  let stdout = "";
+  let stderr = "";
+  const stdoutSpy = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation((chunk) => {
+      stdout += String(chunk);
+      return true;
+    });
+  const stderrSpy = vi
+    .spyOn(process.stderr, "write")
+    .mockImplementation((chunk) => {
+      stderr += String(chunk);
+      return true;
+    });
+  try {
+    return {
+      code: await run(
+        arguments_,
+        { ONE_MEMORY_DATA_DIR: "/synthetic/data" },
+        { stdinIsTTY: false, ...controls },
+      ),
+      stdout,
+      stderr,
+    };
+  } finally {
+    stdoutSpy.mockRestore();
+    stderrSpy.mockRestore();
+  }
+}
@@ -0,0 +1,847 @@
+/**
+ * Switching the embedding model from the CLI: `models activate` when the
+ * embedding changes, `models switch status|cancel`, `models spaces`.
+ *
+ * Core owns every decision (`/api/v1/embedding-switches*`, contract
+ * `docs/contracts/embedding-switch-v1.md`). A change of embedding model or
+ * width is never applied by activation alone: Core plans a switch, the user
+ * confirms it, Core re-embeds every memory into a new space and only then
+ * makes it live. The CLI shows the plan, asks, starts the job and follows it.
+ */
+
+import type { CoreReader } from "./core-client.js";
+import type {
+  CoreDeleteOperations,
+  CoreOperations,
+  OperationOutcome,
+} from "./core-operations.js";
+import { EXIT_FAILED, EXIT_OK, EXIT_USAGE } from "./exit-codes.js";
+import {
+  activateModelProfile,
+  type ModelWriteDocument,
+  modelProfileResult,
+  renderModelWriteText,
+} from "./model-write-flows.js";
+import { PRODUCT } from "./version.js";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const CODE = /^[a-z0-9_.:-]{1,128}$/;
+const TERMINAL = new Set(["done", "rolled_back"]);
+const POLL_MS = 1_000;
+
+export interface SpaceSummary {
+  space_id: string | null;
+  model: string | null;
+  dims: number | null;
+  collection_base: string;
+  vectors?: number | null;
+}
+
+export interface EmbeddingSwitchPlan {
+  needed: boolean;
+  reason: string;
+  plan_token: string;
+  source: SpaceSummary;
+  target: SpaceSummary;
+  target_profile_id: string;
+  target_revision: number;
+  target_provider_kind: string;
+  target_local: boolean;
+  total_vectors: number;
+  users: number | null;
+  graph_vectors: number | null;
+  estimate_s: number | null;
+  requests: number | null;
+  disk_bytes_needed: number;
+  disk_bytes_free: number | null;
+  retention_days: number;
+  blockers: string[];
+}
+
+export interface SwitchProgress {
+  phase: string;
+  done: number;
+  total: number;
+  percent: number;
+  eta_s: number | null;
+}
+
+export interface EmbeddingSwitchJob {
+  job_id: string;
+  kind: "switch" | "merge";
+  state: string;
+  source: SpaceSummary;
+  target: SpaceSummary;
+  progress: SwitchProgress;
+  cancel_requested: boolean;
+  error_code: string | null;
+  finished_at: string | null;
+}
+
+export interface SwitchCurrent {
+  phase: "idle" | "scanning" | "running";
+  writes_paused: boolean;
+  job: EmbeddingSwitchJob | null;
+  last_finished: EmbeddingSwitchJob | null;
+}
+
+export interface SwitchIo {
+  reader: CoreReader;
+  operations: CoreOperations & CoreDeleteOperations;
+  emit: (text: string) => void;
+  asJson: boolean;
+  /** A terminal is attached: may prompt, and follows progress by default. */
+  interactive: boolean;
+  confirm?: (question: string) => Promise<boolean>;
+  wait?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
+  signal?: AbortSignal;
+}
+
+export interface ActivateOptions {
+  confirmed: boolean;
+  /** `--wait` / `--no-wait`; undefined follows on a terminal only. */
+  follow?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Parsing: bounded projections of Core's answers, never passthrough.
+// ---------------------------------------------------------------------------
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function int(value: unknown): number | null {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
+    ? value
+    : null;
+}
+
+function str(value: unknown, max = 256): string | null {
+  return typeof value === "string" && value.length <= max ? value : null;
+}
+
+function space(value: unknown): SpaceSummary | null {
+  const item = record(value);
+  if (!item) return null;
+  return {
+    space_id: str(item.space_id, 64),
+    model: str(item.model),
+    dims: int(item.dims),
+    collection_base: str(item.collection_base) ?? "",
+    vectors: int(item.vectors),
+  };
+}
+
+export function parsePlan(value: unknown): EmbeddingSwitchPlan | null {
+  const plan = record(value);
+  if (!plan || typeof plan.needed !== "boolean") return null;
+  const source = space(plan.source);
+  const target = space(plan.target);
+  const token = str(plan.plan_token, 128);
+  const profile = str(plan.target_profile_id, 128);
+  const revision = int(plan.target_revision);
+  if (!source || !target || !token || !profile || revision === null) {
+    return null;
+  }
+  const blockers = Array.isArray(plan.blockers)
+    ? plan.blockers.filter(
+        (item): item is string => typeof item === "string" && CODE.test(item),
+      )
+    : [];
+  return {
+    needed: plan.needed,
+    reason: str(plan.reason, 64) ?? "",
+    plan_token: token,
+    source,
+    target,
+    target_profile_id: profile,
+    target_revision: revision,
+    target_provider_kind: str(plan.target_provider_kind, 64) ?? "",
+    target_local: plan.target_local === true,
+    total_vectors: int(plan.total_vectors) ?? 0,
+    users: int(plan.users),
+    graph_vectors: int(plan.graph_vectors),
+    estimate_s: int(plan.estimate_s),
+    requests: int(plan.requests),
+    disk_bytes_needed: int(plan.disk_bytes_needed) ?? 0,
+    disk_bytes_free: int(plan.disk_bytes_free),
+    retention_days: int(plan.retention_days) ?? 14,
+    blockers,
+  };
+}
+
+export function parseJob(value: unknown): EmbeddingSwitchJob | null {
+  const job = record(value);
+  if (!job) return null;
+  const jobId = str(job.job_id, 64);
+  const state = str(job.state, 32);
+  const source = space(job.source);
+  const target = space(job.target);
+  const progress = record(job.progress) ?? {};
+  if (!jobId || !state || !source || !target) return null;
+  if (job.kind !== "switch" && job.kind !== "merge") return null;
+  const percent =
+    typeof progress.percent === "number" && Number.isFinite(progress.percent)
+      ? Math.min(100, Math.max(0, progress.percent))
+      : 0;
+  return {
+    job_id: jobId,
+    kind: job.kind,
+    state,
+    source,
+    target,
+    progress: {
+      phase: str(progress.phase, 32) ?? "prepare",
+      done: int(progress.done) ?? 0,
+      total: int(progress.total) ?? 0,
+      percent,
+      eta_s: int(progress.eta_s),
+    },
+    cancel_requested: job.cancel_requested === true,
+    error_code:
+      typeof job.error_code === "string" && CODE.test(job.error_code)
+        ? job.error_code
+        : null,
+    finished_at: str(job.finished_at, 64),
+  };
+}
+
+export function parseCurrent(value: unknown): SwitchCurrent | null {
+  const current = record(value);
+  if (!current) return null;
+  const phase = current.phase;
+  if (phase !== "idle" && phase !== "scanning" && phase !== "running") {
+    return null;
+  }
+  return {
+    phase,
+    writes_paused: current.writes_paused === true,
+    job: current.job == null ? null : parseJob(current.job),
+    last_finished:
+      current.last_finished == null ? null : parseJob(current.last_finished),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Wording
+// ---------------------------------------------------------------------------
+
+const BLOCKER_TEXT: Record<string, string> = {
+  embedding_switch_running: "上一次向量模型切换还在进行，请等待完成或先取消。",
+  embedding_probe_required: "新配置还没有通过探测；先运行 memhub models test。",
+  sdk_reembed_unavailable:
+    "当前运行时的 SDK 不支持重新生成向量，请先升级 MemHub。",
+  embedding_switch_requires_migration:
+    "还有旧版本的向量数据没有迁移完，请先完成升级迁移。",
+  embedding_dimensions_unknown:
+    "新配置的向量维度未知；先探测或在配置里写明 embedding_dimensions。",
+  insufficient_disk_space: "磁盘空间不足，无法容纳新旧两份向量数据。",
+};
+
+const FAILURE_TEXT: Record<string, string> = {
+  writes_did_not_drain: "等待正在进行的记忆整理结束超时",
+  embedding_service_failed: "向量服务连续请求失败",
+  embedding_dimensions_mismatch: "向量服务返回的维度与探测到的不一致",
+  embedding_verification_failed: "新向量没有通过校验",
+  target_profile_changed: "切换期间目标配置被修改",
+  embedding_switch_cancelled: "已取消",
+  model_secret_unavailable: "读不到向量服务的 API Key",
+  secure_storage_unavailable: "系统钥匙串不可用",
+  embedding_switch_clients_busy: "记忆图谱一直被占用，无法重新生成",
+};
+
+const STATE_TEXT: Record<string, string> = {
+  preparing: "准备中（等待记忆整理暂停）",
+  reembedding: "重新生成向量",
+  verifying: "校验新向量",
+  committing: "正式切换",
+  failed: "正在回滚",
+  done: "已完成",
+  rolled_back: "已回滚",
+};
+
+export function blockerText(code: string): string {
+  return BLOCKER_TEXT[code] ?? code;
+}
+
+function spaceLabel(item: SpaceSummary, local?: boolean): string {
+  const dims = item.dims === null ? "维度未知" : `${item.dims} 维`;
+  return `${item.model ?? "未知模型"}（${dims}${local ? "，本地" : ""}）`;
+}
+
+function duration(seconds: number | null): string {
+  if (seconds === null) return "未知";
+  if (seconds < 60) return `${Math.max(1, seconds)} 秒`;
+  return `${Math.round(seconds / 60)} 分钟`;
+}
+
+function megabytes(bytes: number | null): string {
+  return bytes === null ? "未知" : `${Math.ceil(bytes / (1024 * 1024))} MB`;
+}
+
+export function renderPlanText(plan: EmbeddingSwitchPlan): string {
+  const lines = [
+    `将更换向量模型：${spaceLabel(plan.source)} → ${spaceLabel(plan.target, plan.target_local)}`,
+    `需要用新模型重新生成 ${plan.total_vectors.toLocaleString("en-US")} 条向量` +
+      `${plan.users === null ? "" : `（${plan.users} 个用户）`}` +
+      `，预计约 ${duration(plan.estimate_s)}` +
+      `${plan.requests === null ? "，在本机计算，不产生费用" : `，约 ${plan.requests} 次请求`}` +
+      `，额外磁盘约 ${megabytes(plan.disk_bytes_needed)}。`,
+  ];
+  if (plan.graph_vectors) {
+    lines.push(`记忆图谱另有 ${plan.graph_vectors} 条向量一并重新生成。`);
+  }
+  if (
+    plan.source.dims !== null &&
+    plan.source.dims === plan.target.dims &&
+    plan.source.model !== plan.target.model
+  ) {
+    lines.push("新旧模型维度相同，但向量不能通用，仍需重新生成。");
+  }
+  lines.push(
+    "切换期间记忆整理暂停，检索继续使用旧模型；完成并校验通过后才会生效。",
+    `旧的向量数据保留 ${plan.retention_days} 天，可用 memhub models spaces 清理。`,
+  );
+  for (const blocker of plan.blockers) {
+    lines.push(`无法开始：${blockerText(blocker)}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function renderProgressLine(job: EmbeddingSwitchJob): string {
+  const what = job.kind === "merge" ? "正在合并旧向量数据" : "正在切换向量模型";
+  const state = STATE_TEXT[job.state] ?? job.state;
+  if (job.state === "reembedding" && job.progress.total > 0) {
+    const eta =
+      job.progress.eta_s === null
+        ? ""
+        : `  预计还需 ${duration(job.progress.eta_s)}`;
+    return `${what}：${state}  ${job.progress.done.toLocaleString("en-US")}/${job.progress.total.toLocaleString("en-US")}  ${Math.floor(job.progress.percent)}%${eta}`;
+  }
+  return `${what}：${state}`;
+}
+
+export function renderOutcomeText(job: EmbeddingSwitchJob): string {
+  if (job.state === "done") {
+    return job.kind === "merge"
+      ? "旧向量数据已合并，记忆整理已恢复。\n"
+      : `已切换到 ${job.target.model ?? "新模型"}。\n`;
+  }
+  const code = job.error_code ?? "embedding_switch_failed";
+  if (code === "embedding_switch_cancelled") {
+    return `已取消切换，继续使用 ${job.source.model ?? "旧模型"}。\n`;
+  }
+  return `切换未完成，已恢复使用 ${job.source.model ?? "旧模型"}，数据未受影响。原因：${FAILURE_TEXT[code] ?? code}（${code}）\n`;
+}
+
+/** One line for `memhub status`, from `memory-processing.embedding_switch`. */
+export function describeEmbeddingSwitchSummary(value: unknown): string | null {
+  const summary = record(value);
+  if (!summary) return null;
+  const percent =
+    typeof summary.percent === "number" && Number.isFinite(summary.percent)
+      ? Math.floor(summary.percent)
+      : 0;
+  if (summary.state === "scanning") return "正在检查向量数据…";
+  if (summary.kind === "merge") {
+    return `正在合并旧向量数据 ${percent}%，记忆整理已暂停`;
+  }
+  if (summary.state === "failed") return "切换未完成，正在恢复旧向量模型";
+  return `切换中 ${percent}%，记忆整理已暂停`;
+}
+
+// ---------------------------------------------------------------------------
+// Flows
+// ---------------------------------------------------------------------------
+
+function document(
+  command: string,
+  fields: Record<string, unknown>,
+): Record<string, unknown> {
+  return { schema_version: 1, product: PRODUCT, command, ...fields };
+}
+
+function emitDocument(io: SwitchIo, value: Record<string, unknown>): void {
+  io.emit(`${JSON.stringify(value)}\n`);
+}
+
+async function requestPlan(
+  profileId: string,
+  io: SwitchIo,
+): Promise<
+  | { state: "plan"; plan: EmbeddingSwitchPlan }
+  | { state: "unsupported" }
+  | { state: "failed"; code: string }
+> {
+  const outcome = await io.operations.post<unknown>(
+    "/api/v1/embedding-switches/plan",
+    { profile_id: profileId },
+  );
+  if (outcome.state === "committed") {
+    const plan = parsePlan(outcome.data);
+    // Not a plan: activation itself still refuses an embedding change.
+    return plan ? { state: "plan", plan } : { state: "unsupported" };
+  }
+  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") {
+      return { state: "unsupported" };
+    }
+    const plan = parsePlan(record(outcome.body)?.plan);
+    if (plan) return { state: "plan", plan };
+    return { state: "failed", code: outcome.code };
+  }
+  return { state: "failed", code: outcome.code };
+}
+
+function emitActivation(io: SwitchIo, result: ModelWriteDocument): number {
+  io.emit(
+    io.asJson ? `${JSON.stringify(result)}\n` : renderModelWriteText(result),
+  );
+  return result.state === "committed" ? EXIT_OK : EXIT_FAILED;
+}
+
+/**
+ * `memhub models activate <id> [--yes] [--wait|--no-wait] [--json]`.
+ *
+ * Asks Core for the plan first. No embedding change: activate as before.
+ * An embedding change: show the plan, confirm (`--yes`, or a prompt on a
+ * terminal; exit 2 otherwise), start the switch and follow it.
+ */
+export async function activateWithEmbeddingSwitch(
+  profileId: string,
+  options: ActivateOptions,
+  io: SwitchIo,
+): Promise<number> {
+  if (!UUID.test(profileId)) {
+    return emitActivation(
+      io,
+      await activateModelProfile(profileId, io.operations),
+    );
+  }
+  const planned = await requestPlan(profileId, io);
+  if (planned.state === "unsupported") {
+    const activated = await activateOrPlan(profileId, io);
+    return activated.state === "plan"
+      ? confirmAndSwitch(activated.plan, options, io)
+      : emitActivation(io, activated.result);
+  }
+  if (planned.state === "failed") {
+    return reject(io, "models activate", planned.code);
+  }
+  const plan = planned.plan;
+  if (!plan.needed) {
+    if (!io.asJson && plan.reason === "same_embedding") {
+      io.emit("向量模型未变化，无需重新生成向量。\n");
+    }
+    const activated = await activateOrPlan(profileId, io);
+    if (activated.state === "plan") {
+      return confirmAndSwitch(activated.plan, options, io);
+    }
+    return emitActivation(io, activated.result);
+  }
+  return confirmAndSwitch(plan, options, io);
+}
+
+async function activateOrPlan(
+  profileId: string,
+  io: SwitchIo,
+): Promise<
+  | { state: "plan"; plan: EmbeddingSwitchPlan }
+  | { state: "activated"; result: ModelWriteDocument }
+> {
+  const result: OperationOutcome<unknown> = await io.operations.post<unknown>(
+    `/api/v1/model-profiles/${encodeURIComponent(profileId)}/activate`,
+    {},
+  );
+  if (
+    result.state === "rejected" &&
+    result.code === "embedding_switch_required"
+  ) {
+    const plan = parsePlan(record(result.body)?.plan);
+    if (plan) return { state: "plan", plan };
+  }
+  return { state: "activated", result: modelProfileResult(profileId, result) };
+}
+
+function reject(io: SwitchIo, command: string, code: string): number {
+  if (io.asJson) {
+    emitDocument(io, document(command, { state: "rejected", code }));
+  } else {
+    io.emit(`${command} 未完成：${blockerText(code)}（${code}）\n`);
+  }
+  return EXIT_FAILED;
+}
+
+async function confirmAndSwitch(
+  plan: EmbeddingSwitchPlan,
+  options: ActivateOptions,
+  io: SwitchIo,
+): Promise<number> {
+  if (plan.blockers.length > 0) {
+    if (io.asJson) {
+      emitDocument(
+        io,
+        document("models activate", {
+          state: "blocked",
+          code: plan.blockers[0],
+          plan,
+        }),
+      );
+    } else {
+      io.emit(renderPlanText(plan));
+    }
+    return EXIT_FAILED;
+  }
+  if (!options.confirmed) {
+    const ask = io.interactive && !io.asJson ? io.confirm : undefined;
+    if (ask === undefined) {
+      if (io.asJson) {
+        emitDocument(
+          io,
+          document("models activate", {
+            state: "confirmation_required",
+            code: "embedding_switch_required",
+            plan,
+            next_step: `${PRODUCT} models activate ${plan.target_profile_id} --yes`,
+          }),
+        );
+      } else {
+        io.emit(`${renderPlanText(plan)}重新运行并加上 --yes 以确认\n`);
+      }
+      return EXIT_USAGE;
+    }
+    io.emit(renderPlanText(plan));
+    if (!(await ask("继续？[y/N] "))) {
+      io.emit("未开始切换，仍在使用原来的向量模型。\n");
+      return EXIT_OK;
+    }
+  }
+  const started = await io.operations.post<unknown>(
+    "/api/v1/embedding-switches",
+    {
+      profile_id: plan.target_profile_id,
+      expected_revision: plan.target_revision,
+      plan_token: plan.plan_token,
+      requested_by: "cli",
+    },
+  );
+  if (started.state !== "committed") {
+    return reject(io, "models activate", started.code);
+  }
+  const job = parseJob(started.data);
+  if (!job) return reject(io, "models activate", "embedding_switch_invalid");
+  const follow = options.follow ?? io.interactive;
+  if (!follow) {
+    if (io.asJson) {
+      emitDocument(io, document("models activate", progressFields(job)));
+    } else {
+      io.emit(
+        `已开始切换向量模型（${job.job_id}）。用 memhub models switch status 查看进度。\n`,
+      );
+    }
+    return EXIT_OK;
+  }
+  return followJob(job, io, "models activate");
+}
+
+function progressFields(job: EmbeddingSwitchJob): Record<string, unknown> {
+  return {
+    state: job.state,
+    job_id: job.job_id,
+    kind: job.kind,
+    phase: job.progress.phase,
+    percent: job.progress.percent,
+    done: job.progress.done,
+    total: job.progress.total,
+    eta_s: job.progress.eta_s,
+    ...(job.error_code ? { code: job.error_code } : {}),
+  };
+}
+
+async function readCurrent(io: SwitchIo): Promise<SwitchCurrent | null> {
+  const outcome = await io.reader<unknown>(
+    "/api/v1/embedding-switches/current",
+  );
+  return outcome.state === "ok" ? parseCurrent(outcome.data) : null;
+}
+
+/** Poll `current` until the job ends or the user stops watching. */
+async function followJob(
+  started: EmbeddingSwitchJob,
+  io: SwitchIo,
+  command: string,
+): Promise<number> {
+  const wait = io.wait ?? defaultWait;
+  const signal = io.signal ?? new AbortController().signal;
+  let last = "";
+  let job = started;
+  const show = (value: EmbeddingSwitchJob) => {
+    const line = io.asJson
+      ? JSON.stringify(document(command, progressFields(value)))
+      : renderProgressLine(value);
+    if (line !== last) {
+      io.emit(`${line}\n`);
+      last = line;
+    }
+  };
+  show(job);
+  if (!io.asJson) {
+    io.emit(
+      "（Ctrl-C 只停止显示；用 `memhub models switch cancel` 取消切换）\n",
+    );
+  }
+  while (!TERMINAL.has(job.state)) {
+    try {
+      await wait(POLL_MS, signal);
+    } catch {
+      // Aborted below.
+    }
+    if (signal.aborted) {
+      if (!io.asJson) {
+        io.emit(
+          "已停止显示进度；切换仍在后台进行。用 `memhub models switch cancel` 取消。\n",
+        );
+      }
+      return EXIT_OK;
+    }
+    const current = await readCurrent(io);
+    if (current === null) continue;
+    const next =
+      current.job?.job_id === job.job_id
+        ? current.job
+        : current.last_finished?.job_id === job.job_id
+          ? current.last_finished
+          : null;
+    if (next === null) continue;
+    job = next;
+    show(job);
+  }
+  if (io.asJson) {
+    emitDocument(
+      io,
+      document(command, {
+        ...progressFields(job),
+        result: job.state === "done" ? "switched" : "rolled_back",
+      }),
+    );
+  } else {
+    io.emit(renderOutcomeText(job));
+  }
+  return job.state === "done" ? EXIT_OK : EXIT_FAILED;
+}
+
+function defaultWait(milliseconds: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(new Error("aborted"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, milliseconds);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new Error("aborted"));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** `memhub models switch status [--json]`. */
+export async function switchStatus(io: SwitchIo): Promise<number> {
+  const outcome = await io.reader<unknown>(
+    "/api/v1/embedding-switches/current",
+  );
+  if (outcome.state !== "ok")
+    return reject(io, "models switch status", outcome.code);
+  const current = parseCurrent(outcome.data);
+  if (!current) {
+    return reject(io, "models switch status", "embedding_switch_invalid");
+  }
+  if (io.asJson) {
+    emitDocument(
+      io,
+      document("models switch status", {
+        state: current.phase,
+        writes_paused: current.writes_paused,
+        job: current.job ? progressFields(current.job) : null,
+        last_finished: current.last_finished
+          ? progressFields(current.last_finished)
+          : null,
+      }),
+    );
+    return EXIT_OK;
+  }
+  if (current.job) {
+    io.emit(
+      `${renderProgressLine(current.job)}\n记忆整理已暂停，检索不受影响。\n`,
+    );
+  } else if (current.phase === "scanning") {
+    io.emit("正在检查向量数据…\n");
+  } else if (current.last_finished) {
+    io.emit(
+      `没有进行中的向量模型切换。上一次：${renderOutcomeText(current.last_finished)}`,
+    );
+  } else {
+    io.emit("没有进行中的向量模型切换。\n");
+  }
+  return EXIT_OK;
+}
+
+/** `memhub models switch cancel [--json]`: cancel the running job, if any. */
+export async function switchCancel(io: SwitchIo): Promise<number> {
+  const current = await readCurrent(io);
+  if (current === null) {
+    return reject(io, "models switch cancel", "embedding_switch_unavailable");
+  }
+  if (!current.job) {
+    return reject(io, "models switch cancel", "embedding_switch_not_found");
+  }
+  const outcome = await io.operations.post<unknown>(
+    `/api/v1/embedding-switches/${current.job.job_id}/cancel`,
+    {},
+  );
+  if (outcome.state !== "committed") {
+    return reject(io, "models switch cancel", outcome.code);
+  }
+  const job = parseJob(outcome.data) ?? current.job;
+  if (io.asJson) {
+    emitDocument(
+      io,
+      document("models switch cancel", {
+        ...progressFields(job),
+        cancel_requested: true,
+      }),
+    );
+  } else {
+    io.emit("已请求取消；当前批次完成后回滚，继续使用原来的向量模型。\n");
+  }
+  return EXIT_OK;
+}
+
+interface SpaceRow {
+  space_id: string;
+  state: string;
+  model: string | null;
+  dims: number | null;
+  vectors: number | null;
+  keep_until: string | null;
+}
+
+function spaceRows(value: unknown): SpaceRow[] | null {
+  const body = record(value);
+  if (!body || !Array.isArray(body.spaces)) return null;
+  const rows: SpaceRow[] = [];
+  for (const item of body.spaces) {
+    const row = record(item);
+    const spaceId = str(row?.space_id, 64);
+    const state = str(row?.state, 16);
+    if (!row || !spaceId || !state) return null;
+    if (state === "dropped") continue;
+    rows.push({
+      space_id: spaceId,
+      state,
+      model: str(row.model),
+      dims: int(row.dims) ?? int(row.name_dims),
+      vectors: int(row.vectors),
+      keep_until: str(row.keep_until, 64),
+    });
+  }
+  return rows;
+}
+
+const SPACE_STATE: Record<string, string> = {
+  live: "使用中",
+  building: "正在生成",
+  stray: "待合并",
+  retired: "已停用",
+};
+
+/** `memhub models spaces [--json]`. */
+export async function listSpaces(io: SwitchIo): Promise<number> {
+  const outcome = await io.reader<unknown>("/api/v1/embedding-spaces");
+  if (outcome.state !== "ok") return reject(io, "models spaces", outcome.code);
+  const rows = spaceRows(outcome.data);
+  if (!rows) return reject(io, "models spaces", "embedding_spaces_invalid");
+  const body = record(outcome.data) ?? {};
+  const unregistered = Array.isArray(body.scanned)
+    ? body.scanned
+        .map(record)
+        .filter(
+          (item): item is Record<string, unknown> =>
+            item !== null && item.state === "unregistered",
+        )
+        .map((item) => ({
+          collection_base: str(item.collection_base) ?? "",
+          vectors: int(item.vectors) ?? 0,
+        }))
+    : [];
+  if (io.asJson) {
+    emitDocument(
+      io,
+      document("models spaces", {
+        state: "ok",
+        spaces: rows,
+        unregistered,
+        scan_error:
+          typeof body.scan_error === "string" && CODE.test(body.scan_error)
+            ? body.scan_error
+            : null,
+      }),
+    );
+    return EXIT_OK;
+  }
+  const lines = ["向量空间："];
+  for (const row of rows) {
+    const dims = row.dims === null ? "维度未知" : `${row.dims} 维`;
+    const keep =
+      row.state === "retired" && row.keep_until
+        ? `，保留到 ${row.keep_until.slice(0, 10)}`
+        : "";
+    lines.push(
+      `  ${row.space_id}  ${SPACE_STATE[row.state] ?? row.state}  ${row.model ?? "未知模型"}（${dims}）  ${row.vectors ?? "?"} 条${keep}`,
+    );
+  }
+  for (const item of unregistered) {
+    lines.push(
+      `  （未登记）${item.collection_base}  ${item.vectors} 条，下次启动时合并`,
+    );
+  }
+  if (rows.some((row) => row.state === "retired")) {
+    lines.push(
+      "清理已停用的空间：memhub models spaces --cleanup <space-id> --yes",
+    );
+  }
+  io.emit(`${lines.join("\n")}\n`);
+  return EXIT_OK;
+}
+
+/** `memhub models spaces --cleanup <space-id> --yes`: drop a retired space now. */
+export async function cleanupSpace(
+  spaceId: string,
+  io: SwitchIo,
+): Promise<number> {
+  if (!UUID.test(spaceId)) {
+    return reject(io, "models spaces", "embedding_space_not_found");
+  }
+  const outcome = await io.operations.delete<unknown>(
+    `/api/v1/embedding-spaces/${spaceId}`,
+  );
+  if (outcome.state !== "committed") {
+    return reject(io, "models spaces", outcome.code);
+  }
+  if (io.asJson) {
+    emitDocument(
+      io,
+      document("models spaces", { state: "dropped", space_id: spaceId }),
+    );
+  } else {
+    io.emit(`已清理旧向量数据：${spaceId}\n`);
+  }
+  return EXIT_OK;
+}
@@ -23,39 +23,26 @@ function accountHomeDirectory(): string | undefined {
 async function main(): Promise<number> {
  const arguments_ = process.argv.slice(2);
  const command = arguments_[0];
-  const action = arguments_[1];
  // A preview (`--yes` absent) must not create or write any diagnostic file:
  // the contract is that it only emits a plan. Diagnostics for these commands
  // are initialized only once the caller has confirmed the mutation.
-  const confirmed = arguments_.includes("--yes")
-    ? true
-    : arguments_.includes("--confirm");
+  const confirmed = arguments_.includes("--yes");
  const installLike = [
    "install",
    "upgrade",
    "service-install",
    "service-uninstall",
  ].includes(command ?? "");
-  const planFileApply =
-    (command === "sources" && action === "import") ||
-    (command === "models" && (action === "configure" || action === "probe")) ||
-    (command === "processing" && action === "apply") ||
-    (command === "memories" && action === "apply");
-  const isPreview = (installLike || planFileApply) && !confirmed;
-  const mutating =
-    [
-      "start",
-      "stop",
-      "restart",
-      "install",
-      "upgrade",
-      "service-install",
-      "service-uninstall",
-    ].includes(command ?? "") ||
-    (command === "sources" && action === "import") ||
-    (command === "models" && ["configure", "probe"].includes(action ?? "")) ||
-    (command === "processing" && action === "apply") ||
-    (command === "memories" && action === "apply");
+  const isPreview = installLike && !confirmed;
+  const mutating = [
+    "start",
+    "stop",
+    "restart",
+    "install",
+    "upgrade",
+    "service-install",
+    "service-uninstall",
+  ].includes(command ?? "");
  let diagnostics: DiagnosticLogger | null = null;
  if (mutating && !isPreview) {
    try {
@@ -0,0 +1,93 @@
+/**
+ * `memhub graph-width`: the user's decision when the embedding width changed
+ * and the memory graph no longer matches it (`POST /api/v1/graph-width`).
+ *
+ * `keep_existing` and `export_first` change nothing irreversible and run
+ * directly. `rebuild_with_new` archives the current graph and rebuilds it, so
+ * the CLI asks for `--yes` before sending it.
+ */
+
+import { parseGraphWidthDecisionReceipt } from "@one-memory/operations";
+import type { CoreOperations } from "./core-operations.js";
+import { PRODUCT } from "./version.js";
+
+export const GRAPH_WIDTH_DECISIONS = [
+  "keep_existing",
+  "rebuild_with_new",
+  "export_first",
+] as const;
+export type GraphWidthDecision = (typeof GRAPH_WIDTH_DECISIONS)[number];
+
+/** The one decision that cannot be taken back. */
+export function graphWidthDecisionIsDestructive(
+  decision: GraphWidthDecision,
+): boolean {
+  return decision === "rebuild_with_new";
+}
+
+export type GraphWidthDocument =
+  | {
+      schema_version: 1;
+      product: string;
+      command: "graph-width";
+      state: "committed";
+      decision: GraphWidthDecision;
+      receipt: Record<string, unknown>;
+    }
+  | {
+      schema_version: 1;
+      product: string;
+      command: "graph-width";
+      state: "rejected" | "unknown";
+      decision: GraphWidthDecision;
+      code: string;
+    };
+
+export async function decideGraphWidth(
+  decision: GraphWidthDecision,
+  operations: CoreOperations,
+): Promise<GraphWidthDocument> {
+  const base = {
+    schema_version: 1 as const,
+    product: PRODUCT,
+    command: "graph-width" as const,
+    decision,
+  };
+  const result = await operations.post<unknown>("/api/v1/graph-width", {
+    decision,
+  });
+  if (result.state !== "committed") {
+    return { ...base, state: result.state, code: result.code };
+  }
+  const receipt = parseGraphWidthDecisionReceipt(result.data);
+  if (receipt === null) {
+    return { ...base, state: "unknown", code: "graph_width_receipt_invalid" };
+  }
+  return {
+    ...base,
+    state: "committed",
+    receipt: {
+      archived_path: receipt.archived_path ?? null,
+      exported_path: receipt.exported_path ?? null,
+      mismatch: receipt.mismatch ?? null,
+    },
+  };
+}
+
+export function graphWidthExitCode(document: GraphWidthDocument): number {
+  return document.state === "committed" ? 0 : 1;
+}
+
+export function renderGraphWidthText(document: GraphWidthDocument): string {
+  if (document.state === "committed") {
+    const lines = [`已执行图谱宽度决定：${document.decision}`];
+    if (document.receipt.exported_path) {
+      lines.push(`导出：${document.receipt.exported_path}`);
+    }
+    if (document.receipt.archived_path) {
+      lines.push(`旧图谱已归档：${document.receipt.archived_path}`);
+    }
+    return `${lines.join("\n")}\n`;
+  }
+  return `图谱宽度决定未完成：${document.state}（${document.code}）\n`;
+}
@@ -1,4 +1,4 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import type { ImportJob, ModelProfile } from "@one-memory/contracts";
 import {
  buildModelProfileCreateRequest,
@@ -26,45 +26,7 @@ const PROVIDERS = [
  "local_onnx",
 ] as const;

-interface SourceImportPlanBody {
-  schema_version: 1;
-  kind: "source_import";
-  request_id: string;
-  source_ids: string[];
-  source_roots: Record<string, string>;
-  source_candidate_revisions: Record<string, number>;
-  confirm_environment_overrides: boolean;
-  full_rescan: false;
-  onboarding: true;
-}
-
-export type SourceImportPlan = SourceImportPlanBody & { digest: string };
-
-interface ModelCreatePlanBody {
-  schema_version: 1;
-  kind: "model_profile_create";
-  operation_id: string;
-  config: Record<string, unknown>;
-}
-
-export type ModelCreatePlan = ModelCreatePlanBody & { digest: string };
-
-/** A removal only needs an id: there is no config to review, and inventing one
- * to fit the create shape would misrepresent what the command does.
- */
-export interface ModelRemovePlan {
-  schema_version: 1;
-  kind: "model_profile_remove";
-  target: string;
-}
-
 export type FlowDocument =
-  | {
-      schema_version: 1;
-      product: string;
-      state: "preview";
-      plan: SourceImportPlan | ModelCreatePlan | ModelRemovePlan;
-    }
  | {
      schema_version: 1;
      product: string;
@@ -133,10 +95,33 @@ function classifySourceImport(
  return committed(operationId, receipt);
 }

-export async function planSourceImport(
+/**
+ * Connect sources and import their history in one direct request.
+ *
+ * Reads the current candidates, refuses a source whose location comes from an
+ * environment override unless the caller confirmed overrides, and posts one
+ * `/sources/connect` (grant + history import + live sync). `requestId` is the
+ * idempotency key: re-running with the same id reads the first receipt.
+ */
+export async function connectSourcesWithImport(
  reader: CoreReader,
-  sourceIds: readonly string[],
+  operations: CoreOperations,
+  input: {
+    sourceIds: readonly string[];
+    confirmOverrides: boolean;
+    requestId?: string;
+    /** Whose grant this is. Omitted for the default user (`local`). */
+    userId?: string;
+    /** An absolute root other than the source's candidate (a Hermes
+     * profile). Core reads its identity itself, so the source's candidate
+     * root id and revision are not sent for it. */
+    root?: string;
+  },
 ): Promise<FlowDocument> {
+  const sourceIds = input.sourceIds;
+  // A second user's grant is not a first run, and a custom root has no
+  // candidate the app showed: both are a plain connect.
+  const profile = input.root !== undefined || input.userId !== undefined;
  if (
    sourceIds.length < 1 ||
    sourceIds.length > 32 ||
@@ -145,6 +130,8 @@ export async function planSourceImport(
  ) {
    return invalid("invalid_source_selection");
  }
+  const requestId = input.requestId ?? randomUUID();
+  if (!UUID.test(requestId)) return invalid("invalid_request_id");
  const outcome = await reader<unknown>("/api/v1/sources");
  if (outcome.state !== "ok") return fromReadFailure(outcome);
  const candidates = validateSourceConnectionCandidates(outcome.data);
@@ -156,69 +143,72 @@ export async function planSourceImport(
    return invalid("source_unavailable");
  }
  const items = selected.map(([candidate]) => candidate);
-  const body: SourceImportPlanBody = {
-    schema_version: 1,
-    kind: "source_import",
-    request_id: randomUUID(),
-    source_ids: [...sourceIds],
-    source_roots: Object.fromEntries(
-      items.map((item) => [item.source_id, item.candidate_root_id]),
-    ),
-    source_candidate_revisions: Object.fromEntries(
-      items.flatMap((item) =>
-        item.candidate_revision === undefined
-          ? []
-          : [[item.source_id, item.candidate_revision]],
-      ),
-    ),
-    confirm_environment_overrides: items.some(
-      (item) => item.requires_override_confirmation,
-    ),
-    full_rescan: false,
-    onboarding: true,
-  };
-  return preview(withDigest(body));
-}
-
-export async function executeSourceImport(
-  value: unknown,
-  reader: CoreReader,
-  operations: CoreOperations,
-): Promise<FlowDocument> {
-  const plan = validateSourcePlan(value);
-  if (!plan) return invalid("source_plan_invalid");
+  // A custom root is the caller's own choice, not the environment override
+  // the confirmation exists for.
+  const needsOverride =
+    input.root !== undefined
+      ? []
+      : items
+          .filter((item) => item.requires_override_confirmation)
+          .map((item) => item.source_id);
+  if (needsOverride.length > 0 && !input.confirmOverrides) {
+    return {
+      schema_version: 1,
+      product: PRODUCT,
+      state: "rejected",
+      operation_id: requestId,
+      code: "environment_override_confirmation_required",
+      receipt: { override_required_source_ids: needsOverride },
+    };
+  }
  // The shared builder owns the connect body's field set and coalescing, so
  // the CLI and the Web console send the same request by construction.
  let request: ReturnType<typeof buildSourceImportRequest>;
  try {
    request = buildSourceImportRequest({
-      sourceIds: plan.source_ids,
-      sourceRoots: plan.source_roots,
-      sourceCandidateRevisions: plan.source_candidate_revisions,
-      confirmEnvironmentOverrides: plan.confirm_environment_overrides,
-      fullRescan: plan.full_rescan,
-      onboarding: plan.onboarding,
+      sourceIds: [...sourceIds],
+      sourceRoots: Object.fromEntries(
+        items.flatMap((item) =>
+          input.root === undefined
+            ? [[item.source_id, item.candidate_root_id]]
+            : [],
+        ),
+      ),
+      sourceCandidateRevisions: Object.fromEntries(
+        items.flatMap((item) =>
+          item.candidate_revision === undefined || input.root !== undefined
+            ? []
+            : [[item.source_id, item.candidate_revision]],
+        ),
+      ),
+      confirmEnvironmentOverrides: needsOverride.length > 0,
+      fullRescan: false,
+      onboarding: !profile,
      enableSync: true,
-      requestId: plan.request_id,
+      requestId,
    });
  } catch (error) {
    if (error instanceof SourceImportInputError) {
-      return invalid("source_plan_invalid");
+      return invalid("invalid_source_selection");
    }
    throw error;
  }
-  const result = await operations.post<unknown>(request.path, request.body);
+  const result = await operations.post<unknown>(request.path, {
+    ...request.body,
+    ...(input.userId === undefined ? {} : { user_id: input.userId }),
+    ...(input.root === undefined ? {} : { root: input.root }),
+  });
  if (result.state === "rejected") {
-    return rejected(plan.request_id, result.code);
+    return rejected(requestId, result.code);
  }
  if (result.state === "committed") {
-    const receipt = validateSourceReceipt(result.data, plan.request_id);
-    if (!receipt) return unknown(plan.request_id, "source_receipt_invalid");
-    return classifySourceImport(plan.request_id, receipt);
+    const receipt = validateSourceReceipt(result.data, requestId);
+    if (!receipt) return unknown(requestId, "source_receipt_invalid");
+    return classifySourceImport(requestId, receipt);
  }
-  const recovered = await readSourceReceipt(reader, plan.request_id);
+  const recovered = await readSourceReceipt(reader, requestId);
  if (recovered.state === "unknown" || recovered.state === "not_found") {
-    return unknown(plan.request_id, result.code);
+    return unknown(requestId, result.code);
  }
  // A recovered receipt must be classified the same way as a fresh one: an
  // all-rejected or all-busy replay is still not success. Only a terminal
@@ -262,26 +252,23 @@ export async function readSourceReceipt(
  return committed(requestId, receipt);
 }

-export function planModelProfile(value: unknown): FlowDocument {
-  const config = validateModelConfig(value);
-  if (!config) return invalid("model_config_invalid");
-  const body: ModelCreatePlanBody = {
-    schema_version: 1,
-    kind: "model_profile_create",
-    operation_id: randomUUID(),
-    config,
-  };
-  return preview(withDigest(body));
-}
-
-export async function executeModelProfile(
+/**
+ * Create a model profile directly from a bounded config (never containing the
+ * key) plus an optional key read from a controlled file.
+ *
+ * `operationId` is Core's creation idempotency key; the receipt can be read
+ * later with `readModelReceipt`.
+ */
+export async function createModelProfile(
  value: unknown,
  apiKey: string | undefined,
  reader: CoreReader,
  operations: CoreOperations,
+  operationId: string = randomUUID(),
 ): Promise<FlowDocument> {
-  const plan = validateModelPlan(value);
-  if (!plan) return invalid("model_plan_invalid");
+  const config = validateModelConfig(value);
+  if (!config) return invalid("model_config_invalid");
+  if (!UUID.test(operationId)) return invalid("invalid_operation_id");
  // The shared create builder owns the body's allow-list, bounds and the
  // creation_operation_id/api_key handling, so the CLI and the Web console
  // send the same create request.
@@ -289,31 +276,31 @@ export async function executeModelProfile(
  try {
    request = buildModelProfileCreateRequest(
      {
-        ...(plan.config as Record<string, unknown>),
+        ...config,
        ...(apiKey === undefined ? {} : { api_key: apiKey }),
      } as Parameters<typeof buildModelProfileCreateRequest>[0],
-      plan.operation_id,
+      operationId,
    );
  } catch (error) {
    if (error instanceof ModelProfileInputError) {
-      return invalid("model_plan_invalid");
+      return invalid("model_config_invalid");
    }
    throw error;
  }
  const result = await operations.post<unknown>(request.path, request.body);
  if (result.state === "rejected") {
-    return rejected(plan.operation_id, result.code);
+    return rejected(operationId, result.code);
  }
  if (result.state === "committed") {
    const profile = validateModelProfile(result.data);
    return profile
-      ? committed(plan.operation_id, projectProfile(profile))
-      : unknown(plan.operation_id, "model_receipt_invalid");
+      ? committed(operationId, projectProfile(profile))
+      : unknown(operationId, "model_receipt_invalid");
  }
-  const recovered = await readModelReceipt(reader, plan.operation_id);
+  const recovered = await readModelReceipt(reader, operationId);
  return recovered.state === "committed"
    ? { ...recovered, state: "recovered" }
-    : unknown(plan.operation_id, result.code);
+    : unknown(operationId, result.code);
 }

 export async function readModelReceipt(
@@ -362,27 +349,6 @@ export function parseApiKey(bytes: Buffer | null): string | undefined {
 }

 export function renderFlowText(document: FlowDocument): string {
-  if (document.state === "preview") {
-    const plan = document.plan;
-    // A removal has no config digest or operation id to confirm: the target id
-    // *is* the thing being reviewed. Rendering fields it does not have would
-    // print "undefined".
-    if (plan.kind === "model_profile_remove") {
-      return [
-        `预览：${plan.kind}`,
-        `目标配置：${plan.target}`,
-        "未执行任何写操作。加 --confirm 才会真正删除。",
-        "",
-      ].join("\n");
-    }
-    return [
-      `预览：${plan.kind}`,
-      `操作 ID：${"request_id" in plan ? plan.request_id : plan.operation_id}`,
-      `确认摘要：${plan.digest}`,
-      "未执行任何写操作。请把 --json 输出保存为 plan 文件，再用对应命令加 --confirm。",
-      "",
-    ].join("\n");
-  }
  const lines = [
    `操作状态：${document.state}`,
    `操作 ID：${document.operation_id ?? "无"}`,
@@ -407,98 +373,20 @@ export function renderFlowText(document: FlowDocument): string {
    if (document.state === "partial" && Array.isArray(accepted)) {
      lines.push(`  已接入：${accepted.join("、")}`);
    }
+    const overrides = document.receipt.override_required_source_ids;
+    if (Array.isArray(overrides)) {
+      lines.push(
+        `  这些来源的目录来自环境变量覆盖，需要确认：${overrides.join("、")}`,
+        "  确认目录无误后加 --confirm-overrides 重新运行。",
+      );
+    }
  }
  lines.push("");
  return lines.join("\n");
 }

 export function flowExitCode(document: FlowDocument): number {
-  return ["preview", "committed", "recovered"].includes(document.state) ? 0 : 1;
-}
-
-export function inspectExecutionPlan(value: unknown): {
-  kind: "source_import" | "model_profile_create";
-  operationId: string;
-  digest: string;
-} | null {
-  const source = validateSourcePlan(value);
-  if (source) {
-    return {
-      kind: source.kind,
-      operationId: source.request_id,
-      digest: source.digest,
-    };
-  }
-  const model = validateModelPlan(value);
-  return model
-    ? {
-        kind: model.kind,
-        operationId: model.operation_id,
-        digest: model.digest,
-      }
-    : null;
-}
-
-function validateSourcePlan(value: unknown): SourceImportPlan | null {
-  const plan = record(value);
-  const requestId = asString(plan?.request_id);
-  if (
-    plan?.schema_version !== 1 ||
-    plan.kind !== "source_import" ||
-    !UUID.test(requestId) ||
-    !Array.isArray(plan.source_ids) ||
-    plan.source_ids.length < 1 ||
-    plan.source_ids.length > 32 ||
-    plan.source_ids.some(
-      (id) => typeof id !== "string" || !SOURCE_ID.test(id),
-    ) ||
-    new Set(plan.source_ids).size !== plan.source_ids.length ||
-    plan.full_rescan !== false ||
-    plan.onboarding !== true ||
-    typeof plan.confirm_environment_overrides !== "boolean" ||
-    typeof plan.digest !== "string"
-  ) {
-    return null;
-  }
-  const sourceIds = plan.source_ids as string[];
-  const roots = stringMap(plan.source_roots, sourceIds);
-  const revisions = numberMap(plan.source_candidate_revisions, sourceIds);
-  if (!roots || !revisions) return null;
-  const body: SourceImportPlanBody = {
-    schema_version: 1,
-    kind: "source_import",
-    request_id: requestId,
-    source_ids: [...sourceIds],
-    source_roots: roots,
-    source_candidate_revisions: revisions,
-    confirm_environment_overrides: plan.confirm_environment_overrides,
-    full_rescan: false,
-    onboarding: true,
-  };
-  const expected = withDigest(body);
-  return timingSafeText(expected.digest, plan.digest) ? expected : null;
-}
-
-function validateModelPlan(value: unknown): ModelCreatePlan | null {
-  const plan = record(value);
-  const operationId = asString(plan?.operation_id);
-  if (
-    plan?.schema_version !== 1 ||
-    plan.kind !== "model_profile_create" ||
-    !UUID.test(operationId) ||
-    typeof plan.digest !== "string"
-  ) {
-    return null;
-  }
-  const config = validateModelConfig(plan.config);
-  if (!config) return null;
-  const expected = withDigest<ModelCreatePlanBody>({
-    schema_version: 1,
-    kind: "model_profile_create",
-    operation_id: operationId,
-    config,
-  });
-  return timingSafeText(expected.digest, plan.digest) ? expected : null;
+  return ["committed", "recovered"].includes(document.state) ? 0 : 1;
 }

 function validateModelConfig(value: unknown): Record<string, unknown> | null {
@@ -644,37 +532,6 @@ function projectJob(job: ImportJob): Record<string, unknown> {
  };
 }

-function withDigest<T extends object>(body: T): T & { digest: string } {
-  return { ...body, digest: digest(body) };
-}
-
-function digest(value: unknown): string {
-  return createHash("sha256").update(canonical(value)).digest("hex");
-}
-
-function canonical(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
-  if (value && typeof value === "object") {
-    return `{${Object.keys(value)
-      .sort()
-      .map(
-        (key) =>
-          `${JSON.stringify(key)}:${canonical((value as Record<string, unknown>)[key])}`,
-      )
-      .join(",")}}`;
-  }
-  return JSON.stringify(value);
-}
-
-function preview(plan: SourceImportPlan | ModelCreatePlan): FlowDocument {
-  return {
-    schema_version: 1,
-    product: PRODUCT,
-    state: "preview",
-    plan,
-  };
-}
-
 function committed(
  operationId: string,
  receipt: Record<string, unknown>,
@@ -767,43 +624,3 @@ function optionalInteger(
      (value as number) <= maximum)
  );
 }
-
-function stringMap(
-  value: unknown,
-  keys: readonly string[],
-): Record<string, string> | null {
-  const map = record(value);
-  if (
-    !map ||
-    Object.keys(map).length !== keys.length ||
-    keys.some((key) => !boundedText(map[key], 256))
-  ) {
-    return null;
-  }
-  return Object.fromEntries(keys.map((key) => [key, map[key] as string]));
-}
-
-function numberMap(
-  value: unknown,
-  allowedKeys: readonly string[],
-): Record<string, number> | null {
-  const map = record(value);
-  if (
-    !map ||
-    Object.entries(map).some(
-      ([key, revision]) =>
-        !allowedKeys.includes(key) ||
-        !Number.isSafeInteger(revision) ||
-        (revision as number) < 0,
-    )
-  ) {
-    return null;
-  }
-  return Object.fromEntries(
-    Object.entries(map).map(([key, revision]) => [key, revision as number]),
-  );
-}
-
-function timingSafeText(expected: string, actual: unknown): boolean {
-  return typeof actual === "string" && expected === actual;
-}
@@ -1,64 +0,0 @@
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-
-import { initPlanAttemptPath } from "./cli.js";
-import { interactiveInitAttemptPath } from "./init-attempt.js";
-
-// Regression: `init --source <id> --import` used to pass the literal string
-// `"init"` to `claimPlanAttempt`, which resolved to `<cwd>/init.one-memory-attempt`.
-// Two consequences: the fence was shared across unrelated runs in the same
-// directory, and any unrelated file named `init` could make a valid import
-// report a misleading usage error (exit 2) instead of reading its receipt.
-describe("init import attempt fence", () => {
-  it("lives under the data dir, not the current working directory", () => {
-    const fence = initPlanAttemptPath(
-      "/tmp/example data",
-      "11111111-2222-4333-8444-555555555555",
-    );
-    expect(fence).toBe(
-      path.join(
-        "/tmp/example data",
-        ".cli-init-attempt-11111111-2222-4333-8444-555555555555",
-      ),
-    );
-    expect(path.isAbsolute(fence)).toBe(true);
-    expect(fence).not.toBe("init");
-    // Directly under the data dir: no nested directory that could fail to be
-    // created and turn a valid import into a usage error.
-    expect(path.dirname(fence)).toBe("/tmp/example data");
-  });
-
-  it("is per data dir and per operation, so installs/runs cannot collide", () => {
-    const a = initPlanAttemptPath("/tmp/data-a", "op-1");
-    const b = initPlanAttemptPath("/tmp/data-b", "op-1");
-    const c = initPlanAttemptPath("/tmp/data-a", "op-2");
-    expect(new Set([a, b, c]).size).toBe(3);
-  });
-});
-
-// QA-CLI R3 F1: the interactive wizard passed a CWD-relative singleton
-// (`init` or `<journalDir>/init`) to `claimPlanAttempt`. A stale
-// `init.one-memory-attempt` in the working directory then made every later
-// `memhub init` fail with "交互计划无效 / exit 2".
-describe("interactive init attempt fence", () => {
-  it("lives under the data dir and is unique per operation", () => {
-    const fence = interactiveInitAttemptPath(
-      "/tmp/data",
-      "11111111-2222-4333-8444-555555555555",
-    );
-    expect(fence).toBe(
-      path.join(
-        "/tmp/data",
-        ".cli-init-attempt-11111111-2222-4333-8444-555555555555",
-      ),
-    );
-    expect(path.isAbsolute(fence)).toBe(true);
-    expect(fence).not.toBe("init");
-  });
-
-  it("does not reuse one fence for two distinct plans", () => {
-    const first = interactiveInitAttemptPath("/tmp/data", "op-1");
-    const second = interactiveInitAttemptPath("/tmp/data", "op-2");
-    expect(first).not.toBe(second);
-  });
-});
@@ -1,16 +0,0 @@
-import path from "node:path";
-
-/** Where the interactive `init` wizard keeps its durable attempt fence.
- *
- * The wizard originally passed a CWD-relative singleton (`init`) to
- * `claimPlanAttempt`. That shared one fence across unrelated runs and let a
- * stale `init.one-memory-attempt` in the working directory turn every later
- * wizard run into "交互计划无效 / exit 2". Keep the fence under the Runtime's
- * data dir, keyed by the operation id, exactly like `init --source --import`.
- */
-export function interactiveInitAttemptPath(
-  dataDir: string,
-  operationId: string,
-): string {
-  return path.join(dataDir, `.cli-init-attempt-${operationId}`);
-}
@@ -418,9 +418,9 @@ describe("A2 dual-mode init", () => {
  });

  // QA-CLI R3 F1: a stale CWD `init.one-memory-attempt` used to poison every
-  // later wizard run. The fence now lives under the isolated data dir and is
-  // keyed by the operation id.
-  it("ignores a stale CWD init fence and keeps its fence under the data dir", async () => {
+  // later wizard run. There are no plan files or attempt fences any more: the
+  // connect request id is the idempotency key Core keeps.
+  it("ignores a stale CWD init fence and writes no fence files", async () => {
    transport.get.mockImplementation(async (url: string) =>
      url === "/api/v1/sources"
        ? { status: 200, data: [candidate("codex", "Codex")] }
@@ -471,7 +471,7 @@ describe("A2 dual-mode init", () => {
    const dataEntries = await readdir(dataDir);
    expect(
      dataEntries.some((entry) => entry.startsWith(".cli-init-attempt-")),
-    ).toBe(true);
+    ).toBe(false);
  });

  it("keeps selected Harnesses frozen without creating history jobs", async () => {
@@ -506,7 +506,7 @@ describe("A2 dual-mode init", () => {
  });
 });

-describe("A19 init --all-detected", () => {
+describe("A19 sources connect --all-detected (old spelling: init --all-detected)", () => {
  it("connects every found source in one batch call without prompting", async () => {
    transport.get.mockImplementation(async (url: string) =>
      url === "/api/v1/sources"
@@ -556,7 +556,7 @@ describe("A19 init --all-detected", () => {
    expect(prompter.asked).toBe(0);
    expect(code).toBe(0);
    const document = JSON.parse(streams.value());
-    expect(document.command).toBe("init");
+    expect(document.command).toBe("sources connect");
    expect(document.state).toBe("committed");
    expect(
      document.sources.map((row: { source_id: string }) => row.source_id),
@@ -4,18 +4,11 @@ import type {
  CoreDeleteOperations,
  CoreOperations,
 } from "./core-operations.js";
-import {
-  executeModelProfile,
-  type FlowDocument,
-  planModelProfile,
-} from "./headless-flows.js";
+import { createModelProfile, type FlowDocument } from "./headless-flows.js";
 import { approvalFingerprint, listHosts, readHost } from "./host-flow.js";
 import { parseSelection, type WizardPrompter } from "./init-wizard.js";
-import { executeModelProbe, planModelProbe } from "./model-probe-flow.js";
-import {
-  executeModelProfileActivate,
-  planModelProfileActivate,
-} from "./model-write-flows.js";
+import { startModelProbe } from "./model-probe-flow.js";
+import { activateModelProfile } from "./model-write-flows.js";

 type ProviderPreset = {
  id: string;
@@ -359,30 +352,26 @@ export async function runInteractiveModelSetup(
          );
        })
      : new Map<string, string>();
-    const planned = planModelProfile({
-      name: preset.label,
-      provider_kind: preset.provider_kind,
-      base_url: baseUrl,
-      model,
-      embedding_provider_kind: "local_onnx",
-      embedding_model: "bge-small-zh-v1.5",
-      embedding_dimensions: 512,
-      timeout_seconds: 90,
-      max_concurrency: 4,
-      disable_thinking: true,
-    });
-    if (
-      planned.state !== "preview" ||
-      planned.plan.kind !== "model_profile_create"
-    ) {
-      return { state: "failed", code: "model_config_invalid" };
-    }
-    const created = await executeModelProfile(
-      planned.plan,
+    const created = await createModelProfile(
+      {
+        name: preset.label,
+        provider_kind: preset.provider_kind,
+        base_url: baseUrl,
+        model,
+        embedding_provider_kind: "local_onnx",
+        embedding_model: "bge-small-zh-v1.5",
+        embedding_dimensions: 512,
+        timeout_seconds: 90,
+        max_concurrency: 4,
+        disable_thinking: true,
+      },
      apiKey,
      clients.reader,
      clients.operations,
    );
+    if (created.state === "invalid") {
+      return { state: "failed", code: "model_config_invalid" };
+    }
    const profile = receiptProfile(created);
    if (profile === null) {
      prompter.write("模型配置未保存。");
@@ -391,18 +380,11 @@ export async function runInteractiveModelSetup(
    }

    try {
-      const probePlan = await planModelProbe(
+      const probed = await startModelProbe(
        clients.reader,
+        clients.operations,
        profile.profile_id,
      );
-      const probed =
-        probePlan.state === "preview"
-          ? await executeModelProbe(
-              probePlan.plan,
-              clients.reader,
-              clients.operations,
-            )
-          : probePlan;
      if (!probePassed(probed)) {
        await clients.operations.delete(
          `/api/v1/model-profiles/${encodeURIComponent(profile.profile_id)}`,
@@ -421,17 +403,8 @@ export async function runInteractiveModelSetup(
      throw error;
    }

-    const activation = planModelProfileActivate({
-      profileId: profile.profile_id,
-    });
-    if (
-      activation.state !== "preview" ||
-      activation.plan.kind !== "model_profile_activate"
-    ) {
-      return { state: "failed", code: "model_activate_plan_invalid" };
-    }
-    const activated = await executeModelProfileActivate(
-      activation.plan,
+    const activated = await activateModelProfile(
+      profile.profile_id,
      clients.operations,
    );
    if (activated.state !== "committed") {
@@ -101,7 +101,7 @@ describe("memhub jobs", () => {
    expect(transport.post).not.toHaveBeenCalled();
  });

-  it("start previews without a POST", async () => {
+  it("start posts directly, without a preview step", async () => {
    const output = captureStdout();
    let code: number;
    try {
@@ -110,14 +110,14 @@ describe("memhub jobs", () => {
      output.restore();
    }
    expect(code!).toBe(0);
-    expect(transport.post).not.toHaveBeenCalled();
-    expect(JSON.parse(output.value())).toMatchObject({
-      state: "preview",
-      plan: { source_id: "codex", operation: "history" },
-    });
+    expect(transport.post).toHaveBeenCalledWith(
+      "/api/v1/import-jobs",
+      { source_id: "codex", operation: "history" },
+      undefined,
+    );
  });

-  it("start --confirm posts the exact Core request", async () => {
+  it("start still accepts a legacy --confirm", async () => {
    const output = captureStdout();
    let code: number;
    try {
@@ -146,7 +146,7 @@ describe("memhub jobs", () => {
  });

  it.each(["pause", "resume", "cancel"] as const)(
-    "%s previews without a POST",
+    "%s posts the action endpoint directly",
    async (action) => {
      const output = captureStdout();
      let code: number;
@@ -156,11 +156,11 @@ describe("memhub jobs", () => {
        output.restore();
      }
      expect(code!).toBe(0);
-      expect(transport.post).not.toHaveBeenCalled();
-      expect(JSON.parse(output.value())).toMatchObject({
-        state: "preview",
-        plan: { job_id: "job-1", action },
-      });
+      expect(transport.post).toHaveBeenCalledWith(
+        `/api/v1/import-jobs/job-1/${action}`,
+        {},
+        undefined,
+      );
    },
  );

@@ -107,7 +107,11 @@ export async function readLogReport(
  query: LogQuery,
 ): Promise<{
  events: DiagnosticEventV1[];
+  /** Lines that are not JSON: the only ones `memhub logs` calls damaged. */
  invalid_lines: number;
+  /** Whole JSON lines the reader leaves out, such as an older build's
+   * records. Nothing is wrong with them, so the text output says nothing. */
+  unrecognized_lines: number;
  failure?: "log_directory_unreadable";
 }> {
  // `readDiagnosticEvents` treats an unreadable logs path as "no events". That
@@ -119,6 +123,7 @@ export async function readLogReport(
    return {
      events: [],
      invalid_lines: 0,
+      unrecognized_lines: 0,
      failure: "log_directory_unreadable",
    };
  }
@@ -129,6 +134,7 @@ export async function readLogReport(
    return {
      events: [],
      invalid_lines: 0,
+      unrecognized_lines: 0,
      failure: "log_directory_unreadable",
    };
  }
@@ -0,0 +1,583 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { run } from "./cli.js";
+
+const transport = vi.hoisted(() => ({
+  get: vi.fn(),
+  post: vi.fn(),
+  put: vi.fn(),
+  patch: vi.fn(),
+  delete: vi.fn(),
+}));
+vi.mock("axios", () => ({
+  default: { create: vi.fn(() => transport), get: vi.fn() },
+}));
+
+const runtime = vi.hoisted(() => ({
+  inspectRuntimeStatus: vi.fn(),
+  discoverRuntimeAttachment: vi.fn(),
+}));
+vi.mock("@one-memory/runtime-control", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@one-memory/runtime-control")>()),
+  ...runtime,
+}));
+
+const REQUEST = "33333333-3333-4333-8333-333333333333";
+const EVIDENCE = "44444444-4444-4444-8444-444444444444";
+
+function addReceipt(state = "pending", memoryIds: string[] = []) {
+  return {
+    evidence_id: EVIDENCE,
+    text: "Prefers tea",
+    scope: "all-apps",
+    created_at: "2026-10-27T00:00:00Z",
+    state,
+    task_id: null,
+    memory_ids: memoryIds,
+    error: null,
+  };
+}
+
+function memoryRecord(overrides: Record<string, unknown> = {}) {
+  return {
+    memory_id: "exp-1",
+    content: "deploy\nrun make",
+    layer: "experience",
+    status: "active",
+    is_latest: true,
+    supersedes: [],
+    superseded_by: [],
+    tags: [],
+    owner: null,
+    source_raw_ids: [],
+    user_id: "local",
+    agent_id: "",
+    session_id: null,
+    source: "codebuddy",
+    memory_at: null,
+    gmt_created: 1_790_000_000,
+    scene: "working",
+    kind: "experience",
+    variant: "working",
+    task: "deploy",
+    solution: "run make",
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  transport.get.mockReset();
+  transport.post.mockReset();
+  transport.put.mockReset();
+  transport.patch.mockReset();
+  transport.delete.mockReset();
+  runtime.inspectRuntimeStatus.mockResolvedValue({
+    state: "running",
+    code: "runtime_verified",
+    instanceId: "instance-1",
+    host: "127.0.0.1",
+    port: 8765,
+    version: "1.2.3",
+  });
+  runtime.discoverRuntimeAttachment.mockResolvedValue({
+    instanceId: "instance-1",
+    apiToken: "synthetic-runtime-token",
+    host: "127.0.0.1",
+    port: 8765,
+    servicePid: 4242,
+    health: {
+      status: "ok",
+      service: "one-memory-core",
+      version: "1.2.3",
+      instance_id: "instance-1",
+    },
+  });
+});
+
+describe("memories add", () => {
+  it("adds one memory directly and prints the receipt with its request id", async () => {
+    transport.post.mockResolvedValue({ status: 201, data: addReceipt() });
+    const result = await capturedRun([
+      "memories",
+      "add",
+      "Prefers tea",
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    const [url, body] = transport.post.mock.calls[0];
+    expect(url).toBe("/api/v2/memories");
+    expect(body).toMatchObject({ text: "Prefers tea", scope: "all-apps" });
+    expect(body.request_id).toMatch(/^[0-9a-f-]{36}$/);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      schema_version: 2,
+      command: "memories add",
+      state: "accepted",
+      request_id: body.request_id,
+      receipt: { evidence_id: EVIDENCE, state: "pending" },
+    });
+  });
+
+  it("reuses --request-id so a retry is idempotent, and says so in text", async () => {
+    transport.post.mockResolvedValue({ status: 201, data: addReceipt() });
+    const result = await capturedRun([
+      "memories",
+      "add",
+      "Prefers tea",
+      "--request-id",
+      REQUEST,
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.post.mock.calls[0][1].request_id).toBe(REQUEST);
+    expect(result.stdout).toContain(`request_id: ${REQUEST}`);
+    expect(result.stdout).toContain(`memhub memories add-status ${REQUEST}`);
+  });
+
+  it("reads the text from a bounded file", async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), "om-memory-add-"));
+    const file = path.join(directory, "memory.txt");
+    await writeFile(file, "Prefers tea\n", { mode: 0o600 });
+    transport.post.mockResolvedValue({ status: 201, data: addReceipt() });
+    const result = await capturedRun([
+      "memories",
+      "add",
+      "--content-file",
+      file,
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.post.mock.calls[0][1].text).toBe("Prefers tea");
+  });
+
+  it("refuses bad input before contacting Core", async () => {
+    for (const argv of [
+      ["memories", "add"],
+      ["memories", "add", "a", "--content-file", "/tmp/x"],
+      ["memories", "add", "a", "--request-id", "not-a-uuid"],
+      ["memories", "add", "   "],
+      ["memories", "add", "x".repeat(12_001)],
+    ]) {
+      expect((await capturedRun(argv)).code).toBe(2);
+    }
+    expect(transport.post).not.toHaveBeenCalled();
+    expect(runtime.inspectRuntimeStatus).not.toHaveBeenCalled();
+  });
+
+  it("reports a Core conflict as rejected, on stdout, exit 1", async () => {
+    transport.post.mockResolvedValue({
+      status: 409,
+      data: { detail: "memory_add_conflict" },
+    });
+    const result = await capturedRun([
+      "memories",
+      "add",
+      "Other text",
+      "--request-id",
+      REQUEST,
+      "--json",
+    ]);
+    expect(result.code).toBe(1);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      state: "rejected",
+      code: "memory_add_conflict",
+      request_id: REQUEST,
+    });
+  });
+
+  it("never reports a malformed success body as accepted", async () => {
+    transport.post.mockResolvedValue({
+      status: 201,
+      data: { evidence_id: "x" },
+    });
+    const result = await capturedRun(["memories", "add", "tea", "--json"]);
+    expect(result.code).toBe(1);
+    expect(JSON.parse(result.stdout).state).toBe("unknown");
+  });
+
+  it("answers a stopped Runtime with exit 3 and writes nothing", async () => {
+    runtime.inspectRuntimeStatus.mockResolvedValue({
+      state: "stopped",
+      code: "runtime_not_running",
+    });
+    const result = await capturedRun(["memories", "add", "tea", "--json"]);
+    expect(result.code).toBe(3);
+    expect(JSON.parse(result.stdout).code).toBe("runtime_not_running");
+    expect(transport.post).not.toHaveBeenCalled();
+  });
+});
+
+describe("memories add-status", () => {
+  it("reads the addition by request id", async () => {
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: addReceipt("ready", ["m-1"]),
+    });
+    const result = await capturedRun([
+      "memories",
+      "add-status",
+      REQUEST,
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.get).toHaveBeenCalledWith(
+      `/api/v2/memories/additions/${REQUEST}`,
+      undefined,
+    );
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      command: "memories add-status",
+      state: "accepted",
+      receipt: { state: "ready", memory_ids: ["m-1"] },
+    });
+  });
+
+  it("reports an unknown request id as not_found, exit 1", async () => {
+    transport.get.mockResolvedValue({
+      status: 404,
+      data: { detail: "memory_add_not_found" },
+    });
+    const result = await capturedRun(["memories", "status", REQUEST]);
+    expect(result.code).toBe(1);
+    expect(result.stdout).toContain("未找到该 request id");
+  });
+
+  it("refuses a non-UUID request id", async () => {
+    expect((await capturedRun(["memories", "add-status", "abc"])).code).toBe(2);
+    expect(transport.get).not.toHaveBeenCalled();
+  });
+});
+
+describe("memories update / delete pass the namespace", () => {
+  it("updates an experience with kind, variant and task, directly", async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), "om-memory-update-"));
+    const file = path.join(directory, "solution.txt");
+    await writeFile(file, "run make deploy\n", { mode: 0o600 });
+    transport.put.mockResolvedValue({ status: 200, data: memoryRecord() });
+    const result = await capturedRun([
+      "memories",
+      "update",
+      "exp-1",
+      "--content-file",
+      file,
+      "--kind",
+      "experience",
+      "--variant",
+      "working",
+      "--task",
+      "deploy",
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.put).toHaveBeenCalledWith(
+      "/api/v2/memories/exp-1",
+      {
+        content: "run make deploy",
+        kind: "experience",
+        variant: "working",
+        task: "deploy",
+      },
+      undefined,
+    );
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      schema_version: 2,
+      state: "committed",
+      operation: "update",
+    });
+  });
+
+  it("refuses --task on anything but an experience, and a lone --variant", async () => {
+    for (const argv of [
+      ["memories", "update", "m-1", "--content-file", "/tmp/x", "--task", "t"],
+      [
+        "memories",
+        "update",
+        "m-1",
+        "--content-file",
+        "/tmp/x",
+        "--kind",
+        "fact",
+        "--variant",
+        "coding",
+        "--task",
+        "t",
+      ],
+      ["memories", "delete", "m-1", "--variant", "coding"],
+      ["memories", "delete", "m-1", "--kind", "chat", "--variant", "coding"],
+      ["memories", "show", "m-1", "--kind", "nope"],
+    ]) {
+      expect((await capturedRun(argv)).code).toBe(2);
+    }
+    expect(transport.put).not.toHaveBeenCalled();
+    expect(transport.delete).not.toHaveBeenCalled();
+  });
+
+  it("previews a delete without --yes and changes nothing", async () => {
+    const result = await capturedRun([
+      "memories",
+      "delete",
+      "fact-1",
+      "--kind",
+      "fact",
+      "--variant",
+      "coding",
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      schema_version: 2,
+      command: "memories delete",
+      state: "preview",
+      target: "fact-1",
+      applied: false,
+    });
+    expect(JSON.parse(result.stdout).next_step).toContain(
+      "--kind fact --variant coding --yes",
+    );
+    expect(transport.delete).not.toHaveBeenCalled();
+    expect(runtime.inspectRuntimeStatus).not.toHaveBeenCalled();
+  });
+
+  it("deletes with --yes (or the legacy --confirm) and names the namespace", async () => {
+    transport.delete.mockResolvedValue({ status: 204, data: "" });
+    for (const flag of ["--yes", "--confirm"]) {
+      const result = await capturedRun([
+        "memories",
+        "delete",
+        "fact-1",
+        "--kind",
+        "fact",
+        "--variant",
+        "coding",
+        flag,
+        "--json",
+      ]);
+      expect(result.code).toBe(0);
+      expect(JSON.parse(result.stdout)).toMatchObject({
+        schema_version: 2,
+        state: "committed",
+        operation: "delete",
+      });
+    }
+    expect(transport.delete).toHaveBeenCalledWith(
+      "/api/v2/memories/fact-1?kind=fact&variant=coding",
+      undefined,
+    );
+  });
+
+  it("explains an ambiguous id instead of a bare code", async () => {
+    transport.delete.mockResolvedValue({
+      status: 409,
+      data: { detail: "memory_id_ambiguous" },
+    });
+    const result = await capturedRun(["memories", "delete", "dup", "--yes"]);
+    expect(result.code).toBe(1);
+    expect(result.stdout).toContain("--kind");
+  });
+
+  it("shows a memory in its namespace", async () => {
+    transport.get.mockResolvedValue({ status: 200, data: memoryRecord() });
+    const result = await capturedRun([
+      "memories",
+      "show",
+      "exp-1",
+      "--kind",
+      "experience",
+      "--variant",
+      "working",
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.get).toHaveBeenCalledWith("/api/v2/memories/exp-1", {
+      params: { kind: "experience", variant: "working" },
+    });
+    const document = JSON.parse(result.stdout);
+    expect(document.schema_version).toBe(2);
+    expect(document).not.toHaveProperty("evidence");
+    expect(document).not.toHaveProperty("history");
+    expect(document.memory).toMatchObject({
+      kind: "experience",
+      variant: "working",
+      task: "deploy",
+    });
+  });
+});
+
+describe("memories list filters", () => {
+  const page = {
+    memories: [memoryRecord()],
+    total: 1,
+    limit: 100,
+    offset: 0,
+    search_window: 200,
+    window_id: "w1",
+    window_reset: false,
+  };
+
+  it("sends --scene, --source and --query to the library", async () => {
+    transport.get.mockResolvedValue({ status: 200, data: page });
+    const result = await capturedRun([
+      "memories",
+      "list",
+      "--scene",
+      "working",
+      "--source",
+      "codebuddy",
+      "--query",
+      "deploy",
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.get).toHaveBeenCalledWith("/api/v2/memory-library", {
+      params: {
+        offset: 0,
+        limit: 100,
+        scene: "working",
+        source: "codebuddy",
+        query: "deploy",
+      },
+    });
+    const document = JSON.parse(result.stdout);
+    expect(document.schema_version).toBe(2);
+    expect(document.page).toMatchObject({
+      state: "ok",
+      scene: "working",
+      query: "deploy",
+      search_window: 200,
+    });
+    expect(document.memories[0]).toMatchObject({
+      kind: "experience",
+      variant: "working",
+    });
+  });
+
+  it("omits scene for the default all", async () => {
+    transport.get.mockResolvedValue({ status: 200, data: page });
+    await capturedRun(["memories", "list", "--scene", "all", "--json"]);
+    expect(transport.get.mock.calls[0][1].params).not.toHaveProperty("scene");
+  });
+
+  it("validates --status, --scene and --query locally instead of reporting a busy backend", async () => {
+    for (const argv of [
+      ["memories", "list", "--status", "bogus"],
+      ["memories", "list", "--scene", "normal"],
+      ["memories", "list", "--query", "x", "--status", "archived"],
+      ["memories", "list", "--source", "Bad Source"],
+    ]) {
+      expect((await capturedRun(argv)).code).toBe(2);
+    }
+    expect(transport.get).not.toHaveBeenCalled();
+  });
+
+  it("reports a Core 422 as rejected, not as 后台正忙", async () => {
+    transport.get.mockResolvedValue({
+      status: 422,
+      data: { detail: "sdk_search_supports_active_status_only" },
+    });
+    const result = await capturedRun(["memories", "list"]);
+    expect(result.code).toBe(1);
+    expect(result.stdout).not.toContain("后台正忙");
+    expect(result.stdout).toContain("sdk_search_supports_active_status_only");
+  });
+});
+
+describe("graph-width", () => {
+  it("runs a non-destructive decision directly", async () => {
+    transport.post.mockResolvedValue({
+      status: 200,
+      data: { archived_path: null, exported_path: "/tmp/x", mismatch: null },
+    });
+    const result = await capturedRun([
+      "graph-width",
+      "--decision",
+      "export_first",
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.post).toHaveBeenCalledWith(
+      "/api/v1/graph-width",
+      { decision: "export_first" },
+      undefined,
+    );
+    expect(JSON.parse(result.stdout).state).toBe("committed");
+  });
+
+  it("previews rebuild_with_new without --yes and applies it with --yes", async () => {
+    const preview = await capturedRun([
+      "graph-width",
+      "--decision",
+      "rebuild_with_new",
+      "--json",
+    ]);
+    expect(preview.code).toBe(0);
+    expect(JSON.parse(preview.stdout)).toMatchObject({
+      state: "preview",
+      applied: false,
+    });
+    expect(transport.post).not.toHaveBeenCalled();
+    transport.post.mockResolvedValue({
+      status: 200,
+      data: { archived_path: "/tmp/old", exported_path: null, mismatch: null },
+    });
+    const applied = await capturedRun([
+      "graph",
+      "width",
+      "--decision",
+      "rebuild_with_new",
+      "--yes",
+      "--json",
+    ]);
+    expect(applied.code).toBe(0);
+    expect(transport.post).toHaveBeenCalledWith(
+      "/api/v1/graph-width",
+      { decision: "rebuild_with_new" },
+      undefined,
+    );
+  });
+});
+
+describe("removed commands", () => {
+  it.each([
+    ["notes", "add", "--content-file", "/tmp/x"],
+    ["notes", "process", REQUEST, "--confirm"],
+    ["calls", "clear", "--all", "--confirm"],
+    ["processing", "extract", "--evidence", REQUEST, "--confirm"],
+    ["extraction", "set", "--window", "6m", "--confirm"],
+    ["import-file", "upload", "--file", "/tmp/x", "--confirm"],
+  ])("%s is an unknown command that writes nothing", async (...argv) => {
+    const result = await capturedRun(argv as string[]);
+    expect(result.code).toBe(2);
+    expect(result.stderr).toContain("未知命令");
+    expect(transport.post).not.toHaveBeenCalled();
+  });
+});
+
+async function capturedRun(arguments_: string[]) {
+  let stdout = "";
+  let stderr = "";
+  const stdoutSpy = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation((chunk) => {
+      stdout += String(chunk);
+      return true;
+    });
+  const stderrSpy = vi
+    .spyOn(process.stderr, "write")
+    .mockImplementation((chunk) => {
+      stderr += String(chunk);
+      return true;
+    });
+  try {
+    return {
+      code: await run(arguments_, {
+        ONE_MEMORY_DATA_DIR: "/synthetic/data",
+      }),
+      stdout,
+      stderr,
+    };
+  } finally {
+    stdoutSpy.mockRestore();
+    stderrSpy.mockRestore();
+  }
+}
@@ -0,0 +1,318 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { run } from "./cli.js";
+import { parseFeaturesCommand } from "./memory-features-flow.js";
+import { composeStatusReport, renderStatusText } from "./status-report.js";
+
+const transport = vi.hoisted(() => ({
+  get: vi.fn(),
+  post: vi.fn(),
+  put: vi.fn(),
+  patch: vi.fn(),
+  delete: vi.fn(),
+}));
+vi.mock("axios", () => ({
+  default: {
+    create: vi.fn(() => transport),
+    get: vi.fn(),
+    post: vi.fn(),
+    isAxiosError: () => false,
+  },
+}));
+
+const runtime = vi.hoisted(() => ({
+  inspectRuntimeStatus: vi.fn(),
+  discoverRuntimeAttachment: vi.fn(),
+}));
+vi.mock("@one-memory/runtime-control", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@one-memory/runtime-control")>()),
+  ...runtime,
+}));
+
+const DEFAULTS: Record<string, boolean> = {
+  graph_rerank: false,
+  same_series_timeline: false,
+  episode_recall: false,
+  session_episodes: false,
+  episode_summary: false,
+  intention: true,
+  few_shot: false,
+};
+
+function featuresState(
+  configured: Record<string, boolean> = {},
+  mode = "pro",
+  extra: Record<string, unknown> = {},
+) {
+  const nonDefault: Record<string, boolean> = {};
+  const features = Object.entries(DEFAULTS).map(([name, fallback]) => {
+    const enabled = configured[name] ?? fallback;
+    if (enabled !== fallback) nonDefault[name] = enabled;
+    const needsUltra = name === "graph_rerank";
+    const reason = !enabled
+      ? "disabled"
+      : needsUltra && mode !== "ultra"
+        ? "requires_ultra"
+        : null;
+    return {
+      name,
+      enabled,
+      configured: name in configured ? configured[name] : null,
+      default: fallback,
+      active: reason === null,
+      reason,
+      side: "read",
+      requires_mode: needsUltra ? "ultra" : "pro",
+      requires_feature: null,
+      cost: "none",
+      sdk_field: `recall.${name}`,
+      env: `MEMORY_${name.toUpperCase()}`,
+      description: name,
+    };
+  });
+  return { mode, features, non_default: nonDefault, ...extra };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  for (const method of Object.values(transport)) method.mockReset();
+  runtime.inspectRuntimeStatus.mockResolvedValue({
+    state: "running",
+    code: "runtime_verified",
+    instanceId: "instance-1",
+    host: "127.0.0.1",
+    port: 8765,
+    version: "1.2.3",
+  });
+  runtime.discoverRuntimeAttachment.mockResolvedValue({
+    instanceId: "instance-1",
+    apiToken: "synthetic-runtime-token",
+    host: "127.0.0.1",
+    port: 8765,
+    servicePid: 4242,
+    health: {
+      status: "ok",
+      service: "one-memory-core",
+      version: "1.2.3",
+      instance_id: "instance-1",
+    },
+  });
+  transport.get.mockImplementation(async (url: string) =>
+    url === "/api/v1/settings/memory-features"
+      ? { status: 200, data: featuresState() }
+      : { status: 404, data: {} },
+  );
+});
+
+describe("memhub settings features", () => {
+  it("lists every feature with its value and whether it acts", async () => {
+    const result = await capturedRun(["settings", "features", "--json"]);
+    expect(result.code).toBe(0);
+    const json = JSON.parse(result.stdout);
+    expect(json.state).toBe("ok");
+    expect(json.features.features).toHaveLength(7);
+    expect(transport.put).not.toHaveBeenCalled();
+    const text = (await capturedRun(["settings", "features"])).stdout;
+    expect(text).toContain("graph_rerank：关（默认）");
+    expect(text).toContain("intention：开（默认）");
+    expect(text).toContain("先开启 session_episodes");
+  });
+
+  it("prints the plan and changes nothing without --yes", async () => {
+    const result = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "graph_rerank=true",
+      "episode_recall=true",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.put).not.toHaveBeenCalled();
+    expect(result.stdout).toContain(
+      "memhub settings features set graph_rerank=true episode_recall=true --yes",
+    );
+  });
+
+  it("sets features with --yes and reports the ones inactive in this mode", async () => {
+    transport.put.mockResolvedValue({
+      status: 200,
+      data: featuresState({ graph_rerank: true, episode_recall: true }, "pro", {
+        changed: ["graph_rerank", "episode_recall"],
+      }),
+    });
+    const result = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "graph_rerank=true",
+      "episode_recall=true",
+      "--yes",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.put).toHaveBeenCalledWith(
+      "/api/v1/settings/memory-features",
+      { graph_rerank: true, episode_recall: true },
+      undefined,
+    );
+    expect(result.stdout).toContain("已更新：graph_rerank、episode_recall");
+    expect(result.stdout).toContain(
+      "graph_rerank：开（已设置，当前模式下不生效（需要 ultra））",
+    );
+  });
+
+  it("does nothing when the values are already set", async () => {
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: featuresState({ few_shot: true }),
+    });
+    const result = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "few_shot=true",
+      "--yes",
+    ]);
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain("没有需要改动的设置");
+    expect(transport.put).not.toHaveBeenCalled();
+  });
+
+  it("resets the named features, or every set one, to the default", async () => {
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: featuresState({ few_shot: true, intention: false }),
+    });
+    transport.put.mockResolvedValue({
+      status: 200,
+      data: featuresState({}, "pro", { changed: ["intention", "few_shot"] }),
+    });
+    expect(
+      (await capturedRun(["settings", "features", "reset", "few_shot"])).code,
+    ).toBe(0);
+    expect(transport.put).toHaveBeenLastCalledWith(
+      "/api/v1/settings/memory-features",
+      { few_shot: null },
+      undefined,
+    );
+    const all = await capturedRun(["settings", "features", "reset", "--json"]);
+    expect(JSON.parse(all.stdout).state).toBe("committed");
+    expect(transport.put).toHaveBeenLastCalledWith(
+      "/api/v1/settings/memory-features",
+      { intention: null, few_shot: null },
+      undefined,
+    );
+  });
+
+  it("refuses unknown names and malformed values before the Runtime", async () => {
+    for (const bad of [
+      ["settings", "features", "set"],
+      ["settings", "features", "set", "local_rerank=true"],
+      ["settings", "features", "set", "graph_rerank=yes"],
+      ["settings", "features", "set", "graph_rerank"],
+      ["settings", "features", "set", "few_shot=true", "few_shot=false"],
+      ["settings", "features", "reset", "nope"],
+      ["settings", "features", "toggle"],
+    ]) {
+      const result = await capturedRun(bad);
+      expect(result.code, bad.join(" ")).toBe(2);
+    }
+    expect(transport.put).not.toHaveBeenCalled();
+  });
+
+  it("surfaces a 422 from the Runtime as rejected", async () => {
+    transport.put.mockResolvedValue({
+      status: 422,
+      data: { detail: "invalid_request" },
+    });
+    const result = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "few_shot=true",
+      "--yes",
+      "--json",
+    ]);
+    expect(result.code).toBe(1);
+    expect(JSON.parse(result.stdout).state).toBe("rejected");
+  });
+
+  it("parses the forms the help shows", () => {
+    expect(parseFeaturesCommand([])).toEqual({ kind: "show" });
+    expect(parseFeaturesCommand(["set", "intention=false", "--yes"])).toEqual({
+      kind: "set",
+      values: { intention: false },
+      confirmed: true,
+    });
+    expect(parseFeaturesCommand(["reset"])).toEqual({
+      kind: "reset",
+      names: [],
+    });
+  });
+});
+
+describe("status pipeline features", () => {
+  it("shows the features that differ from the defaults", async () => {
+    const processing = {
+      pending: 0,
+      fresh_pending: 0,
+      backlog_pending: 0,
+      outside_window_pending: 0,
+      running: 0,
+      waiting_for_model: 0,
+      completed: 3,
+      failed: 0,
+      blocked_stages: [],
+      pipeline: {
+        mode: "pro",
+        configured_mode: "pro",
+        forced_by_env: false,
+        last_evolve_at: null,
+        graph_build: { state: "idle", users: {} },
+        evolve: { mode: "pro", schedule: null, running: [], users: {} },
+        features: { episode_recall: true, intention: false },
+      },
+    };
+    const report = await composeStatusReport({
+      dataDir: "/tmp/isolated",
+      runtime: { state: "running", code: "ok", host: "127.0.0.1", port: 1 },
+      background: null,
+      reader: (async (path: string) =>
+        path === "/api/v1/memory-processing"
+          ? { state: "ok", data: processing }
+          : { state: "unavailable", code: "x" }) as never,
+    });
+    expect(report.pipeline?.features).toEqual({
+      episode_recall: true,
+      intention: false,
+    });
+    const text = renderStatusText(report, "MemHub");
+    expect(text).toContain("SDK 功能：episode_recall=开、intention=关");
+  });
+});
+
+async function capturedRun(arguments_: string[]) {
+  let stdout = "";
+  let stderr = "";
+  const stdoutSpy = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation((chunk) => {
+      stdout += String(chunk);
+      return true;
+    });
+  const stderrSpy = vi
+    .spyOn(process.stderr, "write")
+    .mockImplementation((chunk) => {
+      stderr += String(chunk);
+      return true;
+    });
+  try {
+    return {
+      code: await run(arguments_, { ONE_MEMORY_DATA_DIR: "/synthetic/data" }),
+      stdout,
+      stderr,
+    };
+  } finally {
+    stdoutSpy.mockRestore();
+    stderrSpy.mockRestore();
+  }
+}
@@ -0,0 +1,273 @@
+/**
+ * `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
+ * 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`
+ * only returns features to their defaults and applies at once.
+ */
+
+import type { CoreReader } from "./core-client.js";
+import type { CorePutOperations } from "./core-operations.js";
+import { PRODUCT } from "./version.js";
+
+export const MEMORY_FEATURES = [
+  "graph_rerank",
+  "same_series_timeline",
+  "episode_recall",
+  "session_episodes",
+  "episode_summary",
+  "intention",
+  "few_shot",
+] as const;
+export type MemoryFeature = (typeof MEMORY_FEATURES)[number];
+
+const FEATURE_LABEL: Record<MemoryFeature, string> = {
+  graph_rerank: "图谱重排（沿知识图谱的边传播支持度；仅 ultra）",
+  same_series_timeline:
+    "同系列时间线（同一系列的记忆按时间放在一起；需图谱重排）",
+  episode_recall:
+    "片段召回（补入同一片段的记忆并多通道打分；pro / ultra，需片段写入）",
+  session_episodes: "片段写入（同一会话提取的记忆归入同一片段）",
+  episode_summary: "片段摘要（片段结束时总结一次；每个片段一次模型调用）",
+  intention: "意图提取（随事实一起提取用户的计划与意图）",
+  few_shot: "提取示例（在提取提示里附上示例；不加调用，输入更长）",
+};
+
+const REASON_TEXT: Record<string, string> = {
+  disabled: "未开启",
+  requires_pro: "lite 模式下不生效（需要 pro 或 ultra）",
+  requires_ultra: "当前模式下不生效（需要 ultra）",
+  requires_graph_rerank: "需要先开启并生效 graph_rerank",
+};
+
+export type FeaturesCommand =
+  | { kind: "show" }
+  | {
+      kind: "set";
+      values: Partial<Record<MemoryFeature, boolean>>;
+      confirmed: boolean;
+    }
+  | { kind: "reset"; names: MemoryFeature[] };
+
+function isFeature(value: string): value is MemoryFeature {
+  return (MEMORY_FEATURES as readonly string[]).includes(value);
+}
+
+/** Arguments after `settings features`; null = usage. */
+export function parseFeaturesCommand(
+  values: readonly string[],
+): FeaturesCommand | null {
+  const rest = values.filter((value) => value !== "--json");
+  if (rest.length === 0) return { kind: "show" };
+  const [verb, ...tail] = rest;
+  const yes = tail.filter((value) => value === "--yes").length;
+  if (yes > 1) return null;
+  const positional = tail.filter((value) => value !== "--yes");
+  if (verb === "set") {
+    if (positional.length === 0) return null;
+    const parsed: Partial<Record<MemoryFeature, boolean>> = {};
+    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";
+    }
+    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[] };
+  }
+  return null;
+}
+
+export interface FeatureState {
+  name: MemoryFeature;
+  enabled: boolean;
+  configured: boolean | null;
+  default: boolean;
+  active: boolean;
+  reason: string | null;
+  cost: string;
+  requires_mode: string;
+  description: string;
+}
+
+export interface FeaturesState {
+  mode: string;
+  features: FeatureState[];
+  non_default: Partial<Record<MemoryFeature, boolean>>;
+  changed?: MemoryFeature[];
+}
+
+function featuresState(value: unknown): FeaturesState | null {
+  if (!value || typeof value !== "object") return null;
+  const item = value as Record<string, unknown>;
+  if (
+    typeof item.mode !== "string" ||
+    !Array.isArray(item.features) ||
+    !item.non_default ||
+    typeof item.non_default !== "object"
+  ) {
+    return null;
+  }
+  for (const feature of item.features) {
+    if (
+      !feature ||
+      typeof feature !== "object" ||
+      typeof (feature as FeatureState).name !== "string" ||
+      typeof (feature as FeatureState).enabled !== "boolean" ||
+      typeof (feature as FeatureState).active !== "boolean"
+    ) {
+      return null;
+    }
+  }
+  return item as unknown as FeaturesState;
+}
+
+export type FeaturesDocument = {
+  schema_version: 1;
+  product: string;
+  command: "settings features";
+} & (
+  | { state: "ok"; features: FeaturesState }
+  | {
+      state: "preview";
+      features: FeaturesState;
+      target: Partial<Record<MemoryFeature, boolean>>;
+      applied: false;
+      next_step: string;
+    }
+  | { state: "unchanged"; features: FeaturesState }
+  | { state: "committed"; features: FeaturesState; changed: MemoryFeature[] }
+  | { state: "rejected" | "unknown" | "unavailable"; code: string }
+);
+
+const BASE = {
+  schema_version: 1 as const,
+  product: PRODUCT,
+  command: "settings features" as const,
+};
+
+const PATH = "/api/v1/settings/memory-features";
+
+export async function runFeaturesCommand(
+  command: FeaturesCommand,
+  reader: CoreReader,
+  operations: CorePutOperations,
+): Promise<FeaturesDocument> {
+  const read = await reader<unknown>(PATH);
+  if (read.state !== "ok") {
+    return { ...BASE, state: "unavailable", code: read.code };
+  }
+  const current = featuresState(read.data);
+  if (current === null) {
+    return { ...BASE, state: "unavailable", code: "response_invalid" };
+  }
+  if (command.kind === "show") {
+    return { ...BASE, state: "ok", features: current };
+  }
+  let body: Record<string, unknown>;
+  if (command.kind === "set") {
+    const configured = new Map(
+      current.features.map((feature) => [feature.name, feature.configured]),
+    );
+    const differs = Object.entries(command.values).some(
+      ([name, value]) => configured.get(name as MemoryFeature) !== value,
+    );
+    if (!differs) return { ...BASE, state: "unchanged", features: current };
+    if (!command.confirmed) {
+      const pairs = Object.entries(command.values)
+        .map(([name, value]) => `${name}=${value}`)
+        .join(" ");
+      return {
+        ...BASE,
+        state: "preview",
+        features: current,
+        target: command.values,
+        applied: false,
+        next_step: `${PRODUCT} settings features set ${pairs} --yes`,
+      };
+    }
+    body = { ...command.values };
+  } else {
+    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,
+      )
+    ) {
+      return { ...BASE, state: "unchanged", features: current };
+    }
+    body = Object.fromEntries(names.map((name) => [name, null]));
+  }
+  const result = await operations.put<unknown>(PATH, body);
+  if (result.state !== "committed") {
+    return { ...BASE, state: result.state, code: result.code };
+  }
+  const changed = featuresState(result.data);
+  if (changed === null) {
+    return { ...BASE, state: "unknown", code: "response_invalid" };
+  }
+  return {
+    ...BASE,
+    state: "committed",
+    features: changed,
+    changed: changed.changed ?? [],
+  };
+}
+
+export function featuresExitCode(document: FeaturesDocument): number {
+  return ["ok", "preview", "unchanged", "committed"].includes(document.state)
+    ? 0
+    : 1;
+}
+
+function featureLine(feature: FeatureState): string {
+  const label = FEATURE_LABEL[feature.name] ?? feature.name;
+  const value = feature.enabled ? "开" : "关";
+  const origin = feature.configured === null ? "默认" : "已设置";
+  const activity =
+    feature.enabled && !feature.active && feature.reason
+      ? `，${REASON_TEXT[feature.reason] ?? feature.reason}`
+      : "";
+  return `${feature.name}：${value}（${origin}${activity}）— ${label}`;
+}
+
+export function renderFeaturesText(document: FeaturesDocument): string {
+  if ("code" in document) {
+    return `SDK 功能未能${document.state === "unavailable" ? "读取" : "修改"}：${document.code}\n`;
+  }
+  const state = document.features;
+  const lines = [`当前模式：${state.mode}`];
+  for (const feature of state.features) lines.push(featureLine(feature));
+  lines.push(
+    "片段召回（episode_recall）只对带片段的记忆有用：先开启 session_episodes，之后提取的记忆才会带片段。",
+  );
+  if (document.state === "unchanged") lines.push("没有需要改动的设置。");
+  if (document.state === "preview") {
+    lines.push("将设置：");
+    for (const [name, value] of Object.entries(document.target)) {
+      lines.push(`- ${name} = ${value ? "开" : "关"}`);
+    }
+    lines.push(`未执行任何改动。确认后运行：${document.next_step}`);
+  }
+  if (document.state === "committed") {
+    lines.push(
+      document.changed.length > 0
+        ? `已更新：${document.changed.join("、")}。正在进行的写入按原设置完成，之后的写入和检索使用新设置。`
+        : "已保存，生效的值没有变化。",
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}
@@ -0,0 +1,309 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { run } from "./cli.js";
+import { modeEffects, parseSettingsCommand } from "./memory-mode-flow.js";
+import { composeStatusReport, renderStatusText } from "./status-report.js";
+
+const transport = vi.hoisted(() => ({
+  get: vi.fn(),
+  post: vi.fn(),
+  put: vi.fn(),
+  patch: vi.fn(),
+  delete: vi.fn(),
+}));
+vi.mock("axios", () => ({
+  default: {
+    create: vi.fn(() => transport),
+    get: vi.fn(),
+    post: vi.fn(),
+    isAxiosError: () => false,
+  },
+}));
+
+const runtime = vi.hoisted(() => ({
+  inspectRuntimeStatus: vi.fn(),
+  discoverRuntimeAttachment: vi.fn(),
+}));
+vi.mock("@one-memory/runtime-control", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@one-memory/runtime-control")>()),
+  ...runtime,
+}));
+
+const RUN_ID = "11111111-2222-4333-8444-555555555555";
+
+function modeState(mode: string, configured = mode) {
+  return {
+    mode,
+    configured_mode: configured,
+    forced_by_env: false,
+    modes: ["lite", "pro", "ultra"],
+    graph_build: { state: "idle", users: {} },
+  };
+}
+
+function receipt(state: string, extra: Record<string, unknown> = {}) {
+  return {
+    run_id: RUN_ID,
+    user_id: "wife",
+    agent_id: "all-apps",
+    state,
+    trigger: "manual",
+    started_at: "2026-11-01T03:00:00Z",
+    rounds: state === "running" ? 0 : 2,
+    tasks_processed: state === "running" ? 0 : 5,
+    batch_failures: 0,
+    capped: false,
+    elapsed_ms: 10,
+    results: { schemas: ["never printed"] },
+    ...extra,
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  for (const method of Object.values(transport)) method.mockReset();
+  runtime.inspectRuntimeStatus.mockResolvedValue({
+    state: "running",
+    code: "runtime_verified",
+    instanceId: "instance-1",
+    host: "127.0.0.1",
+    port: 8765,
+    version: "1.2.3",
+  });
+  runtime.discoverRuntimeAttachment.mockResolvedValue({
+    instanceId: "instance-1",
+    apiToken: "synthetic-runtime-token",
+    host: "127.0.0.1",
+    port: 8765,
+    servicePid: 4242,
+    health: {
+      status: "ok",
+      service: "one-memory-core",
+      version: "1.2.3",
+      instance_id: "instance-1",
+    },
+  });
+  transport.get.mockImplementation(async (url: string) =>
+    url === "/api/v1/settings/memory-mode"
+      ? { status: 200, data: modeState("pro") }
+      : { status: 404, data: {} },
+  );
+});
+
+describe("memhub settings mode", () => {
+  it("shows the current mode without changing it", async () => {
+    const result = await capturedRun(["settings", "mode", "--json"]);
+    expect(result.code).toBe(0);
+    expect(JSON.parse(result.stdout).mode.mode).toBe("pro");
+    expect(transport.put).not.toHaveBeenCalled();
+  });
+
+  it("prints the plan and changes nothing without --yes", async () => {
+    const result = await capturedRun(["settings", "mode", "lite"]);
+    expect(result.code).toBe(0);
+    expect(transport.put).not.toHaveBeenCalled();
+    expect(result.stdout).toContain("更高模式生成的记忆仍保存着");
+    expect(result.stdout).toContain("memhub settings mode lite --yes");
+    const json = JSON.parse(
+      (await capturedRun(["settings", "mode", "ultra", "--json"])).stdout,
+    );
+    expect(json.state).toBe("preview");
+    expect(json.applied).toBe(false);
+    expect(json.effects).toEqual(["existing_memories_added_to_graph"]);
+  });
+
+  it("changes the mode with --yes and reports what changed", async () => {
+    transport.put.mockResolvedValue({
+      status: 200,
+      data: {
+        ...modeState("lite"),
+        previous_mode: "pro",
+        effects: ["higher_mode_memories_hidden"],
+      },
+    });
+    const result = await capturedRun(["settings", "mode", "lite", "--yes"]);
+    expect(result.code).toBe(0);
+    expect(transport.put).toHaveBeenCalledWith(
+      "/api/v1/settings/memory-mode",
+      { mode: "lite" },
+      undefined,
+    );
+    expect(result.stdout).toContain("已切换");
+    expect(result.stdout).toContain("原始对话：全部保留");
+  });
+
+  it("does nothing for the mode already set, and refuses bad input", async () => {
+    const same = await capturedRun(["settings", "mode", "pro", "--yes"]);
+    expect(same.code).toBe(0);
+    expect(same.stdout).toContain("已经是这个模式");
+    expect(transport.put).not.toHaveBeenCalled();
+    for (const bad of [
+      ["settings"],
+      ["settings", "mode", "max"],
+      ["settings", "mode", "--yes"],
+      ["settings", "mode", "lite", "pro"],
+      ["settings", "language", "en"],
+    ]) {
+      expect((await capturedRun(bad)).code, bad.join(" ")).toBe(2);
+    }
+  });
+
+  it("plans the same effects Core reports", () => {
+    expect(modeEffects("lite", "pro")).toEqual([
+      "earlier_raw_not_extracted",
+      "lite_search_stops",
+    ]);
+    expect(modeEffects("ultra", "lite")).toEqual([
+      "higher_mode_memories_hidden",
+      "evolve_stopped",
+    ]);
+    expect(modeEffects("pro", "pro")).toEqual([]);
+    expect(parseSettingsCommand(["mode", "ultra", "--yes"])).toEqual({
+      kind: "set",
+      mode: "ultra",
+      confirmed: true,
+    });
+  });
+});
+
+describe("memhub evolve", () => {
+  it("starts a run for the named user and returns at once", async () => {
+    transport.post.mockResolvedValue({ status: 202, data: receipt("running") });
+    const result = await capturedRun([
+      "evolve",
+      "--user-id",
+      "wife",
+      "--agent-id",
+      "all-apps",
+      "--max-batches",
+      "3",
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.post).toHaveBeenCalledWith(
+      "/api/v2/evolve",
+      { user_id: "wife", agent_id: "all-apps", max_batches: 3 },
+      undefined,
+    );
+    const document = JSON.parse(result.stdout);
+    expect(document.state).toBe("running");
+    expect(document.run.results).toBeUndefined();
+  });
+
+  it("follows the run with --wait until it ends", async () => {
+    transport.post.mockResolvedValue({ status: 202, data: receipt("running") });
+    const reads = [receipt("running"), receipt("succeeded")];
+    transport.get.mockImplementation(async (url: string) =>
+      url === `/api/v2/evolve/${RUN_ID}`
+        ? { status: 200, data: reads.shift() }
+        : { status: 404, data: {} },
+    );
+    const result = await capturedRun(["evolve", "--wait"], {
+      sleep: async () => undefined,
+    });
+    expect(result.code).toBe(0);
+    expect(transport.post).toHaveBeenCalledWith(
+      "/api/v2/evolve",
+      {},
+      undefined,
+    );
+    expect(result.stdout).toContain("进化完成");
+    expect(result.stdout).toContain("2 轮");
+  });
+
+  it("names the mode when Core refuses outside ultra", async () => {
+    transport.post.mockResolvedValue({
+      status: 409,
+      data: { detail: "memory_mode_not_ultra" },
+    });
+    const result = await capturedRun(["evolve"]);
+    expect(result.code).toBe(1);
+    expect(result.stdout).toContain("memhub settings mode ultra --yes");
+    expect((await capturedRun(["evolve", "--max-batches", "0"])).code).toBe(2);
+    expect((await capturedRun(["evolve", "--now"])).code).toBe(2);
+  });
+});
+
+describe("status pipeline", () => {
+  it("reports pipeline.mode and the last evolve from memory-processing", async () => {
+    const processing = {
+      pending: 0,
+      fresh_pending: 0,
+      backlog_pending: 0,
+      outside_window_pending: 0,
+      running: 0,
+      waiting_for_model: 0,
+      completed: 3,
+      failed: 0,
+      blocked_stages: [],
+      pipeline: {
+        mode: "ultra",
+        configured_mode: "ultra",
+        forced_by_env: false,
+        last_evolve_at: "2026-11-01T03:00:05+08:00",
+        graph_build: { state: "succeeded", users: {} },
+        evolve: {
+          mode: "ultra",
+          schedule: { enabled: true, time: "03:00" },
+          running: [],
+          users: {
+            local: {
+              last_run_at: "2026-11-01T03:00:05+08:00",
+              last_result: { state: "succeeded", tasks_processed: 4 },
+              last_error: null,
+            },
+          },
+        },
+      },
+    };
+    const report = await composeStatusReport({
+      dataDir: "/tmp/isolated",
+      runtime: { state: "running", code: "ok", host: "127.0.0.1", port: 1 },
+      background: null,
+      reader: (async (path: string) =>
+        path === "/api/v1/memory-processing"
+          ? { state: "ok", data: processing }
+          : { state: "unavailable", code: "x" }) as never,
+    });
+    expect(report.pipeline?.mode).toBe("ultra");
+    expect(report.pipeline?.last_evolve_at).toBe("2026-11-01T03:00:05+08:00");
+    expect(report.pipeline?.evolve_users.local?.state).toBe("succeeded");
+    const text = renderStatusText(report, "MemHub");
+    expect(text).toContain("记忆模式：ultra");
+    expect(text).toContain("每日 03:00 自动进化");
+  });
+});
+
+async function capturedRun(
+  arguments_: string[],
+  controls: Parameters<typeof run>[2] = {},
+) {
+  let stdout = "";
+  let stderr = "";
+  const stdoutSpy = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation((chunk) => {
+      stdout += String(chunk);
+      return true;
+    });
+  const stderrSpy = vi
+    .spyOn(process.stderr, "write")
+    .mockImplementation((chunk) => {
+      stderr += String(chunk);
+      return true;
+    });
+  try {
+    return {
+      code: await run(
+        arguments_,
+        { ONE_MEMORY_DATA_DIR: "/synthetic/data" },
+        controls,
+      ),
+      stdout,
+      stderr,
+    };
+  } finally {
+    stdoutSpy.mockRestore();
+    stderrSpy.mockRestore();
+  }
+}
@@ -0,0 +1,372 @@
+/**
+ * `memhub settings mode` and `memhub evolve`.
+ *
+ * The mode (lite / pro / ultra) decides what the SDK does with every
+ * conversation, and switching it migrates nothing: what one mode made is not
+ * shown by a lower one, and raw kept by lite is not extracted until it is
+ * imported again. So a change prints its plan first and needs `--yes`, like
+ * every other command whose effect a person cannot simply take back.
+ *
+ * `memhub evolve` starts System 2 (ultra only) and, with `--wait`, follows
+ * the run until it ends.
+ */
+
+import type { CoreReader } from "./core-client.js";
+import type { CoreOperations, CorePutOperations } from "./core-operations.js";
+import { PRODUCT } from "./version.js";
+
+export const MEMORY_MODES = ["lite", "pro", "ultra"] as const;
+export type MemoryMode = (typeof MEMORY_MODES)[number];
+
+export type ModeEffect =
+  | "earlier_raw_not_extracted"
+  | "higher_mode_memories_hidden"
+  | "existing_memories_added_to_graph"
+  | "evolve_stopped"
+  | "lite_search_stops"
+  | "graph_backfill_already_running";
+
+const MODE_SUMMARY: Record<MemoryMode, string> = {
+  lite: "lite：不调用模型，保留全部原始对话，只在原始对话里检索",
+  pro: "pro：模型从对话中提取记忆（System 1）",
+  ultra: "ultra：pro + 每晚自动进化（System 2，使用知识图谱）",
+};
+
+const EFFECT_TEXT: Record<ModeEffect, string> = {
+  earlier_raw_not_extracted:
+    "lite 下已处理完的对话不会再被提取；只有尚未处理的和之后的新对话会由模型整理成记忆，检索立即改为记忆检索",
+  higher_mode_memories_hidden:
+    "更高模式生成的记忆仍保存着，但在这个模式下不会显示",
+  existing_memories_added_to_graph:
+    "已有记忆会在后台加入知识图谱（每个用户一次）",
+  evolve_stopped: "每晚的自动进化（System 2）停止",
+  lite_search_stops: "lite 只在原始对话里的检索立即停止，改为检索记忆",
+  graph_backfill_already_running: "知识图谱的补建已在进行中",
+};
+
+/** The same rule Core applies (`memory_mode_effects`), for the plan. */
+export function modeEffects(
+  previous: MemoryMode,
+  next: MemoryMode,
+): ModeEffect[] {
+  if (previous === next) return [];
+  const rank: Record<MemoryMode, number> = { lite: 0, pro: 1, ultra: 2 };
+  const effects: ModeEffect[] = [];
+  if (previous === "lite") {
+    effects.push("earlier_raw_not_extracted", "lite_search_stops");
+  }
+  if (rank[next] < rank[previous]) effects.push("higher_mode_memories_hidden");
+  if (previous === "ultra") effects.push("evolve_stopped");
+  if (next === "ultra") effects.push("existing_memories_added_to_graph");
+  return effects;
+}
+
+export type ModeCommand =
+  | { kind: "show" }
+  | { kind: "set"; mode: MemoryMode; confirmed: boolean };
+
+/** `settings mode [lite|pro|ultra] [--yes]` after `settings`; null = usage. */
+export function parseSettingsCommand(
+  values: readonly string[],
+): ModeCommand | null {
+  const rest = values.filter((value) => value !== "--json");
+  if (rest[0] !== "mode") return null;
+  const tail = rest.slice(1);
+  const confirmed = tail.includes("--yes");
+  const positional = tail.filter((value) => value !== "--yes");
+  if (tail.filter((value) => value === "--yes").length > 1) return null;
+  if (positional.length === 0) return confirmed ? null : { kind: "show" };
+  if (positional.length !== 1) return null;
+  const mode = positional[0] as MemoryMode;
+  if (!(MEMORY_MODES as readonly string[]).includes(mode)) return null;
+  return { kind: "set", mode, confirmed };
+}
+
+export interface ModeState {
+  mode: MemoryMode;
+  configured_mode: MemoryMode;
+  forced_by_env: boolean;
+  graph_build?: { state?: string } | null;
+  previous_mode?: MemoryMode;
+  effects?: ModeEffect[];
+}
+
+function modeState(value: unknown): ModeState | null {
+  if (!value || typeof value !== "object") return null;
+  const item = value as Record<string, unknown>;
+  if (
+    !(MEMORY_MODES as readonly unknown[]).includes(item.mode) ||
+    !(MEMORY_MODES as readonly unknown[]).includes(item.configured_mode) ||
+    typeof item.forced_by_env !== "boolean"
+  ) {
+    return null;
+  }
+  return item as unknown as ModeState;
+}
+
+export type ModeDocument = {
+  schema_version: 1;
+  product: string;
+  command: "settings mode";
+} & (
+  | { state: "ok"; mode: ModeState }
+  | {
+      state: "preview";
+      mode: ModeState;
+      target: MemoryMode;
+      effects: ModeEffect[];
+      applied: false;
+      next_step: string;
+    }
+  | { state: "unchanged"; mode: ModeState }
+  | { state: "committed"; mode: ModeState; effects: ModeEffect[] }
+  | { state: "rejected" | "unknown" | "unavailable"; code: string }
+);
+
+const BASE = {
+  schema_version: 1 as const,
+  product: PRODUCT,
+  command: "settings mode" as const,
+};
+
+export async function runModeCommand(
+  command: ModeCommand,
+  reader: CoreReader,
+  operations: CorePutOperations,
+): Promise<ModeDocument> {
+  const read = await reader<unknown>("/api/v1/settings/memory-mode");
+  if (read.state !== "ok") {
+    return { ...BASE, state: "unavailable", code: read.code };
+  }
+  const current = modeState(read.data);
+  if (current === null) {
+    return { ...BASE, state: "unavailable", code: "response_invalid" };
+  }
+  if (command.kind === "show") return { ...BASE, state: "ok", mode: current };
+  if (current.configured_mode === command.mode) {
+    return { ...BASE, state: "unchanged", mode: current };
+  }
+  if (!command.confirmed) {
+    return {
+      ...BASE,
+      state: "preview",
+      mode: current,
+      target: command.mode,
+      effects: modeEffects(current.mode, command.mode),
+      applied: false,
+      next_step: `${PRODUCT} settings mode ${command.mode} --yes`,
+    };
+  }
+  const result = await operations.put<unknown>("/api/v1/settings/memory-mode", {
+    mode: command.mode,
+  });
+  if (result.state !== "committed") {
+    return { ...BASE, state: result.state, code: result.code };
+  }
+  const changed = modeState(result.data);
+  if (changed === null) {
+    return { ...BASE, state: "unknown", code: "response_invalid" };
+  }
+  return {
+    ...BASE,
+    state: "committed",
+    mode: changed,
+    effects: changed.effects ?? [],
+  };
+}
+
+export function modeExitCode(document: ModeDocument): number {
+  return ["ok", "preview", "unchanged", "committed"].includes(document.state)
+    ? 0
+    : 1;
+}
+
+export function renderModeText(document: ModeDocument): string {
+  if ("code" in document) {
+    return `记忆模式未能${document.state === "unavailable" ? "读取" : "修改"}：${document.code}\n`;
+  }
+  const mode = document.mode;
+  const lines = [`当前模式：${MODE_SUMMARY[mode.mode]}`];
+  if (mode.forced_by_env) {
+    lines.push(
+      `设置里是 ${mode.configured_mode}；环境变量 ONE_MEMORY_GRAPH_STORE 强制使用 ultra。`,
+    );
+  }
+  lines.push("原始对话：全部保留（任何模式都不删除）");
+  if (document.state === "unchanged") {
+    lines.push("已经是这个模式，未做改动。");
+  }
+  if (document.state === "preview") {
+    lines.push(`将切换到：${MODE_SUMMARY[document.target]}`);
+    for (const effect of document.effects)
+      lines.push(`- ${EFFECT_TEXT[effect]}`);
+    lines.push(`未执行任何改动。确认后运行：${document.next_step}`);
+  }
+  if (document.state === "committed") {
+    lines.push("已切换。");
+    for (const effect of document.effects)
+      lines.push(`- ${EFFECT_TEXT[effect]}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export type EvolveCommand = {
+  agentId?: string;
+  maxBatches?: number;
+  wait: boolean;
+};
+
+/** `evolve [--agent-id <id>] [--max-batches <n>] [--wait]`; null = usage. */
+export function parseEvolveCommand(
+  values: readonly string[],
+): EvolveCommand | null {
+  const parsed: EvolveCommand = { wait: false };
+  const rest = values.filter((value) => value !== "--json");
+  for (let index = 0; index < rest.length; index += 1) {
+    const flag = rest[index];
+    if (flag === "--wait" && !parsed.wait) {
+      parsed.wait = true;
+    } else if (flag === "--agent-id" && parsed.agentId === undefined) {
+      const value = rest[index + 1];
+      if (!value || !/^[A-Za-z0-9._:-]{1,128}$/.test(value)) return null;
+      parsed.agentId = value;
+      index += 1;
+    } else if (flag === "--max-batches" && parsed.maxBatches === undefined) {
+      const value = Number(rest[index + 1]);
+      if (!Number.isInteger(value) || value < 1 || value > 1000) return null;
+      parsed.maxBatches = value;
+      index += 1;
+    } else {
+      return null;
+    }
+  }
+  return parsed;
+}
+
+export type EvolveDocument = {
+  schema_version: 1;
+  product: string;
+  command: "evolve";
+} & (
+  | { state: "running" | "succeeded" | "failed"; run: Record<string, unknown> }
+  | { state: "rejected" | "unknown" | "unavailable"; code: string }
+);
+
+const RUN_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+function evolveRun(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object") return null;
+  const run = value as Record<string, unknown>;
+  if (
+    typeof run.run_id !== "string" ||
+    !RUN_ID.test(run.run_id) ||
+    !["running", "succeeded", "failed"].includes(String(run.state))
+  ) {
+    return null;
+  }
+  return run;
+}
+
+export async function runEvolveCommand(
+  command: EvolveCommand,
+  options: {
+    userId?: string;
+    reader: CoreReader;
+    operations: CoreOperations;
+    sleep?: (ms: number) => Promise<void>;
+    pollMs?: number;
+  },
+): Promise<EvolveDocument> {
+  const base = {
+    schema_version: 1 as const,
+    product: PRODUCT,
+    command: "evolve" as const,
+  };
+  const body: Record<string, unknown> = {};
+  if (options.userId !== undefined) body.user_id = options.userId;
+  if (command.agentId !== undefined) body.agent_id = command.agentId;
+  if (command.maxBatches !== undefined) body.max_batches = command.maxBatches;
+  const started = await options.operations.post<unknown>(
+    "/api/v2/evolve",
+    body,
+  );
+  if (started.state !== "committed") {
+    return { ...base, state: started.state, code: started.code };
+  }
+  let run = evolveRun(started.data);
+  if (run === null)
+    return { ...base, state: "unknown", code: "response_invalid" };
+  const sleep =
+    options.sleep ??
+    ((ms: number) => new Promise((done) => setTimeout(done, ms)));
+  while (command.wait && run.state === "running") {
+    await sleep(options.pollMs ?? 2_000);
+    const read = await options.reader<unknown>(
+      `/api/v2/evolve/${run.run_id}`,
+      options.userId === undefined ? {} : { user_id: options.userId },
+    );
+    if (read.state !== "ok") {
+      return { ...base, state: "unavailable", code: read.code };
+    }
+    const next = evolveRun(read.data);
+    if (next === null)
+      return { ...base, state: "unknown", code: "response_invalid" };
+    run = next;
+  }
+  return {
+    ...base,
+    state: run.state as "running" | "succeeded" | "failed",
+    run: projectRun(run),
+  };
+}
+
+/** Counts and codes; SDK result bodies stay in the Core receipt. */
+function projectRun(run: Record<string, unknown>): Record<string, unknown> {
+  const keep = [
+    "run_id",
+    "user_id",
+    "agent_id",
+    "state",
+    "trigger",
+    "started_at",
+    "finished_at",
+    "rounds",
+    "tasks_processed",
+    "batch_failures",
+    "cycle_status",
+    "should_continue",
+    "continuation_reason",
+    "remaining_clusters",
+    "remaining_actionable_clusters",
+    "remaining_fresh_facts",
+    "capped",
+    "elapsed_ms",
+    "error_code",
+    "failure_kind",
+  ];
+  return Object.fromEntries(
+    keep.filter((key) => key in run).map((key) => [key, run[key]]),
+  );
+}
+
+export function evolveExitCode(document: EvolveDocument): number {
+  return document.state === "running" || document.state === "succeeded" ? 0 : 1;
+}
+
+export function renderEvolveText(document: EvolveDocument): string {
+  if ("code" in document) {
+    return document.code === "memory_mode_not_ultra"
+      ? "进化只在 ultra 模式下可用。切换：memhub settings mode ultra --yes\n"
+      : `进化未能开始：${document.code}\n`;
+  }
+  const run = document.run;
+  if (document.state === "running") {
+    return `进化已开始（${run.run_id}），在后台运行；加 --wait 等待结果。\n`;
+  }
+  if (document.state === "failed") {
+    return `进化失败（${run.run_id}）：${String(run.error_code ?? "unknown")}\n`;
+  }
+  return `进化完成（${run.run_id}）：${run.rounds} 轮，处理 ${run.tasks_processed} 项${
+    run.cycle_status ? `，周期 ${run.cycle_status}` : ""
+  }${run.capped ? "，已到轮数上限，可再次运行继续" : ""}\n`;
+}
@@ -1,7 +1,38 @@
-import type { SdkMemoryPage, SdkMemoryRecord } from "@one-memory/contracts";
+import { randomUUID } from "node:crypto";
+import type {
+  MemoryAddReceipt,
+  SdkMemoryPage,
+  SdkMemoryRecord,
+} from "@one-memory/contracts";
+import {
+  buildMemoryAddRequest,
+  MemoryAddInputError,
+  memoryAddStatusPath,
+  parseMemoryAddReceipt,
+} from "@one-memory/operations";
 import { type CoreReader, RESERVED_MEMORY_SEGMENTS } from "./core-client.js";
+import type { CoreOperations } from "./core-operations.js";
 import { PRODUCT } from "./version.js";

+/** A MemHub user id, the same shape Core accepts. `local` is the default. */
+const USER_ID = /^[A-Za-z0-9._-]{1,64}$/;
+export const DEFAULT_USER_ID = "local";
+
+export function isUserId(value: string): boolean {
+  return USER_ID.test(value);
+}
+
+/**
+ * The `user_id` to send, or nothing. The default user is never named on the
+ * wire, so a request without `--user-id` stays exactly what it was before
+ * multi-user support and still works against an older Core.
+ */
+export function userIdParameters(userId?: string): { user_id?: string } {
+  return userId === undefined || userId === DEFAULT_USER_ID
+    ? {}
+    : { user_id: userId };
+}
+
 /** Output budget: a long memory is shortened visibly, never dropped silently. */
 const CONTENT_BUDGET = 240;

@@ -38,42 +69,74 @@ export function parseMemoryContent(bytes: Buffer): string | null {
    : null;
 }

+export const MEMORY_SCENES = ["all", "chat", "working", "coding"] as const;
+export type MemoryScene = (typeof MEMORY_SCENES)[number];
+export const MEMORY_KINDS = ["chat", "experience", "fact"] as const;
+export type MemoryKind = (typeof MEMORY_KINDS)[number];
+export const MEMORY_VARIANTS = ["working", "coding"] as const;
+export type MemoryVariant = (typeof MEMORY_VARIANTS)[number];
+
+/** Which SDK namespace a memory lives in. A chat memory needs neither; a
+ * working/coding experience or fact needs both so Core does not have to guess
+ * (an id present in two namespaces is refused as ambiguous). */
+export interface MemoryNamespace {
+  kind?: MemoryKind;
+  variant?: MemoryVariant;
+}
+
+export function namespaceParameters(
+  namespace: MemoryNamespace,
+): Record<string, string> {
+  return {
+    ...(namespace.kind === undefined ? {} : { kind: namespace.kind }),
+    ...(namespace.variant === undefined ? {} : { variant: namespace.variant }),
+  };
+}
+
 export interface MemoryQuery {
  query?: string;
  status?: string;
  source?: string;
+  scene?: MemoryScene;
  offset: number;
  limit: number;
 }

+/** Every `memories` document is schema 2: list/show share it with
+ * add/update/delete, and the v1-era `evidence`/`history` fields are gone. */
 export interface MemoryPageDocument {
-  schema_version: 1;
+  schema_version: 2;
  product: string;
  page: Record<string, unknown>;
  memories: Record<string, unknown>[];
 }

 export interface MemoryDetailDocument {
-  schema_version: 1;
+  schema_version: 2;
  product: string;
  memory: Record<string, unknown>;
-  evidence: Record<string, unknown>[];
-  history: Record<string, unknown>[];
 }

 export async function readMemoryPage(
  reader: CoreReader,
  query: MemoryQuery,
+  userId?: string,
 ): Promise<MemoryPageDocument> {
  const parameters: Record<string, string | number> = {
    offset: query.offset,
    limit: query.limit,
+    ...userIdParameters(userId),
  };
  if (query.status !== undefined) parameters.statuses = query.status;
+  if (query.source !== undefined) parameters.source = query.source;
+  if (query.query !== undefined) parameters.query = query.query;
+  if (query.scene !== undefined && query.scene !== "all") {
+    parameters.scene = query.scene;
+  }
  const outcome = await reader<unknown>("/api/v2/memory-library", parameters);
  if (outcome.state !== "ok") {
    return {
-      schema_version: 1,
+      schema_version: 2,
      product: PRODUCT,
      page: { state: outcome.state, code: outcome.code },
      memories: [],
@@ -82,7 +145,7 @@ export async function readMemoryPage(
  const page = sdkMemoryPage(outcome.data);
  if (page === null) {
    return {
-      schema_version: 1,
+      schema_version: 2,
      product: PRODUCT,
      page: { state: "invalid", code: "response_invalid" },
      memories: [],
@@ -90,15 +153,21 @@ export async function readMemoryPage(
  }
  const items = page.memories;
  return {
-    schema_version: 1,
+    schema_version: 2,
    product: PRODUCT,
    page: {
      state: "ok",
+      scene: query.scene ?? "all",
+      ...(query.query === undefined ? {} : { query: query.query }),
      total: page.total,
      offset: page.offset,
      limit: page.limit,
      returned: items.length,
      has_more: page.offset + items.length < page.total,
+      // A keyword search only looks among this many most relevant memories.
+      ...(typeof page.search_window === "number"
+        ? { search_window: page.search_window }
+        : {}),
    },
    memories: items.map((item) => describeMemory(item)),
  };
@@ -107,42 +176,211 @@ export async function readMemoryPage(
 export async function readMemoryDetail(
  reader: CoreReader,
  memoryId: string,
+  namespace: MemoryNamespace = {},
+  userId?: string,
 ): Promise<MemoryDetailDocument> {
-  const outcome = await reader<unknown>(`/api/v2/memories/${memoryId}`);
+  const parameters = {
+    ...namespaceParameters(namespace),
+    ...userIdParameters(userId),
+  };
+  const outcome = await reader<unknown>(
+    `/api/v2/memories/${memoryId}`,
+    Object.keys(parameters).length > 0 ? parameters : undefined,
+  );
  if (outcome.state !== "ok") {
    return {
-      schema_version: 1,
+      schema_version: 2,
      product: PRODUCT,
      memory: { state: outcome.state, code: outcome.code },
-      evidence: [],
-      history: [],
    };
  }
  const memory = sdkMemory(outcome.data);
  if (memory === null || memory.memory_id !== memoryId) {
    return {
-      schema_version: 1,
+      schema_version: 2,
      product: PRODUCT,
      memory: { state: "invalid", code: "response_invalid" },
-      evidence: [],
-      history: [],
    };
  }
  return {
-    schema_version: 1,
+    schema_version: 2,
    product: PRODUCT,
    memory: { state: "ok", ...describeMemory(memory) },
-    evidence: [],
-    history: [],
  };
 }

+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** The same bound the app's 添加记忆 box applies. */
+export const MEMORY_ADD_MAX_CHARACTERS = 12_000;
+
+export interface MemoryAddDocument {
+  schema_version: 2;
+  product: string;
+  command: "memories add" | "memories add-status";
+  state: "accepted" | "rejected" | "unknown" | "not_found" | "invalid";
+  request_id: string;
+  code?: string;
+  receipt?: Record<string, unknown>;
+}
+
+export function isRequestId(value: string): boolean {
+  return UUID.test(value);
+}
+
+/** A memory text: non-blank, bounded, no control characters except tab and
+ * newline. */
+export function validMemoryText(text: string): boolean {
+  return (
+    text.trim().length > 0 &&
+    [...text].length <= MEMORY_ADD_MAX_CHARACTERS &&
+    ![...text].some((character) => {
+      const code = character.charCodeAt(0);
+      return code <= 8 || (code >= 11 && code <= 31) || code === 127;
+    })
+  );
+}
+
+function addReceipt(receipt: MemoryAddReceipt): Record<string, unknown> {
+  return {
+    evidence_id: receipt.evidence_id,
+    state: receipt.state,
+    created_at: receipt.created_at,
+    task_id: receipt.task_id,
+    memory_ids: receipt.memory_ids,
+    error: receipt.error,
+  };
+}
+
+/**
+ * Add one memory directly, the same request as the app's 添加记忆.
+ *
+ * `requestId` is Core's idempotency key: retrying with the same id and text
+ * returns the first receipt; the same id with other text is refused.
+ */
+export async function addMemory(
+  operations: CoreOperations,
+  text: string,
+  requestId: string = randomUUID(),
+  userId?: string,
+): Promise<MemoryAddDocument> {
+  const base = {
+    schema_version: 2 as const,
+    product: PRODUCT,
+    command: "memories add" as const,
+    request_id: requestId,
+  };
+  if (!validMemoryText(text) || !UUID.test(requestId)) {
+    return { ...base, state: "invalid", code: "memory_add_invalid" };
+  }
+  let request: ReturnType<typeof buildMemoryAddRequest>;
+  try {
+    request = buildMemoryAddRequest({
+      request_id: requestId,
+      text,
+      scope: "all-apps",
+    });
+  } catch (error) {
+    if (error instanceof MemoryAddInputError) {
+      return { ...base, state: "invalid", code: "memory_add_invalid" };
+    }
+    throw error;
+  }
+  const result = await operations.post<unknown>(request.path, {
+    ...request.body,
+    ...userIdParameters(userId),
+  });
+  if (result.state !== "committed") {
+    return { ...base, state: result.state, code: result.code };
+  }
+  const receipt = parseMemoryAddReceipt(result.data);
+  return receipt === null
+    ? { ...base, state: "unknown", code: "memory_add_receipt_invalid" }
+    : { ...base, state: "accepted", receipt: addReceipt(receipt) };
+}
+
+/** Read how one addition is doing, by the request id it was submitted with. */
+export async function readMemoryAddStatus(
+  reader: CoreReader,
+  requestId: string,
+  userId?: string,
+): Promise<MemoryAddDocument> {
+  const base = {
+    schema_version: 2 as const,
+    product: PRODUCT,
+    command: "memories add-status" as const,
+    request_id: requestId,
+  };
+  if (!UUID.test(requestId)) {
+    return { ...base, state: "invalid", code: "invalid_request_id" };
+  }
+  const user = userIdParameters(userId);
+  const outcome =
+    user.user_id === undefined
+      ? await reader<unknown>(memoryAddStatusPath(requestId))
+      : await reader<unknown>(memoryAddStatusPath(requestId), user);
+  if (outcome.state === "not_found") {
+    return { ...base, state: "not_found", code: "memory_add_not_found" };
+  }
+  if (outcome.state !== "ok") {
+    return {
+      ...base,
+      state: outcome.state === "rejected" ? "rejected" : "unknown",
+      code: outcome.code,
+    };
+  }
+  const receipt = parseMemoryAddReceipt(outcome.data);
+  return receipt === null
+    ? { ...base, state: "unknown", code: "memory_add_receipt_invalid" }
+    : { ...base, state: "accepted", receipt: addReceipt(receipt) };
+}
+
+export function memoryAddExitCode(document: MemoryAddDocument): number {
+  return document.state === "accepted" ? 0 : 1;
+}
+
+export function renderMemoryAddText(document: MemoryAddDocument): string {
+  if (document.state === "accepted" && document.receipt) {
+    return [
+      `request_id: ${document.request_id}`,
+      `evidence_id: ${document.receipt.evidence_id}`,
+      `state: ${document.receipt.state}`,
+      ...((document.receipt.memory_ids as string[]).length > 0
+        ? [`memory_ids: ${(document.receipt.memory_ids as string[]).join(",")}`]
+        : []),
+      document.command === "memories add"
+        ? `查询进度：memhub memories add-status ${document.request_id}；重试请带上同一个 --request-id，不会重复添加。`
+        : "",
+      "",
+    ]
+      .filter((line, index, all) => line !== "" || index === all.length - 1)
+      .join("\n");
+  }
+  if (document.state === "not_found") {
+    return `未找到该 request id：${document.request_id}\n`;
+  }
+  return [
+    `添加记忆未完成：${document.state}（${document.code}）`,
+    document.state === "unknown"
+      ? `结果未知；可以用同一个 --request-id ${document.request_id} 安全重试。`
+      : "",
+    "",
+  ]
+    .filter((line, index, all) => line !== "" || index === all.length - 1)
+    .join("\n");
+}
+
 export function renderMemoryPageText(document: MemoryPageDocument): string {
  const page = document.page;
  if (page.state !== "ok") {
+    if (page.state === "unavailable" && page.code === "embedding_unavailable") {
+      return "向量服务不可用，无法检索；请检查向量模型配置。\n";
+    }
    if (page.state === "unavailable") {
      return "后台正忙，记忆列表这次没查完，不代表没有记忆，请稍后再试\n";
    }
+    if (page.state === "rejected") {
+      return `记忆查询被拒绝（${page.code}），请检查参数。\n`;
+    }
    return `记忆查询未完成：${page.state}（${page.code}）\n`;
  }
  const lines = [
@@ -150,9 +388,16 @@ export function renderMemoryPageText(document: MemoryPageDocument): string {
      page.has_more ? "，还有更多，请用 --offset 继续" : ""
    }`,
  ];
+  if (typeof page.search_window === "number") {
+    lines.push(`（搜索只在最相关的 ${page.search_window} 条里匹配关键词）`);
+  }
  for (const memory of document.memories) {
+    const namespace =
+      memory.kind === "chat"
+        ? ""
+        : ` kind=${memory.kind} variant=${memory.variant}`;
    lines.push(
-      `- ${memory.memory_id}  ${memory.status}/${memory.layer}  source=${memory.source ?? "未知"}`,
+      `- ${memory.memory_id}  [${memory.scene}] ${memory.status}/${memory.layer}  source=${memory.source ?? "未知"}${namespace}`,
      `  ${memory.content}${memory.content_truncated ? ` …（共 ${memory.content_characters} 字）` : ""}`,
    );
  }
@@ -167,10 +412,14 @@ export function renderMemoryDetailText(document: MemoryDetailDocument): string {
    if (memory.state === "unavailable") {
      return "后台正忙，记忆详情这次没查完，不代表没有这条记忆，请稍后再试\n";
    }
+    if (memory.code === "memory_id_ambiguous") {
+      return "这个 ID 同时存在于多个场景；请加 --kind（以及 --variant）指明是哪一条。\n";
+    }
    return `记忆读取未完成：${memory.state}（${memory.code}）\n`;
  }
  const lines = [
    `记忆 ${memory.memory_id}`,
+    `场景：${memory.scene}  类型：${memory.kind}${memory.variant ? `（${memory.variant}）` : ""}`,
    `状态：${memory.status}  层：${memory.layer}  来源：${memory.source ?? "未知"}`,
    `owner：${memory.owner ?? "未知"}  latest：${memory.is_latest}`,
    `raw IDs：${(memory.source_raw_ids as string[]).join(",") || "无"}`,
@@ -188,6 +437,10 @@ function describeMemory(memory: SdkMemoryRecord): Record<string, unknown> {
  const budgeted = budget(memory.content ?? "");
  return {
    memory_id: memory.memory_id,
+    // Pre-2.0.6 Core listed chat memories only and named no scene.
+    scene: memory.scene ?? "chat",
+    kind: memory.kind ?? "chat",
+    variant: memory.variant ?? null,
    status: memory.status,
    layer: memory.layer,
    is_latest: memory.is_latest,
@@ -199,6 +452,9 @@ function describeMemory(memory: SdkMemoryRecord): Record<string, unknown> {
    tags: memory.tags ?? [],
    memory_at: memory.memory_at,
    gmt_created: memory.gmt_created,
+    ...(memory.task === undefined || memory.task === null
+      ? {}
+      : { task: memory.task }),
    content: budgeted.text,
    content_truncated: budgeted.truncated,
    content_characters: budgeted.characters,
@@ -216,6 +472,9 @@ function sdkMemoryPage(value: unknown): SdkMemoryPage | null {
    total: value.total,
    limit: value.limit,
    offset: value.offset,
+    ...(integer(value.search_window)
+      ? { search_window: value.search_window }
+      : {}),
  };
 }

@@ -231,8 +490,9 @@ function sdkMemory(value: unknown): SdkMemoryRecord | null {
    !strings(value.superseded_by) ||
    !strings(value.tags) ||
    !strings(value.source_raw_ids) ||
-    !text(value.user_id) ||
-    !text(value.agent_id)
+    // Working/coding memories may carry an empty user or agent id.
+    typeof value.user_id !== "string" ||
+    typeof value.agent_id !== "string"
  )
    return null;
  return value as unknown as SdkMemoryRecord;
@@ -3,9 +3,9 @@ import { describe, expect, it, vi } from "vitest";
 import type { CoreReader } from "./core-client.js";
 import type { CoreOperations } from "./core-operations.js";
 import {
-  executeModelProbe,
-  planModelProbe,
+  modelProbeExitCode,
  readModelProbeReceipt,
+  startModelProbe,
 } from "./model-probe-flow.js";

 const PROFILE_ID = "22222222-2222-4222-8222-222222222222";
@@ -83,67 +83,101 @@ function completed(operationId: string) {
  };
 }

-describe("model probe operation flow", () => {
-  it("plans against the exact current profile revision", async () => {
-    const reader = vi.fn().mockResolvedValue({ state: "ok", data: [PROFILE] });
-    const document = await planModelProbe(reader as CoreReader, PROFILE_ID);
-    expect(document.state).toBe("preview");
-    if (document.state !== "preview") throw new Error("expected preview");
-    expect(document.plan).toMatchObject({
-      kind: "model_profile_probe",
-      profile_id: PROFILE_ID,
-      expected_profile_revision: 3,
-    });
-    expect(document.plan.operation_id).toMatch(
-      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
-    );
-    expect(document.plan.digest).toMatch(/^[0-9a-f]{64}$/);
-  });
+const OPERATION_ID = "33333333-3333-4333-8333-333333333333";

-  it("proves operation support with schema-1 not_found before posting", async () => {
-    const planned = await planModelProbe(
-      vi.fn().mockResolvedValue({ state: "ok", data: [PROFILE] }) as CoreReader,
-      PROFILE_ID,
-    );
-    if (planned.state !== "preview") throw new Error("expected preview");
-    const operationId = planned.plan.operation_id;
-    const reader = vi
-      .fn()
-      .mockResolvedValueOnce({ state: "ok", data: notFound(operationId) });
+/** Reader that answers the profile list, then the queued operation reads. */
+function readerWith(...operationReads: unknown[]) {
+  const reader = vi.fn(async (path: string) => {
+    if (path === "/api/v1/model-profiles") {
+      return { state: "ok", data: [PROFILE] };
+    }
+    return operationReads.shift() ?? { state: "not_found", code: "http_404" };
+  });
+  return reader;
+}
+
+describe("model probe operation flow", () => {
+  it("probes the exact current profile revision once support is proven", async () => {
+    const reader = readerWith({ state: "ok", data: notFound(OPERATION_ID) });
    const post = vi
      .fn()
-      .mockResolvedValue({ state: "committed", data: completed(operationId) });
+      .mockResolvedValue({ state: "committed", data: completed(OPERATION_ID) });

-    const result = await executeModelProbe(
-      planned.plan,
-      reader as CoreReader,
+    const result = await startModelProbe(
+      reader as unknown as CoreReader,
      { post } as CoreOperations,
+      PROFILE_ID,
+      OPERATION_ID,
    );

    expect(result.state).toBe("completed");
    expect(reader).toHaveBeenCalledWith(
-      `/api/v1/model-probe-operations/${operationId}`,
+      `/api/v1/model-probe-operations/${OPERATION_ID}`,
    );
    expect(post).toHaveBeenCalledWith(
      `/api/v1/model-profiles/${PROFILE_ID}/probe`,
-      { operation_id: operationId, expected_profile_revision: 3 },
+      { operation_id: OPERATION_ID, expected_profile_revision: 3 },
    );
  });

-  it("does not post when the Core lacks the exact operation contract", async () => {
-    const planned = await planModelProbe(
-      vi.fn().mockResolvedValue({ state: "ok", data: [PROFILE] }) as CoreReader,
+  it("generates its own operation id and treats a pending probe as submitted", async () => {
+    const post = vi.fn(
+      async (_path: string, body: Record<string, unknown>) => ({
+        state: "committed",
+        data: {
+          ...notFound(String(body.operation_id)),
+          profile_id: PROFILE_ID,
+          expected_profile_revision: 3,
+          state: "pending",
+          stale: false,
+        },
+      }),
+    );
+    const reader = vi.fn(async (path: string) =>
+      path === "/api/v1/model-profiles"
+        ? { state: "ok", data: [PROFILE] }
+        : {
+            state: "ok",
+            data: notFound(path.split("/").at(-1) ?? ""),
+          },
+    );
+    const result = await startModelProbe(
+      reader as unknown as CoreReader,
+      { post } as unknown as CoreOperations,
      PROFILE_ID,
    );
-    if (planned.state !== "preview") throw new Error("expected preview");
+    expect(result.state).toBe("pending");
+    expect(result.operation_id).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+    expect(modelProbeExitCode(result)).toBe(0);
+  });
+
+  it("refuses an unknown profile without posting", async () => {
    const post = vi.fn();
-    const result = await executeModelProbe(
-      planned.plan,
-      vi.fn().mockResolvedValue({
+    const result = await startModelProbe(
+      readerWith() as unknown as CoreReader,
+      { post } as CoreOperations,
+      "44444444-4444-4444-8444-444444444444",
+      OPERATION_ID,
+    );
+    expect(result).toMatchObject({
+      state: "not_found",
+      code: "model_profile_not_found",
+    });
+    expect(post).not.toHaveBeenCalled();
+  });
+
+  it("does not post when the Core lacks the exact operation contract", async () => {
+    const post = vi.fn();
+    const result = await startModelProbe(
+      readerWith({
        state: "not_found",
        code: "http_404",
-      }) as CoreReader,
+      }) as unknown as CoreReader,
      { post } as CoreOperations,
+      PROFILE_ID,
+      OPERATION_ID,
    );
    expect(result).toMatchObject({
      state: "disabled",
@@ -153,19 +187,15 @@ describe("model probe operation flow", () => {
  });

  it("does not post when a legacy Core returns a non-operation body", async () => {
-    const planned = await planModelProbe(
-      vi.fn().mockResolvedValue({ state: "ok", data: [PROFILE] }) as CoreReader,
-      PROFILE_ID,
-    );
-    if (planned.state !== "preview") throw new Error("expected preview");
    const post = vi.fn();
-    const result = await executeModelProbe(
-      planned.plan,
-      vi.fn().mockResolvedValue({
+    const result = await startModelProbe(
+      readerWith({
        state: "ok",
        data: { detail: "legacy_route_shape" },
-      }) as CoreReader,
+      }) as unknown as CoreReader,
      { post } as CoreOperations,
+      PROFILE_ID,
+      OPERATION_ID,
    );
    expect(result).toMatchObject({
      state: "disabled",
@@ -175,24 +205,19 @@ describe("model probe operation flow", () => {
  });

  it("reconciles an unknown POST by GET and never treats not_found as replay permission", async () => {
-    const planned = await planModelProbe(
-      vi.fn().mockResolvedValue({ state: "ok", data: [PROFILE] }) as CoreReader,
-      PROFILE_ID,
+    const reader = readerWith(
+      { state: "ok", data: notFound(OPERATION_ID) },
+      { state: "ok", data: notFound(OPERATION_ID) },
    );
-    if (planned.state !== "preview") throw new Error("expected preview");
-    const operationId = planned.plan.operation_id;
-    const reader = vi
-      .fn()
-      .mockResolvedValueOnce({ state: "ok", data: notFound(operationId) })
-      .mockResolvedValueOnce({ state: "ok", data: notFound(operationId) });
    const post = vi.fn().mockResolvedValue({
      state: "unknown",
      code: "transport_result_unknown",
    });
-    const result = await executeModelProbe(
-      planned.plan,
-      reader as CoreReader,
+    const result = await startModelProbe(
+      reader as unknown as CoreReader,
      { post } as CoreOperations,
+      PROFILE_ID,
+      OPERATION_ID,
    );
    expect(result).toMatchObject({
      state: "unknown",
@@ -1,11 +1,10 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import type { CoreReader, ReadOutcome } from "./core-client.js";
 import type { CoreOperations } from "./core-operations.js";
 import { validateModelProfiles } from "./core-responses.js";
 import { PRODUCT } from "./version.js";

 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
-const DIGEST = /^[0-9a-f]{64}$/;
 const RECEIPT_KEYS = new Set([
  "schema_version",
  "operation_id",
@@ -23,6 +22,10 @@ const RESULT_KEYS = new Set([
  "stages",
  "capabilities",
 ]);
+const OPTIONAL_RESULT_KEYS = [
+  "embedding_width",
+  "embedding_switch_required",
+] as const;
 const STAGE_KEYS = new Set([
  "stage",
  "ok",
@@ -59,23 +62,7 @@ const CODES = new Set([
  "embedding_unavailable",
 ]);

-interface ModelProbePlanBody {
-  schema_version: 1;
-  kind: "model_profile_probe";
-  operation_id: string;
-  profile_id: string;
-  expected_profile_revision: number;
-}
-
-export type ModelProbePlan = ModelProbePlanBody & { digest: string };
-
 export type ModelProbeFlowDocument =
-  | {
-      schema_version: 1;
-      product: string;
-      state: "preview";
-      plan: ModelProbePlan;
-    }
  | {
      schema_version: 1;
      product: string;
@@ -91,11 +78,25 @@ export type ModelProbeFlowDocument =
      code: string;
    };

-export async function planModelProbe(
+/**
+ * Start one capability probe of a model profile (one real model request).
+ *
+ * Reads the profile's current revision so Core can refuse a probe of a
+ * profile that changed meanwhile, checks that this Core tracks probe
+ * operations (an old Core would start an untracked request), then submits it.
+ * The probe runs asynchronously: the answer is usually `pending`, and
+ * `models receipt <operation-id>` reads the result.
+ */
+export async function startModelProbe(
  reader: CoreReader,
+  operations: CoreOperations,
  profileId: string,
+  operationId: string = randomUUID(),
 ): Promise<ModelProbeFlowDocument> {
  if (!UUID.test(profileId)) return failure("invalid", "invalid_profile_id");
+  if (!UUID.test(operationId)) {
+    return failure("invalid", "invalid_probe_operation_id");
+  }
  const outcome = await reader<unknown>("/api/v1/model-profiles");
  if (outcome.state !== "ok") return fromReadFailure(outcome);
  const profiles = validateModelProfiles(outcome.data);
@@ -105,71 +106,46 @@ export async function planModelProbe(
  );
  if (matches.length !== 1)
    return failure("not_found", "model_profile_not_found");
-  const profile = matches[0];
-  if (!Number.isSafeInteger(profile.revision) || profile.revision < 1) {
+  const revision = matches[0].revision;
+  if (!Number.isSafeInteger(revision) || revision < 1) {
    return failure("invalid", "model_profile_revision_invalid");
  }
-  const plan = withDigest({
-    schema_version: 1 as const,
-    kind: "model_profile_probe" as const,
-    operation_id: randomUUID(),
-    profile_id: profileId,
-    expected_profile_revision: profile.revision,
-  });
-  return { schema_version: 1, product: PRODUCT, state: "preview", plan };
-}
-
-export async function executeModelProbe(
-  value: unknown,
-  reader: CoreReader,
-  operations: CoreOperations,
-): Promise<ModelProbeFlowDocument> {
-  const plan = validatePlan(value);
-  if (!plan) return failure("invalid", "model_probe_plan_invalid");

  // A 404 or a legacy/malformed body is not support. Some old Core versions
  // ignore the operation body and start an untracked external model request.
-  const support = await reader<unknown>(operationPath(plan.operation_id));
+  const support = await reader<unknown>(operationPath(operationId));
  if (support.state !== "ok") {
    return failure(
      "disabled",
      "model_probe_operations_unsupported",
-      plan.operation_id,
+      operationId,
    );
  }
-  const supportReceipt = validateReceipt(support.data, plan.operation_id);
+  const supportReceipt = validateReceipt(support.data, operationId);
  if (supportReceipt?.state !== "not_found") {
    return failure(
      "disabled",
      "model_probe_operations_unsupported",
-      plan.operation_id,
+      operationId,
    );
  }

-  const outcome = await operations.post<unknown>(
-    `/api/v1/model-profiles/${plan.profile_id}/probe`,
-    {
-      operation_id: plan.operation_id,
-      expected_profile_revision: plan.expected_profile_revision,
-    },
+  const posted = await operations.post<unknown>(
+    `/api/v1/model-profiles/${profileId}/probe`,
+    { operation_id: operationId, expected_profile_revision: revision },
  );
-  if (outcome.state === "rejected") {
-    return failure("rejected", outcome.code, plan.operation_id);
+  if (posted.state === "rejected") {
+    return failure("rejected", posted.code, operationId);
  }
-  if (outcome.state === "committed") {
-    return receiptDocument(
-      outcome.data,
-      plan.operation_id,
-      plan.profile_id,
-      plan.expected_profile_revision,
-    );
+  if (posted.state === "committed") {
+    return receiptDocument(posted.data, operationId, profileId, revision);
  }
-  const reconciled = await readModelProbeReceipt(reader, plan.operation_id);
+  const reconciled = await readModelProbeReceipt(reader, operationId);
  return reconciled.state === "not_found"
    ? failure(
        "unknown",
        "model_probe_receipt_not_found_after_attempt",
-        plan.operation_id,
+        operationId,
      )
    : reconciled;
 }
@@ -190,32 +166,24 @@ export async function readModelProbeReceipt(
  return receiptDocument(outcome.data, operationId);
 }

-export function inspectModelProbePlan(value: unknown): ModelProbePlan | null {
-  return validatePlan(value);
-}
-
 export function modelProbeExitCode(document: ModelProbeFlowDocument): number {
-  return ["preview", "completed"].includes(document.state) ? 0 : 1;
+  // `pending` is a submitted probe still running: the submit succeeded.
+  return ["completed", "pending"].includes(document.state) ? 0 : 1;
 }

 export function renderModelProbeText(document: ModelProbeFlowDocument): string {
-  if (document.state === "preview") {
-    return [
-      "预览：模型能力探测",
-      `模型配置：${document.plan.profile_id}`,
-      `预期版本：${document.plan.expected_profile_revision}`,
-      `操作 ID：${document.plan.operation_id}`,
-      `确认摘要：${document.plan.digest}`,
-      "未发起模型请求。请保存 --json 输出，再用 models probe --plan-file <path> --confirm。",
-      "",
-    ].join("\n");
-  }
-  return [
+  const lines = [
    `探测状态：${document.state}`,
    `操作 ID：${document.operation_id ?? "无"}`,
    "code" in document ? `代码：${document.code}` : "已返回有界操作回执。",
-    "",
-  ].join("\n");
+  ];
+  if (document.state === "pending" && document.operation_id) {
+    lines.push(
+      `探测在后台进行；用 memhub models receipt ${document.operation_id} 查看结果。`,
+    );
+  }
+  lines.push("");
+  return lines.join("\n");
 }

 function receiptDocument(
@@ -249,31 +217,6 @@ function receiptDocument(
  };
 }

-function validatePlan(value: unknown): ModelProbePlan | null {
-  const plan = record(value);
-  if (
-    plan?.schema_version !== 1 ||
-    plan.kind !== "model_profile_probe" ||
-    typeof plan.operation_id !== "string" ||
-    !UUID.test(plan.operation_id) ||
-    typeof plan.profile_id !== "string" ||
-    !UUID.test(plan.profile_id) ||
-    !positiveInteger(plan.expected_profile_revision) ||
-    typeof plan.digest !== "string" ||
-    !DIGEST.test(plan.digest)
-  ) {
-    return null;
-  }
-  const expected = withDigest({
-    schema_version: 1 as const,
-    kind: "model_profile_probe" as const,
-    operation_id: plan.operation_id,
-    profile_id: plan.profile_id,
-    expected_profile_revision: plan.expected_profile_revision,
-  });
-  return expected.digest === plan.digest ? expected : null;
-}
-
 function validateReceipt(
  value: unknown,
  operationId: string,
@@ -333,9 +276,34 @@ function validateResult(
  inputRevision: number,
 ): Record<string, unknown> | null {
  const result = record(value);
+  // A Core with the embedding registry adds what the embedding stage measured
+  // and whether using it needs an embedding switch; older Cores send neither.
+  const optional = Object.fromEntries(
+    OPTIONAL_RESULT_KEYS.filter((key) => key in (result ?? {})).map((key) => [
+      key,
+      result?.[key],
+    ]),
+  );
+  const required = result
+    ? Object.fromEntries(
+        Object.entries(result).filter(
+          ([key]) => !(OPTIONAL_RESULT_KEYS as readonly string[]).includes(key),
+        ),
+      )
+    : null;
  if (
    !result ||
-    !exactKeys(result, RESULT_KEYS) ||
+    !required ||
+    !exactKeys(required, RESULT_KEYS) ||
+    !(
+      optional.embedding_width === undefined ||
+      optional.embedding_width === null ||
+      positiveInteger(optional.embedding_width)
+    ) ||
+    !(
+      optional.embedding_switch_required === undefined ||
+      typeof optional.embedding_switch_required === "boolean"
+    ) ||
    result.profile_id !== profileId ||
    result.input_profile_revision !== inputRevision ||
    !positiveInteger(result.profile_revision) ||
@@ -409,27 +377,6 @@ function failure(
  };
 }

-function withDigest<T extends object>(body: T): T & { digest: string } {
-  return {
-    ...body,
-    digest: createHash("sha256").update(canonical(body)).digest("hex"),
-  };
-}
-
-function canonical(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
-  if (value && typeof value === "object") {
-    return `{${Object.keys(value)
-      .sort()
-      .map(
-        (key) =>
-          `${JSON.stringify(key)}:${canonical((value as Record<string, unknown>)[key])}`,
-      )
-      .join(",")}}`;
-  }
-  return JSON.stringify(value);
-}
-
 function record(value: unknown): Record<string, unknown> | null {
  return value !== null && typeof value === "object" && !Array.isArray(value)
    ? (value as Record<string, unknown>)
@@ -41,7 +41,7 @@ export type ModelReportDocument =
  | {
      schema_version: 1;
      product: string;
-      state: "denied" | "unavailable" | "not_found" | "invalid";
+      state: "denied" | "unavailable" | "not_found" | "invalid" | "rejected";
      code: string;
    };

@@ -136,7 +136,7 @@ function project(profile: ModelProfile): SafeModelProfile {
 }

 function failure(
-  state: "denied" | "unavailable" | "not_found" | "invalid",
+  state: "denied" | "unavailable" | "not_found" | "invalid" | "rejected",
  code: string,
 ): ModelReportDocument {
  return { schema_version: 1, product: PRODUCT, state, code };
@@ -126,29 +126,12 @@ describe("models activate", () => {
    expect(runtime.inspectRuntimeStatus).not.toHaveBeenCalled();
  });

-  it("previews without contacting Core", async () => {
-    const result = await capturedRun(["models", "activate", PROFILE, "--json"]);
-    expect(result.code).toBe(0);
-    const document = JSON.parse(result.stdout);
-    expect(document.state).toBe("preview");
-    expect(document.plan.kind).toBe("model_profile_activate");
-    // Activation has no CAS body, so the plan must not pretend to carry one.
-    expect(document.plan).not.toHaveProperty("expected_revision");
-    expect(transport.post).not.toHaveBeenCalled();
-  });
-
-  it("posts the activate endpoint with --confirm and reports the profile", async () => {
+  it("posts the activate endpoint directly and reports the profile", async () => {
    transport.post.mockResolvedValue({
      status: 200,
      data: profileResponse(),
    });
-    const result = await capturedRun([
-      "models",
-      "activate",
-      PROFILE,
-      "--confirm",
-      "--json",
-    ]);
+    const result = await capturedRun(["models", "activate", PROFILE, "--json"]);
    expect(result.code).toBe(0);
    expect(transport.post).toHaveBeenCalledWith(
      `/api/v1/model-profiles/${PROFILE}/activate`,
@@ -196,31 +179,22 @@ describe("models activate", () => {
  });
 });

-describe("models edit", () => {
-  it("previews a patch from a config file without writing", async () => {
-    const directory = await mkdtemp(path.join(tmpdir(), "om-model-edit-"));
-    const config = path.join(directory, "patch.json");
-    await writeFile(
-      config,
-      JSON.stringify({ expected_revision: 4, name: "Renamed" }),
-      { mode: 0o600 },
-    );
-    const result = await capturedRun([
-      "models",
-      "edit",
-      PROFILE,
-      "--config-file",
-      config,
-      "--json",
-    ]);
+describe("models remove", () => {
+  it("previews without --yes and changes nothing", async () => {
+    const result = await capturedRun(["models", "remove", PROFILE, "--json"]);
    expect(result.code).toBe(0);
-    const document = JSON.parse(result.stdout);
-    expect(document.state).toBe("preview");
-    expect(document.plan.patch).toEqual({ name: "Renamed" });
-    expect(transport.patch).not.toHaveBeenCalled();
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      command: "models remove",
+      state: "preview",
+      target: PROFILE,
+      applied: false,
+    });
+    expect(runtime.inspectRuntimeStatus).not.toHaveBeenCalled();
  });
+});

-  it("sends the exact patch body with the CAS revision on confirm", async () => {
+describe("models edit", () => {
+  it("sends the exact patch body with the CAS revision directly", async () => {
    const directory = await mkdtemp(path.join(tmpdir(), "om-model-edit-"));
    const config = path.join(directory, "patch.json");
    await writeFile(
@@ -242,7 +216,6 @@ describe("models edit", () => {
      PROFILE,
      "--config-file",
      config,
-      "--confirm",
      "--json",
    ]);
    expect(result.code).toBe(0);
@@ -3,14 +3,12 @@
 * activate (`POST /model-profiles/{id}/activate`) and edit
 * (`PATCH /model-profiles/{id}`).
 *
- * Core owns the semantics. These flows reuse the same two-phase convention as
- * `models configure`: plan without `--confirm` (or produce a plan file), then
- * apply exactly that plan. The edit body mirrors the Web console's
- * `ModelProfilePatch`, including `expected_revision` as the compare-and-swap
- * guard Core requires.
+ * Core owns the semantics. Both run directly: activation is reversible (activate
+ * another profile) and an edit is guarded by `expected_revision`, the
+ * compare-and-swap Core requires, mirroring the Web console's
+ * `ModelProfilePatch`.
 */

-import { createHash, randomUUID } from "node:crypto";
 import type { ModelProfile } from "@one-memory/contracts";
 import {
  buildModelProfileUpdateRequest,
@@ -22,29 +20,7 @@ import { PRODUCT } from "./version.js";

 const PROFILE_ID = /^[A-Za-z0-9][\w.-]{0,127}$/;

-export type ModelWritePlan =
-  | {
-      schema_version: 1;
-      kind: "model_profile_activate";
-      profile_id: string;
-      digest: string;
-    }
-  | {
-      schema_version: 1;
-      kind: "model_profile_edit";
-      profile_id: string;
-      expected_revision: number;
-      patch: Record<string, unknown>;
-      digest: string;
-    };
-
 export type ModelWriteDocument =
-  | {
-      schema_version: 1;
-      product: string;
-      state: "preview";
-      plan: ModelWritePlan;
-    }
  | {
      schema_version: 1;
      product: string;
@@ -60,38 +36,6 @@ export type ModelWriteDocument =
      code: string;
    };

-function canonical(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
-  if (value !== null && typeof value === "object") {
-    return `{${Object.entries(value as Record<string, unknown>)
-      .sort(([left], [right]) => left.localeCompare(right))
-      .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
-      .join(",")}}`;
-  }
-  if (value === undefined) return "null";
-  return JSON.stringify(value);
-}
-
-function digestOf(value: unknown): string {
-  return createHash("sha256").update(canonical(value)).digest("hex");
-}
-
-function preview(
-  plan:
-    | Omit<
-        Extract<ModelWritePlan, { kind: "model_profile_activate" }>,
-        "digest"
-      >
-    | Omit<Extract<ModelWritePlan, { kind: "model_profile_edit" }>, "digest">,
-): ModelWriteDocument {
-  return {
-    schema_version: 1,
-    product: PRODUCT,
-    state: "preview",
-    plan: { ...plan, digest: digestOf(plan) } as ModelWritePlan,
-  };
-}
-
 function invalid(code: string): ModelWriteDocument {
  return { schema_version: 1, product: PRODUCT, state: "invalid", code };
 }
@@ -122,87 +66,45 @@ function projectProfile(profile: ModelProfile): Record<string, unknown> {
  };
 }

-// --- activate -------------------------------------------------------------
-
-/**
- * Activation has no request body, so the plan carries only the target. There
- * is deliberately no `expected_revision`: Core would never read one, and
- * recording a check it does not perform would be a fake guard.
- */
-export function planModelProfileActivate(input: {
-  profileId: string;
-}): ModelWriteDocument {
-  return PROFILE_ID.test(input.profileId)
-    ? preview({
-        schema_version: 1,
-        kind: "model_profile_activate",
-        profile_id: input.profileId,
-      })
-    : invalid("model_profile_activate_input_invalid");
-}
-
-export async function executeModelProfileActivate(
-  plan: Extract<ModelWritePlan, { kind: "model_profile_activate" }>,
+/** Make `profileId` the active profile. Activation has no request body, so
+ * there is no revision for Core to check. */
+export async function activateModelProfile(
+  profileId: string,
  operations: CoreOperations,
 ): Promise<ModelWriteDocument> {
+  if (!PROFILE_ID.test(profileId)) {
+    return invalid("model_profile_activate_input_invalid");
+  }
  const result = await operations.post<unknown>(
-    `/api/v1/model-profiles/${encodeURIComponent(plan.profile_id)}/activate`,
+    `/api/v1/model-profiles/${encodeURIComponent(profileId)}/activate`,
    {},
  );
-  return modelProfileResult(plan.profile_id, result);
+  return modelProfileResult(profileId, result);
 }

-// --- edit -----------------------------------------------------------------
-
-export function planModelProfileEdit(input: {
-  profileId: string;
-  patch: unknown;
-}): ModelWriteDocument {
-  // The shared builder owns patch validation (14-key allow-list,
-  // expected_revision CAS, field bounds, api_key/clear_api_key exclusivity).
-  // A rejected patch is `invalid`, never a plan the caller could confirm.
-  let request: ReturnType<typeof buildModelProfileUpdateRequest>;
-  try {
-    request = buildModelProfileUpdateRequest(input.profileId, input.patch);
-  } catch (error) {
-    if (error instanceof ModelProfileInputError) {
-      return invalid("model_profile_edit_input_invalid");
-    }
-    throw error;
-  }
-  const patch = request.body as Record<string, unknown>;
-  if (!PROFILE_ID.test(input.profileId)) {
+/** Apply a bounded patch (carrying `expected_revision`) to one profile; the
+ * key, when given, comes from a controlled file and never from the patch. */
+export async function editModelProfile(
+  profileId: string,
+  patch: unknown,
+  apiKey: string | undefined,
+  operations: CorePatchOperations,
+): Promise<ModelWriteDocument> {
+  if (
+    !PROFILE_ID.test(profileId) ||
+    patch === null ||
+    typeof patch !== "object" ||
+    Array.isArray(patch) ||
+    "api_key" in patch
+  ) {
    return invalid("model_profile_edit_input_invalid");
  }
-  return preview({
-    schema_version: 1,
-    kind: "model_profile_edit",
-    profile_id: input.profileId,
-    expected_revision: patch.expected_revision as number,
-    // `api_key` is read from a controlled file at apply time, exactly like
-    // `models configure`; the plan never carries the credential. The revision
-    // is a top-level field, so it is stripped from the nested patch rather
-    // than being duplicated in both places.
-    patch: Object.fromEntries(
-      Object.entries(patch).filter(
-        ([key]) => key !== "api_key" && key !== "expected_revision",
-      ),
-    ),
-  });
-}
-
-export async function executeModelProfileEdit(
-  plan: Extract<ModelWritePlan, { kind: "model_profile_edit" }>,
-  operations: CorePatchOperations,
-  apiKey: string | undefined,
-): Promise<ModelWriteDocument> {
-  // Re-validate through the shared builder at apply time too, so a hand-edited
-  // plan cannot smuggle an out-of-bounds patch past the write.
+  // The shared builder owns patch validation (allow-list, expected_revision
+  // CAS, field bounds, api_key/clear_api_key exclusivity).
  let request: ReturnType<typeof buildModelProfileUpdateRequest>;
  try {
-    request = buildModelProfileUpdateRequest(plan.profile_id, {
-      ...plan.patch,
-      expected_revision: plan.expected_revision,
+    request = buildModelProfileUpdateRequest(profileId, {
+      ...(patch as Record<string, unknown>),
      ...(apiKey === undefined ? {} : { api_key: apiKey }),
    });
  } catch (error) {
@@ -212,10 +114,10 @@ export async function executeModelProfileEdit(
    throw error;
  }
  const result = await operations.patch<unknown>(request.path, request.body);
-  return modelProfileResult(plan.profile_id, result);
+  return modelProfileResult(profileId, result);
 }

-function modelProfileResult(
+export function modelProfileResult(
  operationId: string,
  result:
    | Awaited<ReturnType<CoreOperations["post"]>>
@@ -254,69 +156,11 @@ function modelProfileResult(
  return committed(operationId, profile);
 }

-export function validateModelWritePlan(value: unknown): ModelWritePlan | null {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    return null;
-  }
-  const candidate = value as Record<string, unknown>;
-  if (candidate.schema_version !== 1 || typeof candidate.kind !== "string") {
-    return null;
-  }
-  const { digest, ...withoutDigest } = candidate;
-  if (typeof digest !== "string" || digest !== digestOf(withoutDigest)) {
-    return null;
-  }
-  switch (candidate.kind) {
-    case "model_profile_activate":
-      return typeof candidate.profile_id === "string" &&
-        PROFILE_ID.test(candidate.profile_id) &&
-        Object.keys(candidate).length === 3
-        ? (candidate as unknown as ModelWritePlan)
-        : null;
-    case "model_profile_edit": {
-      if (
-        typeof candidate.profile_id !== "string" ||
-        !PROFILE_ID.test(candidate.profile_id) ||
-        !Number.isSafeInteger(candidate.expected_revision)
-      ) {
-        return null;
-      }
-      // The shared builder is the single judge of a patch body; the plan must
-      // not carry `api_key` (that is read from a controlled file at apply).
-      let built: ReturnType<typeof buildModelProfileUpdateRequest>;
-      try {
-        built = buildModelProfileUpdateRequest(candidate.profile_id, {
-          ...(candidate.patch as Record<string, unknown>),
-          expected_revision: candidate.expected_revision,
-        });
-      } catch {
-        return null;
-      }
-      if ("api_key" in built.body) return null;
-      return Object.keys(candidate).length === 6
-        ? (candidate as unknown as ModelWritePlan)
-        : null;
-    }
-    default:
-      return null;
-  }
-}
-
 export function modelWriteExitCode(document: ModelWriteDocument): number {
-  return ["preview", "committed"].includes(document.state) ? 0 : 1;
+  return document.state === "committed" ? 0 : 1;
 }

 export function renderModelWriteText(document: ModelWriteDocument): string {
-  if (document.state === "preview") {
-    const plan = document.plan;
-    return [
-      `预览：${plan.kind}`,
-      `目标配置：${plan.profile_id}`,
-      `确认摘要：${plan.digest}`,
-      "未执行任何写操作。请把 --json 输出保存为 plan 文件，再用对应命令加 --confirm。",
-      "",
-    ].join("\n");
-  }
  if (document.state === "committed") {
    return `已保存模型配置：${document.receipt.profile_id}\nrevision=${document.receipt.revision}\n`;
  }
@@ -1,57 +0,0 @@
-import { constants } from "node:fs";
-import { type FileHandle, open } from "node:fs/promises";
-import { readBoundedJson } from "./bounded-file.js";
-
-export type PlanAttempt = {
-  schema_version: 1;
-  operation_id: string;
-  plan_digest: string;
-};
-
-/**
- * Durable client fence written before a mutating request. Once present, the
- * same plan may only query its operation receipt; it is never blindly posted
- * again after an unknown result.
- */
-export async function claimPlanAttempt(
-  planFile: string,
-  attempt: PlanAttempt,
-): Promise<"first" | "prior" | "invalid"> {
-  const journal = `${planFile}.one-memory-attempt`;
-  let handle: FileHandle;
-  try {
-    handle = await open(
-      journal,
-      constants.O_WRONLY |
-        constants.O_CREAT |
-        constants.O_EXCL |
-        (constants.O_NOFOLLOW ?? 0),
-      0o600,
-    );
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "EEXIST") return "invalid";
-    const current = await readBoundedJson(journal, 1024);
-    return sameAttempt(current, attempt) ? "prior" : "invalid";
-  }
-  try {
-    await handle.writeFile(`${JSON.stringify(attempt)}\n`, "utf8");
-    await handle.sync();
-    return "first";
-  } catch {
-    return "invalid";
-  } finally {
-    await handle.close().catch(() => undefined);
-  }
-}
-
-function sameAttempt(value: unknown, expected: PlanAttempt): boolean {
-  return (
-    value !== null &&
-    typeof value === "object" &&
-    !Array.isArray(value) &&
-    (value as Record<string, unknown>).schema_version === 1 &&
-    (value as Record<string, unknown>).operation_id === expected.operation_id &&
-    (value as Record<string, unknown>).plan_digest === expected.plan_digest &&
-    Object.keys(value).length === 3
-  );
-}
@@ -104,7 +104,7 @@ describe("package matrix harness", () => {
    });
  });

-  it("fails closed on every destructive UI-write command without a Runtime", {
+  it("fails closed on every write command without a Runtime", {
    timeout: 120_000,
  }, async () => {
    const runtimeDist = await mkdtemp(
@@ -140,7 +140,7 @@ describe("package matrix harness", () => {
    expect(document.state).toBe("verified");
    const results = document.commands.stopped_destructive.results;
    // Every destructive command fails closed while Runtime is stopped.
-    expect(Object.keys(results)).toHaveLength(7);
+    expect(Object.keys(results)).toHaveLength(8);
    for (const [name, result] of Object.entries(results)) {
      expect(result, `${name} did not fail closed`).toEqual({
        exit: 3,
@@ -164,7 +164,7 @@ describe("package matrix harness", () => {
    const shim = [
      "#!/usr/bin/env node",
      "const a=process.argv.slice(2);",
-      "if(['calls','notes','graph','models','memories'].includes(a[0])){",
+      "if(['graph-width','models','memories','sources'].includes(a[0])){",
      '  process.stdout.write(\'{"schema_version":1,"product":"memhub","state":"committed","operation_id":"x","receipt":{}}\\n\');',
      "  process.exit(0);",
      "}",
@@ -190,7 +190,7 @@ describe("package matrix harness", () => {
    expect(failure?.state).toBe("failed");
    expect(
      failure?.failures.filter((item) => item.includes("did not fail closed")),
-    ).toHaveLength(7);
+    ).toHaveLength(8);
  });

  it("can require an expected bundle SHA and reports bundle metadata", {
@@ -291,9 +291,7 @@ describe("package matrix harness", () => {
      "sync",
      "memories",
      "profile",
-      "calls",
-      "notes",
-      "graph",
+      "graph-width",
      "models",
      "host",
      "doctor",
@@ -311,14 +309,12 @@ describe("package matrix harness", () => {
      "uninstall",
      "delete-data",
      "recall",
-      "setup",
      "scan",
      "progress",
      "jobs",
-      "path",
+      "scan-roots",
      "adapter",
      "write",
-      "task",
      "serve",
    ];
    const catalog = {
@@ -145,13 +145,15 @@ describe("memhub short-command contract", () => {
      [command.usage, command.alternative_usage ?? ""].join("\n"),
    ).join("\n");
    for (const shortForm of [
-      "memhub calls clear",
-      "memhub notes add",
-      "memhub notes process",
+      "memhub memories add",
+      "memhub memories add-status",
      "memhub models setup",
+      "memhub models add",
+      "memhub models test",
      "memhub models activate",
      "memhub models edit",
-      "memhub graph width",
+      "memhub graph-width",
+      "memhub sources connect",
      "memhub write submit",
      "memhub write status",
      "memhub memories update",
@@ -159,6 +161,10 @@ describe("memhub short-command contract", () => {
    ]) {
      expect(flattened).toContain(shortForm);
    }
+    // No "note" concept and no plan files on the CLI surface.
+    for (const removed of ["memhub notes", "memhub calls", "--plan-file"]) {
+      expect(flattened).not.toContain(removed);
+    }
    expect(COMMANDS.some((command) => command.name === "permission")).toBe(
      false,
    );
@@ -211,7 +217,7 @@ describe("memhub short-command contract", () => {
  // but an earlier catalog text still claimed they were "尚不可用". A user
  // reading `help path` would not try a command that works.
  it("does not call the wired path/adapter commands unavailable", () => {
-    for (const name of ["path", "adapter"]) {
+    for (const name of ["scan-roots", "adapter"]) {
      const command = COMMANDS.find((entry) => entry.name === name);
      expect(command).toBeDefined();
      const text = [
@@ -277,7 +283,7 @@ describe("memhub short-command contract", () => {
    }
  });

-  it("keeps plan-file apply previews free of diagnostic side effects", {
+  it("keeps destructive previews free of diagnostic side effects", {
    timeout: 20_000,
  }, async () => {
    expect(
@@ -291,9 +297,10 @@ describe("memhub short-command contract", () => {
    );
    try {
      for (const [index, argv] of [
-        ["sources", "import", "--plan-file", path.join(root, "plan.json")],
-        ["models", "configure", "--plan-file", path.join(root, "plan.json")],
-        ["memories", "apply", "--plan-file", path.join(root, "plan.json")],
+        ["memories", "delete", "m-1"],
+        ["models", "remove", "44444444-4444-4444-8444-444444444444"],
+        ["backup", "restore", "--source", path.join(root, "backup.sqlite3")],
+        ["graph-width", "--decision", "rebuild_with_new"],
      ].entries()) {
        const dataDir = path.join(root, `data-${index}`);
        await import("node:fs/promises").then(({ mkdir }) =>
@@ -305,8 +312,8 @@ describe("memhub short-command contract", () => {
            stdio: "pipe",
          });
        } catch {
-          // The missing plan or stopped Runtime is expected; the guard is
-          // that even the failure path did not add a diagnostic file.
+          // A failure path is acceptable; the guard is that no preview adds
+          // a diagnostic file.
        }
        expect(await readdir(dataDir)).toEqual([]);
      }
@@ -1,122 +1,56 @@
-// A6: the rules behind the six product commands.
+// The rules behind the commands that attach to the Runtime directly.
 //
-// The parsers are where the contract actually lives — "needs --yes to change
-// anything" and "no write without evidence" are decisions, not formatting — so
-// they are tested directly rather than only through the CLI.
+// The parsers are where the contract actually lives — "only irreversible
+// operations ask for --yes" and "unknown flags are rejected" are decisions,
+// not formatting — so they are tested directly rather than only through the
+// CLI.

 import { describe, expect, it } from "vitest";

 import { parseOpenAIMessages } from "./core-client.js";
 import {
-  asPlanDocument,
-  describe as describePlan,
-  parseProductCommand,
+  parseBackupCommand,
+  parseScanCommand,
+  parseScanRootsCommand,
  parseTaskCommand,
  parseWriteCommand,
  restoreConfirmationMatches,
 } from "./product-flows.js";

-describe("mutating commands are two-phase", () => {
-  it("plans without --yes", () => {
-    const parsed = parseProductCommand("scan", ["--root", "/tmp/a"]);
-    expect(parsed?.confirmed).toBe(false);
-  });
-
-  it("confirms with --yes", () => {
-    const parsed = parseProductCommand("scan", ["--root", "/tmp/a", "--yes"]);
-    expect(parsed?.confirmed).toBe(true);
-  });
-
-  it("says what it would do", () => {
-    const parsed = parseProductCommand("scan", ["--root", "/tmp/a"]);
-    // `?.plan!` would let a null parse pass silently; assert the parse first.
-    if (parsed === null) {
-      throw new Error("scan with a root must parse");
-    }
-    expect(describePlan(parsed.plan)).toContain("scan: /tmp/a");
-  });
-
-  it("marks a plan as not applied", () => {
-    // Assert the parse itself: `?.` let a null result satisfy this test for as
-    // long as `backup create` was unparseable.
-    const parsed = parseProductCommand("backup", [
-      "create",
-      "--target",
-      "/tmp/b",
-    ]);
-    if (parsed === null) {
-      throw new Error("backup create must parse");
-    }
-    expect(parsed.plan.verb).toBe("create");
-    expect(asPlanDocument(parsed.plan).applied).toBe(false);
-  });
-
-  it("parses the verb for every command that takes one", () => {
-    // `path add` / `path remove` / `backup create` were rejected outright
-    // before the verb was skipped in parsing.
+describe("scan-roots", () => {
+  it("reads the root, source and recursive flag off add", () => {
    expect(
-      parseProductCommand("path", ["add", "--root", "/tmp/x"])?.plan.action,
-    ).toBe("add scan root");
-    expect(
-      parseProductCommand("path", ["remove", "--root", "/tmp/x"])?.plan.action,
-    ).toBe("remove scan root");
-    expect(
-      parseProductCommand("backup", ["restore", "--source", "/tmp/b"])?.plan
-        .action,
-    ).toBe("restore backup");
+      parseScanRootsCommand([
+        "add",
+        "--root",
+        "/tmp/x",
+        "--source",
+        "codex",
+        "--no-recursive",
+      ]),
+    ).toEqual({
+      kind: "add",
+      root: "/tmp/x",
+      source: "codex",
+      recursive: false,
+    });
+    expect(parseScanRootsCommand(["add", "--root", "/tmp/x"])).toEqual({
+      kind: "add",
+      root: "/tmp/x",
+      recursive: true,
+    });
  });

-  it("defaults a scan to all registered roots", () => {
-    const parsed = parseProductCommand("scan", []);
-    expect(parsed?.plan.target).toBe("all registered roots");
-  });
-});
-
-describe("unknown flags are rejected", () => {
-  it("rejects a typo'd flag rather than ignoring it", () => {
-    // A silently ignored --yes would turn a real apply into a plan, and the
-    // user would believe the change had been made.
-    expect(parseProductCommand("scan", ["--yesx"])).toBeNull();
-    expect(parseProductCommand("scan", ["--root"])).toBeNull();
-    expect(parseProductCommand("scan", ["--root", "--yes"])).toBeNull();
-  });
-
-  it("rejects an unknown verb for backup", () => {
+  it("distinguishes remove from add and refuses add-only flags on remove", () => {
+    expect(parseScanRootsCommand(["remove", "--root", "/tmp/x"])).toEqual({
+      kind: "remove",
+      root: "/tmp/x",
+    });
    expect(
-      parseProductCommand("backup", ["make", "--target", "/tmp/b"]),
+      parseScanRootsCommand(["remove", "--root", "/tmp/x", "--no-recursive"]),
    ).toBeNull();
-  });
-
-  // `path` and `scan` share one parser. Before this guard, an unknown verb was
-  // silently treated as `path add` or a default `scan`, so `--yes` executed a
-  // different operation than the one the caller named.
-  it("rejects an unknown verb for path without turning it into add", () => {
    expect(
-      parseProductCommand("path", ["frobnicate", "--root", "/tmp/x", "--yes"]),
-    ).toBeNull();
-  });
-
-  it("rejects an unknown verb for scan without turning it into all", () => {
-    expect(
-      parseProductCommand("scan", ["frobnicate", "--all", "--yes"]),
-    ).toBeNull();
-    expect(parseProductCommand("scan", ["frobnicate", "--yes"])).toBeNull();
-  });
-
-  it("still accepts the documented verbless scan", () => {
-    expect(parseProductCommand("scan", ["--all", "--yes"])?.plan.all).toBe(
-      true,
-    );
-    expect(
-      parseProductCommand("scan", ["--source", "codex"])?.plan.sourceId,
-    ).toBe("codex");
-  });
-
-  it("rejects flags that the named verb does not consume", () => {
-    // These were accepted and then silently dropped. An operator who typed
-    // `path remove --source codex` would believe the source filter applied.
-    expect(
-      parseProductCommand("path", [
+      parseScanRootsCommand([
        "remove",
        "--root",
        "/tmp/x",
@@ -124,137 +58,103 @@ describe("unknown flags are rejected", () => {
        "codex",
      ]),
    ).toBeNull();
+  });
+
+  it("is direct, but keeps accepting a legacy --yes", () => {
+    expect(parseScanRootsCommand(["add", "--root", "/tmp/x", "--yes"])).toEqual(
+      { kind: "add", root: "/tmp/x", recursive: true },
+    );
+  });
+
+  it("rejects unknown verbs, typos and repeated flags", () => {
+    expect(parseScanRootsCommand(["create", "--root", "/tmp/x"])).toBeNull();
+    expect(parseScanRootsCommand(["add", "--rot", "/tmp/x"])).toBeNull();
+    expect(parseScanRootsCommand(["add"])).toBeNull();
    expect(
-      parseProductCommand("path", [
-        "remove",
-        "--root",
-        "/tmp/x",
-        "--no-recursive",
-      ]),
+      parseScanRootsCommand(["add", "--root", "/a", "--root", "/b"]),
    ).toBeNull();
    expect(
-      parseProductCommand("path", ["add", "--root", "/tmp/x", "--full"]),
+      parseScanRootsCommand(["add", "--root", "/a", "--yes", "--yes"]),
+    ).toBeNull();
+  });
+});
+
+describe("scan", () => {
+  it("needs a source: there is no endpoint that scans a bare path", () => {
+    expect(parseScanCommand(["--source", "codex"])).toEqual({
+      kind: "source",
+      sourceId: "codex",
+    });
+    expect(parseScanCommand([])).toBeNull();
+    expect(parseScanCommand(["--root", "/tmp/a"])).toBeNull();
+  });
+
+  it("no longer accepts --full, which was never sent to Core", () => {
+    expect(parseScanCommand(["--source", "codex", "--full"])).toBeNull();
+  });
+
+  it("keeps --all as a hidden alias and a legacy --yes", () => {
+    expect(parseScanCommand(["--all", "--yes"])).toEqual({ kind: "all" });
+    expect(parseScanCommand(["--all", "--source", "codex"])).toBeNull();
+    expect(parseScanCommand(["--source", "codex", "--yes"])).toEqual({
+      kind: "source",
+      sourceId: "codex",
+    });
+  });
+
+  it("rejects a verb, a bad source id and repeated flags", () => {
+    expect(parseScanCommand(["all"])).toBeNull();
+    expect(parseScanCommand(["--source", "Bad Id"])).toBeNull();
+    expect(
+      parseScanCommand(["--source", "codex", "--source", "cursor"]),
    ).toBeNull();
    expect(
-      parseProductCommand("backup", [
-        "create",
-        "--target",
-        "/tmp/b",
-        "--source",
-        "/tmp/s",
-      ]),
+      parseScanCommand(["--source", "codex", "--json", "--json"]),
    ).toBeNull();
+  });
+});
+
+describe("backup", () => {
+  it("creates directly and requires a target", () => {
+    expect(parseBackupCommand(["create", "--target", "/tmp/b"])).toEqual({
+      verb: "create",
+      target: "/tmp/b",
+    });
+    expect(parseBackupCommand(["create"])).toBeNull();
    expect(
-      parseProductCommand("backup", [
-        "restore",
-        "--source",
-        "/tmp/s",
-        "--target",
-        "/tmp/t",
-      ]),
+      parseBackupCommand(["create", "--target", "/tmp/b", "--source", "/x"]),
    ).toBeNull();
  });

-  // A later value silently won before this guard. For `scan --source` that
-  // means one extra shell/make variable can change which source is scanned
-  // while the operator believes both were applied.
-  it("rejects repeated value-bearing flags instead of letting the last one win", () => {
+  it("restores only with --yes and requires a source", () => {
+    expect(parseBackupCommand(["restore", "--source", "/tmp/b"])).toEqual({
+      verb: "restore",
+      source: "/tmp/b",
+      confirmed: false,
+    });
    expect(
-      parseProductCommand("scan", ["--source", "codex", "--source", "cursor"]),
-    ).toBeNull();
-    expect(
-      parseProductCommand("path", [
-        "add",
-        "--root",
-        "/tmp/a",
-        "--root",
-        "/tmp/b",
-      ]),
-    ).toBeNull();
-    expect(
-      parseProductCommand("backup", [
-        "create",
-        "--target",
-        "/tmp/a",
-        "--target",
-        "/tmp/b",
-      ]),
-    ).toBeNull();
+      parseBackupCommand(["restore", "--source", "/tmp/b", "--yes"]),
+    ).toMatchObject({ confirmed: true });
+    expect(parseBackupCommand(["restore", "--yes"])).toBeNull();
  });

-  it("rejects repeated boolean flags instead of treating them as idempotent", () => {
-    expect(parseProductCommand("scan", ["--all", "--all", "--yes"])).toBeNull();
-    expect(
-      parseProductCommand("scan", ["--full", "--full", "--yes"]),
-    ).toBeNull();
-    expect(
-      parseProductCommand("path", [
-        "add",
-        "--root",
-        "/tmp/a",
-        "--no-recursive",
-        "--no-recursive",
-      ]),
-    ).toBeNull();
-    expect(
-      parseProductCommand("backup", [
-        "create",
-        "--target",
-        "/tmp/a",
-        "--yes",
-        "--yes",
-      ]),
-    ).toBeNull();
-  });
-
-  it("rejects a repeated global --json spelling", () => {
-    expect(
-      parseProductCommand("scan", ["--root", "/tmp/a", "--json", "--json"]),
-    ).toBeNull();
-    expect(
-      parseProductCommand("backup", [
-        "create",
-        "--target",
-        "/tmp/a",
-        "--json",
-        "--json",
-      ]),
-    ).toBeNull();
-  });
-
-  it("requires a source when restoring", () => {
-    expect(
-      parseProductCommand("backup", ["restore", "--target", "/tmp/b"]),
-    ).toBeNull();
-  });
-
-  it("parses the explicit restore confirmation path", () => {
-    const parsed = parseProductCommand("backup", [
+  it("accepts the legacy --confirm <path> and checks it lexically", () => {
+    const parsed = parseBackupCommand([
      "restore",
      "--source",
-      "/tmp/backups/a.sqlite3",
+      "/tmp/b",
      "--yes",
      "--confirm",
-      "/tmp/backups/a.sqlite3",
+      "/tmp/b",
    ]);
-    expect(parsed).not.toBeNull();
-    expect(parsed?.confirmPath).toBe("/tmp/backups/a.sqlite3");
-    expect(
-      restoreConfirmationMatches("/tmp/backups/a.sqlite3", parsed?.confirmPath),
-    ).toBe(true);
-    expect(
-      restoreConfirmationMatches("/tmp/backups/a.sqlite3", undefined),
-    ).toBe(false);
-    expect(
-      restoreConfirmationMatches(
-        "/tmp/backups/a.sqlite3",
-        "/tmp/backups/../backups/a.sqlite3",
-      ),
-    ).toBe(false);
+    expect(parsed).toMatchObject({ confirmPath: "/tmp/b" });
+    expect(restoreConfirmationMatches("/tmp/b", "/tmp/b")).toBe(true);
+    expect(restoreConfirmationMatches("/tmp/b", undefined)).toBe(true);
+    expect(restoreConfirmationMatches("/tmp/b", "/tmp/./b")).toBe(false);
  });

-  it("requires a target when creating a backup", () => {
-    expect(parseProductCommand("backup", ["create"])).toBeNull();
+  it("rejects an unknown verb", () => {
+    expect(parseBackupCommand(["delete", "--target", "/tmp/b"])).toBeNull();
  });
 });

@@ -305,11 +205,19 @@ describe("write", () => {
    ).toBeNull();
  });

-  it("parses status under write", () => {
+  it("parses status under write, positional or --id", () => {
    expect(parseWriteCommand(["status", "--id", "request-1"])).toEqual({
      kind: "status",
      id: "request-1",
    });
+    expect(parseWriteCommand(["status", "request-1"])).toEqual({
+      kind: "status",
+      id: "request-1",
+    });
+  });
+
+  it("rejects a repeated --session instead of letting the last one win", () => {
+    expect(parseWriteCommand([...base, "--session", "s2"])).toBeNull();
  });

  it("marks --live as priority live", () => {
@@ -366,53 +274,3 @@ describe("task", () => {
    expect(parseTaskCommand(["--id", "req-1", "--json", "--json"])).toBeNull();
  });
 });
-
-describe("path add and remove carry what the endpoint needs", () => {
-  it("reads the source and recursive flag off the path add", () => {
-    const parsed = parseProductCommand("path", [
-      "add",
-      "--root",
-      "/tmp/scanme",
-      "--source",
-      "codex",
-      "--no-recursive",
-    ]);
-    // `?.plan!` let a null parse pass silently, so assert the parse itself.
-    if (parsed === null) {
-      throw new Error("path add must parse");
-    }
-    expect(parsed.plan.action).toBe("add scan root");
-    expect(parsed.plan.target).toBe("/tmp/scanme");
-    expect(parsed.plan.detail).toContain("source=codex");
-    expect(parsed.plan.detail).toContain("recursive=false");
-  });
-
-  it("distinguishes remove from add", () => {
-    const parsed = parseProductCommand("path", [
-      "remove",
-      "--root",
-      "/tmp/scanme",
-    ]);
-    if (parsed === null) {
-      throw new Error("path remove must parse");
-    }
-    // The action is the discriminator at apply time: add and remove share a
-    // `--root`, so a mis-set action would register the directory it meant to delete.
-    expect(parsed.plan.action).toBe("remove scan root");
-  });
-
-  it("does not silently drop --yes", () => {
-    const parsed = parseProductCommand("path", [
-      "add",
-      "--root",
-      "/tmp/a",
-      "--yes",
-    ]);
-    expect(parsed?.confirmed).toBe(true);
-    // Without this, a typo'd `--yes` would fall through to a plan and the user
-    // would believe the change had been made.
-
-    const without = parseProductCommand("path", ["add", "--root", "/tmp/a"]);
-    expect(without?.confirmed).toBe(false);
-  });
-});
@@ -1,258 +1,163 @@
-// A6: the product commands Runtime exposes on the CLI.
+// Parsers for the commands that attach to the Runtime directly:
+// `scan-roots` (alias `path`), `scan`, `backup`, `write`.
 //
-// These are the six commands the objective names: path, adapter, scan, write,
-// task, backup. Two rules run through all of them:
+// Rules shared by all of them:
 //
-// - **Mutating commands are two-phase.** Without `--yes` they print a plan and
-//   change nothing. This is the convention the existing install/service
-//   commands already follow, and it is why `scan` and `backup` default to a
-//   plan rather than quietly doing work.
-// - **Output is machine-readable.** `--json` emits one document on stdout so an
-//   agent can consume it; the human form is text. Never both, so a caller that
-//   parses stdout is not surprised by prose.
+// - **Only irreversible operations ask for `--yes`.** `backup restore`
+//   overwrites the database, so without `--yes` it previews and changes
+//   nothing. Registering a scan root, scanning a source, creating a backup and
+//   submitting a write are direct. A legacy `--yes` on a direct command is
+//   accepted and ignored so older scripts keep working.
+// - **Unknown or repeated flags are rejected**, never ignored: a dropped typo
+//   would silently change what the command does.
+// - **Output is machine-readable.** `--json` emits one document on stdout.
 //
 // The commands talk to the Runtime's HTTP API, not to the database and not to
-// HY. That is the A6 rule: CLI and Electron are clients of the same Runtime.
+// the SDK: CLI and desktop are clients of the same Runtime.

-/** What a mutating command would do, before it is allowed to do it. */
-export interface Plan {
-  readonly action: string;
-  readonly target: string;
-  readonly detail?: string;
-  /** Which form of the command this plan is for, when one name has several.
-   *
-   * `backup` has `create` and `restore`, and applying the wrong one is not a
-   * harmless mistake — so the verb travels with the plan the user confirmed.
-   */
-  readonly verb?: string;
-  /** The source the Runtime endpoint addresses, when the plan names one.
-   *
-   * Carried on the plan rather than re-parsed at apply time so the plan the
-   * user confirmed and the request actually sent cannot disagree.
-   */
-  readonly sourceId?: string;
-  /** `scan --all`: every source Runtime actually found, not a named one. */
-  readonly all?: boolean;
+export type ScanRootsCommand =
+  | {
+      readonly kind: "add";
+      readonly root: string;
+      readonly source?: string;
+      readonly recursive: boolean;
+    }
+  | { readonly kind: "remove"; readonly root: string };
+
+export type ScanCommand =
+  | { readonly kind: "source"; readonly sourceId: string }
+  /** Hidden alias of `sources connect --all-detected --import`. */
+  | { readonly kind: "all" };
+
+export type BackupCommand =
+  | { readonly verb: "create"; readonly target: string }
+  | {
+      readonly verb: "restore";
+      readonly source: string;
+      readonly confirmed: boolean;
+      /** Legacy `--confirm <path>`: accepted, and must repeat `--source`. */
+      readonly confirmPath?: string;
+    };
+
+interface ParsedFlags {
+  readonly values: Map<string, string>;
+  readonly switches: Set<string>;
 }

-export function planAddRoot(
-  root: string,
-  source: string | undefined,
-  recursive: boolean,
-): Plan {
-  return {
-    action: "add scan root",
-    target: root,
-    detail: `source=${source ?? "auto"} recursive=${recursive}`,
-  };
-}
-
-export function planRemoveRoot(root: string): Plan {
-  return { action: "remove scan root", target: root };
-}
-
-export function planScan(root: string | undefined, full: boolean): Plan {
-  return {
-    action: "scan",
-    target: root ?? "all registered roots",
-    detail: `full=${full}`,
-  };
-}
-
-export function planScanSource(sourceId: string, full: boolean): Plan {
-  return {
-    action: "scan",
-    target: `source ${sourceId}`,
-    detail: `full=${full}`,
-    sourceId,
-  };
-}
-
-export function planScanAll(full: boolean): Plan {
-  return {
-    action: "scan",
-    target: "all detected sources",
-    detail: `full=${full}`,
-    all: true,
-  };
-}
-
-export function planBackup(target: string): Plan {
-  return { action: "create backup", target, verb: "create" };
-}
-
-export function planRestore(source: string): Plan {
-  return { action: "restore backup", target: source, verb: "restore" };
-}
-
-export interface ProductCommand {
-  readonly plan: Plan;
-  readonly confirmed: boolean;
-  /** For destructive verbs with a named artifact, the exact value repeated by
-   * the user. `backup restore` requires this to match `--source`. */
-  readonly confirmPath?: string;
-}
-
-/** Parse a mutating product command.
- *
- * Unknown flags are rejected rather than ignored: a typo'd `--yes` that is
- * silently dropped would turn a real apply into a plan, and the user would
- * believe the change had been made.
- */
-export function parseProductCommand(
-  name: string,
+/** Read `--flag value` pairs and bare switches; null on anything unknown,
+ * repeated or missing its value. */
+function parseFlags(
  args: readonly string[],
-): ProductCommand | null {
-  let root: string | undefined;
-  let source: string | undefined;
-  let target: string | undefined;
-  let recursive = true;
-  let full = false;
-  let all = false;
-  let confirmed = false;
-  let confirmPath: string | undefined;
-  const seen = new Set<string>();
-  const seenValues = new Set<string>();
-
-  const flags = new Set([
-    "--root",
-    "--source",
-    "--target",
-    "--confirm",
-    "--no-recursive",
-    "--full",
-    "--all",
-    "--yes",
-    "--json",
-  ]);
-
-  // The first token is the verb for commands that have one (`path add`,
-  // `backup create`). It used to fall into the flag loop and be rejected as an
-  // unknown flag, which made every one of these commands permanently
-  // unparseable — `path add --root X` printed "参数无效" even though `help`
-  // documented it. The tests missed this because they asserted
-  // `parsed?.plan!` and null satisfies `?.` + `!`.
-  const verb = args[0];
-  const start = verb !== undefined && !verb.startsWith("--") ? 1 : 0;
-
-  for (let index = start; index < args.length; index += 1) {
+  valueFlags: readonly string[],
+  switchFlags: readonly string[],
+): ParsedFlags | null {
+  const values = new Map<string, string>();
+  const switches = new Set<string>();
+  for (let index = 0; index < args.length; index += 1) {
    const arg = args[index];
-    if (!flags.has(arg)) return null;
-    // A repeated flag is a malformed argv, not an idempotent spelling. The
-    // other command parsers already apply this rule to --json as well.
-    if (seen.has(arg)) return null;
-    seen.add(arg);
-    if (arg === "--yes") {
-      confirmed = true;
-      continue;
-    }
-    if (arg === "--confirm") {
-      const value = args[index + 1];
-      if (value === undefined || value.startsWith("--")) return null;
-      if (confirmPath !== undefined) return null;
-      confirmPath = value;
-      index += 1;
-      continue;
-    }
-    if (arg === "--json") continue;
-    if (arg === "--no-recursive") {
-      recursive = false;
-      continue;
-    }
-    if (arg === "--full") {
-      full = true;
-      continue;
-    }
-    if (arg === "--all") {
-      all = true;
+    if (switchFlags.includes(arg)) {
+      if (switches.has(arg)) return null;
+      switches.add(arg);
      continue;
    }
+    if (!valueFlags.includes(arg) || values.has(arg)) return null;
    const value = args[index + 1];
    if (value === undefined || value.startsWith("--")) return null;
-    if (seenValues.has(arg)) return null;
-    seenValues.add(arg);
+    values.set(arg, value);
    index += 1;
-    if (arg === "--root") root = value;
-    else if (arg === "--source") source = value;
-    else target = value;
  }
+  return { values, switches };
+}

-  if (name === "path") {
-    if (confirmPath !== undefined) return null;
-    if (target !== undefined) return null;
-    if (root === undefined) return null;
-    if (source === undefined && args.includes("--source")) return null;
-    if (seen.has("--full") || seen.has("--all")) return null;
-    if (args[0] !== "add" && args[0] !== "remove") return null;
-    if (
-      args[0] === "remove" &&
-      (seen.has("--source") || seen.has("--no-recursive"))
-    ) {
-      return null;
-    }
+const SOURCE_ID = /^[a-z0-9][a-z0-9-]{0,127}$/;
+
+/** `scan-roots add --root <path> [--source <id>] [--no-recursive]` and
+ * `scan-roots remove --root <path>` (`list` is answered separately). */
+export function parseScanRootsCommand(
+  args: readonly string[],
+): ScanRootsCommand | null {
+  const verb = args[0];
+  if (verb === "add") {
+    const flags = parseFlags(
+      args.slice(1),
+      ["--root", "--source"],
+      ["--no-recursive", "--yes", "--json"],
+    );
+    const root = flags?.values.get("--root");
+    if (!flags || root === undefined) return null;
+    const source = flags.values.get("--source");
+    if (source !== undefined && !SOURCE_ID.test(source)) return null;
    return {
-      plan:
-        args[0] === "add"
-          ? planAddRoot(root, source, recursive)
-          : planRemoveRoot(root),
-      confirmed,
+      kind: "add",
+      root,
+      ...(source === undefined ? {} : { source }),
+      recursive: !flags.switches.has("--no-recursive"),
    };
  }
-  if (name === "scan") {
-    if (confirmPath !== undefined) return null;
-    if (target !== undefined) return null;
-    if (seen.has("--no-recursive")) return null;
-    if (args[0] !== undefined && !args[0].startsWith("--")) return null;
-    // `--all` means "every source Runtime actually found", so naming one too
-    // would make the command mean two different things.
-    if (all && source !== undefined) return null;
-    if (all) return { plan: planScanAll(full), confirmed };
-    // A source is the thing the Runtime scan endpoint addresses. A bare root is
-    // still accepted for planning (it means "all registered roots") but cannot
-    // be applied, because there is no endpoint that scans a raw path — the CLI
-    // must not pretend it can.
-    if (source === undefined) return { plan: planScan(root, full), confirmed };
-    return { plan: planScanSource(source, full), confirmed };
+  if (verb === "remove") {
+    const flags = parseFlags(args.slice(1), ["--root"], ["--yes", "--json"]);
+    const root = flags?.values.get("--root");
+    return flags && root !== undefined ? { kind: "remove", root } : null;
  }
-  if (name === "backup") {
-    const verb = args[0];
-    if (verb !== "create" && verb !== "restore") return null;
-    if (seen.has("--full") || seen.has("--all") || seen.has("--no-recursive")) {
-      return null;
-    }
-    if (verb === "restore") {
-      if (source === undefined) return null;
-      if (target !== undefined) return null;
-      return {
-        plan: planRestore(source),
-        confirmed,
-        ...(confirmPath === undefined ? {} : { confirmPath }),
-      };
-    }
-    if (confirmPath !== undefined) return null;
-    if (source !== undefined) return null;
-    if (target === undefined) return null;
+  return null;
+}
+
+/** `scan --source <id>`. A scan names a source: the Runtime has no endpoint
+ * that scans a bare path, so a missing `--source` is a usage error rather
+ * than a preview of something that can never run. */
+export function parseScanCommand(args: readonly string[]): ScanCommand | null {
+  const flags = parseFlags(args, ["--source"], ["--all", "--yes", "--json"]);
+  if (!flags) return null;
+  const source = flags.values.get("--source");
+  if (flags.switches.has("--all")) {
+    return source === undefined ? { kind: "all" } : null;
+  }
+  return source !== undefined && SOURCE_ID.test(source)
+    ? { kind: "source", sourceId: source }
+    : null;
+}
+
+/** `backup create --target <path>` and
+ * `backup restore --source <path> [--yes]`. */
+export function parseBackupCommand(
+  args: readonly string[],
+): BackupCommand | null {
+  const verb = args[0];
+  if (verb === "create") {
+    const flags = parseFlags(args.slice(1), ["--target"], ["--yes", "--json"]);
+    const target = flags?.values.get("--target");
+    return flags && target !== undefined ? { verb: "create", target } : null;
+  }
+  if (verb === "restore") {
+    const flags = parseFlags(
+      args.slice(1),
+      ["--source", "--confirm"],
+      ["--yes", "--json"],
+    );
+    const source = flags?.values.get("--source");
+    if (!flags || source === undefined) return null;
+    const confirmPath = flags.values.get("--confirm");
    return {
-      plan: planBackup(target),
-      confirmed,
+      verb: "restore",
+      source,
+      confirmed: flags.switches.has("--yes"),
      ...(confirmPath === undefined ? {} : { confirmPath }),
    };
  }
  return null;
 }

-/** Whether `--confirm <path>` names the same restore source.
+/** Whether a legacy `--confirm <path>` names the same restore source.
 *
 * The comparison is lexical on purpose: the CLI must not resolve symlinks or
 * touch the filesystem before Core has validated the managed source. A
- * different string is a different confirmation, so a typo or a path escape
- * can never be applied as a side effect of `--yes`.
+ * different string is a different confirmation.
 */
 export function restoreConfirmationMatches(
  source: string,
  confirmPath: string | undefined,
 ): boolean {
-  return confirmPath === source;
+  return confirmPath === undefined || confirmPath === source;
 }

 export interface WriteSubmitCommand {
@@ -272,41 +177,33 @@ export interface WriteStatusCommand {

 export type WriteCommand = WriteSubmitCommand | WriteStatusCommand;

-/** Parse SDK-native `write submit|status`. */
+/** Parse `write submit ...` and `write status <request-id>` (or `--id`). */
 export function parseWriteCommand(
  args: readonly string[],
 ): WriteCommand | null {
  if (args.filter((item) => item === "--json").length > 1) return null;
  const meaningful = args.filter((item) => item !== "--json");
  if (meaningful[0] === "status") {
-    const status = parseTaskCommand(meaningful.slice(1));
+    const rest = meaningful.slice(1);
+    if (rest.length === 1 && !rest[0].startsWith("--")) {
+      return { kind: "status", id: rest[0] };
+    }
+    const status = parseTaskCommand(rest);
    return status === null ? null : { kind: "status", id: status.id };
  }
+  // `write --session ...` without `submit` stays accepted for older scripts.
  const input = meaningful[0] === "submit" ? meaningful.slice(1) : meaningful;
-  let session: string | undefined;
-  let source = "memhub-cli";
-  let messagesFile: string | undefined;
-  let requestId: string | undefined;
-  let memoryAt: string | undefined;
-  let priority: "live" | "normal" | undefined;
-
-  for (let index = 0; index < input.length; index += 1) {
-    const arg = input[index];
-    if (arg === "--live") {
-      priority = "live";
-      continue;
-    }
-    const value = input[index + 1];
-    if (value === undefined || value.startsWith("--")) return null;
-    index += 1;
-    if (arg === "--session") session = value;
-    else if (arg === "--source") source = value;
-    else if (arg === "--messages-file") messagesFile = value;
-    else if (arg === "--request-id") requestId = value;
-    else if (arg === "--memory-at") memoryAt = value;
-    else return null;
-  }
-
+  const flags = parseFlags(
+    input,
+    ["--session", "--source", "--messages-file", "--request-id", "--memory-at"],
+    ["--live"],
+  );
+  if (!flags) return null;
+  const session = flags.values.get("--session");
+  const source = flags.values.get("--source") ?? "memhub-cli";
+  const messagesFile = flags.values.get("--messages-file");
+  const requestId = flags.values.get("--request-id");
+  const memoryAt = flags.values.get("--memory-at");
  if (session === undefined || messagesFile === undefined || !source)
    return null;
  if (
@@ -323,39 +220,23 @@ export function parseWriteCommand(
    ...(requestId === undefined ? {} : { request_id: requestId }),
    ...(memoryAt === undefined ? {} : { memory_at: memoryAt }),
  };
-  return priority === undefined ? command : { ...command, priority };
+  return flags.switches.has("--live")
+    ? { ...command, priority: "live" }
+    : command;
 }

 export interface TaskCommand {
  readonly id: string;
 }

+/** `--id <request-id>`: the legacy `task` spelling of `write status`. */
 export function parseTaskCommand(args: readonly string[]): TaskCommand | null {
  if (args.filter((item) => item === "--json").length > 1) return null;
-  let id: string | undefined;
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === "--json") continue;
-    if (arg !== "--id") return null;
-    const value = args[index + 1];
-    if (value === undefined || value.startsWith("--")) return null;
-    index += 1;
-    id = value;
-  }
+  const flags = parseFlags(
+    args.filter((item) => item !== "--json"),
+    ["--id"],
+    [],
+  );
+  const id = flags?.values.get("--id");
  return id === undefined ? null : { id };
 }
-
-/** The human form. Kept separate from the JSON form on purpose. */
-export function describe(plan: Plan): string {
-  const line = `${plan.action}: ${plan.target}`;
-  return plan.detail ? `${line} (${plan.detail})` : line;
-}
-
-/** The machine form: one document, nothing else on stdout. */
-export function asPlanDocument(plan: Plan): {
-  schema_version: 1;
-  plan: Plan;
-  applied: boolean;
-} {
-  return { schema_version: 1, plan, applied: false };
-}
@@ -0,0 +1,166 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { run } from "./cli.js";
+
+const transport = vi.hoisted(() => ({
+  get: vi.fn(),
+  post: vi.fn(),
+  put: vi.fn(),
+  patch: vi.fn(),
+  delete: vi.fn(),
+}));
+vi.mock("axios", () => ({
+  default: {
+    create: vi.fn(() => transport),
+    get: vi.fn(),
+    post: vi.fn(),
+    isAxiosError: () => false,
+  },
+}));
+
+const runtime = vi.hoisted(() => ({
+  inspectRuntimeStatus: vi.fn(),
+  discoverRuntimeAttachment: vi.fn(),
+}));
+vi.mock("@one-memory/runtime-control", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@one-memory/runtime-control")>()),
+  ...runtime,
+}));
+
+const VERSIONS = {
+  user_id: "wife",
+  request_id: "r-versions",
+  elapsed_ms: 2,
+  chains: [
+    {
+      memory_id: "l0-head",
+      content: "The user's name is Fei.",
+      status: "active",
+      memory_at: null,
+      gmt_created: 1_790_000_100,
+      basic_info: { name: "Fei" },
+      versions: [
+        {
+          memory_id: "l0-head",
+          content: "The user's name is Fei.",
+          memory_at: null,
+          gmt_created: 1_790_000_100,
+          current: true,
+        },
+        {
+          memory_id: "l0-old",
+          content: "The user's name is 费天翔.",
+          memory_at: null,
+          gmt_created: 1_790_000_000,
+          current: false,
+        },
+      ],
+    },
+  ],
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  for (const method of Object.values(transport)) method.mockReset();
+  runtime.inspectRuntimeStatus.mockResolvedValue({
+    state: "running",
+    code: "runtime_verified",
+    instanceId: "instance-1",
+    host: "127.0.0.1",
+    port: 8765,
+    version: "1.2.3",
+  });
+  runtime.discoverRuntimeAttachment.mockResolvedValue({
+    instanceId: "instance-1",
+    apiToken: "synthetic-runtime-token",
+    host: "127.0.0.1",
+    port: 8765,
+    servicePid: 4242,
+    health: {
+      status: "ok",
+      service: "one-memory-core",
+      version: "1.2.3",
+      instance_id: "instance-1",
+    },
+  });
+  transport.get.mockImplementation(async (url: string) =>
+    url === "/api/v2/user-profile/versions"
+      ? { status: 200, data: VERSIONS }
+      : { status: 404, data: {} },
+  );
+});
+
+describe("memhub profile --versions", () => {
+  it("reads the L0 version chain for the named user", async () => {
+    const result = await capturedRun([
+      "profile",
+      "--versions",
+      "--user-id",
+      "wife",
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.get).toHaveBeenCalledWith(
+      "/api/v2/user-profile/versions",
+      { params: { user_id: "wife" } },
+    );
+    const document = JSON.parse(result.stdout);
+    expect(document.state).toBe("ok");
+    expect(document.chains[0].versions).toHaveLength(2);
+  });
+
+  it("marks the current version in text and names no user for local", async () => {
+    const result = await capturedRun(["profile", "--versions"]);
+    expect(result.code).toBe(0);
+    const [url, config] = transport.get.mock.calls[0] ?? [];
+    expect(url).toBe("/api/v2/user-profile/versions");
+    expect(config?.params?.user_id).toBeUndefined();
+    expect(result.stdout).toContain("* l0-head");
+    expect(result.stdout).toContain("  l0-old");
+    expect(result.stdout).toContain("费天翔");
+  });
+
+  it("refuses an unknown flag and a repeated --versions", async () => {
+    expect((await capturedRun(["profile", "--version-chain"])).code).toBe(2);
+    expect(
+      (await capturedRun(["profile", "--versions", "--versions"])).code,
+    ).toBe(2);
+    expect(transport.get).not.toHaveBeenCalled();
+  });
+
+  it("reports a malformed answer as invalid", async () => {
+    transport.get.mockResolvedValue({ status: 200, data: { chains: "x" } });
+    const result = await capturedRun(["profile", "--versions", "--json"]);
+    expect(result.code).toBe(1);
+    expect(JSON.parse(result.stdout).code).toBe("response_invalid");
+  });
+});
+
+async function capturedRun(arguments_: string[]) {
+  let stdout = "";
+  let stderr = "";
+  const stdoutSpy = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation((chunk) => {
+      stdout += String(chunk);
+      return true;
+    });
+  const stderrSpy = vi
+    .spyOn(process.stderr, "write")
+    .mockImplementation((chunk) => {
+      stderr += String(chunk);
+      return true;
+    });
+  try {
+    return {
+      code: await run(arguments_, {
+        ONE_MEMORY_DATA_DIR: "/synthetic/data",
+      }),
+      stdout,
+      stderr,
+    };
+  } finally {
+    stdoutSpy.mockRestore();
+    stderrSpy.mockRestore();
+  }
+}
@@ -697,6 +697,66 @@ describe("CLI-21 memory reads", () => {
    expect(report.memories[1].content.length).toBeLessThan(400);
  });

+  it("lists working and coding memories with their scene and kind", async () => {
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: {
+        total: 2,
+        offset: 0,
+        limit: 20,
+        totals: { chat: 1, working: 1, coding: 0 },
+        window_id: null,
+        window_reset: false,
+        memories: [
+          memory("m1", "对话记忆"),
+          {
+            ...memory("e1", "修复测试\n固定随机种子"),
+            layer: "experience",
+            agent_id: "",
+            owner: null,
+            source_raw_ids: [],
+            scene: "working",
+            kind: "experience",
+            variant: "working",
+            task: "修复测试",
+            solution: "固定随机种子",
+            created_at: 1_790_000_000,
+            updated_at: 1_790_000_100,
+          },
+        ],
+      },
+    });
+    const streams = captureStreams();
+    try {
+      expect(await run(["memories", "list", "--json"], {})).toBe(0);
+    } finally {
+      streams.restore();
+    }
+    const report = JSON.parse(streams.stdout());
+    expect(report.page).toMatchObject({ state: "ok", total: 2, returned: 2 });
+    expect(report.memories[0]).toMatchObject({
+      memory_id: "m1",
+      scene: "chat",
+      kind: "chat",
+      variant: null,
+    });
+    expect(report.memories[1]).toMatchObject({
+      memory_id: "e1",
+      scene: "working",
+      kind: "experience",
+      variant: "working",
+      layer: "experience",
+    });
+
+    const text = captureStreams();
+    try {
+      expect(await run(["memories", "list"], {})).toBe(0);
+    } finally {
+      text.restore();
+    }
+    expect(text.stdout()).toContain("- e1  [working] active/experience");
+  });
+
  it("passes the requested filters through as query parameters", async () => {
    await run(
      [
@@ -818,8 +878,11 @@ describe("CLI-21 memory reads", () => {
      layer: "L2_FACT",
      status: "active",
    });
-    expect(report.evidence).toEqual([]);
-    expect(report.history).toEqual([]);
+    // Schema 2, like add/update/delete; the v1-era always-empty
+    // `evidence`/`history` fields are gone.
+    expect(report.schema_version).toBe(2);
+    expect(report).not.toHaveProperty("evidence");
+    expect(report).not.toHaveProperty("history");
  });

  // Core registers /api/v2/memories/graph before /{memory_id}, and that static
@@ -1077,14 +1140,16 @@ describe("backup create target refusal is rejected, not usage_error", () => {
    let code: number;
    try {
      code = await run(
-        ["backup", "create", "--target", "/tmp/outside.db", "--yes", "--json"],
+        ["backup", "create", "--target", "/tmp/outside.db", "--json"],
        {},
      );
    } finally {
      streams.restore();
    }
    expect(code!).toBe(1);
-    const document = JSON.parse(streams.stderr());
+    // A result, on stdout like every --json document.
+    expect(streams.stderr()).toBe("");
+    const document = JSON.parse(streams.stdout());
    expect(document.status).not.toBe("usage_error");
    expect(document).toMatchObject({
      command: "backup",
@@ -14,6 +14,11 @@ import {
  validateProcessing,
  validateSources,
 } from "./core-responses.js";
+import {
+  describePipeline,
+  type PipelineSummary,
+  pipelineLine,
+} from "./status-report.js";
 import { PRODUCT } from "./version.js";

 type ReadState =
@@ -38,6 +43,21 @@ export interface SourcesDocument {
  state: ReadState["state"];
  code?: string;
  sources: Array<Record<string, unknown>>;
+  /** Every grant of every user (`GET /api/v1/source-grants`). Absent when
+   * Core is too old to list them; `sources` is the default user's view. */
+  grants?: SourceGrant[];
+}
+
+/** One source grant. Only Hermes has grants for users other than `local`,
+ * one per Hermes profile root. */
+export interface SourceGrant {
+  user_id: string;
+  source_id: string;
+  root_label: string | null;
+  root_path: string | null;
+  authorized: boolean;
+  revoked_at: string | null;
+  sync_enabled: boolean;
 }

 export interface SyncDocument {
@@ -69,6 +89,8 @@ export interface ProgressDocument {
    summary_state: ReadState;
    summary: Record<string, unknown> | null;
  };
+  /** The SDK mode and last evolve per user; absent on an older Core. */
+  pipeline?: PipelineSummary | null;
 }

 export async function readSources(
@@ -86,14 +108,66 @@ export async function readSources(
      sources: [],
    };
  }
+  const grants = await readSourceGrants(reader);
  return {
    schema_version: SCHEMA_VERSION,
    product: PRODUCT,
    state: "ok",
-    sources: result.data.map(projectSource),
+    // `/api/v1/sources` is the default user's view of every source.
+    sources: result.data.map((source) => ({
+      ...projectSource(source),
+      user_id: "local",
+    })),
+    ...(grants === null ? {} : { grants }),
  };
 }

+/** The grants of every user, or null when Core cannot list them (an older
+ * Core answers 404): the source list is then shown as before. */
+async function readSourceGrants(
+  reader: CoreReader,
+): Promise<SourceGrant[] | null> {
+  let outcome: ReadOutcome<unknown>;
+  try {
+    outcome = await reader<unknown>("/api/v1/source-grants");
+  } catch {
+    return null;
+  }
+  if (outcome.state !== "ok") return null;
+  const value = outcome.data;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const items = (value as { grants?: unknown }).grants;
+  if (!Array.isArray(items)) return null;
+  const grants: SourceGrant[] = [];
+  const text = (candidate: unknown): string | null =>
+    typeof candidate === "string" && candidate.length <= 4096
+      ? candidate
+      : null;
+  for (const item of items) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return null;
+    const grant = item as Record<string, unknown>;
+    if (
+      typeof grant.user_id !== "string" ||
+      !/^[A-Za-z0-9._-]{1,64}$/.test(grant.user_id) ||
+      typeof grant.source_id !== "string" ||
+      !/^[a-z0-9][a-z0-9-]{0,127}$/.test(grant.source_id) ||
+      typeof grant.authorized !== "boolean"
+    ) {
+      return null;
+    }
+    grants.push({
+      user_id: grant.user_id,
+      source_id: grant.source_id,
+      root_label: text(grant.root_label),
+      root_path: text(grant.root_path),
+      authorized: grant.authorized,
+      revoked_at: text(grant.revoked_at),
+      sync_enabled: grant.sync_enabled === true,
+    });
+  }
+  return grants;
+}
+
 export async function readSync(reader: CoreReader): Promise<SyncDocument> {
  const result = validated(
    await reader<unknown>("/api/v1/live-sync"),
@@ -216,6 +290,10 @@ export async function readProgress(
      summary:
        processing.state === "ok" ? projectProcessing(processing.data) : null,
    },
+    pipeline:
+      processingRead.state === "ok"
+        ? describePipeline(processingRead.data)
+        : null,
  };
 }

@@ -231,6 +309,22 @@ export function renderSourcesText(document: SourcesDocument): string {
    );
  }
  if (document.sources.length === 0) lines.push("（没有来源）");
+  // The list above is the default user's (`local`). Another user's grant,
+  // a Hermes profile, is listed with its user so it is not mistaken for it.
+  const others = (document.grants ?? []).filter(
+    (grant) => grant.user_id !== "local",
+  );
+  if (others.length > 0) {
+    lines.push("其他用户的连接：");
+    for (const grant of others) {
+      const name =
+        document.sources.find((source) => source.source_id === grant.source_id)
+          ?.display_name ?? grant.source_id;
+      lines.push(
+        `- ${name}（用户 ${grant.user_id}）：${grant.authorized ? "已连接" : grant.revoked_at ? "已撤销" : "未连接"}；处理${grant.sync_enabled ? "已开启" : "已冻结"}${grant.root_path ? `；目录 ${grant.root_path}` : ""}`,
+      );
+    }
+  }
  lines.push("");
  return lines.join("\n");
 }
@@ -270,6 +364,18 @@ export function renderProgressText(document: ProgressDocument): string {
      ? `记忆整理：待处理 ${document.generation.summary.pending} · 进行中 ${document.generation.summary.running} · 等待模型 ${document.generation.summary.waiting_for_model} · 失败 ${document.generation.summary.failed}`
      : "记忆整理：暂时无法读取",
  );
+  if (document.pipeline) {
+    lines.push(`记忆模式：${pipelineLine(document.pipeline)}`);
+    for (const [userId, user] of Object.entries(
+      document.pipeline.evolve_users,
+    )) {
+      lines.push(
+        `  进化 ${userId}：${user.last_run_at ?? "尚未进化"}${
+          user.last_error ? `（失败：${user.last_error}）` : ""
+        }`,
+      );
+    }
+  }
  if (document.imports.output_truncated) {
    lines.push("这里只显示汇总；完整记录请使用 --json。");
  }
@@ -341,7 +447,11 @@ function validated<T>(
 ):
  | { state: "ok"; data: T }
  | { state: Exclude<ReadState["state"], "ok">; code: string } {
-  if (outcome.state !== "ok") return outcome;
+  if (outcome.state !== "ok") {
+    // A Core refusal of the request itself reads as an invalid answer here.
+    const state = outcome.state === "rejected" ? "invalid" : outcome.state;
+    return { state, code: outcome.code };
+  }
  const data = validate(outcome.data);
  return data === null
    ? { state: "invalid", code: "response_invalid" }
@@ -179,12 +179,72 @@ describe("CLI-07/10 source and synchronization reads", () => {
      sync_enabled: true,
      sync_completeness: "additions_only",
    });
-    expect(requestedPaths()).toEqual(["/api/v1/sources"]);
+    // The grants list answers 404 here, as an older Core does: the source
+    // list is shown as before, every row the default user's.
+    expect(report.sources[0].user_id).toBe("local");
+    expect(report.grants).toBeUndefined();
+    expect(requestedPaths()).toEqual([
+      "/api/v1/sources",
+      "/api/v1/source-grants",
+    ]);
    expect(requestedPaths().some((path) => path.includes("detect"))).toBe(
      false,
    );
  });

+  it("shows every user's grant, a Hermes profile with its user", async () => {
+    const grants = {
+      schema_version: 1,
+      grants: [
+        {
+          user_id: "local",
+          source_id: "codex",
+          root_label: ".codex",
+          root_path: "/home/synthetic/.codex",
+          authorized: true,
+          revoked_at: null,
+          sync_enabled: true,
+        },
+        {
+          user_id: "wife",
+          source_id: "hermes",
+          root_label: "wife",
+          root_path: "/home/synthetic/.hermes/profiles/wife",
+          authorized: true,
+          revoked_at: null,
+          sync_enabled: true,
+        },
+      ],
+    };
+    transport.get.mockImplementation(async (url: string) =>
+      url === "/api/v1/source-grants"
+        ? { status: 200, data: grants }
+        : (RESPONSES.get(url) ?? { status: 404, data: {} }),
+    );
+    let streams = captureStreams();
+    try {
+      expect(await run(["sources", "list", "--json"], {})).toBe(0);
+    } finally {
+      streams.restore();
+    }
+    const report = JSON.parse(streams.stdout());
+    expect(report.grants).toEqual(grants.grants);
+    expect(report.sources[0]).toMatchObject({
+      source_id: "codex",
+      user_id: "local",
+    });
+    streams = captureStreams();
+    try {
+      expect(await run(["sources", "list"], {})).toBe(0);
+    } finally {
+      streams.restore();
+    }
+    expect(streams.stdout()).toContain("其他用户的连接：");
+    expect(streams.stdout()).toContain(
+      "hermes（用户 wife）：已连接；处理已开启；目录 /home/synthetic/.hermes/profiles/wife",
+    );
+  });
+
  it("keeps degraded synchronization distinct and prints its error code", async () => {
    const streams = captureStreams();
    try {
@@ -552,6 +612,7 @@ describe("CLI-19 progress and issue reads", () => {
      requestedPaths().every((path) =>
        [
          "/api/v1/sources",
+          "/api/v1/source-grants",
          "/api/v1/live-sync",
          "/api/v1/import-jobs",
          "/api/v1/memory-processing",
@@ -18,6 +18,7 @@ import {
  validateProcessing,
  validateSources,
 } from "./core-responses.js";
+import { describeEmbeddingSwitchSummary } from "./embedding-switch-flow.js";
 import { PRODUCT } from "./version.js";

 const MIGRATION_ISSUES_URL =
@@ -57,6 +58,9 @@ export interface StatusDocument {
    broker?: BackgroundHealth["broker"];
  };
  sections: Record<string, Section>;
+  /** R10: the SDK mode and System 2 state; null when the Runtime is not read
+   * or is older than the setting. */
+  pipeline?: PipelineSummary | null;
  summary: {
    state: "ok" | "partial";
    degraded: string[];
@@ -64,6 +68,99 @@ export interface StatusDocument {
  };
 }

+export interface PipelineSummary {
+  mode: "lite" | "pro" | "ultra";
+  configured_mode: "lite" | "pro" | "ultra";
+  forced_by_env: boolean;
+  last_evolve_at: string | null;
+  evolve_schedule: { enabled: boolean; time: string } | null;
+  evolve_running: number;
+  evolve_users: Record<
+    string,
+    {
+      last_run_at: string | null;
+      last_error: string | null;
+      state: string | null;
+    }
+  >;
+  graph_build: string | null;
+  /** SDK features (`memory_features`) whose value differs from the default. */
+  features: Record<string, boolean>;
+}
+
+const MODES = new Set(["lite", "pro", "ultra"]);
+
+/** Projection of `pipeline` in `/api/v1/memory-processing`; null if absent or malformed. */
+export function describePipeline(value: unknown): PipelineSummary | null {
+  if (!value || typeof value !== "object") return null;
+  const pipeline = (value as { pipeline?: unknown }).pipeline;
+  if (!pipeline || typeof pipeline !== "object") return null;
+  const item = pipeline as Record<string, unknown>;
+  if (
+    !MODES.has(String(item.mode)) ||
+    !MODES.has(String(item.configured_mode))
+  ) {
+    return null;
+  }
+  const evolve =
+    item.evolve && typeof item.evolve === "object"
+      ? (item.evolve as Record<string, unknown>)
+      : {};
+  const schedule =
+    evolve.schedule && typeof evolve.schedule === "object"
+      ? (evolve.schedule as Record<string, unknown>)
+      : null;
+  const users: PipelineSummary["evolve_users"] = {};
+  if (evolve.users && typeof evolve.users === "object") {
+    for (const [userId, raw] of Object.entries(
+      evolve.users as Record<string, unknown>,
+    )) {
+      const user =
+        raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+      const result =
+        user.last_result && typeof user.last_result === "object"
+          ? (user.last_result as Record<string, unknown>)
+          : {};
+      users[userId] = {
+        last_run_at:
+          typeof user.last_run_at === "string" ? user.last_run_at : null,
+        last_error:
+          typeof user.last_error === "string" ? user.last_error : null,
+        state: typeof result.state === "string" ? result.state : null,
+      };
+    }
+  }
+  const features: Record<string, boolean> = {};
+  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;
+    }
+  }
+  const graph =
+    item.graph_build && typeof item.graph_build === "object"
+      ? (item.graph_build as Record<string, unknown>)
+      : {};
+  return {
+    mode: item.mode as PipelineSummary["mode"],
+    configured_mode: item.configured_mode as PipelineSummary["mode"],
+    forced_by_env: item.forced_by_env === true,
+    last_evolve_at:
+      typeof item.last_evolve_at === "string" ? item.last_evolve_at : null,
+    evolve_schedule:
+      schedule &&
+      typeof schedule.enabled === "boolean" &&
+      typeof schedule.time === "string"
+        ? { enabled: schedule.enabled, time: schedule.time }
+        : null,
+    evolve_running: Array.isArray(evolve.running) ? evolve.running.length : 0,
+    evolve_users: users,
+    graph_build: typeof graph.state === "string" ? graph.state : null,
+    features,
+  };
+}
+
 const SECTION_NAMES = [
  "sources",
  "sync",
@@ -97,6 +194,7 @@ export async function composeStatusReport(options: {
  attachFailure?: string;
 }): Promise<StatusDocument> {
  const sections: Record<string, Section> = {};
+  let pipeline: PipelineSummary | null = null;
  if (options.reader === null) {
    const state: SectionState =
      options.attachFailure === undefined ? "not_checked" : "unavailable";
@@ -118,6 +216,8 @@ export async function composeStatusReport(options: {
      validateProcessing,
      describeProcessing,
    );
+    pipeline =
+      processing.state === "ok" ? describePipeline(processing.data) : null;
    sections.model = section(model, validateModelProfiles, describeModel);
    sections.memories = section(
      memories,
@@ -169,6 +269,7 @@ export async function composeStatusReport(options: {
    },
    bridge,
    sections,
+    pipeline,
    summary: {
      state:
        degraded.length === 0 && notChecked.length === 0 ? "ok" : "partial",
@@ -205,6 +306,11 @@ export function renderStatusText(
      `${SECTION_LABELS[name]}：${sectionLine(report.sections[name])}`,
    );
  }
+  if (report.pipeline) lines.push(`记忆模式：${pipelineLine(report.pipeline)}`);
+  const embeddingSwitch = describeEmbeddingSwitchSummary(
+    report.sections.processing?.embedding_switch,
+  );
+  if (embeddingSwitch !== null) lines.push(`向量模型：${embeddingSwitch}`);
  if (report.summary.state === "partial") {
    const notes = [
      report.summary.degraded.length > 0
@@ -220,6 +326,36 @@ export function renderStatusText(
  return lines.join("\n");
 }

+export function pipelineLine(pipeline: PipelineSummary): string {
+  const parts: string[] = [pipeline.mode];
+  if (pipeline.forced_by_env)
+    parts.push("（ONE_MEMORY_GRAPH_STORE 强制 ultra）");
+  if (pipeline.mode === "ultra") {
+    const schedule = pipeline.evolve_schedule;
+    parts.push(
+      schedule?.enabled
+        ? `，每日 ${schedule.time} 自动进化`
+        : "，自动进化已关闭",
+    );
+    parts.push(
+      pipeline.last_evolve_at
+        ? `，上次进化 ${pipeline.last_evolve_at}`
+        : "，尚未进化",
+    );
+    if (pipeline.evolve_running > 0)
+      parts.push(`，进行中 ${pipeline.evolve_running}`);
+  }
+  const changed = Object.entries(pipeline.features);
+  if (changed.length > 0) {
+    parts.push(
+      `；SDK 功能：${changed
+        .map(([name, value]) => `${name}=${value ? "开" : "关"}`)
+        .join("、")}`,
+    );
+  }
+  return parts.join("");
+}
+
 function runtimeLine(report: StatusDocument): string {
  if (report.runtime.state !== "running") {
    return report.runtime.state === "stopped" ? "未运行" : "暂时无法确认";
@@ -234,7 +370,10 @@ function sectionLine(section: Section | undefined): string {
  if (section.state === "not_checked") return "未检查";
  if (section.state !== "ok") return "暂时不可用，请稍后重试";
  return Object.entries(section)
-    .filter(([key]) => key !== "state" && key !== "code")
+    .filter(
+      ([key]) =>
+        key !== "state" && key !== "code" && key !== "embedding_switch",
+    )
    .map(([key, value]) => `${fieldLabel(key)} ${formatValue(value)}`)
    .join(" ");
 }
@@ -350,9 +489,30 @@ function describeProcessing(
      reason: block.reason,
      count: block.count,
    })),
+    ...embeddingSwitchField(summary),
  };
 }

+/** The running switch or merge, projected; absent when none runs. */
+function embeddingSwitchField(
+  summary: MemoryProcessingSummary,
+): Record<string, unknown> {
+  const value = (summary as unknown as Record<string, unknown>)
+    .embedding_switch;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const item = value as Record<string, unknown>;
+  const kind = item.kind === "merge" ? "merge" : "switch";
+  const state =
+    typeof item.state === "string" && /^[a-z_]{1,32}$/.test(item.state)
+      ? item.state
+      : "unknown";
+  const percent =
+    typeof item.percent === "number" && Number.isFinite(item.percent)
+      ? Math.min(100, Math.max(0, item.percent))
+      : 0;
+  return { embedding_switch: { kind, state, percent } };
+}
+
 /** Projection, not passthrough: a Core that leaks a key must not make us leak. */
 function describeModel(profiles: ModelProfile[]): Record<string, unknown> {
  const active = profiles.find((profile) => profile.is_active);
@@ -102,6 +102,10 @@ export function uiSessionFailure(code: string): { code: string } {

 export function uiExitCode(result: UiResult): number {
  if (result.state === "opened") return 0;
+  // A stopped Runtime is the same exit 3 every other command reports.
+  if (result.state === "blocked" && result.code === "runtime_not_running") {
+    return 3;
+  }
  if (result.state === "blocked") return 4;
  return 1;
 }
@@ -1,479 +0,0 @@
-import { mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-import { run } from "./cli.js";
-
-const transport = vi.hoisted(() => ({
-  get: vi.fn(),
-  post: vi.fn(),
-  put: vi.fn(),
-  patch: vi.fn(),
-  delete: vi.fn(),
-}));
-vi.mock("axios", () => ({
-  default: { create: vi.fn(() => transport), get: vi.fn() },
-}));
-
-const runtime = vi.hoisted(() => ({
-  inspectRuntimeStatus: vi.fn(),
-  discoverRuntimeAttachment: vi.fn(),
-}));
-vi.mock("@one-memory/runtime-control", async (importOriginal) => ({
-  ...(await importOriginal<typeof import("@one-memory/runtime-control")>()),
-  ...runtime,
-}));
-
-const EVENT = "11111111-1111-4111-8111-111111111111";
-const UPLOAD = "22222222-2222-4222-8222-222222222222";
-const NOTE = "33333333-3333-4333-8333-333333333333";
-
-beforeEach(() => {
-  vi.clearAllMocks();
-  // clearAllMocks keeps prior mock implementations, so a mockResolvedValue
-  // from an earlier test would leak into the next one and fake its response.
-  transport.get.mockReset();
-  transport.post.mockReset();
-  transport.put.mockReset();
-  transport.patch.mockReset();
-  transport.delete.mockReset();
-  runtime.inspectRuntimeStatus.mockResolvedValue({
-    state: "running",
-    code: "runtime_verified",
-    instanceId: "instance-1",
-    host: "127.0.0.1",
-    port: 8765,
-    version: "1.2.3",
-  });
-  runtime.discoverRuntimeAttachment.mockResolvedValue({
-    instanceId: "instance-1",
-    apiToken: "synthetic-runtime-token",
-    host: "127.0.0.1",
-    port: 8765,
-    servicePid: 4242,
-    health: {
-      status: "ok",
-      service: "one-memory-core",
-      version: "1.2.3",
-      instance_id: "instance-1",
-    },
-  });
-});
-
-describe("calls clear", () => {
-  it("reports runtime_stopped (exit 3) without attempting a write", async () => {
-    runtime.inspectRuntimeStatus.mockResolvedValue({
-      state: "stopped",
-      code: "runtime_not_running",
-    });
-    const result = await capturedRun([
-      "calls",
-      "clear",
-      "--all",
-      "--confirm",
-      "--json",
-    ]);
-    expect(result.code).toBe(3);
-    expect(JSON.parse(result.stdout).code).toBe("runtime_not_running");
-    expect(transport.post).not.toHaveBeenCalled();
-  });
-
-  it("previews without contacting Core", async () => {
-    const result = await capturedRun([
-      "calls",
-      "clear",
-      "--event",
-      EVENT,
-      "--json",
-    ]);
-    expect(result.code).toBe(0);
-    const document = JSON.parse(result.stdout);
-    expect(document.state).toBe("preview");
-    expect(document.plan.kind).toBe("call_events_clear");
-    expect(transport.post).not.toHaveBeenCalled();
-    expect(transport.delete).not.toHaveBeenCalled();
-  });
-
-  it("sends the exact Core body with --confirm", async () => {
-    transport.post.mockResolvedValue({ status: 200, data: { removed: 1 } });
-    const result = await capturedRun([
-      "calls",
-      "clear",
-      "--event",
-      EVENT,
-      "--confirm",
-      "--json",
-    ]);
-    expect(result.code).toBe(0);
-    expect(transport.post).toHaveBeenCalledWith(
-      "/api/v1/call-events/clear",
-      { event_ids: [EVENT], user_confirmed: true },
-      undefined,
-    );
-    expect(JSON.parse(result.stdout).state).toBe("committed");
-  });
-
-  it("clears all without naming events", async () => {
-    transport.post.mockResolvedValue({ status: 200, data: { removed: 4 } });
-    const result = await capturedRun([
-      "calls",
-      "clear",
-      "--all",
-      "--confirm",
-      "--json",
-    ]);
-    expect(result.code).toBe(0);
-    expect(transport.post).toHaveBeenCalledWith(
-      "/api/v1/call-events/clear-all",
-      { user_confirmed: true },
-      undefined,
-    );
-  });
-
-  it("rejects a malformed event id without contacting Core", async () => {
-    const result = await capturedRun([
-      "calls",
-      "clear",
-      "--event",
-      "not-a-uuid",
-      "--json",
-    ]);
-    expect(result.code).toBe(2);
-    expect(transport.post).not.toHaveBeenCalled();
-  });
-
-  it("never reports committed for a malformed success body", async () => {
-    transport.post.mockResolvedValue({ status: 200, data: { wrong: true } });
-    const result = await capturedRun([
-      "calls",
-      "clear",
-      "--event",
-      EVENT,
-      "--confirm",
-      "--json",
-    ]);
-    expect(result.code).toBe(1);
-    const document = JSON.parse(result.stdout);
-    expect(document.state).toBe("unknown");
-    expect(document.code).toBe("ui_write_receipt_invalid");
-  });
-});
-
-describe.skip("retired import-file", () => {
-  it("never uploads without --confirm", async () => {
-    const directory = await mkdtemp(path.join(tmpdir(), "om-import-"));
-    const file = path.join(directory, "export.json");
-    await writeFile(file, '{"conversations":[]}', { mode: 0o600 });
-    const result = await capturedRun([
-      "import-file",
-      "upload",
-      "--file",
-      file,
-      "--json",
-    ]);
-    expect(result.code).toBe(0);
-    const document = JSON.parse(result.stdout);
-    expect(document.state).toBe("preview");
-    expect(document.plan.operation_id).toBeDefined();
-    expect(transport.post).not.toHaveBeenCalled();
-  });
-
-  it("uploads the file with a deterministic operation id on confirm", async () => {
-    const directory = await mkdtemp(path.join(tmpdir(), "om-import-"));
-    const file = path.join(directory, "export.json");
-    await writeFile(file, '{"conversations":[]}', { mode: 0o600 });
-    transport.post.mockResolvedValue({
-      status: 201,
-      data: {
-        schema_version: 1,
-        operation_id: "ignored-here",
-        state: "completed",
-        upload_id: UPLOAD,
-        upload_state: "staged",
-      },
-    });
-    const preview = await capturedRun([
-      "import-file",
-      "upload",
-      "--file",
-      file,
-      "--json",
-    ]);
-    const plan = JSON.parse(preview.stdout).plan;
-    transport.post.mockResolvedValue({
-      status: 201,
-      data: {
-        schema_version: 1,
-        operation_id: plan.operation_id,
-        state: "completed",
-        upload_id: UPLOAD,
-        upload_state: "staged",
-      },
-    });
-    const result = await capturedRun([
-      "import-file",
-      "upload",
-      "--file",
-      file,
-      "--confirm",
-      "--json",
-    ]);
-    expect(result.code).toBe(0);
-    const url = transport.post.mock.calls.at(-1)?.[0] as string;
-    expect(url).toContain("/api/v1/import-files?");
-    expect(url).toContain(`operation_id=${plan.operation_id}`);
-    expect(url).toContain("filename=export.json");
-    expect(JSON.parse(result.stdout).state).toBe("committed");
-  });
-
-  it("commits and discards only with explicit confirmation", async () => {
-    const preview = await capturedRun([
-      "import-file",
-      "commit",
-      UPLOAD,
-      "--json",
-    ]);
-    expect(preview.code).toBe(0);
-    expect(JSON.parse(preview.stdout).state).toBe("preview");
-    expect(transport.post).not.toHaveBeenCalled();
-
-    transport.post.mockResolvedValue({
-      status: 200,
-      data: {
-        upload_id: UPLOAD,
-        filename: "x.json",
-        vendor: "generic",
-        source_id: "generic-export",
-        messages: 0,
-        conversations: 0,
-        human_messages: 0,
-        agent_messages: 0,
-        skipped_records: 0,
-        ignored_files: 0,
-        checksum: "a".repeat(64),
-        created_at: "T",
-        committed: true,
-      },
-    });
-    const committed = await capturedRun([
-      "import-file",
-      "commit",
-      UPLOAD,
-      "--confirm",
-      "--json",
-    ]);
-    expect(committed.code).toBe(0);
-    expect(transport.post).toHaveBeenCalledWith(
-      `/api/v1/import-files/${UPLOAD}/commit`,
-      { confirmed: true },
-      undefined,
-    );
-
-    transport.delete.mockResolvedValue({ status: 204, data: "" });
-    const discarded = await capturedRun([
-      "import-file",
-      "discard",
-      UPLOAD,
-      "--confirm",
-      "--json",
-    ]);
-    expect(discarded.code).toBe(0);
-    expect(JSON.parse(discarded.stdout).state).toBe("committed");
-    expect(transport.delete).toHaveBeenCalledWith(
-      `/api/v1/import-files/${UPLOAD}`,
-      undefined,
-    );
-  });
-
-  it("maps a Core 404 to a stable rejected code, not a fake success", async () => {
-    transport.post.mockResolvedValue({
-      status: 404,
-      data: { detail: "import_file_not_found" },
-    });
-    const result = await capturedRun([
-      "import-file",
-      "commit",
-      UPLOAD,
-      "--confirm",
-      "--json",
-    ]);
-    expect(result.code).toBe(1);
-    const document = JSON.parse(result.stdout);
-    expect(document.state).toBe("rejected");
-    expect(document.code).toBe("import_file_not_found");
-  });
-});
-
-describe("notes / extraction / graph / manual extract", () => {
-  it("adds a note from a bounded file and re-verifies content on apply", async () => {
-    const directory = await mkdtemp(path.join(tmpdir(), "om-note-"));
-    const content = path.join(directory, "note.txt");
-    await writeFile(content, "记住这个决定", { mode: 0o600 });
-    const preview = await capturedRun([
-      "notes",
-      "add",
-      "--content-file",
-      content,
-      "--json",
-    ]);
-    expect(preview.code).toBe(0);
-    const planFile = path.join(directory, "plan.json");
-    await writeFile(planFile, preview.stdout, { mode: 0o600 });
-    transport.post.mockResolvedValue({
-      status: 201,
-      // A realistic Core `MemoryNoteReceipt`: the shared parser requires
-      // `scope` and `memory_ids` too, so a minimal `{evidence_id,state}` stub
-      // is a malformed body, not a success.
-      data: {
-        evidence_id: NOTE,
-        text: "记住这个决定",
-        scope: "all-apps",
-        created_at: "2026-09-19T00:00:00Z",
-        state: "pending",
-        task_id: null,
-        memory_ids: [],
-        error: null,
-      },
-    });
-    const applied = await capturedRun([
-      "notes",
-      "apply",
-      "--plan-file",
-      planFile,
-      "--content-file",
-      content,
-      "--confirm",
-      "--json",
-    ]);
-    expect(applied.code).toBe(0);
-    const body = transport.post.mock.calls.at(-1)?.[1] as Record<
-      string,
-      unknown
-    >;
-    expect(body.text).toBe("记住这个决定");
-    expect(body.scope).toBe("all-apps");
-    expect(JSON.parse(applied.stdout).state).toBe("committed");
-  });
-
-  it.skip("plans then applies the extraction window", async () => {
-    const preview = await capturedRun([
-      "extraction",
-      "set",
-      "--window",
-      "6m",
-      "--json",
-    ]);
-    expect(preview.code).toBe(0);
-    expect(JSON.parse(preview.stdout).state).toBe("preview");
-    expect(transport.put).not.toHaveBeenCalled();
-    transport.put.mockResolvedValue({
-      status: 200,
-      data: { window_preset: "6m" },
-    });
-    const applied = await capturedRun([
-      "extraction",
-      "set",
-      "--window",
-      "6m",
-      "--confirm",
-      "--json",
-    ]);
-    expect(applied.code).toBe(0);
-    expect(transport.put).toHaveBeenCalledWith(
-      "/api/v1/extraction-settings",
-      { window_preset: "6m" },
-      undefined,
-    );
-  });
-
-  it("does not call graph width without --confirm", async () => {
-    const preview = await capturedRun([
-      "graph",
-      "width",
-      "--decision",
-      "rebuild_with_new",
-      "--json",
-    ]);
-    expect(preview.code).toBe(0);
-    expect(transport.post).not.toHaveBeenCalled();
-    transport.post.mockResolvedValue({
-      status: 200,
-      data: { archived_path: "/tmp/old", exported_path: null, mismatch: null },
-    });
-    const applied = await capturedRun([
-      "graph",
-      "width",
-      "--decision",
-      "rebuild_with_new",
-      "--confirm",
-      "--json",
-    ]);
-    expect(applied.code).toBe(0);
-    expect(transport.post).toHaveBeenCalledWith(
-      "/api/v1/graph-width",
-      { decision: "rebuild_with_new" },
-      undefined,
-    );
-  });
-
-  it.skip("plans manual extraction and applies it only on confirm", async () => {
-    const preview = await capturedRun([
-      "processing",
-      "extract",
-      "--evidence",
-      NOTE,
-      "--json",
-    ]);
-    expect(preview.code).toBe(0);
-    expect(JSON.parse(preview.stdout).state).toBe("preview");
-    expect(transport.post).not.toHaveBeenCalled();
-    transport.post.mockResolvedValue({
-      status: 200,
-      data: { promoted: 1, batches_planned: 2, batches_current: 1 },
-    });
-    const applied = await capturedRun([
-      "processing",
-      "extract",
-      "--evidence",
-      NOTE,
-      "--confirm",
-      "--json",
-    ]);
-    expect(applied.code).toBe(0);
-    expect(transport.post).toHaveBeenCalledWith(
-      "/api/v1/memory-processing/manual-extract",
-      { evidence_ids: [NOTE] },
-      undefined,
-    );
-  });
-});
-
-async function capturedRun(arguments_: string[]) {
-  let stdout = "";
-  let stderr = "";
-  const stdoutSpy = vi
-    .spyOn(process.stdout, "write")
-    .mockImplementation((chunk) => {
-      stdout += String(chunk);
-      return true;
-    });
-  const stderrSpy = vi
-    .spyOn(process.stderr, "write")
-    .mockImplementation((chunk) => {
-      stderr += String(chunk);
-      return true;
-    });
-  try {
-    return {
-      code: await run(arguments_, {
-        ONE_MEMORY_DATA_DIR: "/synthetic/data",
-      }),
-      stdout,
-      stderr,
-    };
-  } finally {
-    stdoutSpy.mockRestore();
-    stderrSpy.mockRestore();
-  }
-}
@@ -1,501 +0,0 @@
-/**
- * The remaining Web Console mutating operations the CLI did not expose:
- * 端内新增记忆 (memory-notes), extraction window, graph width, and manual
- * extraction.
- *
- * Core owns every rule; this module only validates the input it is about to
- * send, performs one explicit two-phase write, and normalises the receipt so
- * the CLI never reports a write as committed without evidence.
- */
-
-import { createHash, randomUUID } from "node:crypto";
-import {
-  buildMemoryNoteSaveRequest,
-  MemoryNoteInputError,
-  parseExtractionSettingsReceipt,
-  parseGraphWidthDecisionReceipt,
-  parseManualExtractReceipt,
-  parseMemoryNoteReceipt,
-} from "@one-memory/operations";
-import type { CoreOperations, CorePutOperations } from "./core-operations.js";
-import { PRODUCT } from "./version.js";
-
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
-const DIGEST = /^[0-9a-f]{64}$/;
-const NOTE_MAX_CHARACTERS = 12_000;
-const EXTRACTION_PRESETS = ["3m", "6m", "1y", "all"] as const;
-const GRAPH_DECISIONS = [
-  "keep_existing",
-  "rebuild_with_new",
-  "export_first",
-] as const;
-const NOTE_STATES = [
-  "waiting_for_model",
-  "waiting_for_permission",
-  "pending",
-  "running",
-  "failed",
-  "ready",
-  "no_memories",
-] as const;
-
-export type NoteState = (typeof NOTE_STATES)[number];
-
-export type ExtendedWritePlan =
-  | {
-      schema_version: 1;
-      kind: "memory_note_add";
-      request_id: string;
-      content_sha256: string;
-      content_characters: number;
-      digest: string;
-    }
-  | {
-      schema_version: 1;
-      kind: "memory_note_process";
-      evidence_id: string;
-      digest: string;
-    }
-  | {
-      schema_version: 1;
-      kind: "extraction_window_set";
-      window_preset: (typeof EXTRACTION_PRESETS)[number];
-      digest: string;
-    }
-  | {
-      schema_version: 1;
-      kind: "graph_width_decide";
-      decision: (typeof GRAPH_DECISIONS)[number];
-      digest: string;
-    }
-  | {
-      schema_version: 1;
-      kind: "manual_extract";
-      evidence_ids: string[];
-      digest: string;
-    };
-
-export type ExtendedWriteOutcome =
-  | {
-      schema_version: 1;
-      product: string;
-      state: "preview";
-      plan: ExtendedWritePlan;
-    }
-  | {
-      schema_version: 1;
-      product: string;
-      state: "committed" | "recovered";
-      operation_id: string;
-      receipt: Record<string, unknown>;
-    }
-  | {
-      schema_version: 1;
-      product: string;
-      state: "rejected" | "unknown" | "invalid";
-      operation_id?: string;
-      code: string;
-    };
-
-function canonical(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
-  if (value !== null && typeof value === "object") {
-    return `{${Object.entries(value as Record<string, unknown>)
-      .sort(([left], [right]) => left.localeCompare(right))
-      .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
-      .join(",")}}`;
-  }
-  if (value === undefined) return "null";
-  return JSON.stringify(value);
-}
-
-function digestOf(value: unknown): string {
-  return createHash("sha256").update(canonical(value)).digest("hex");
-}
-
-type Draft =
-  | Omit<Extract<ExtendedWritePlan, { kind: "memory_note_add" }>, "digest">
-  | Omit<Extract<ExtendedWritePlan, { kind: "memory_note_process" }>, "digest">
-  | Omit<
-      Extract<ExtendedWritePlan, { kind: "extraction_window_set" }>,
-      "digest"
-    >
-  | Omit<Extract<ExtendedWritePlan, { kind: "graph_width_decide" }>, "digest">
-  | Omit<Extract<ExtendedWritePlan, { kind: "manual_extract" }>, "digest">;
-
-function preview(plan: Draft): ExtendedWriteOutcome {
-  return {
-    schema_version: 1,
-    product: PRODUCT,
-    state: "preview",
-    plan: { ...plan, digest: digestOf(plan) } as ExtendedWritePlan,
-  };
-}
-
-function invalid(code: string): ExtendedWriteOutcome {
-  return { schema_version: 1, product: PRODUCT, state: "invalid", code };
-}
-
-function committed(
-  operationId: string,
-  receipt: Record<string, unknown>,
-  state: "committed" | "recovered" = "committed",
-): ExtendedWriteOutcome {
-  return {
-    schema_version: 1,
-    product: PRODUCT,
-    state,
-    operation_id: operationId,
-    receipt,
-  };
-}
-
-function rejected(
-  operationId: string | undefined,
-  code: string,
-): ExtendedWriteOutcome {
-  return {
-    schema_version: 1,
-    product: PRODUCT,
-    state: "rejected",
-    ...(operationId === undefined ? {} : { operation_id: operationId }),
-    code,
-  };
-}
-
-function unknown(
-  operationId: string | undefined,
-  code: string,
-): ExtendedWriteOutcome {
-  return {
-    schema_version: 1,
-    product: PRODUCT,
-    state: "unknown",
-    ...(operationId === undefined ? {} : { operation_id: operationId }),
-    code,
-  };
-}
-
-// --- memory-notes ---------------------------------------------------------
-
-export function planMemoryNoteAdd(text: string): ExtendedWriteOutcome {
-  // The plan keeps only the note's identity, like `memories plan add`: the
-  //正文 lives in a bounded file and is re-read and re-hashed at apply time, so
-  // a plan file never carries the user's private text.
-  if (!validNoteText(text)) return invalid("memory_note_text_invalid");
-  const requestId = randomUUID();
-  return preview({
-    schema_version: 1,
-    kind: "memory_note_add",
-    request_id: requestId,
-    content_sha256: createHash("sha256").update(text, "utf8").digest("hex"),
-    content_characters: [...text].length,
-  });
-}
-
-export function validNoteText(text: string): boolean {
-  return (
-    text.length > 0 &&
-    [...text].length <= NOTE_MAX_CHARACTERS &&
-    text.trim().length > 0 &&
-    ![...text].some((character) => {
-      const code = character.charCodeAt(0);
-      return code <= 8 || (code >= 11 && code <= 31) || code === 127;
-    })
-  );
-}
-
-export function planMemoryNoteProcess(
-  evidenceId: string,
-): ExtendedWriteOutcome {
-  return UUID.test(evidenceId)
-    ? preview({
-        schema_version: 1,
-        kind: "memory_note_process",
-        evidence_id: evidenceId,
-      })
-    : invalid("memory_note_id_invalid");
-}
-
-function noteReceipt(
-  operationId: string,
-  data: { evidence_id: string; state: NoteState },
-): ExtendedWriteOutcome {
-  return committed(operationId, { ...data });
-}
-
-export async function executeMemoryNoteAdd(
-  plan: Extract<ExtendedWritePlan, { kind: "memory_note_add" }>,
-  operations: CoreOperations,
-  text: string,
-): Promise<ExtendedWriteOutcome> {
-  if (
-    !validNoteText(text) ||
-    createHash("sha256").update(text, "utf8").digest("hex") !==
-      plan.content_sha256 ||
-    [...text].length !== plan.content_characters
-  ) {
-    return invalid("memory_note_content_mismatch");
-  }
-  // The shared builder owns the save body (request_id/text/scope=all-apps), so
-  // the CLI and the Web console post the same three fields. Its own text check
-  // already ran above, so a throw here means an unusable plan.
-  let request: ReturnType<typeof buildMemoryNoteSaveRequest>;
-  try {
-    request = buildMemoryNoteSaveRequest({
-      request_id: plan.request_id,
-      text,
-      scope: "all-apps",
-    } as Parameters<typeof buildMemoryNoteSaveRequest>[0]);
-  } catch (error) {
-    if (error instanceof MemoryNoteInputError) {
-      return invalid("memory_note_content_mismatch");
-    }
-    throw error;
-  }
-  const result = await operations.post<unknown>(request.path, request.body);
-  if (result.state === "rejected") {
-    return rejected(plan.request_id, result.code);
-  }
-  if (result.state === "unknown") {
-    return unknown(plan.request_id, result.code);
-  }
-  const receipt = asNoteReceipt(result.data);
-  return receipt === null
-    ? unknown(plan.request_id, "ui_write_receipt_invalid")
-    : noteReceipt(plan.request_id, receipt);
-}
-
-export async function executeMemoryNoteProcess(
-  plan: Extract<ExtendedWritePlan, { kind: "memory_note_process" }>,
-  operations: CoreOperations,
-): Promise<ExtendedWriteOutcome> {
-  const result = await operations.post<unknown>(
-    `/api/v1/memory-notes/${plan.evidence_id}/process`,
-    {},
-  );
-  if (result.state === "rejected") {
-    return rejected(plan.evidence_id, result.code);
-  }
-  if (result.state === "unknown") {
-    return unknown(plan.evidence_id, result.code);
-  }
-  const receipt = asNoteReceipt(result.data);
-  return receipt === null
-    ? unknown(plan.evidence_id, "ui_write_receipt_invalid")
-    : noteReceipt(plan.evidence_id, receipt);
-}
-
-function asNoteReceipt(
-  value: unknown,
-): { evidence_id: string; state: NoteState } | null {
-  // The shared parser is the single judge of a note receipt; a malformed body
-  // returns null and the caller reports `unknown`, never a saved note.
-  const receipt = parseMemoryNoteReceipt(value);
-  return receipt === null
-    ? null
-    : { evidence_id: receipt.evidence_id, state: receipt.state as NoteState };
-}
-
-// --- extraction window / graph width / manual extract ---------------------
-
-export function planExtractionWindowSet(
-  windowPreset: string,
-): ExtendedWriteOutcome {
-  return (EXTRACTION_PRESETS as readonly string[]).includes(windowPreset)
-    ? preview({
-        schema_version: 1,
-        kind: "extraction_window_set",
-        window_preset: windowPreset as (typeof EXTRACTION_PRESETS)[number],
-      })
-    : invalid("extraction_window_preset_invalid");
-}
-
-export function planGraphWidthDecide(decision: string): ExtendedWriteOutcome {
-  return (GRAPH_DECISIONS as readonly string[]).includes(decision)
-    ? preview({
-        schema_version: 1,
-        kind: "graph_width_decide",
-        decision: decision as (typeof GRAPH_DECISIONS)[number],
-      })
-    : invalid("graph_width_decision_invalid");
-}
-
-export function planManualExtract(evidenceIds: string[]): ExtendedWriteOutcome {
-  const ids = [...new Set(evidenceIds)];
-  return ids.length === evidenceIds.length && ids.every((id) => UUID.test(id))
-    ? preview({
-        schema_version: 1,
-        kind: "manual_extract",
-        evidence_ids: ids,
-      })
-    : invalid("manual_extract_evidence_ids_invalid");
-}
-
-export async function executeExtractionWindowSet(
-  plan: Extract<ExtendedWritePlan, { kind: "extraction_window_set" }>,
-  operations: CorePutOperations,
-): Promise<ExtendedWriteOutcome> {
-  const result = await operations.put<unknown>("/api/v1/extraction-settings", {
-    window_preset: plan.window_preset,
-  });
-  if (result.state === "rejected") {
-    return rejected(plan.window_preset, result.code);
-  }
-  if (result.state === "unknown") {
-    return unknown(plan.window_preset, result.code);
-  }
-  // The shared parser also enforces that the receipt echoes the requested
-  // preset, so a response belonging to another write cannot pass.
-  const parsed = parseExtractionSettingsReceipt(
-    result.data,
-    plan.window_preset,
-  );
-  if (parsed === null) {
-    return unknown(plan.window_preset, "ui_write_receipt_invalid");
-  }
-  return committed(plan.window_preset, { window_preset: plan.window_preset });
-}
-
-export async function executeGraphWidthDecide(
-  plan: Extract<ExtendedWritePlan, { kind: "graph_width_decide" }>,
-  operations: CoreOperations,
-): Promise<ExtendedWriteOutcome> {
-  const result = await operations.post<unknown>("/api/v1/graph-width", {
-    decision: plan.decision,
-  });
-  if (result.state === "rejected") {
-    return rejected(plan.decision, result.code);
-  }
-  if (result.state === "unknown") {
-    return unknown(plan.decision, result.code);
-  }
-  const receipt = parseGraphWidthDecisionReceipt(result.data);
-  if (receipt === null) {
-    return unknown(plan.decision, "ui_write_receipt_invalid");
-  }
-  return committed(plan.decision, {
-    archived_path: receipt.archived_path ?? null,
-    exported_path: receipt.exported_path ?? null,
-    mismatch: receipt.mismatch ?? null,
-  });
-}
-
-export async function executeManualExtract(
-  plan: Extract<ExtendedWritePlan, { kind: "manual_extract" }>,
-  operations: CoreOperations,
-): Promise<ExtendedWriteOutcome> {
-  const result = await operations.post<unknown>(
-    "/api/v1/memory-processing/manual-extract",
-    { evidence_ids: plan.evidence_ids },
-  );
-  if (result.state === "rejected") {
-    return rejected("manual_extract", result.code);
-  }
-  if (result.state === "unknown") {
-    return unknown("manual_extract", result.code);
-  }
-  const receipt = parseManualExtractReceipt(result.data);
-  if (receipt === null) {
-    return unknown("manual_extract", "ui_write_receipt_invalid");
-  }
-  return committed("manual_extract", {
-    promoted: receipt.promoted,
-    batches_planned: receipt.batches_planned,
-    batches_current: receipt.batches_current,
-  });
-}
-
-export function validateExtendedWritePlan(
-  value: unknown,
-): ExtendedWritePlan | null {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    return null;
-  }
-  const candidate = value as Record<string, unknown>;
-  if (candidate.schema_version !== 1 || typeof candidate.kind !== "string") {
-    return null;
-  }
-  const { digest, ...withoutDigest } = candidate;
-  if (typeof digest !== "string" || digest !== digestOf(withoutDigest)) {
-    return null;
-  }
-  switch (candidate.kind) {
-    case "memory_note_add":
-      return typeof candidate.request_id === "string" &&
-        UUID.test(candidate.request_id) &&
-        typeof candidate.content_sha256 === "string" &&
-        DIGEST.test(candidate.content_sha256) &&
-        Number.isSafeInteger(candidate.content_characters) &&
-        (candidate.content_characters as number) >= 1 &&
-        (candidate.content_characters as number) <= NOTE_MAX_CHARACTERS &&
-        Object.keys(candidate).length === 6
-        ? (candidate as unknown as ExtendedWritePlan)
-        : null;
-    case "memory_note_process":
-      return typeof candidate.evidence_id === "string" &&
-        UUID.test(candidate.evidence_id) &&
-        Object.keys(candidate).length === 4
-        ? (candidate as unknown as ExtendedWritePlan)
-        : null;
-    case "extraction_window_set":
-      return (EXTRACTION_PRESETS as readonly string[]).includes(
-        String(candidate.window_preset),
-      ) && Object.keys(candidate).length === 4
-        ? (candidate as unknown as ExtendedWritePlan)
-        : null;
-    case "graph_width_decide":
-      return (GRAPH_DECISIONS as readonly string[]).includes(
-        String(candidate.decision),
-      ) && Object.keys(candidate).length === 4
-        ? (candidate as unknown as ExtendedWritePlan)
-        : null;
-    case "manual_extract":
-      return Array.isArray(candidate.evidence_ids) &&
-        candidate.evidence_ids.every(
-          (id) => typeof id === "string" && UUID.test(id),
-        ) &&
-        Object.keys(candidate).length === 4
-        ? (candidate as unknown as ExtendedWritePlan)
-        : null;
-    default:
-      return null;
-  }
-}
-
-export function extendedWriteExitCode(document: ExtendedWriteOutcome): number {
-  return ["preview", "committed", "recovered"].includes(document.state) ? 0 : 1;
-}
-
-export function renderExtendedWriteText(
-  document: ExtendedWriteOutcome,
-): string {
-  if (document.state === "preview") {
-    const lines = ["以下操作尚未执行；加 --confirm 后才会写入："];
-    const plan = document.plan;
-    switch (plan.kind) {
-      case "memory_note_add":
-        lines.push(`新增端内记忆：${plan.content_characters} 字符`);
-        break;
-      case "memory_note_process":
-        lines.push(`处理端内记忆：${plan.evidence_id}`);
-        break;
-      case "extraction_window_set":
-        lines.push(`设置提取窗口：${plan.window_preset}`);
-        break;
-      case "graph_width_decide":
-        lines.push(`图谱宽度决定：${plan.decision}`);
-        break;
-      case "manual_extract":
-        lines.push(`手动提取：${plan.evidence_ids.length} 条证据`);
-        break;
-    }
-    lines.push(`plan_digest：${plan.digest}`);
-    return `${lines.join("\n")}\n`;
-  }
-  if (document.state === "committed" || document.state === "recovered") {
-    return `${document.state === "recovered" ? "已从回执恢复" : "已提交"}：${document.operation_id}\n${JSON.stringify(document.receipt)}\n`;
-  }
-  const code = "code" in document ? document.code : "ui_write_state_invalid";
-  return `操作未完成：${document.state}（${code}）\n`;
-}
@@ -1,144 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import type {
-  CoreDeleteOperations,
-  CoreOperations,
-} from "./core-operations.js";
-import {
-  executeCallEventsClear,
-  executeCallEventsClearAll,
-  executeImportFileCommit,
-  executeImportFileDiscard,
-  planCallEventsClear,
-  planCallEventsClearAll,
-  planImportFileCommit,
-  planImportFileDiscard,
-  planImportFileUpload,
-  validateUiWritePlan,
-} from "./ui-write-flows.js";
-
-const EVENT = "11111111-1111-4111-8111-111111111111";
-const UPLOAD = "22222222-2222-4222-8222-222222222222";
-
-function planOf(value: ReturnType<typeof planCallEventsClear>) {
-  if (value.state !== "preview") throw new Error("expected preview");
-  return value.plan;
-}
-
-describe("UI write plans", () => {
-  it("permits only valid call-event ids and rejects duplicates", () => {
-    expect(planCallEventsClear([EVENT]).state).toBe("preview");
-    expect(planCallEventsClear([]).state).toBe("invalid");
-    expect(planCallEventsClear([EVENT, EVENT]).state).toBe("invalid");
-  });
-
-  it("plans all remaining UI write operations", () => {
-    expect(planCallEventsClearAll().state).toBe("preview");
-    expect(planImportFileCommit(UPLOAD).state).toBe("preview");
-    expect(planImportFileDiscard(UPLOAD).state).toBe("preview");
-    expect(
-      planImportFileUpload({
-        path: "/tmp/export.json",
-        bytes: 42,
-        sha256: "a".repeat(64),
-        inputKind: "raw_conversation",
-      }).state,
-    ).toBe("preview");
-  });
-
-  it("rejects a tampered plan digest", async () => {
-    const plan = planOf(planCallEventsClear([EVENT]));
-    expect(validateUiWritePlan(plan)).toEqual(plan);
-    expect(validateUiWritePlan({ ...plan, event_ids: [UPLOAD] })).toBeNull();
-  });
-});
-
-describe("UI write execution", () => {
-  it("posts clear with Core's confirmation field", async () => {
-    const post = vi.fn(async () => ({
-      state: "committed" as const,
-      data: { removed: 1 },
-    }));
-    const plan = planOf(planCallEventsClear([EVENT]));
-    if (plan.kind !== "call_events_clear") throw new Error("kind");
-    const result = await executeCallEventsClear(plan, {
-      post,
-    } as unknown as CoreOperations);
-    expect(result.state).toBe("committed");
-    expect(post).toHaveBeenCalledWith("/api/v1/call-events/clear", {
-      event_ids: [EVENT],
-      user_confirmed: true,
-    });
-  });
-
-  it("posts clear-all with Core's confirmation field", async () => {
-    const post = vi.fn(async () => ({
-      state: "committed" as const,
-      data: { removed: 2 },
-    }));
-    const plan = planOf(planCallEventsClearAll());
-    if (plan.kind !== "call_events_clear_all") throw new Error("kind");
-    await executeCallEventsClearAll(plan, {
-      post,
-    } as unknown as CoreOperations);
-    expect(post).toHaveBeenCalledWith("/api/v1/call-events/clear-all", {
-      user_confirmed: true,
-    });
-  });
-
-  it("uses POST commit and DELETE discard endpoints", async () => {
-    const post = vi.fn(async () => ({
-      state: "committed" as const,
-      data: {
-        upload_id: UPLOAD,
-        filename: "x.json",
-        vendor: "generic",
-        source_id: "generic-export",
-        messages: 0,
-        conversations: 0,
-        human_messages: 0,
-        agent_messages: 0,
-        skipped_records: 0,
-        ignored_files: 0,
-        checksum: "a".repeat(64),
-        created_at: "T",
-        committed: true,
-      },
-    }));
-    const del = vi.fn(async <T>() => ({
-      state: "committed" as const,
-      data: {} as T,
-    }));
-    const operations = {
-      post,
-      delete: del,
-    } as unknown as CoreOperations & CoreDeleteOperations;
-    const commit = planOf(planImportFileCommit(UPLOAD));
-    if (commit.kind !== "import_file_commit") throw new Error("kind");
-    await executeImportFileCommit(commit, operations);
-    expect(post).toHaveBeenCalledWith(`/api/v1/import-files/${UPLOAD}/commit`, {
-      confirmed: true,
-    });
-    const discard = planOf(planImportFileDiscard(UPLOAD));
-    if (discard.kind !== "import_file_discard") throw new Error("kind");
-    expect((await executeImportFileDiscard(discard, operations)).state).toBe(
-      "committed",
-    );
-    expect(del).toHaveBeenCalledWith(`/api/v1/import-files/${UPLOAD}`);
-  });
-
-  it("treats a malformed success receipt as unknown", async () => {
-    const plan = planOf(planCallEventsClear([EVENT]));
-    if (plan.kind !== "call_events_clear") throw new Error("kind");
-    const result = await executeCallEventsClear(plan, {
-      post: vi.fn(async () => ({
-        state: "committed" as const,
-        data: { wrong: true },
-      })),
-    } as unknown as CoreOperations);
-    expect(result).toMatchObject({
-      state: "unknown",
-      code: "ui_write_receipt_invalid",
-    });
-  });
-});
@@ -1,555 +0,0 @@
-/**
- * The Web Console's remaining mutating operations, exposed to the CLI without
- * duplicating Core semantics. Each operation is planned first; callers apply
- * the exact plan they reviewed.
- */
-
-import { createHash } from "node:crypto";
-import { constants } from "node:fs";
-import { type FileHandle, open } from "node:fs/promises";
-import type {
-  CoreDeleteOperations,
-  CoreOperations,
-  CoreUploadOperations,
-} from "./core-operations.js";
-import { PRODUCT } from "./version.js";
-
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
-const INPUT_KINDS = ["raw_conversation", "memory_content"] as const;
-const MAX_UPLOAD_BYTES = 128 * 1024 * 1024;
-
-export type UiWritePlan =
-  | {
-      schema_version: 1;
-      kind: "call_events_clear";
-      event_ids: string[];
-      digest: string;
-    }
-  | {
-      schema_version: 1;
-      kind: "call_events_clear_all";
-      digest: string;
-    }
-  | {
-      schema_version: 1;
-      kind: "import_file_commit";
-      upload_id: string;
-      digest: string;
-    }
-  | {
-      schema_version: 1;
-      kind: "import_file_discard";
-      upload_id: string;
-      digest: string;
-    }
-  | {
-      schema_version: 1;
-      kind: "import_file_upload";
-      operation_id: string;
-      path: string;
-      filename: string;
-      input_kind: (typeof INPUT_KINDS)[number];
-      bytes: number;
-      sha256: string;
-      digest: string;
-    };
-
-export type UiWriteOutcome =
-  | {
-      schema_version: 1;
-      product: string;
-      state: "preview";
-      plan: UiWritePlan;
-    }
-  | {
-      schema_version: 1;
-      product: string;
-      state: "committed" | "recovered";
-      operation_id: string;
-      receipt: Record<string, unknown>;
-    }
-  | {
-      schema_version: 1;
-      product: string;
-      state: "rejected" | "unknown" | "invalid";
-      operation_id?: string;
-      code: string;
-      receipt?: Record<string, unknown>;
-    };
-
-function digestOf(value: unknown): string {
-  return createHash("sha256").update(canonical(value)).digest("hex");
-}
-
-function canonical(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
-  if (value !== null && typeof value === "object") {
-    return `{${Object.entries(value as Record<string, unknown>)
-      .sort(([left], [right]) => left.localeCompare(right))
-      .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
-      .join(",")}}`;
-  }
-  if (value === undefined) return "null";
-  return JSON.stringify(value);
-}
-
-export type UiWritePlanDraft =
-  | Omit<Extract<UiWritePlan, { kind: "call_events_clear" }>, "digest">
-  | Omit<Extract<UiWritePlan, { kind: "call_events_clear_all" }>, "digest">
-  | Omit<Extract<UiWritePlan, { kind: "import_file_commit" }>, "digest">
-  | Omit<Extract<UiWritePlan, { kind: "import_file_discard" }>, "digest">
-  | Omit<Extract<UiWritePlan, { kind: "import_file_upload" }>, "digest">;
-
-function preview(plan: UiWritePlanDraft): UiWriteOutcome {
-  return {
-    schema_version: 1,
-    product: PRODUCT,
-    state: "preview",
-    plan: { ...plan, digest: digestOf(plan) } as UiWritePlan,
-  };
-}
-
-function invalid(code: string): UiWriteOutcome {
-  return { schema_version: 1, product: PRODUCT, state: "invalid", code };
-}
-
-function committed(
-  operationId: string,
-  receipt: Record<string, unknown>,
-  state: "committed" | "recovered" = "committed",
-): UiWriteOutcome {
-  return {
-    schema_version: 1,
-    product: PRODUCT,
-    state,
-    operation_id: operationId,
-    receipt,
-  };
-}
-
-export function planCallEventsClear(
-  eventIds: readonly string[],
-): UiWriteOutcome {
-  if (
-    eventIds.length < 1 ||
-    eventIds.length > 100 ||
-    new Set(eventIds).size !== eventIds.length ||
-    eventIds.some((id) => !UUID.test(id))
-  ) {
-    return invalid("call_event_ids_invalid");
-  }
-  return preview({
-    schema_version: 1,
-    kind: "call_events_clear",
-    event_ids: [...eventIds],
-  });
-}
-
-export function planCallEventsClearAll(): UiWriteOutcome {
-  return preview({ schema_version: 1, kind: "call_events_clear_all" });
-}
-
-export function planImportFileCommit(uploadId: string): UiWriteOutcome {
-  return UUID.test(uploadId)
-    ? preview({
-        schema_version: 1,
-        kind: "import_file_commit",
-        upload_id: uploadId,
-      })
-    : invalid("import_file_id_invalid");
-}
-
-export function planImportFileDiscard(uploadId: string): UiWriteOutcome {
-  return UUID.test(uploadId)
-    ? preview({
-        schema_version: 1,
-        kind: "import_file_discard",
-        upload_id: uploadId,
-      })
-    : invalid("import_file_id_invalid");
-}
-
-export function planImportFileUpload(input: {
-  path: string;
-  bytes: number;
-  sha256: string;
-  inputKind: "raw_conversation" | "memory_content";
-}): UiWriteOutcome {
-  const filename = input.path.split(/[/\\]/).pop() ?? "";
-  if (
-    input.path.length === 0 ||
-    !Number.isSafeInteger(input.bytes) ||
-    input.bytes < 0 ||
-    input.bytes > MAX_UPLOAD_BYTES ||
-    !/^[0-9a-f]{64}$/.test(input.sha256) ||
-    !INPUT_KINDS.includes(input.inputKind) ||
-    filename.length === 0 ||
-    [...filename].length > 200 ||
-    !/\.(?:zip|json|md|txt)$/i.test(filename)
-  ) {
-    return invalid("import_file_upload_invalid");
-  }
-  return preview({
-    schema_version: 1,
-    kind: "import_file_upload",
-    operation_id: fileUploadOperationId(
-      filename,
-      input.inputKind,
-      input.sha256,
-    ),
-    path: input.path,
-    filename,
-    input_kind: input.inputKind,
-    bytes: input.bytes,
-    sha256: input.sha256,
-  });
-}
-
-/**
- * Read one regular, non-symlinked export without buffering past the 128 MiB
- * limit. Returns the bytes plus the checksum the plan records, so apply can
- * prove the file it uploads is the one the caller reviewed.
- */
-export async function readImportFileUpload(
-  filePath: string,
-  inputKind: "raw_conversation" | "memory_content",
-): Promise<{ plan: UiWritePlan; bytes: Buffer } | null> {
-  let handle: FileHandle;
-  try {
-    handle = await open(
-      filePath,
-      constants.O_RDONLY |
-        (constants.O_NONBLOCK ?? 0) |
-        (constants.O_NOFOLLOW ?? 0),
-    );
-  } catch {
-    return null;
-  }
-  try {
-    const stats = await handle.stat();
-    if (!stats.isFile() || stats.nlink !== 1 || stats.size > MAX_UPLOAD_BYTES) {
-      return null;
-    }
-    const buffer = Buffer.alloc(Number(stats.size));
-    let offset = 0;
-    while (offset < buffer.length) {
-      const chunk = await handle.read(
-        buffer,
-        offset,
-        buffer.length - offset,
-        offset,
-      );
-      if (chunk.bytesRead === 0) break;
-      offset += chunk.bytesRead;
-    }
-    if (offset !== buffer.length) return null;
-    const checksum = createHash("sha256").update(buffer).digest("hex");
-    const result = planImportFileUpload({
-      path: filePath,
-      bytes: buffer.byteLength,
-      sha256: checksum,
-      inputKind,
-    });
-    if (result.state !== "preview") return null;
-    return { plan: result.plan, bytes: buffer };
-  } catch {
-    return null;
-  } finally {
-    await handle.close().catch(() => undefined);
-  }
-}
-
-/**
- * Core keys upload idempotency by `operation_id` and rejects a replay whose
- * fingerprint differs. Deriving it from the file's own identity means a retry
- * after a dropped response resumes the same staging operation instead of
- * creating a second upload; a genuinely different payload maps to a different
- * operation and cannot overwrite the first.
- */
-function fileUploadOperationId(
-  filename: string,
-  inputKind: (typeof INPUT_KINDS)[number],
-  checksum: string,
-): string {
-  const hex = createHash("sha256")
-    .update(JSON.stringify([filename, inputKind, checksum]))
-    .digest("hex");
-  return [
-    hex.slice(0, 8),
-    hex.slice(8, 12),
-    `4${hex.slice(13, 16)}`,
-    `${(8 + (parseInt(hex[16]!, 16) % 4)).toString(16)}${hex.slice(17, 20)}`,
-    hex.slice(20, 32),
-  ].join("-");
-}
-
-export function validateUiWritePlan(value: unknown): UiWritePlan | null {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    return null;
-  }
-  const candidate = value as Record<string, unknown>;
-  if (candidate.schema_version !== 1 || typeof candidate.kind !== "string") {
-    return null;
-  }
-  const { digest, ...withoutDigest } = candidate;
-  if (typeof digest !== "string" || digest !== digestOf(withoutDigest)) {
-    return null;
-  }
-  switch (candidate.kind) {
-    case "call_events_clear":
-      return Array.isArray(candidate.event_ids) &&
-        candidate.event_ids.length >= 1 &&
-        candidate.event_ids.length <= 100 &&
-        new Set(candidate.event_ids).size === candidate.event_ids.length &&
-        candidate.event_ids.every(
-          (id) => typeof id === "string" && UUID.test(id),
-        )
-        ? (candidate as unknown as UiWritePlan)
-        : null;
-    case "call_events_clear_all":
-      return Object.keys(candidate).length === 3
-        ? (candidate as unknown as UiWritePlan)
-        : null;
-    case "import_file_commit":
-    case "import_file_discard":
-      return typeof candidate.upload_id === "string" &&
-        UUID.test(candidate.upload_id) &&
-        Object.keys(candidate).length === 4
-        ? (candidate as unknown as UiWritePlan)
-        : null;
-    case "import_file_upload":
-      return typeof candidate.operation_id === "string" &&
-        UUID.test(candidate.operation_id) &&
-        typeof candidate.path === "string" &&
-        typeof candidate.filename === "string" &&
-        candidate.filename === candidate.path.split(/[/\\]/).pop() &&
-        /^[0-9a-f]{64}$/.test(String(candidate.sha256)) &&
-        INPUT_KINDS.includes(
-          candidate.input_kind as (typeof INPUT_KINDS)[number],
-        ) &&
-        Number.isSafeInteger(candidate.bytes) &&
-        (candidate.bytes as number) >= 0 &&
-        (candidate.bytes as number) <= 128 * 1024 * 1024
-        ? (candidate as unknown as UiWritePlan)
-        : null;
-    default:
-      return null;
-  }
-}
-
-export function uiWriteExitCode(document: UiWriteOutcome): number {
-  return ["preview", "committed", "recovered"].includes(document.state) ? 0 : 1;
-}
-
-export function renderUiWriteText(document: UiWriteOutcome): string {
-  if (document.state === "preview") {
-    return `以下操作尚未执行；加 --confirm 后才会写入：\n${document.plan.kind}\nplan_digest：${document.plan.digest}\n`;
-  }
-  if (document.state === "committed" || document.state === "recovered") {
-    return `已提交：${document.operation_id}\n${JSON.stringify(document.receipt)}\n`;
-  }
-  const code = "code" in document ? document.code : "ui_write_state_invalid";
-  return `操作未完成：${document.state}（${code}）\n`;
-}
-
-export async function executeCallEventsClear(
-  plan: Extract<UiWritePlan, { kind: "call_events_clear" }>,
-  operations: CoreOperations,
-): Promise<UiWriteOutcome> {
-  const result = await operations.post<unknown>("/api/v1/call-events/clear", {
-    event_ids: plan.event_ids,
-    user_confirmed: true,
-  });
-  return outcome(result, plan.event_ids.join(","), ["removed"]);
-}
-
-export async function executeCallEventsClearAll(
-  plan: Extract<UiWritePlan, { kind: "call_events_clear_all" }>,
-  operations: CoreOperations,
-): Promise<UiWriteOutcome> {
-  const result = await operations.post<unknown>(
-    "/api/v1/call-events/clear-all",
-    { user_confirmed: true },
-  );
-  return outcome(result, "all", ["removed"]);
-}
-
-export async function executeImportFileCommit(
-  plan: Extract<UiWritePlan, { kind: "import_file_commit" }>,
-  operations: CoreOperations,
-): Promise<UiWriteOutcome> {
-  const result = await operations.post<unknown>(
-    `/api/v1/import-files/${plan.upload_id}/commit`,
-    { confirmed: true },
-  );
-  return outcome(result, plan.upload_id, [
-    "upload_id",
-    "filename",
-    "vendor",
-    "source_id",
-    "messages",
-    "conversations",
-    "human_messages",
-    "agent_messages",
-    "skipped_records",
-    "ignored_files",
-    "checksum",
-    "created_at",
-    "committed",
-  ]);
-}
-
-export async function executeImportFileDiscard(
-  plan: Extract<UiWritePlan, { kind: "import_file_discard" }>,
-  operations: CoreDeleteOperations,
-): Promise<UiWriteOutcome> {
-  const result = await operations.delete<unknown>(
-    `/api/v1/import-files/${plan.upload_id}`,
-  );
-  // Core answers 204 with no body. A successful delete is a committed
-  // operation even though there is no receipt to validate; requiring a body
-  // here would report every real discard as `ui_write_receipt_invalid`.
-  return outcome(result, plan.upload_id, null);
-}
-
-/** Upload one local file through the same recoverable Core staging flow the
- * Web console uses. The operation id is part of the plan, so a retry after a
- * dropped response resumes the same staging record instead of duplicating it.
- */
-export async function executeImportFileUpload(
-  plan: Extract<UiWritePlan, { kind: "import_file_upload" }>,
-  operations: CoreUploadOperations,
-): Promise<UiWriteOutcome> {
-  // Re-read the file at apply time and re-derive its identity. A plan that
-  // names a path whose content changed after review is refused rather than
-  // uploading something the caller never saw.
-  const reread = await readImportFileUpload(plan.path, plan.input_kind);
-  if (reread === null) {
-    return invalid("import_file_upload_unreadable");
-  }
-  const bytes = reread.bytes;
-  const checksum = createHash("sha256").update(bytes).digest("hex");
-  if (
-    bytes.byteLength !== plan.bytes ||
-    checksum !== plan.sha256 ||
-    reread.plan.digest !== plan.digest
-  ) {
-    return invalid("import_file_upload_content_mismatch");
-  }
-  const result = await operations.uploadImportFile<unknown>({
-    bytes,
-    filename: plan.filename,
-    inputKind: plan.input_kind,
-    operationId: plan.operation_id,
-  });
-  if (result.state === "rejected") {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "rejected",
-      operation_id: plan.operation_id,
-      code: result.code,
-    };
-  }
-  if (result.state === "unknown") {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "unknown",
-      operation_id: plan.operation_id,
-      code: result.code,
-    };
-  }
-  const receipt =
-    result.data !== null &&
-    typeof result.data === "object" &&
-    !Array.isArray(result.data)
-      ? (result.data as Record<string, unknown>)
-      : null;
-  if (
-    receipt === null ||
-    receipt.operation_id !== plan.operation_id ||
-    typeof receipt.state !== "string"
-  ) {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "unknown",
-      operation_id: plan.operation_id,
-      code: "ui_write_receipt_invalid",
-    };
-  }
-  // Core reports the staged upload as `completed`; `pending`/`not_found` here
-  // means the operation record did not settle, so the result is not known.
-  if (receipt.state !== "completed") {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "unknown",
-      operation_id: plan.operation_id,
-      code: `import_upload_${receipt.state}`,
-    };
-  }
-  const uploadId =
-    typeof receipt.upload_id === "string" ? receipt.upload_id : undefined;
-  if (uploadId === undefined || !UUID.test(uploadId)) {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "unknown",
-      operation_id: plan.operation_id,
-      code: "ui_write_receipt_invalid",
-    };
-  }
-  return committed(plan.operation_id, {
-    operation_id: plan.operation_id,
-    upload_id: uploadId,
-    upload_state: receipt.upload_state ?? null,
-  });
-}
-
-function outcome(
-  result:
-    | Awaited<ReturnType<CoreOperations["post"]>>
-    | Awaited<ReturnType<CoreDeleteOperations["delete"]>>,
-  operationId: string,
-  required: readonly string[] | null,
-): UiWriteOutcome {
-  if (result.state === "rejected") {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "rejected",
-      operation_id: operationId,
-      code: result.code,
-    };
-  }
-  if (result.state === "unknown") {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "unknown",
-      operation_id: operationId,
-      code: result.code,
-    };
-  }
-  if (required === null) {
-    return committed(operationId, {});
-  }
-  const data =
-    result.data !== null &&
-    typeof result.data === "object" &&
-    !Array.isArray(result.data)
-      ? (result.data as Record<string, unknown>)
-      : null;
-  if (data === null || required.some((key) => !Object.hasOwn(data, key))) {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "unknown",
-      operation_id: operationId,
-      code: "ui_write_receipt_invalid",
-    };
-  }
-  return committed(operationId, data);
-}
@@ -13,7 +13,16 @@ const GLOBAL_OPTIONS: readonly CommandOption[] = [
    summary: "显示帮助；可与 --json 组合输出机器可读目录。",
  },
  { flag: "--version, -V", summary: "显示 CLI 版本。" },
-  { flag: "--json", summary: "以 JSON 输出到 stdout，供脚本与 Agent 消费。" },
+  {
+    flag: "--json",
+    summary:
+      "以 JSON 输出到 stdout，供脚本与 Agent 消费；结果与失败都在 stdout，只有参数错误写 stderr。",
+  },
+  {
+    flag: "--data-dir <path>",
+    summary:
+      "本次使用的 MemHub 数据目录（绝对路径）；默认 ONE_MEMORY_DATA_DIR > 安装回执 > ~/.one-memory。",
+  },
 ];

 export function renderGeneralHelp(): string {
@@ -33,6 +42,9 @@ export function renderGeneralHelp(): string {
      (exit) => `  ${exit.code}  ${pad(exit.name, 17)}${exit.summary}`,
    ),
    "",
+    "确认约定：只有不可逆操作（memories delete、models remove、delete-data、backup restore、graph-width --decision rebuild_with_new）需要 --yes；不加时只说明将要做什么，不做任何改动，exit 0。delete-data 与 backup restore 还要用 --confirm <path> 再写一遍目标路径。install/upgrade/uninstall/service-install/service-uninstall 不加 --yes 时只出计划。其它写命令直接执行。",
+    "异步操作返回 ID，用对应命令查进度：sources receipt、models receipt、memories add-status、write status。",
+    "目前仅支持 macOS 与 Linux 连接本机 Runtime。",
    "stdout 只输出数据，进度与诊断写入 stderr。",
    `运行 ${PRODUCT} help <command> 查看单个命令的参数。`,
    "",
@@ -55,6 +67,8 @@ export function renderCommandHelp(command: CommandDescriptor): string {
    );
  }
  lines.push(
+    "Global options: --json、--data-dir <path>（见 memhub help）。",
+    "",
    "Exit codes:",
    ...EXIT_CODES.filter((exit) => command.exit_codes.includes(exit.code)).map(
      (exit) => `  ${exit.code}  ${pad(exit.name, 17)}${exit.summary}`,
@@ -0,0 +1,405 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import os, { tmpdir } from "node:os";
+import path from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { run } from "./cli.js";
+
+const transport = vi.hoisted(() => ({
+  get: vi.fn(),
+  post: vi.fn(),
+  put: vi.fn(),
+  patch: vi.fn(),
+  delete: vi.fn(),
+}));
+const direct = vi.hoisted(() => ({ get: vi.fn(), post: vi.fn() }));
+vi.mock("axios", () => ({
+  default: {
+    create: vi.fn(() => transport),
+    get: direct.get,
+    post: direct.post,
+    isAxiosError: () => false,
+  },
+}));
+
+const runtime = vi.hoisted(() => ({
+  inspectRuntimeStatus: vi.fn(),
+  discoverRuntimeAttachment: vi.fn(),
+}));
+vi.mock("@one-memory/runtime-control", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@one-memory/runtime-control")>()),
+  ...runtime,
+}));
+
+const REQUEST = "33333333-3333-4333-8333-333333333333";
+const HERMES = {
+  source_id: "hermes",
+  display_name: "Hermes",
+  storage_kinds: ["sqlite"],
+  available: true,
+  authorized: true,
+  detected: null,
+  root_label: ".hermes",
+  candidate_path: "~/.hermes",
+  candidate_kind: "default",
+  candidate_revision: 0,
+  candidate_root_id: "hermes-root-identity",
+  imported_messages: 0,
+  imported_conversations: 0,
+  capabilities: {
+    historical_import: "implemented",
+    incremental_import: "implemented",
+    live_sync: "implemented",
+    recall: "implemented",
+    installer: "not_implemented",
+    verification: "fixture_only",
+  },
+  sync_completeness: "additions_only",
+  location_state: "found",
+};
+const CODEX = {
+  ...HERMES,
+  source_id: "codex",
+  display_name: "Codex",
+  candidate_root_id: "codex-root-identity",
+};
+
+function addReceipt() {
+  return {
+    evidence_id: "44444444-4444-4444-8444-444444444444",
+    text: "Prefers tea",
+    scope: "all-apps",
+    created_at: "2026-10-27T00:00:00Z",
+    state: "pending",
+    task_id: null,
+    memory_ids: [],
+    error: null,
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  for (const method of [
+    ...Object.values(transport),
+    ...Object.values(direct),
+  ]) {
+    method.mockReset();
+  }
+  runtime.inspectRuntimeStatus.mockResolvedValue({
+    state: "running",
+    code: "runtime_verified",
+    instanceId: "instance-1",
+    host: "127.0.0.1",
+    port: 8765,
+    version: "1.2.3",
+  });
+  runtime.discoverRuntimeAttachment.mockResolvedValue({
+    instanceId: "instance-1",
+    apiToken: "synthetic-runtime-token",
+    host: "127.0.0.1",
+    port: 8765,
+    servicePid: 4242,
+    health: {
+      status: "ok",
+      service: "one-memory-core",
+      version: "1.2.3",
+      instance_id: "instance-1",
+    },
+  });
+  transport.get.mockImplementation(async (url: string) => {
+    if (url === "/api/v1/sources") {
+      return { status: 200, data: [HERMES, CODEX] };
+    }
+    if (url === "/api/v2/user-profile") {
+      return {
+        status: 200,
+        data: { request_id: "r-1", profile: null, elapsed_ms: 1 },
+      };
+    }
+    return { status: 404, data: {} };
+  });
+  transport.post.mockImplementation(
+    async (url: string, body: Record<string, unknown>) =>
+      url === "/api/v1/sources/connect"
+        ? {
+            status: 200,
+            data: {
+              request_id: body.request_id,
+              accepted_source_ids: ["hermes"],
+              failed_sources: {},
+              jobs: [],
+            },
+          }
+        : url === "/api/v2/memories"
+          ? { status: 201, data: addReceipt() }
+          : { status: 404, data: {} },
+  );
+  transport.put.mockResolvedValue({ status: 200, data: {} });
+  transport.delete.mockResolvedValue({ status: 204, data: "" });
+  direct.post.mockResolvedValue({
+    status: 202,
+    data: {
+      request_id: REQUEST,
+      state: "accepted",
+      created_at: "T1",
+      updated_at: "T1",
+    },
+  });
+  direct.get.mockResolvedValue({
+    data: {
+      request_id: REQUEST,
+      state: "accepted",
+      created_at: "T1",
+      updated_at: "T1",
+    },
+  });
+});
+
+describe("--user-id on the memory commands", () => {
+  it("passes the user as a query parameter to memory reads and deletes", async () => {
+    await capturedRun(["memories", "list", "--user-id", "wife", "--json"]);
+    expect(transport.get).toHaveBeenCalledWith("/api/v2/memory-library", {
+      params: { offset: 0, limit: 100, user_id: "wife" },
+    });
+    // Global: the flag may come before the subcommand too.
+    await capturedRun(["memories", "--user-id", "wife", "show", "m-1"]);
+    expect(transport.get).toHaveBeenCalledWith("/api/v2/memories/m-1", {
+      params: { user_id: "wife" },
+    });
+    await capturedRun(["memories", "add-status", REQUEST, "--user-id", "wife"]);
+    expect(transport.get).toHaveBeenCalledWith(
+      `/api/v2/memories/additions/${REQUEST}`,
+      { params: { user_id: "wife" } },
+    );
+    await capturedRun(["profile", "--user-id", "wife", "--json"]);
+    expect(transport.get).toHaveBeenCalledWith("/api/v2/user-profile", {
+      params: { user_id: "wife" },
+    });
+    await capturedRun([
+      "memories",
+      "delete",
+      "fact-1",
+      "--kind",
+      "fact",
+      "--yes",
+      "--user-id",
+      "wife",
+    ]);
+    expect(transport.delete).toHaveBeenCalledWith(
+      "/api/v2/memories/fact-1?kind=fact&user_id=wife",
+      undefined,
+    );
+    await capturedRun([
+      "memories",
+      "delete",
+      "m-1",
+      "--yes",
+      "--user-id",
+      "wife",
+    ]);
+    expect(transport.delete).toHaveBeenCalledWith(
+      "/api/v2/memories/m-1?user_id=wife",
+      undefined,
+    );
+    await capturedRun(["write", "status", REQUEST, "--user-id", "wife"]);
+    expect(direct.get.mock.calls[0][0]).toBe(
+      `http://127.0.0.1:8765/api/v2/memory-writes/${REQUEST}`,
+    );
+    expect(direct.get.mock.calls[0][1].params).toEqual({ user_id: "wife" });
+  });
+
+  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");
+    expect(transport.post.mock.calls[0][1]).toMatchObject({
+      text: "Prefers tea",
+      scope: "all-apps",
+      user_id: "wife",
+    });
+    const directory = await mkdtemp(path.join(tmpdir(), "om-user-id-"));
+    const content = path.join(directory, "content.txt");
+    await writeFile(content, "Prefers green tea\n");
+    await capturedRun([
+      "memories",
+      "update",
+      "m-1",
+      "--content-file",
+      content,
+      "--user-id",
+      "wife",
+    ]);
+    expect(transport.put.mock.calls[0][0]).toBe("/api/v2/memories/m-1");
+    expect(transport.put.mock.calls[0][1]).toMatchObject({ user_id: "wife" });
+    await capturedRun(["recall", "tea", "--user-id", "wife", "--json"]);
+    const search = transport.post.mock.calls.find(
+      ([url]) => url === "/api/v2/context/search",
+    );
+    expect(search?.[1]).toMatchObject({ query: "tea", user_id: "wife" });
+    const messages = path.join(directory, "messages.json");
+    await writeFile(
+      messages,
+      JSON.stringify([{ role: "user", content: "I like tea" }]),
+    );
+    await capturedRun([
+      "write",
+      "submit",
+      "--messages-file",
+      messages,
+      "--session",
+      "s-1",
+      "--user-id",
+      "wife",
+    ]);
+    expect(direct.post.mock.calls[0][0]).toBe(
+      "http://127.0.0.1:8765/api/v2/memory-writes",
+    );
+    expect(direct.post.mock.calls[0][1]).toMatchObject({
+      session_id: "s-1",
+      user_id: "wife",
+    });
+  });
+
+  it("names no user by default or for --user-id local", async () => {
+    for (const extra of [[], ["--user-id", "local"]]) {
+      transport.get.mockClear();
+      transport.post.mockClear();
+      await capturedRun(["memories", "list", ...extra, "--json"]);
+      expect(transport.get).toHaveBeenCalledWith("/api/v2/memory-library", {
+        params: { offset: 0, limit: 100 },
+      });
+      await capturedRun(["profile", ...extra]);
+      expect(transport.get).toHaveBeenCalledWith(
+        "/api/v2/user-profile",
+        undefined,
+      );
+      await capturedRun(["memories", "add", "Prefers tea", ...extra]);
+      expect(transport.post.mock.calls[0][1]).not.toHaveProperty("user_id");
+      await capturedRun(["recall", "tea", ...extra, "--json"]);
+      const search = transport.post.mock.calls.find(
+        ([url]) => url === "/api/v2/context/search",
+      );
+      expect(search?.[1]).not.toHaveProperty("user_id");
+    }
+  });
+
+  it("refuses a malformed user id before contacting Core", async () => {
+    for (const value of ["bad:id", "", "x".repeat(65), "a b", "--json"]) {
+      const result = await capturedRun([
+        "memories",
+        "list",
+        "--user-id",
+        value,
+      ]);
+      expect(result.code).toBe(2);
+    }
+    expect(
+      (await capturedRun(["profile", "--user-id", "a", "--user-id", "b"])).code,
+    ).toBe(2);
+    expect((await capturedRun(["recall", "tea", "--user-id"])).code).toBe(2);
+    expect(transport.get).not.toHaveBeenCalled();
+    expect(transport.post).not.toHaveBeenCalled();
+  });
+});
+
+describe("sources connect for a Hermes profile", () => {
+  it("connects hermes for another user from its own root", async () => {
+    const result = await capturedRun([
+      "sources",
+      "connect",
+      "hermes",
+      "--user-id",
+      "wife",
+      "--root",
+      "~/.hermes/profiles/wife",
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.post).toHaveBeenCalledTimes(1);
+    const [url, body] = transport.post.mock.calls[0];
+    expect(url).toBe("/api/v1/sources/connect");
+    expect(body).toMatchObject({
+      source_ids: ["hermes"],
+      // Core reads the custom root's identity itself.
+      source_roots: {},
+      source_candidate_revisions: {},
+      onboarding: false,
+      user_id: "wife",
+      root: path.join(os.homedir(), ".hermes/profiles/wife"),
+    });
+  });
+
+  it("keeps a plain connect unchanged and accepts --import with a profile", async () => {
+    await capturedRun(["sources", "connect", "hermes", "--import", "--json"]);
+    const plain = transport.post.mock.calls[0][1];
+    expect(plain).not.toHaveProperty("user_id");
+    expect(plain).not.toHaveProperty("root");
+    expect(plain).toMatchObject({
+      source_roots: { hermes: "hermes-root-identity" },
+      onboarding: true,
+    });
+    transport.post.mockClear();
+    const result = await capturedRun([
+      "sources",
+      "connect",
+      "hermes",
+      "--import",
+      "--user-id",
+      "wife",
+      "--root",
+      "/profiles/wife",
+      "--request-id",
+      REQUEST,
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.post.mock.calls[0][1]).toMatchObject({
+      request_id: REQUEST,
+      user_id: "wife",
+      root: "/profiles/wife",
+    });
+  });
+
+  it("refuses --user-id and --root for any source but hermes", async () => {
+    for (const argv of [
+      ["sources", "connect", "codex", "--user-id", "wife"],
+      ["sources", "connect", "codex", "--root", "/somewhere", "--import"],
+      ["sources", "connect", "hermes", "codex", "--user-id", "wife"],
+      ["sources", "connect", "--all-detected", "--user-id", "wife"],
+      ["sources", "connect", "hermes", "--user-id", "bad:id"],
+    ]) {
+      const result = await capturedRun(argv);
+      expect(result.code).toBe(2);
+      expect(result.stderr).toContain("hermes");
+    }
+    expect(transport.post).not.toHaveBeenCalled();
+  });
+});
+
+async function capturedRun(arguments_: string[]) {
+  let stdout = "";
+  let stderr = "";
+  const stdoutSpy = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation((chunk) => {
+      stdout += String(chunk);
+      return true;
+    });
+  const stderrSpy = vi
+    .spyOn(process.stderr, "write")
+    .mockImplementation((chunk) => {
+      stderr += String(chunk);
+      return true;
+    });
+  try {
+    return {
+      code: await run(arguments_, {
+        ONE_MEMORY_DATA_DIR: "/synthetic/data",
+      }),
+      stdout,
+      stderr,
+    };
+  } finally {
+    stdoutSpy.mockRestore();
+    stderrSpy.mockRestore();
+  }
+}
@@ -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.5",
+    "hy-memory==2.0.10",
    # 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",