work-ally 0.2.0-alpha.1

package/docs/planning/SPEC-assistant-rename.md

@@ -0,0 +1,610 @@
+# SPEC: Assistant 改名
+
+更新时间：2026-03-18  
+状态：Implemented / Pending acceptance  
+Owner：work-ally product / engineering  
+相关文档：
+- `docs/product-spec-standard.md`
+- `docs/planning/SPEC-codex-same-machine-session-handoff.md`
+- `README.md`
+- `docs/user-quickstart.md`
+- `docs/ops-runbook.md`
+
+## 1. Summary
+
+这份 spec 为 `work-ally` 增加一条正式的 assistant 改名能力：
+
+> 用户可以把一个已经存在的 assistant 从旧名字改成新名字，同时保留同一个 assistant desk、同一份记忆和历史、同一组项目绑定、同一批 runtime / handoff 资产。
+
+这不是“新建一个 assistant 再人工搬东西”，也不是“让用户自己改几处文件名”。当前 assistant name 已经是系统级 key，贯穿 registry、desk 路径、`.system/config.env`、runtime state、global lock、work session / same-machine handoff 持久化，以及 desktop read model。rename 的本质是一笔受控迁移。
+
+V1 只提供 CLI 正式入口：`./ally.sh assistant rename <old> <new>`。rename 只能在安全前提满足时执行；不安全时必须明确拒绝。rename 成功后，旧名字不再是正式控制入口，也不提供 alias 兼容。
+
+这份 spec 同时收口一个关键边界：**系统管理的结构化身份要 clean migration；用户自己写下的自由文本不承诺被静默全局改写。**
+
+## 2. 背景
+
+当前仓库已经支持 assistant 的创建、绑定、运行、停止、查看和删除，但没有 rename。
+
+现状里 assistant 名字并不是 display label，而是以下结构的共同锚点：
+
+- `~/.work-ally/assistants/<name>/` desk 根目录
+- `assistants/registry.yaml` 的顶层键
+- `projects/registry.yaml` 中的 `assistant: <name>`
+- `~/.work-ally/assistants/<name>/.system/config.env` 中的 `WORK_ALLY_ASSISTANT_NAME` 及相关 assistant path 字段
+- `~/.work-ally/assistants/<name>/.system/runtime/assistant.env`
+- `~/.work-ally/locks/assistant-<name>.lock`
+- `~/.work-ally/assistants/<name>/.system/runtime/work-sessions/` 下的 assistant index 与 `meta.json` 中的 `assistantName` / `assistantCodexHome`
+- same-machine handoff 导出的 payload 里的 `assistantName`
+- desktop backend / tauri snapshot 中的 assistant `id` / `name` / project `assistant_names`
+
+因此，用户今天如果想把 `allen` 改成 `ramond`，并不存在一条官方、安全、可验证的路径。手工修改会同时暴露这些风险：
+
+- registry 改了，但 desk 路径没改
+- desk 路径改了，但 `.system/config.env` / `assistant.env` / lock 仍指向旧名字
+- shell 层看似能用，work session / handoff 还挂着旧 assistantName
+- desktop 刷新后还显示旧名字或 ghost record
+- 用户长期资产里哪些该改、哪些不该改，没有明确边界
+
+这说明 assistant rename 不是小修文案，而是需要先拍板合同的系统级 feature。
+
+## 3. 问题定义
+
+本专题要解决 6 个问题。
+
+### 3.1 用户没有正式的 rename 主路径
+
+当前用户只能创建新 assistant 或删除旧 assistant，不能把“同一个 assistant”换名字。对真实使用来说，这会直接导致身份割裂：名字起错了，只能重建。
+
+### 3.2 当前名字耦合得太深，手工修改不可信
+
+assistant 名字今天同时承担产品名、CLI 句柄、registry 主键、desk 路径名、runtime 锁键、handoff / work-session 索引键、desktop 控制键。任何“改一两处就行”的认知都不成立。
+
+### 3.3 系统缺少对 rename 安全边界的定义
+
+没有 spec 时，rename 很容易被做成危险补丁：
+
+- assistant 运行中也允许改
+- target 已存在时靠覆盖或猜测继续
+- 迁移中途失败后不回滚
+- 用户自由文本被静默全局替换
+
+这些都不可接受。
+
+### 3.4 assistant 的“系统身份”和“用户写过的文字”边界没有讲清
+
+`SOUL.md`、`NOW.md`、`MEMORY.md`、`journal/`、`conversations/` 等长期资产里可能出现旧名字；其中有些是系统模板生成的，有些是用户自己写的。rename 如果不先定义自动改写边界，就无法做到既安全又可预期。
+
+### 3.5 `.system/config.env` 与 runtime state 会放大脏状态
+
+当前 desktop 会直接读取 `.system/config.env` 作为本地输入来源；runtime / global tooling 会读取 `assistant.env`、lock、runtime dir。rename 如果只改 registry 和路径，不同步这些受管理状态，系统会出现“名字看似改了，但控制和本地输入还挂在旧 assistant 下”的错位。
+
+### 3.6 same-machine handoff / work session 会在 rename 后残留旧 owner
+
+bridge 当前已经持久化 work session，对象里直接存 `assistantName` 与 `assistantCodexHome`，assistant index 文件名也按名字生成。rename 如果不迁移这层，后续 handoff export / attach、active work session 解析、ownership 判定都会残留旧名字。
+
+## 4. 目标 / 非目标
+
+### 4.1 目标
+
+1. 提供正式命令 `./ally.sh assistant rename <old> <new>`。
+2. rename 成功后，系统认定这仍是同一个 assistant，而不是新的 assistant 身份。
+3. assistant registry、project registry、desk 路径、`.system/config.env`、runtime `assistant.env`、global lock、work session / same-machine handoff 持久化、desktop read model 都迁移到新名字。
+4. rename 只在安全前提满足时成功；不安全时稳定拒绝。
+5. 如果 rename 过程中的某一步失败，系统要么完整回滚到旧状态，要么明确报出 rollback 失败，不允许静默留下半迁移状态。
+6. 明确自动改写边界：系统管理字段与受管理模板引用必须更新；用户自由文本不承诺全量自动改名。
+7. 补齐 rename 的 shell / unit / 必要 desktop 验证与用户文档。
+
+### 4.2 非目标
+
+1. 不在 V1 引入新的持久对象，例如独立 `assistant_id`。
+2. 不在 V1 支持 display name / alias 与系统 key 并存。
+3. 不在 V1 提供 desktop GUI rename 按钮。
+4. 不支持 assistant 正在运行、被活锁占用、或被外部 surface 持有时 rename。
+5. 不对 `MEMORY.md`、`NOW.md`、`MISTAKES.md`、`journal/`、`conversations/`、`.system/archive/` 里的任意旧名字做全局搜索替换。
+6. 不负责把旧名字作为兼容命令继续保留。
+7. 不迁移 channel lock key；channel lock 与 app id 绑定，不与 assistant name 绑定。
+
+## 5. 产品定义与用户路径
+
+### 5.1 一句话定义
+
+assistant rename 是一笔针对既有 assistant 身份的**受控迁移**：把旧名字下的系统结构切换到新名字，同时保留同一个 assistant 的历史和绑定。
+
+### 5.2 正式入口
+
+V1 唯一正式入口：
+
+```bash
+./ally.sh assistant rename <old> <new>
+```
+
+成功时返回至少包含：
+
+- `old_name`
+- `new_name`
+- `assistant_home`
+- `codex_home`
+- `workspace`
+- 如有必要，附带 warnings
+
+### 5.3 主路径
+
+用户场景：已经有一个 assistant，例如 `allen`，但不满意这个名字，希望改成 `ramond`，同时保留原 desk、Git 历史、绑定项目和 handoff / runtime 资产。
+
+主路径：
+
+1. 用户执行 `./ally.sh assistant rename allen ramond`。
+2. 系统校验 source assistant 存在、target 名字符合规则且未被占用。
+3. 系统确认 assistant 当前不在运行，也不存在活锁或被外部 surface 持有的 busy 状态。
+4. 系统校验 source assistant 仍处于 canonical 可迁移状态。
+5. 系统在 staging / backup 保护下完成迁移。
+6. 系统输出 rename 成功结果。
+7. 后续 `assistant list/show/status/start/stop/logs`、`global list/stop --assistant`、desktop snapshot、same-machine handoff、project binding 都只认新名字。
+
+### 5.4 拒绝路径
+
+以下情况必须明确拒绝：
+
+1. source assistant 不存在。
+2. target name 非法。
+3. target name 已存在于 assistant registry。
+4. target assistant home、target assistant index、或 target lock file 路径已存在。
+5. source assistant 当前正在运行、被活锁占用，或当前 assistant index 指向一个 active work session 且 surface 不是 `idle` / `closed`。
+6. source assistant 的 registry 路径与 canonical 目录推导不一致，无法安全判定 rename 边界。
+7. staging 或 rollback 失败，系统不能确认最终状态。
+
+### 5.5 Rename 完成后的用户体验事实
+
+rename 成功后，下面这些事实必须同时成立：
+
+- `assistant list` 只能看到新名字。
+- `assistant show <new>` 可以看到原 desk 的长期资产与新路径。
+- 旧名字不再是合法控制入口。
+- desk Git 仓库仍然是原来的那份仓库，只是目录名变了。
+- same-machine handoff 与 active work session 只认新名字。
+- desktop 刷新后只看到新名字，不保留旧名字 ghost record。
+
+## 6. 当前影响面总表
+
+当前 rename 需要触达的代码与对象至少包括以下几层。
+
+### 6.1 命令面与分发
+
+- `ally.sh`
+- `internal/dispatch.sh`
+- `internal/modules/assistant/manage.sh`
+
+这里决定是否存在正式 `assistant rename` 命令面，以及 help / usage 是否暴露该能力。
+
+### 6.2 assistant registry 与 name-derived path
+
+- `internal/lib/common.sh`
+- `internal/modules/assistant/manage.sh`
+
+这里定义了 assistant home / codex home / runtime / logs / cache / runs / state file 路径推导，以及 registry 的查找和字段读取。当前这些函数都把 name 当成根键。
+
+### 6.3 project registry 绑定
+
+- `internal/lib/common.sh`
+
+`projects/registry.yaml` 里记录的是 `assistant: <name>`，rename 必须同步迁移 workspace -> assistant 绑定值。
+
+### 6.4 本地 config 与 runtime state
+
+- `internal/lib/common.sh`
+- `internal/modules/bootstrap/setup.sh`
+- `internal/modules/runtime/start.sh`
+- `internal/modules/runtime/stop.sh`
+- `internal/modules/runtime/status.sh`
+- `internal/modules/runtime/supervisor.sh`
+- `internal/modules/global/manage.sh`
+- `internal/modules/ops/logs.sh`
+- `internal/modules/routines/manage.sh`
+- `internal/modules/mcp/manage.sh`
+- `internal/modules/handoff/manage.sh`
+
+这里会读取：
+
+- `.system/config.env`
+- `.system/runtime/assistant.env`
+- `.system/runtime/bridge.pid` / health files
+- `~/.work-ally/locks/assistant-<name>.lock`
+
+rename 后如果任何一处仍指向旧名字，控制链路就会断或显示错位。
+
+### 6.5 desk 模板与受管理内容
+
+- `internal/modules/assistant/manage.sh`
+
+当前至少有以下受管理内容显式嵌入 assistant 名字或 assistant home 路径：
+
+- `SOUL.md` 模板中的“名字：<name>`
+- `assistant_home/AGENTS.md`
+- `.system/codex-home/AGENTS.md`
+- `.system/codex-home/config.toml` 中的 assistant desk trusted root / writable root
+
+### 6.6 work session / same-machine handoff
+
+- `bridge/src/work-session-store.ts`
+- `bridge/src/handoff-service.ts`
+- `bridge/src/types.ts`
+- `bridge/src/server.ts`
+- `bridge/src/receiver.ts`
+- `docs/planning/SPEC-codex-same-machine-session-handoff.md`
+
+这里已经持久化：
+
+- work session `meta.json` 中的 `assistantName` / `assistantCodexHome`
+- `indexes/assistants/<name>.json`
+- handoff export / attach payload 里的 `assistantName`
+
+rename 后这些对象必须与新名字一致。
+
+### 6.7 desktop read model 与控制面
+
+- `desktop/backend/rust/src/repository.rs`
+- `desktop/backend/rust/src/models.rs`
+- `desktop/src-tauri/src/repository.rs`
+- `desktop/src-tauri/src/models.rs`
+- `desktop/src-tauri/src/lib.rs`
+
+desktop 当前直接读取 registry 与 `.system/config.env`，构建 `AssistantSnapshot.name/id` 与 `ProjectSnapshot.assistant_names`，并把 assistant name 当作控制命令参数。
+
+### 6.8 测试与 fixtures
+
+- `tests/shell/assistant.sh`
+- `tests/shell/assistant-remove.sh`
+- 新增 `tests/shell/assistant-rename.sh`
+- 必要的 bridge / desktop backend tests
+- `tests/fixtures/empty-work-ally-home/...`
+
+现有测试覆盖 add / bind / remove，但没有 rename 主路径。
+
+## 7. 机制设计
+
+### 7.1 V1 不新增 `assistant_id`
+
+V1 不引入新的稳定对象 ID。当前 rename 直接迁移现有 assistant key 本身。
+
+原因：
+
+- 用户当前已经通过名字理解 assistant 身份。
+- 仓库现状所有关键路径都围绕 name 展开。
+- 先把 rename 合同收口，比同时引入新主键体系更可控。
+
+这也意味着 V1 的 rename 不是“改 display name”，而是真正迁移系统键。
+
+### 7.2 Canonical 可迁移前提
+
+只有满足以下前提，rename 才能执行：
+
+1. `assistants/registry.yaml` 中 source assistant 存在。
+2. source assistant 的 `assistant_home` 等于 canonical 路径 `~/.work-ally/assistants/<old>`。
+3. source assistant 的 `codex_home` 等于 canonical 路径 `~/.work-ally/assistants/<old>/.system/codex-home`。
+4. 目标 canonical 路径 `~/.work-ally/assistants/<new>` 不存在。
+5. 目标 assistant index 文件 `.../.system/runtime/work-sessions/indexes/assistants/<new>.json` 不存在。
+6. 目标 lock 文件 `~/.work-ally/locks/assistant-<new>.lock` 不存在。
+7. source assistant 不 busy。
+
+如果 registry 已被人工改成非 canonical 路径，V1 不尝试猜测如何迁移，而是直接拒绝，并要求先把 profile 修回 canonical 状态。
+
+### 7.3 Preflight 规则
+
+rename 开始前，系统必须一次性完成以下 preflight：
+
+- 校验 `old`、`new` 都满足 assistant name 规则。
+- 校验 `old != new`。
+- 校验 source assistant 已注册。
+- 校验 target assistant 未注册。
+- 校验 source assistant 未运行、未 busy。
+- 只允许清理 stale source lock；不允许绕过活锁。
+- 校验 source desk 目录存在，target desk 目录不存在。
+- 校验 source registry 字段完整，且路径与 canonical 推导一致。
+- 如果存在 `.system/config.env`、`.system/runtime/assistant.env`、assistant index 文件，则它们必须是可读的常规文件；不可读或类型异常时直接拒绝。
+
+任一失败都直接退出，不触发任何迁移写入。
+
+### 7.4 Busy 定义
+
+V1 的 rename busy 定义如下；命中任一条件都必须拒绝：
+
+1. `work_ally_assistant_is_busy <old>` 判断为 running。
+2. source lock 文件存在且 PID 存活。
+3. source assistant index 指向一个未归档 work session，且该 session 的 `activeSurface` 为 `work_ally_channel` 或 `official_codex_cli`。
+
+下列情况允许继续：
+
+- source lock 为 stale，且可被清理。
+- source assistant index 不存在。
+- source assistant index 指向的 work session 已归档，或 `activeSurface` 为 `idle` / `closed`。
+
+这里的判断目的是避免 rename 发生在 live runtime / live handoff 期间。
+
+### 7.5 迁移事务模型
+
+rename 必须按“先 staging，再 commit；失败即 rollback”的方式执行。
+
+最小事务顺序如下：
+
+1. 读取并缓存 source assistant registry block、project registry 当前内容、source `.system/config.env`、source `.system/runtime/assistant.env`、source lock、source assistant index、所有受影响 work session meta。
+2. 在临时目录生成 rewritten registry / project registry / rewritten managed files / rewritten work session metas。
+3. 执行 desk 根目录 rename：`assistants/<old>` -> `assistants/<new>`。
+4. 在新 desk 路径下写入受管理文件改写：`AGENTS.md`、`SOUL.md` 受管理名字区块、`codex_home/config.toml`、`.system/config.env`、`.system/runtime/assistant.env`。
+5. 写入 assistant registry、project registry、work session metas、assistant index、lock 文件名与内容。
+6. 删除旧 assistant index 文件与旧 lock 文件。
+7. 只有全部成功后才返回 success。
+
+rollback 要求：
+
+- registry 恢复旧版本。
+- project registry 恢复旧版本。
+- new desk 目录改回 old 路径。
+- `.system/config.env`、`.system/runtime/assistant.env`、assistant index、work session metas、lock 恢复旧内容。
+- 如果已经创建了 target index / target lock，但原状态里不存在，rollback 时必须清掉它们。
+
+如果 rollback 也失败，命令必须明确输出 `rollback_failed` 类错误，并附带现场路径，不能假装成功。
+
+### 7.6 需要自动迁移的结构化对象
+
+#### 7.6.1 `assistants/registry.yaml`
+
+rename 时必须更新：
+
+- 顶层键：`old` -> `new`
+- `assistant_home`
+- `codex_home`
+- `updated_at`
+
+必须保留：
+
+- `created_at`
+- `description`
+- `workspace_root`
+
+#### 7.6.2 `projects/registry.yaml`
+
+所有 `assistant: <old>` 都必须改成 `assistant: <new>`。
+
+V1 不保留 alias；rename 成功后 project registry 只认新名字。
+
+#### 7.6.3 desk 根目录
+
+必须迁移整个 desk 根目录：
+
+- `~/.work-ally/assistants/<old>/` -> `~/.work-ally/assistants/<new>/`
+
+这意味着以下资产自然跟随迁移：
+
+- `SOUL.md`
+- `NOW.md`
+- `MEMORY.md`
+- `MISTAKES.md`
+- `journal/`
+- `conversations/`
+- `.system/archive/`
+- `.git/`
+
+#### 7.6.4 `.system/config.env`
+
+如果 source assistant 存在 `.system/config.env`，rename 后必须重写以下受管理键：
+
+- `WORK_ALLY_ASSISTANT_NAME`
+- `WORK_ALLY_ASSISTANT_HOME`（若存在）
+- `WORK_ALLY_ASSISTANT_CODEX_HOME`（若存在）
+- `WORK_ALLY_STATE_DIR`（若存在）
+
+必须保持不变：
+
+- `FEISHU_*`
+- `WORK_ALLY_ALLOWED_USER_IDS`
+- `WORK_ALLY_CHANNEL_IMPL`
+- `WORK_ALLY_RUNTIME_MODE`
+- `WORK_ALLY_ASSISTANT_GIT_REMOTE`
+- 其他用户本地输入
+
+V1 规则：
+
+- 只重写受管理键，不删除、不重排其他键。
+- `.system/config.env` 不存在时不强行创建；沿用现状。
+
+#### 7.6.5 `.system/runtime/assistant.env`
+
+如果 source assistant 有 `.system/runtime/assistant.env`，rename 后必须重写其中至少这些字段：
+
+- `WORK_ALLY_ASSISTANT_NAME`
+- `WORK_ALLY_ASSISTANT_HOME`
+- `WORK_ALLY_ASSISTANT_CODEX_HOME`
+- `WORK_ALLY_STATE_DIR`
+
+以及所有仍然内嵌 old canonical path 的字段。
+
+#### 7.6.6 global lock
+
+如果 source assistant 有 stale lock 文件，rename 后 lock 文件名和内容都要对齐新名字：
+
+- 文件名：`assistant-<old>.lock` -> `assistant-<new>.lock`
+- 内容中的 `assistant=<old>` -> `assistant=<new>`
+
+活锁场景不允许 rename，因此不会出现边运行边迁移 lock owner 的合同。
+
+#### 7.6.7 work sessions / same-machine handoff 持久化
+
+如果 source assistant 存在 `.../.system/runtime/work-sessions/`，rename 后必须迁移：
+
+- 所有 `meta.json` 中 `assistantName == <old>` 的对象，改成 `assistantName == <new>`
+- 所有 `meta.json` 中 `assistantCodexHome == <old canonical codex home>` 的对象，改成新 canonical codex home
+- assistant index 文件：`indexes/assistants/<old>.json` -> `indexes/assistants/<new>.json`
+- assistant index 内容中的 `assistantName` 改成新名字
+
+必须保持不变：
+
+- `workSessionId`
+- `runtimeThreadId`
+- `deliveryChannel` / `deliveryConversationKey`
+- `lastTurnId`、`lastPromptPreview`、`lastReplyPreview`
+- archived / history 语义
+
+额外合同：
+
+- archived work session 也要迁移 `assistantName`，因为它仍属于同一个 assistant 的历史资产。
+- delivery index 文件按 conversation key 建立，不按 assistant name 建立，因此不需要重命名。
+- rename 成功后，same-machine handoff 的 export / attach / active session 解析必须只认新名字。
+
+#### 7.6.8 明确不迁移的 channel lock
+
+channel lock key 与 channel / app id 绑定，不与 assistant name 绑定。V1 rename 不改写 channel lock。
+
+原因：
+
+- rename 只允许 idle / not busy 场景。
+- live channel lock 场景本就会被 busy preflight 拒绝。
+
+### 7.7 需要自动改写的受管理文件
+
+#### 7.7.1 `assistant_home/AGENTS.md`
+
+rename 后必须把旧 desk 路径重写成新 desk 路径。
+
+#### 7.7.2 `codex_home/AGENTS.md`
+
+同上，内部包含 assistant home 路径，也必须更新。
+
+#### 7.7.3 `codex_home/config.toml`
+
+rename 后必须把 assistant desk 根目录相关 trusted root / writable root 从旧路径更新到新路径。
+
+workspace root 不变，不得误改。
+
+#### 7.7.4 `SOUL.md`
+
+`SOUL.md` 只允许更新受管理的名字区块，不允许把整个文件当模板重写。
+
+V1 合同：
+
+- 如果 `SOUL.md` 中存在标准区块 `## 你的名称` 下的行 `- 名字：<old>`，rename 时将其改为 `- 名字：<new>`。
+- rename 不尝试全局替换 `SOUL.md` 其他段落中的旧名字。
+- rename 不重排、不覆盖用户已经写下的其他人格内容。
+
+### 7.8 明确不自动改写的内容
+
+以下内容不做全局改名：
+
+- `NOW.md`
+- `MEMORY.md`
+- `MISTAKES.md`
+- `journal/`
+- `conversations/`
+- `.system/archive/`
+- 任何历史日志、历史对话、用户自由书写的说明文案
+
+原因：
+
+- 这些内容里出现旧名字，可能是历史事实，不应被系统静默重写。
+- V1 无法可靠区分“应改的新身份指代”与“应保留的历史记录”。
+
+### 7.9 CLI、global、handoff、desktop 合同
+
+rename 成功后必须同时成立：
+
+- `assistant list/show/status/start/stop/logs` 只认新名字。
+- `global list` 只枚举新名字；`global stop --assistant <new>` 有效，旧名字无效。
+- `handoff export` / `handoff attach` / active work session 解析只认新名字。
+- `AssistantSnapshot.id` 与 `name` 只暴露新名字。
+- `ProjectSnapshot.assistant_names` 只暴露新名字。
+- 以 assistant name 为参数的 desktop 控制动作，后续必须使用新名字。
+- refresh 后不再出现旧名字 ghost record。
+
+### 7.10 命令输出合同
+
+成功输出至少包含：
+
+- `old_name: <old>`
+- `new_name: <new>`
+- `assistant_home: <new path>`
+- `codex_home: <new path>`
+- `workspace: <workspace_root>`
+
+拒绝输出必须短、准、直接，并说明原因，例如：
+
+- `Assistant rename refused: target name already exists`
+- `Assistant rename refused: assistant is currently running`
+- `Assistant rename refused: work session is still active`
+- `Assistant rename refused: profile path is not canonical`
+- `Assistant rename failed: rollback_failed`
+
+## 8. 验收标准
+
+### 8.1 功能验收
+
+以下主路径必须成立：
+
+1. source assistant idle，target name 可用时，rename 成功。
+2. rename 后 `assistant list`、`assistant show`、`status`、`start`、`stop`、`logs`、`global list/stop --assistant` 都只认新名字。
+3. rename 后原 desk 内容、Git 历史、项目绑定、`codex_home`、长期资产都还在。
+4. rename 后 `.system/config.env` 与 `.system/runtime/assistant.env` 中的受管理 assistant 字段对齐新名字。
+5. rename 后 existing work sessions / assistant index / same-machine handoff 只认新名字。
+6. rename 后 desktop snapshot 只暴露新名字。
+
+### 8.2 拒绝路径验收
+
+以下场景必须稳定拒绝：
+
+1. source assistant 不存在。
+2. target name 非法或已存在。
+3. source assistant 正在运行、被活锁占用，或当前仍有 active work session surface。
+4. target canonical path、target index path、或 target lock path 已存在。
+5. source registry 路径不是 canonical，系统无法安全迁移。
+6. `.system/config.env` / `assistant.env` / assistant index 存在但不可读或无法安全回写。
+
+### 8.3 自动化验证基线
+
+至少覆盖：
+
+- `bash -n ally.sh`
+- `bash -n internal/dispatch.sh`
+- `bash -n internal/modules/assistant/manage.sh`
+- shell：新增 `tests/shell/assistant-rename.sh`
+- shell：成功 rename、busy 拒绝、target exists 拒绝、canonical mismatch 拒绝、rollback 场景
+- shell：rename 后 `global list/stop --assistant <new>` 与旧名字失效
+- shell / unit：rename 后 `.system/config.env` 与 `assistant.env` 的受管理键更新正确
+- bridge/unit：work session assistant index 与 `meta.json` 迁移正确
+- 必要的 desktop/backend 测试：rename 后 machine snapshot / project snapshot 不再保留旧名字
+
+### 8.4 文档验收
+
+以下文档必须回写：
+
+- `README.md`
+- `docs/user-quickstart.md`
+- 必要时 `docs/ops-runbook.md`
+
+文档必须明确：
+
+- 已支持 `assistant rename`
+- rename 是系统级迁移，不是 display alias
+- 哪些用户自由文本不会被自动改名
+- rename 不支持运行中 assistant
+
+## 9. 风险 / 假设 / 待决问题
+
+### 9.1 风险
+
+- 当前 registry 解析是自定义文本处理，不是强 schema parser；rename 若实现粗糙，容易留下半迁移状态。
+- assistant 名字深度耦合到 shell、bridge、handoff 与 desktop 读模型；任何遗漏都会被用户直接看到。
+- `SOUL.md` 与其他长期资产有用户自写内容，rename 不能装作能把所有旧名字都改干净。
+
+### 9.2 假设
+
+- assistant desk 默认仍位于 canonical 目录 `~/.work-ally/assistants/<name>/`。
+- rename 发生在同一文件系统卷内，目录 rename 可按本地 move 处理。
+- desktop V1 继续只读 registry / config / snapshot，不在 rename 过程中持有独立写缓存。
+
+### 9.3 待决问题
+
+当前无阻塞实现的产品级待决问题；V1 边界在本文已固定：
+
+- 不做 alias
+- 不做 desktop rename 入口
+- 不做用户自由文本全量改名
+- 不引入新 `assistant_id`