agent-purge 0.2.9 → 0.2.11

package/docs/LEGAL.md

@@ -0,0 +1,27 @@
+# 免责与合规声明
+
+## 许可与适用范围
+
+agent-purge 用于在使用者有权管理的 coding agent 中配置人设和提示词入口。项目采用 [MIT License](../LICENSE)；本说明用于解释用途、风险和使用责任，不替代 LICENSE，也不对 MIT 授权范围附加额外限制。复制、修改或分发软件时，请按 LICENSE 保留必要的版权和许可声明。
+
+## 合法、授权使用
+
+使用者应遵守适用法律法规、宿主软件与模型服务的条款，以及相关第三方授权。请勿将本项目用于未经授权的访问、攻击、数据窃取、隐私侵害或其他违法活动。安装本工具不代表你获得了操作第三方系统、使用他人数据或调用模型服务的授权。
+
+## 配置与模型行为风险
+
+提示词改写可能改变模型输出、工具调用倾向和原有工作流程；严格替换也可能移除可控入口中的原有说明。本项目不保证模型输出正确、安全、合法或适合特定用途，也不替代宿主的权限控制、沙箱、人工审核和安全策略。
+
+用于重要项目之前，请备份配置并在隔离环境测试。执行敏感操作前应自行审核模型输出；恢复遇到冲突时，保留原文件和恢复凭据，不要直接删除备份。
+
+## 数据与网络
+
+人设和配置默认保存在本机，但启用后会随宿主请求发送给其配置的模型服务。更新检查、软件安装和宿主运行可能访问外部网络。请勿在人设中放入不应发送给服务提供方的密钥、个人信息或机密数据；本工具不提供完整的网络隔离或数据防泄漏保障。
+
+## 保证与责任
+
+软件按 LICENSE 约定以“按现状”方式提供，不作其中所列的明示或默示保证。使用者应评估自身使用场景、保管凭据并审核产生的结果。在适用法律允许的范围内，作者与贡献者的保证排除及责任限制以 LICENSE 为准；本说明不排除法律规定不得排除的责任。
+
+## 第三方独立性
+
+本项目是独立开发的工具，与所支持的 coding agent、模型提供商及其关联主体不存在默认的隶属、授权、合作或背书关系。文中的产品名称和标识归相应权利人所有，兼容性说明不代表第三方对本项目作出认可或担保。

package/docs/architecture.md

@@ -0,0 +1,39 @@
+# 架构与界面约定
+
+## 模块边界
+
+- `bin/agent-purge.mjs` 解析 CLI，`web/server.mjs` 提供本地控制 API。
+- 两个入口通过 `lib/apply.mjs` 应用配置，不各自实现不同的安装/暂停语义。
+- `lib/state.mjs` 管理配置，`lib/activation.mjs` 解析最终启用状态。
+- `lib/persist.mjs`、`lib/slashes.mjs`、`lib/shim.mjs`、`lib/project.mjs` 管理不同通道。
+- `lib/footprints.mjs` 和 `lib/restore.mjs` 保留写入所有权与恢复凭据；失败不得抹掉恢复材料。
+- `backends/` 负责宿主启动参数；`lib/capture.mjs` 和 `bench/` 负责请求级验证。
+- 用户数据独立于安装目录。升级程序不得覆盖人设和状态。
+
+## 产品约定
+
+Web 是配置台，不是内嵌交互终端。默认启动项、通道范围、表单草稿与已保存状态分别显示。
+
+配置写入、历史测试和当前会话实际生效必须区分：
+
+- 已加载动态插件下一轮读取；静态入口需要新会话。
+- 插件首次安装或代码更新需要重新加载宿主。
+- 失败逐项显示，保留草稿并允许重试。
+- 暂停保留通道选择；撤销与删除用户数据必须明确区分。
+
+## UI 基础
+
+原生 HTML/CSS/JavaScript，不引入前端框架或外部字体。
+
+| 用途 | 约定 |
+|---|---|
+| 页面 / 表面 | `#f6f7f9` / `#ffffff` |
+| 正文 / 次级文字 | `#101828` / `#344054` / `#5d6b81` |
+| 操作色 | `#2459cf`，hover `#1d4ab2` |
+| 状态色 | 成功 `#067647`、警告 `#93370d`、错误 `#b42318`；始终附文字 |
+| 字体 | 系统中文字体；正文 14px、标题 22px；路径用等宽字体 |
+| 间距 / 圆角 | 4/8px 体系；6/8/12px 圆角 |
+
+控制台、人设库、验证与诊断共享导航。一次只展开一个执行器详情，避免将所有技术路径铺在首页。
+
+新界面应具备可见焦点、键盘可达、清晰错误、减少动态效果支持；验证 1440/768/390/320px，无页面横向溢出。刷新不得覆盖未保存编辑，离开脏表单需确认。

package/docs/compatibility.md

@@ -0,0 +1,78 @@
+# 兼容性与已知限制
+
+[返回项目首页](../README.md)
+
+以下是 **2026-11-01 的本地验收快照**，只适用于列出的版本；不代表所有宿主版本或远端发行包均通过。
+
+## 宿主请求验证
+
+真实宿主进程使用隔离 HOME、配置与本地测试 provider，不继承生产凭据。九个宿主的 `off / strict / replace / append` 共 36 次主请求均完成捕获，进程退出码为 0。
+
+| 执行器 | 实测版本 | 实际角色 | off → strict 字符数 | 同会话热切 |
+|---|---|---|---|---|
+| pi | 1.4.0 | system | 2,845 → 111 | 通过 |
+| omp | 18.14.1 | system | 10,588 → 568 | 通过（扩展入口） |
+| codex | 0.166.0 | developer | 20,745 → 3,685 | 未验证；启动参数入口 |
+| claude | 2.1.316 | system | 27,237 → 254 | 未验证；启动参数入口 |
+| codebuddy | 2.179.0 | system | 17,261 → 119 | 未验证；启动参数入口 |
+| grok | 1.0.73 | system | 5,121 → 113 | 未验证；启动参数入口 |
+| opencode | 1.19.5 | system | 10,992 → 117 | 通过 |
+| opencode2 | 2.2.5 | system | 10,052 → 118 | 通过 |
+| dsh | 0.2.1-rc.5 | system | 2,729 → 112 | 通过（SDK 同会话；headless/web/desktop 三形态四模式已抓） |
+
+热切保持同一进程和会话，执行 A → B → strict → off，检查旧人设残留和工具定义。字符数用于描述一次请求，不是质量评分。
+
+- Claude 的 strict 仍含固定身份句；Codex 和 OMP 仍有额外运行说明。`strict` 仅替换可控入口。
+- DSH 的 replace 曾漏掉包含 `{{model}}` 的身份模板行，工作区已补回归；身份行匹配仍不是完整语义识别。
+- DSH 三形态已于 2026-11-02 补测（`0.2.1-rc.5`，本地 loopback provider）：headless 用 CLI，web 用 `dsh web`，desktop 用 `DeepSeek Harness.exe`；三形态各 `off / strict / replace / append` 四模式，共 12 次主请求均在 system 层捕获，marker 命中 1（off 为 0），user 层 0。见 `out/capture/dsh-surfaces-2026-11-01T18-05-22-727Z/report.json`。desktop 的 strict 仍含宿主注入的约 11.4K `billion-context` 系统提醒，因此 strict 不是纯人设。
+- Hermes、zcode、antigravity 未找到入口，不计成功。
+- `opencode`（`opencode-ai` 1.x）与 `opencode2`（`@opencode/cli` 2.x）是不同接口，不能混用插件。
+- 不支持注入的闭源桌面入口不会标为注入成功；有些只能原样启动，有些会明确拒绝。
+
+## 系统、浏览器与发行形式
+
+| 项目 | 已执行 | 尚不能据此承诺 |
+|---|---|---|
+| Windows 11 x64 | Node 20.20.2 / 22.23.4 / 24.13.1 回归 | 所有 Windows/CPU 版本 |
+| Ubuntu 24.04 WSL2 x64 | Node 20.20.2 / 22.23.4 / 24.13.1 回归 | 原生 Linux 桌面及其他发行版 |
+| Web | Edge 156、Firefox 157、WebKit 27.2 共 21 项；320/390/768/1440px | macOS/Safari 系统集成、完整人工无障碍认证 |
+| npm | Windows 与 Linux 实际 tarball 离线安装、CLI/Web | 未测的包管理器和受限企业环境 |
+| Windows ZIP / 独立 EXE | 解压后运行；独立 EXE 在无 Node 的 PATH 下运行 | 全新操作系统或已签名发行 |
+| Windows 安装器 | 临时目录连续三轮安装、重装、原生启动器、冲突阻止卸载及数据保留 | 干净 VM、跨版本升级、所有目录 |
+| macOS | 已配置 CI 矩阵 | 本轮没有 macOS 实机或远端运行证据 |
+
+Linux 上的 Windows 参数桥接测试明确跳过。CI 矩阵定义不等于远端执行成功，必须核对对应提交。
+
+## 已知发布限制
+
+- **覆盖安装存在环境相关失败**：工作区所在 H 盘出现两次卸载日志文件占用，重装退出码为 4；系统临时目录连续通过，但占用者与根因尚未确认。不要把“重跑通过”视为问题已修复。
+- 当前本地 Windows 产物未签名。SHA-256 只用于核对字节，不等于发布者签名。
+- 干净 Windows、macOS、跨版本升级和 Release 上传后重新下载核对仍需完成。
+- 不保证提示词改写后的模型表现；请求角色、人设命中与模型行为是三件事。
+
+## 验证状态与第三方中转
+
+Web 的“隔离验证”使用临时 HOME、测试人设和本地 provider。DSH 的 headless/web/desktop 三形态四模式已分别抓包，同会话热切使用 SDK 验证；隔离抓包仍不能替代用户正在运行的会话，也不能证明第三方中转完整转发了提示词。
+
+- **未捕获请求**：没有足够请求证据，不能判定人设未命中。
+- **验证出错**：进程退出失败或超时，保留错误原因与隔离进程输出。
+- **请求未命中**：确实捕获到主请求，但 system/developer 未出现测试人设。
+- **隔离测试命中**：相应测试入口成功传递了测试人设，不等于模型会服从，也不代表当前会话。
+- **暂停验证通过**：off 模式没有残留测试人设，不应显示为“未命中”。
+
+2026-11-02 排查发现：DSH 单模式验证原先缺少首次 profile 初始化，四模式测试中先运行 off 恰好掩盖了该缺陷；工作区现已修复，并将辅助标题请求与主请求分开判定。
+
+第三方中转需要另行验证 **宿主 → 中转 → 上游模型**。应使用不含私密数据的测试标记，核对两端实际请求字段；仅比较“你是谁”的回答，不能判断 system 是否被删除。改变人设提示词也不能保证修复中转的协议转换或服务端过滤。
+
+## 复现
+
+```bash
+npm test
+npm run test:package
+npm run test:ui
+node bench/capture-system.mjs --hot --no-publish
+```
+
+真实宿主测试需先安装相应宿主。原始请求和日志进入被 Git 忽略的 `out/`；`--no-publish` 不替换用户已有 Web 验证报告。HTTP 代理隔离不等于操作系统网络沙箱。
+
+版本表只保留便于维护的结论；原始诊断、截图迭代和逐文件哈希不进入源码仓库。每次发布的证据应随对应 CI artifact 保存，见[发布流程](releasing.md)。

package/docs/releasing.md

@@ -0,0 +1,87 @@
+# 发布流程
+
+构建和检查不会提交代码、推送、打标签、发布 npm 或创建 GitHub Release。`release-check` 只上传 Actions artifact。
+
+## 发布前检查
+
+```bash
+npm ci --ignore-scripts
+npm run check:repo
+npm test
+npm run test:package
+npx playwright install chromium firefox webkit
+npm run test:ui
+```
+
+同时审核[兼容性与已知限制](compatibility.md)。原始测试输出放在 `out/`，不要提交截图过程稿、缓存、私人配置或测试安装目录。
+
+## Windows 构建
+
+构建机需要 Node.js 20+、Bun、GCC/windres 和 Inno Setup 6。当前 CI 固定 Bun 1.4.4；每次发布记录实际工具链版本。
+
+```bash
+npm run build:setup
+npm run build:exe
+npm run test:artifacts
+npm run release:checksums
+```
+
+| 文件 | 内容 |
+|---|---|
+| `dist/agent-purge-<版本>.zip` | Node 薄包及图形启动器，需要外部 Node |
+| `dist/agent-purge-<版本>-setup.exe` | 薄包安装器，需要外部 Node |
+| `dist/agent-purge.exe` | 内含运行时的独立 Windows EXE |
+| `dist/SHA256SUMS.txt` | 最终三个产物的校验值 |
+
+ZIP 里的 `agent-purge.exe` 是薄启动器，**不是**独立 EXE。安装器构建会校验薄包的 manifest 与当前源码，不能复用旧目录或混装产品。
+
+## 安装验收
+
+`scripts/check-installer.ps1` 默认只接受临时 Windows Actions runner。本机验收需要明确使用：
+
+```powershell
+./scripts/check-installer.ps1 -AllowLocalMachine
+```
+
+脚本会先检查是否已有安装记录、桌面快捷方式或开始菜单组，存在则拒绝改动。测试使用系统临时目录、独立 HOME 和专属数据，执行：
+
+1. 缺少 Node 时拒绝安装且不挂起。
+2. 中文/空格路径的安装、CLI 应用、同版本重装。
+3. 通过实际原生启动器访问 Web 和静态资源。
+4. 恢复冲突时停止卸载并保留凭据。
+5. 修复后卸载，核对人设与原配置字节、注册表和快捷方式。
+
+本机隔离测试不等于全新系统。发布前还需检查低版本 Node、GUI 提示、SmartScreen、跨版本升级、权限不足和[已知覆盖安装问题](compatibility.md#已知发布限制)。
+
+## CI
+
+- `test.yml`：Windows / Ubuntu / macOS × Node 20 / 22 / 24，tarball 安装，以及三浏览器 UI 检查。
+- `release-check.yml`：Windows 构建、ZIP/EXE、安装卸载、校验值和候选包 artifact。
+- `release.yml`：版本 tag 或手动触发的正式发布流程；先跑完整测试与打包，再发布 npm 和 GitHub Release。
+- Actions 固定到 commit SHA；构建任务只读，只有 publish job 获得 `contents: write` 和 `id-token: write`。
+- 本地未提交改动不在远端历史绿色记录覆盖范围内，必须在最终提交上重新运行。
+
+## 正式发行
+
+`release.yml` 是唯一的自动发布入口；`release-check.yml` 仍然只产出候选 artifact，不会发布。发布前确认：
+
+1. `package.json` 版本与 tag 一致（例如 `0.2.11` 对应 `v0.2.11`）。
+2. GitHub 仓库 secret `NPM_TOKEN` 是 npm automation/granular token，具备 `agent-purge` 的 publish 权限；不要提交到 `.npmrc` 或源码。
+3. 版本、变更、许可和兼容性说明已审核；工作区干净。
+
+发布方式：
+
+```bash
+git tag v0.2.11
+git push origin v0.2.11
+```
+
+tag 推送会触发 `release.yml`：
+
+1. `verify`：Node 24 上 `npm ci`、`check:repo`、全部测试、`test:package`。
+2. `build`：Windows 上构建 ZIP/EXE/setup，跑安装验收和校验和，把三个产物及 `SHA256SUMS.txt`、manifest、npm tarball 上传为 Actions artifact。
+3. `publish`：校验 tag 与版本一致；`npm publish --provenance`（已存在的同版本会跳过）；创建 GitHub Release 并上传附件。
+
+需要重跑时使用 Actions 的 `workflow_dispatch`，输入已存在的 tag；发布是幂等的，不会重复上传同版本 npm 包，Release 附件使用 `--clobber` 覆盖。
+
+正式发行前核对 [LICENSE](../LICENSE)、README 和[免责与合规声明](LEGAL.md)的表述。软件继续采用 MIT 许可；使用声明用于说明风险与责任，不附加相冲突的授权限制。修改声明时应同步 README 中的完整文本。

package/docs/usage.md

@@ -0,0 +1,158 @@
+# 使用指南
+
+[返回项目首页](../README.md)
+
+## 选择人设
+
+运行 `agent-purge web` 打开本地控制台，在「人设库」编辑中性模板或新建人设，再回「控制台」应用。
+
+```bash
+agent-purge ls
+agent-purge use <id>
+agent-purge mode append
+agent-purge sync
+```
+
+CLI 和 Web 共用状态。切换人设、模式或编辑当前正文时，会同步已选择的通道；失败项可在「验证与诊断」查看和重试。
+
+默认执行器只决定裸敲 `agent-purge` 时启动谁，**不决定应用范围**。要让其他入口也读取人设，需要选择对应通道。
+
+### 人设文件
+
+默认目录为 `~/.agent-purge/personas/`，每份人设是 `<id>.md`：
+
+```markdown
+---
+id: concise
+name: 简洁协作
+description: 中文、先结论、修改前先读代码
+harness: ["*"]
+model: ["*"]
+order: 10
+---
+
+用简体中文协作。先给结论，再给依据。
+修改代码前先阅读现有实现；不确定时明确说明。
+```
+
+只有正文进入提示词。`description` 用于列表说明，旧键 `desc` 仍兼容；Web 编辑会保留表单未涉及的元数据。`active` 是内部保留标识，请勿用作人设名。
+
+### 为一家执行器单独配置
+
+```bash
+agent-purge use concise --for codex
+agent-purge mode append --for codex
+agent-purge use follow --for codex
+agent-purge mode follow --for codex
+```
+
+`follow` 取消该字段的例外配置。全局暂停优先于分家模式，恢复时仍保留原选择。
+
+## 处理模式
+
+| 模式 | 行为 | 注意 |
+|---|---|---|
+| `replace` | 在可读取的宿主文本中近似移除身份行，再放入人设 | 没有宿主文本读取口的启动入口按 `strict` 处理 |
+| `strict` | 替换可控入口里的宿主文本 | 该入口原有说明也会移除；宿主仍可能另加文本 |
+| `append` | 保留宿主说明并追加人设 | 可能出现相互矛盾的身份说明 |
+| `off` | 停止当前入口注入 | 全局暂停与单次启动参数的范围不同 |
+
+`codex / claude / grok / codebuddy / hermes` 的 CLI 启动入口没有宿主文本读取口，`replace` 按 `strict` 执行，并在终端提示。希望保留宿主说明时可选择 `append`。
+
+CLI 的 `append` 将人设放在后面；[magpie 插件](../magpie-plugin/README.md)放在前面。实际角色可能是 `system`、`developer` 或项目上下文，详见[兼容性](compatibility.md)。
+
+## 单次启动
+
+```bash
+agent-purge codex
+agent-purge pi --persona concise
+agent-purge codex --mode append
+agent-purge pi --ask "解释这段代码"
+agent-purge codex --dry-run
+agent-purge codex -- --help
+```
+
+`--` 后的参数交给宿主，不再由 agent-purge 解析。`--dry-run` 展示启动命令，不启动宿主。
+
+`--mode off` 只影响本次启动，不撤销已经安装到磁盘的其他通道；若与常驻或项目内容冲突，先执行 `agent-purge pause`，不要把单次 off 当成全量卸载。
+
+## 常驻与项目通道
+
+| 通道 | 做什么 | 何时读取 |
+|---|---|---|
+| `install` | 写入宿主的托管配置或插件 | 静态配置需新会话；动态插件加载后下一轮 |
+| `shim` | 在 PATH 前面放同名命令，转发给 agent-purge | 下一次从该命令启动 |
+| `slash` | 安装会话内 `/purge` 扩展 | pi / omp / dsh 加载扩展后使用 |
+| `project` | 在指定项目规则文件中写入托管块 | 对应目录的新会话 |
+
+```bash
+agent-purge install codex
+agent-purge arm pi --slash
+agent-purge arm codex --shim
+agent-purge arm pi
+agent-purge status
+```
+
+`arm <h>` 尝试开启该执行器的常驻、命令和 slash 通道，结果逐项报告；不是每个执行器都支持全部通道。首次安装或更新插件代码后需重新加载宿主。Linux/macOS 的 shim 目录需要按命令提示加入 shell 的 PATH。
+
+DSH 只写入它已初始化的 profile，不凭空创建 desktop/web/headless 配置。其 slash 插件只是开关，注入还需要常驻插件；实际处理的 profile 会在命令结果中列出。
+
+### 项目规则
+
+```bash
+agent-purge project on pi --dir /path/to/project
+agent-purge project status --dir /path/to/project
+agent-purge project off --dir /path/to/project
+```
+
+目录以绝对路径登记。后续同步只处理已登记的目录，不跟着当前工作目录漂移；暂停保留登记，恢复后按原范围应用。
+
+项目通道不提供每个文件夹独立的人设；仍跟随全局或分家配置。其他执行器可能也读取同名 `AGENTS.md` / `CLAUDE.md`，同时开启项目与全局入口可能重复提供人设。
+
+## 暂停、撤销和卸载
+
+| 目的 | 命令 | 人设数据 |
+|---|---|---|
+| 临时暂停 / 恢复原范围 | `agent-purge pause` / `agent-purge resume` | 保留 |
+| 只撤销常驻通道 | `agent-purge uninstall dsh` | 保留；slash 和 shim 不受影响 |
+| 撤销一家已选的全部通道 | `agent-purge disarm dsh` | 保留 |
+| 撤销全部登记的接管 | `agent-purge clean` | 保留 |
+| 卸载 npm 程序 | 先 `agent-purge clean`，再 `npm uninstall -g agent-purge` | 保留 |
+| 永久删除用户数据 | `agent-purge self-uninstall --yes` | **删除，先备份** |
+
+`self-uninstall --dry-run` 只预览。不传 `--yes` 不会永久删除。
+
+Windows 安装器卸载会先撤销接管，再移除程序；恢复冲突时停止卸载并保留凭据。ZIP / 独立 EXE 也应先 `clean` 再删除程序。外部编辑会保留，旧版或被修改的 DSH 插件可能改名为 `.disabled-by-agent-purge*`；核对后再自行处理。
+
+`arm --all` / `disarm --all` 会同时操作总电源和执行器通道。只需临时停用时用 `pause`，不要全量卸载。历史会话中已经发送的内容不会被撤回。
+
+## 数据与隐私
+
+用户数据与程序分开保存，默认位置：
+
+- Windows：`C:\Users\<用户>\.agent-purge\`
+- Linux/macOS：`~/.agent-purge/`
+
+其中包括人设、`state.json` 和恢复凭据。升级不会用发行包覆盖这份目录。需要改位置时：
+
+```bash
+export AGENT_PURGE_HOME=/path/to/ap-data
+```
+
+```powershell
+$env:AGENT_PURGE_HOME = 'D:\ap-data'
+```
+
+PowerShell 赋值仅影响当前会话；`setx` 影响之后新开的进程。旧版包目录中的数据会在首次运行时尝试迁移，原件保留。
+
+配置和提示词改写在本地执行，更新检查会访问 GitHub。启用后，人设会随宿主请求发送给其配置的模型服务；agent-purge 不提供网络隔离。Web 仅监听 `127.0.0.1`，不要直接暴露到公网。
+
+## 常见问题
+
+- **保存后没效果**：执行 `agent-purge status`，检查人设、模式和通道；新建会话或重新加载插件。配置写入成功不是当前会话的请求证据。
+- **暂停后仍有旧内容**：已有历史不会清除；检查是否仍在旧会话，或另有独立提示词插件。
+- **恢复冲突**：保留报错指出的原文件和恢复材料，比较修改后再合并，不要直接删除备份。
+- **Windows 提示缺 Node**：薄包和安装器需要 PATH 中的 Node 20+；独立 `agent-purge.exe` 自带运行时。
+- **SSH / WSL 无桌面**：使用 `agent-purge web --no-open`，按终端地址访问；默认端口为 `7788`。
+- **更新显示无公开 Release**：不代表 npm 已是最新版。npm 安装用 `npm outdated -g agent-purge` 检查版本。
+- **换模型或中转后人设表现不同**：先区分“请求是否包含人设”和“模型是否遵循人设”。Web 的隔离验证不测试你的真实中转；需要核对中转前后的 system/developer 字段。不要把 API Key 或完整私密人设贴进公开 issue，见[验证范围](compatibility.md#验证状态与第三方中转)。

package/lib/activation.mjs

@@ -0,0 +1,38 @@
+// 配置值与执行许可分开：暂停不擦掉选择，环境变量本身不授予许可。
+export function resolveConfigured(state, id) {
+	const modes = ["strict", "replace", "append", "off"];
+	const override = state?.overrides?.[id] ?? {};
+	const hasPersona = typeof override.persona === "string" && override.persona !== "";
+	const hasMode = modes.includes(override.mode);
+	return {
+		persona: hasPersona ? override.persona : state?.persona ?? null,
+		mode: hasMode ? override.mode : state?.default?.mode ?? "replace",
+		personaFrom: hasPersona ? "override" : "global", modeFrom: hasMode ? "override" : "global",
+	};
+}
+
+/** launch 只能由通过进程归属核验的调用方传入 true，绝不直接来自 FORCE/token。 */
+export function resolveActivation(state, id, context = {}) {
+	const configured = resolveConfigured(state, id);
+	const mode = context.mode ?? configured.mode;
+	const result = { ...configured, persona: context.persona ?? configured.persona, configuredMode: configured.mode, mode, on: false, source: null, blockedBy: null };
+	const stop = reason => ({ ...result, mode: "off", blockedBy: reason });
+	if (!state || typeof state !== "object" || Array.isArray(state)) return stop("missing-state");
+	if (state.default?.mode === "off") return stop("global-pause");
+	if (state.overrides?.[id]?.mode === "off") return stop("harness-off");
+	if (Array.isArray(state.disabledHarnesses) && state.disabledHarnesses.includes(id)) return stop("harness-disabled");
+	if (context.session === false || context.enabled === false) return stop("session-off");
+	if (context.profile && Array.isArray(state.dshProfiles) && !state.dshProfiles.includes(context.profile)) return stop("profile-off");
+	if (!["strict", "replace", "append"].includes(mode)) return stop(mode === "off" ? "mode-off" : "invalid-mode");
+	const channels = Array.isArray(state.armed?.[id]) ? state.armed[id] : [];
+	let source = null;
+	if (context.launch === true) source = "explicit-launch";
+	else if (context.channel === "install" && channels.includes("install")) source = "resident";
+	else if (context.channel === "slash" && channels.includes("slash")) {
+		if (context.session === true) source = "session-command";
+		else if (state[id + "Auto"] === true) source = "auto";
+	}
+	return source ? { ...result, on: true, source } : stop("not-enabled");
+}
+
+export const activationRuntime = [resolveConfigured, resolveActivation].map(fn => fn.toString()).join("\n") + "\nconst resolveCfg = resolveConfigured;\n";