omdsh-dev · Grivn · Aug 16, 2026 · Aug 16, 2026 · Aug 16, 2026
diff --git a/README.md b/README.md
@@ -16,7 +16,7 @@
 - **Cross-agent sharing**: Mnemon-enabled agents can read and reuse DSH's Mnemon Memory Spaces.
 - **Three cooperating tiers**: Runtime Memory, Project Documents, and Memory Spaces retain information at the right granularity.
 - **Supervised writes**: isolated memory subagents make semantic decisions; the Host enforces paths, permissions, capacity, locks, and revisions.
-- **Native DSH experience**: a Sidebar workbench by default, turn memory, a Save-to-memory dialog, bilingual copy, and global themes.
+- **Web and Headless**: a complete Sidebar workbench for interactive management, plus the same Agent tools, memory context, and cwd routing in one-shot Headless tasks.
 
 Current user instructions, repository files, and live tool results always take precedence over historical memory.
 
@@ -56,15 +56,25 @@ Expand-Archive -Path $archive -DestinationPath $installDir -Force
 
 ### 2. Install the plugin
 
+For the complete Web workbench:
+
 ```sh
 dsh plugin --profile web add dsh-mnemon
 dsh --profile web
 ```
 
+DSH profiles have independent plugin rosters. Install it separately for one-shot Headless tasks:
+
+```sh
+dsh plugin --profile headless add dsh-mnemon
+dsh --profile headless "Check durable project context before answering this task."
+```
+
 Use an absolute path for a local development checkout:
 
 ```sh
 dsh plugin --profile web add "link:/absolute/path/to/dsh-mnemon"
+dsh plugin --profile headless add "link:/absolute/path/to/dsh-mnemon"
 ```
 
 ### 3. Open Memory System
@@ -79,6 +89,8 @@ New installations use `sidebar` by default. Click **Memory System** in the DSH s
 
 See [Getting Started](./docs/en/getting-started.md) for provider requirements and complete verification.
 
+Headless has no workbench or conversation buttons. It still mounts Runtime context, Documents, Memory Space tools, lifecycle guidance, and supervised writes. With `storageScope=workspace`, its memory root follows the invocation directory. Because the process exits as soon as the one-shot Agent becomes idle, delayed background review is cancelled at shutdown; explicit or model-guided writes completed during the task remain durable.
+
 ## One workbench, three memory tiers
 
 | Tier | Best for | How it reaches context |
@@ -180,7 +192,7 @@ pnpm install
 pnpm run verify
 ```
 
-`verify` runs TypeScript checks, Vitest, a reproducible double build, and published-package validation. `lib/` is generated and intentionally not tracked.
+`verify` runs TypeScript checks, Vitest, a reproducible double build, an isolated real Headless-profile activation check, and published-package validation. `lib/` is generated and intentionally not tracked.
 
 ## License
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -16,7 +16,7 @@
 - **跨 Agent 共享**：DSH 的 Mnemon 记忆体可以被其他支持 Mnemon 的 Agent 读取和复用。
 - **三层协作**：运行时记忆、项目档案、记忆体各自保存适合自己的信息粒度。
 - **受监督写入**：语义判断交给隔离的记忆子 Agent，路径、权限、容量、锁与 revision 由 Host 控制。
-- **DSH 原生体验**：默认 Sidebar 工作台、对话内回合记忆、存入记忆弹窗、双语界面与明暗主题。
+- **Web 与 Headless**：Web 提供完整 Sidebar 工作台；一次性 Headless 任务获得同一套 Agent 工具、记忆上下文和 cwd 路由。
 
 当前用户指令、仓库文件与实时工具结果始终高于历史记忆。
 
@@ -56,15 +56,25 @@ Expand-Archive -Path $archive -DestinationPath $installDir -Force
 
 ### 2. 安装插件
 
+完整 Web 工作台：
+
 ```sh
 dsh plugin --profile web add dsh-mnemon
 dsh --profile web
 ```
 
+DSH 各 profile 的插件清单彼此独立；一次性 Headless 任务需要单独安装：
+
+```sh
+dsh plugin --profile headless add dsh-mnemon
+dsh --profile headless "回答前先检查持久化的项目上下文。"
+```
+
 本地开发检出使用绝对路径：
 
 ```sh
 dsh plugin --profile web add "link:/absolute/path/to/dsh-mnemon"
+dsh plugin --profile headless add "link:/absolute/path/to/dsh-mnemon"
 ```
 
 ### 3. 打开记忆系统
@@ -79,6 +89,8 @@ dsh plugin --profile web add "link:/absolute/path/to/dsh-mnemon"
 
 更完整的安装、Provider 要求与验证步骤见[快速开始](./docs/zh-CN/getting-started.md)。
 
+Headless 没有工作台和对话按钮，但仍会挂载运行时上下文、档案、记忆体工具、生命周期提示和受监督写入。`storageScope=workspace` 时，记忆根跟随启动命令所在目录。一次性 Agent 进入 idle 后进程立即退出，因此延迟后台审查会在关闭时取消；任务内已经完成的显式或模型引导写入仍会持久化。
+
 ## 一个工作台，三层记忆
 
 | 层级 | 适合保存 | 如何进入上下文 |
@@ -180,7 +192,7 @@ pnpm install
 pnpm run verify
 ```
 
-`verify` 依次运行 TypeScript 检查、Vitest、两次可复现构建和发布包校验。`lib/` 是生成目录，不再提交到仓库。
+`verify` 依次运行 TypeScript 检查、Vitest、两次可复现构建、隔离的真实 Headless profile 激活检查和发布包校验。`lib/` 是生成目录，不再提交到仓库。
 
 ## License
 

diff --git a/docs/assets/diagrams/en/project-architecture.svg b/docs/assets/diagrams/en/project-architecture.svg
diff --git a/docs/assets/diagrams/zh-CN/project-architecture.svg b/docs/assets/diagrams/zh-CN/project-architecture.svg
diff --git a/docs/en/architecture.md b/docs/en/architecture.md
@@ -36,7 +36,13 @@ settings.register("mnemon")
   -> register RPC when a Web connection exists
 ```
 
-The Host declares dependencies on `tools`, `settings`, `commands`, `agents`, and `subagents`. The Web client additionally depends on slots, connection, and DSH locale services.
+The Host declares dependencies on `tools`, `settings`, `commands`, `agents`, and `subagents`. `workspaceRegistry` is discovered optionally through the Host service registry and is used only for authorized Web inspection. The Web client additionally depends on slots, connection, and DSH locale services.
+
+## Web and Headless Boundaries
+
+The core Host composition is profile-neutral. Both Web and Headless mount settings, Runtime context, Documents, Memory Space tools, lifecycle hooks, and supervised workers. Agent operations always derive `workspace` storage from the session cwd.
+
+Web additionally provides `workspaceRegistry`, client slots, and `connection`. Those services enable cross-workspace inspection, RPC, Sidebar / Buildin, settings UI, Turn memory, and Save to memory. Headless provides none of those browser services; its one-shot runner submits an ordinary user message, waits for Agent idle, flushes the session, prints the final answer, and exits. Plugin disposal cancels a pending delayed review, so Headless relies on explicit or model-guided writes completed inside the task rather than post-idle maintenance.
 
 ## Dual Paths for the Root Agent and Workers
 
@@ -91,7 +97,7 @@ whether a reusable artifact exists  UTF-8 capacity accounting
 
 Persona constraints must be distinguished from hard Host guarantees. For example, the MEMORY archival worker is instructed to cover every committed hot-memory item, but the Host can strictly validate only the structured action, revision, and byte budget; the Host does validate USER compaction source coverage item by item.
 
-## Web Boundary
+## Web RPC Boundary
 
 The WebUI does not start system processes or open SQLite directly:
 

diff --git a/docs/en/configuration.md b/docs/en/configuration.md
@@ -77,6 +77,8 @@ Web workbench inspection: resolve(workspaceRegistry.get(selectedWorkspaceId).pat
 
 Each DSH workspace owns an independent three-tier memory root. Agents, model tools, commands, and lifecycle hooks route by the current session cwd and are unaffected by the Web workbench's inspection target. The workbench can select only Host-registered workspaces, never an arbitrary path. When inspection and execution differ, the header shows both paths and offers one-click alignment with the current session. Agent-backed actions are rejected while misaligned to prevent writes to the wrong project.
 
+Headless has no `workspaceRegistry`; its fresh session cwd is the directory from which `dsh --profile headless ...` was launched, so `workspace` resolves directly to `<invocation cwd>/.mnemon`.
+
 ### `custom`
 
 ```yaml

diff --git a/docs/en/development.md b/docs/en/development.md
@@ -80,10 +80,11 @@ The existing Vitest suites cover:
 - worker tool isolation, the schema subset, and structured receipts;
 - lifecycle cues, scoring, idle debounce, cancellation, and watermark retention;
 - RPC authority, read-only behavior, and settings revisions;
-- the Web workspace, bilingual copy, and key interactions.
+- the Web workspace, bilingual copy, and key interactions;
+- core activation without Web-only services and Agent-cwd routing for Headless;
 - Client/Host source boundaries, deterministic build hashes, package contents, exports, and TypeScript resolution.
 
-These are primarily integration tests using temporary directories, fake runners, and a mock Host. They are not equivalent to automated end-to-end tests of the real DSH + Mnemon WebUI.
+These are primarily integration tests using temporary directories, fake runners, and a mock Host. In addition, `verify:headless` builds the package, installs it into an isolated real DSH Headless profile, serves a local mock model, and asserts that representative Mnemon tools reach the model request. Automated end-to-end testing of the real DSH + Mnemon WebUI remains separate.
 
 ## Real WebUI Verification
 
@@ -175,6 +176,7 @@ When the Web locale changes, the Chinese key set remains the type source of trut
 [ ] confirm the worktree contains no generated lib changes
 [ ] confirm package validation reports only runtime files, declarations, root documents, and cordis.patch.yml
 [ ] install the built/local bundle into an isolated Web profile
+[ ] confirm `verify:headless` activates the built bundle in an isolated Headless profile
 [ ] run real Mnemon CLI and WebUI smoke tests
 [ ] verify Chinese and English workspaces
 [ ] verify global/workspace/custom paths as applicable

diff --git a/docs/en/getting-started.md b/docs/en/getting-started.md
@@ -8,7 +8,7 @@ This guide goes from a blank environment to the first verified recall. It uses S
 
 You need:
 
-- a DSH Web profile that starts successfully;
+- a DSH Web or Headless profile that starts successfully;
 - a locally executable `mnemon` CLI;
 - a DSH subagent provider for isolated memory tasks.
 
@@ -84,7 +84,7 @@ mnemon:
 
 ## 3. Install dsh-mnemon
 
-Install into the Web profile:
+Install into the Web profile for the complete workbench:
 
 ```sh
 dsh plugin --profile web add dsh-mnemon
@@ -111,6 +111,17 @@ dsh plugin --profile web remove dsh-mnemon
 
 Uninstall removes the plugin registration, not memory data in global, workspace, or custom roots.
 
+Profiles have independent plugin rosters. Install the package separately into Headless when one-shot tasks also need memory:
+
+```sh
+dsh plugin --profile headless add dsh-mnemon
+dsh --profile headless "Check durable project context before answering this task."
+```
+
+For a development checkout, replace the package name with `"link:/absolute/path/to/dsh-mnemon"`. Headless mounts the same Runtime context, Documents, Memory Space tools, lifecycle guidance, and supervised write path as a Web Agent. It does not mount the workbench, conversation buttons, RPC channels, or an interactive slash-command surface.
+
+With `storageScope=workspace`, Headless resolves `<invocation cwd>/.mnemon`; no Web workspace registry is required. The one-shot runner exits when its Agent becomes idle, so shutdown cancels any delayed score-based background review that has not started. Explicit or model-guided writes that finish during the task are durable.
+
 ## 4. Choose entry point and storage
 
 Open **Settings → Memory System**:

diff --git a/docs/en/interfaces.md b/docs/en/interfaces.md
@@ -1,4 +1,4 @@
-# WebUI, Tools, Commands, and RPC
+# Web, Headless, Tools, Commands, and RPC
 
 [简体中文](../zh-CN/interfaces.md) | **English** | [Documentation hub](./README.md)
 
@@ -17,6 +17,19 @@ This page is an integration reference. For daily use, start with the [Sidebar an
 
 Sidebar and Buildin are live, mutually exclusive mounts that share functionality, data, and Host services. The two conversation entries can be disabled independently through `mnemon-ui` settings.
 
+## Profile surfaces
+
+| Capability | Web | Headless |
+|---|---:|---:|
+| Runtime context and lifecycle guidance | Yes | Yes |
+| Model tools and supervised subagents | Yes | Yes |
+| Agent-cwd routing for `workspace` scope | Yes | Yes |
+| Sidebar / Buildin / conversation actions | Yes | No |
+| Host-to-client RPC | Yes | No |
+| Delayed score-based review after Agent idle | While the Host remains alive | Cancelled when the one-shot process exits |
+
+Headless receives the full model-tool surface. Its task argument is submitted as an ordinary user message, so it does not provide an interactive slash-command dispatcher. Explicit and model-guided writes that finish before the Agent becomes idle are durable.
+
 ## Model tools
 
 ### Read-only tools
@@ -83,13 +96,15 @@ Both are additive and replace no official DSH rendering. The assistant-message c
 
 ## Workspace routing
 
-Workbench requests carry `sessionId` and an optional `workspaceId`. The Host accepts only IDs registered in `workspaceRegistry`:
+Web workbench requests carry `sessionId` and an optional `workspaceId`. The Host accepts only IDs registered in `workspaceRegistry`:
 
 - deterministic reads and manual maintenance may route to the inspected root selected by `workspaceId`;
 - Agents, tools, commands, and lifecycle hooks still route by the Agent cwd associated with `sessionId`;
 - `status.workspaceContext` returns selected / effective roots and `aligned`;
 - Agent-backed operations are rejected while misaligned.
 
+Profiles without a Web workspace registry, including Headless, have no arbitrary inspection target. Agent execution still routes `workspace` scope directly from the session cwd.
+
 ## RPC channels
 
 RPC is an internal Host-to-client bridge, not a stable external HTTP API.

diff --git a/docs/en/operations.md b/docs/en/operations.md
@@ -133,6 +133,7 @@ Report vulnerabilities privately through [SECURITY.md](../../SECURITY.md), not a
 | Symptom | Check and resolution |
 |---|---|
 | Mnemon unavailable | macOS/Linux: run `command -v mnemon`, `mnemon --version`. Windows PowerShell: run `Get-Command mnemon`, `Test-Path "$env:LOCALAPPDATA\Programs\mnemon\mnemon.exe"`. Set `MNEMON_CLI_PATH` or `mnemon.cliPath`, then restart |
+| Headless Agent has no Mnemon tools | Plugins are profile-local. Run `dsh plugin --profile headless add dsh-mnemon`; a Web-profile installation does not carry over |
 | Memory System missing from sidebar | Check `tabEnabled=true`, `displayMode=sidebar`; Buildin is in the conversation area; for a local link run `pnpm run build`, then restart |
 | Status healthy but recall empty | Check active spaces, storage scope, inspected root, effective session root, and query focus |
 | Header reports misalignment | The workbench is inspecting another workspace; align or keep deliberate read-only inspection; Agent-backed actions are rejected |

diff --git a/docs/en/project-overview.md b/docs/en/project-overview.md
@@ -64,7 +64,7 @@ The default `global` root, `~/.mnemon`, is the simplest choice for several local
 
 ## Architecture
 
-[![dsh-mnemon runtime architecture with DSH Web, Root Agent, supervised control, and three local tiers](../assets/diagrams/en/project-architecture.svg)](../assets/diagrams/en/project-architecture.svg)
+[![dsh-mnemon runtime architecture with DSH Web or Headless, Root Agent, supervised control, and three local tiers](../assets/diagrams/en/project-architecture.svg)](../assets/diagrams/en/project-architecture.svg)
 
 Four boundaries shape the system:
 

diff --git a/docs/zh-CN/architecture.md b/docs/zh-CN/architecture.md
@@ -36,7 +36,13 @@ settings.register("mnemon")
   -> register RPC when a Web connection exists
 ```
 
-Host 声明依赖 `tools`、`settings`、`commands`、`agents` 和 `subagents`。Web client 另外依赖 slots、connection 和 DSH locale 服务。
+Host 声明依赖 `tools`、`settings`、`commands`、`agents` 和 `subagents`。`workspaceRegistry` 通过 Host 服务目录可选发现，只用于 Web 的受权查看。Web client 另外依赖 slots、connection 和 DSH locale 服务。
+
+## Web 与 Headless 边界
+
+核心 Host 组合与 profile 无关。Web 和 Headless 都会挂载设置、运行时上下文、档案、记忆体工具、生命周期钩子和受监督 worker；Agent 操作始终根据 session cwd 解析 `workspace` 存储。
+
+Web 额外提供 `workspaceRegistry`、客户端 slots 和 `connection`，用于跨工作区查看、RPC、Sidebar / Buildin、设置界面、本回合记忆和存入记忆。Headless 不提供这些浏览器服务；一次性 runner 把任务作为普通用户消息提交，等待 Agent idle、flush session、输出最终答案后退出。插件销毁会取消尚未执行的延迟审查，因此 Headless 依赖任务内完成的显式或模型引导写入，而不是 idle 后维护。
 
 ## 主 Agent 与 worker 的双路径
 
@@ -91,7 +97,7 @@ whether a reusable artifact exists  UTF-8 capacity accounting
 
 必须区分“persona 约束”和“Host 硬保证”。例如 MEMORY 归档 worker 被要求覆盖每条已提交热记忆，但 Host 只能硬校验结构化 action、revision 和字节预算；USER 压缩的 source coverage 则由 Host 逐项验证。
 
-## Web 边界
+## Web RPC 边界
 
 WebUI 不启动系统进程，也不直接打开 SQLite：
 

diff --git a/docs/zh-CN/configuration.md b/docs/zh-CN/configuration.md
@@ -77,6 +77,8 @@ Web 工作台查看：resolve(workspaceRegistry.get(selectedWorkspaceId).path, "
 
 每个 DSH 工作区拥有独立的三层记忆根。Agent、模型工具、命令和生命周期按当前会话的 cwd 路由，不受 Web 工作台查看目标影响。工作台只能从 Host 已登记的工作区中选择，不能提交任意路径；查看目标与会话实际目录不一致时，顶部会显示两条路径并提供“一键对齐当前会话”。需要 Agent 子任务的操作在未对齐时会被 Host 拒绝，避免写入错误项目。
 
+Headless 没有 `workspaceRegistry`；其新 session 的 cwd 就是启动 `dsh --profile headless ...` 的目录，因此 `workspace` 直接解析为 `<启动命令 cwd>/.mnemon`。
+
 ### `custom`
 
 ```yaml
-Original file line number
+Diff line change
@@ Expand Up @@
     Each DSH workspace owns an independent three-tier memory root. Agents, model tools, commands, and lifecycle hooks route by the current session cwd and are unaffected by the Web workbench's inspection target. The workbench can select only Host-registered workspaces, never an arbitrary path. When inspection and execution differ, the header shows both paths and offers one-click alignment with the current session. Agent-backed actions are rejected while misaligned to prevent writes to the wrong project.
+    Headless has no `workspaceRegistry`; its fresh session cwd is the directory from which `dsh --profile headless ...` was launched, so `workspace` resolves directly to `<invocation cwd>/.mnemon`.
     ### `custom`
     ```yaml
@@ Expand Down @@