work-ally 0.2.0-alpha.1

package/docs/planning/SPEC-codex-same-machine-session-handoff.md

@@ -0,0 +1,873 @@
+# SPEC: Codex 同机双向会话接续
+
+更新时间：2026-03-18  
+状态：已验收通过  
+Owner：work-ally product / engineering  
+相关文档：
+- `docs/planning/SPEC-runtime-abstraction-phase-1.md`
+- `docs/planning/SPEC-bridge-app-server-protocol-alignment.md`
+- `docs/planning/SPEC-runtime-connection-and-turn-recovery-semantics.md`
+- `docs/planning/SPEC-remove-websocket-runtime-transport.md`
+- `docs/implementation/SPEC-codex-same-machine-session-handoff-implementation.md`
+
+当前验收结论：
+
+- 2026-03-18：本专题已通过产品验收；`/codex`、`handoff codex|attach`、linked / attached `/takeover` 主合同成立。
+- 当前自动化与 shell 验证已成立；真实 Codex runtime smoke 仍受当前环境上游网络请求失败影响，因此不记为“真实链路全绿”。
+
+## 1. Summary
+
+这份 spec 要把 `work-ally` 从“单通道连续对话”升级成一种**同机双向无缝接续工作**能力。
+
+用户可以在同一台电脑上，把同一个 assistant、同一个 workspace、同一个 Codex 连续上下文，在这两类表面之间切换：
+
+- `work-ally` 渠道侧（V1 以 Feishu 单聊为主）
+- 官方 `Codex CLI` 本地侧
+
+核心目标不是“多一个兜底命令”，而是：
+
+> 当工作场景切换时，用户不需要重新讲背景、不需要人工复制摘要、不需要新开一条假会话，而是继续同一条真实工作线程。
+
+这不是跨设备云同步，也不是多客户端同时写同一线程。V1 只解决**同一台机器上的双向接续**，并坚持**单活 ownership**。
+
+## 2. 第一性原理与核心判断
+
+### 2.1 用户真正要连续的是“工作”，不是“聊天窗口”
+
+用户不在意自己此刻是在桌面终端、桌面 app，还是手机里的 Feishu。
+
+用户真正在意的是：
+
+- 还是同一个 assistant
+- 还是同一个项目工作现场
+- 还是同一条正在进行的 Codex 工作上下文
+- 我换个表面以后，不要让我从头再解释一遍
+
+因此，本专题的主对象不是“导出命令”，而是**连续工作的会话本体**。
+
+### 2.2 `work-ally` 不应再造一个会话脑子
+
+`work-ally` 的角色不是复制一份对话语义，更不是自建第二套 agent 会话引擎。
+
+正确边界是：
+
+- 官方 Codex thread 是底层连续上下文真相
+- `work-ally` 持有产品级映射、ownership、入口、绑定关系与审计账本
+- 渠道只是接入面，不是会话主身份
+
+### 2.3 这件事的本质是“handoff”，不是“backup”
+
+旧心智把它理解为：当 `work-ally` 不稳定时，给用户一个命令行恢复出口。
+
+这个理解现在已经不够了。
+
+现在更准确的产品定义应是：
+
+> `work-ally` 负责把“渠道工作”和“官方 Codex 本地工作”接成同一条连续工作流，并允许用户在同机双向切换。
+
+### 2.4 V1 必须明确坚持“单活”
+
+双向接续不等于双端并发协作。
+
+如果 Feishu 和官方 Codex 同时向同一条 thread 发起新 turn：
+
+- 用户会失去因果理解
+- bridge 会更难判断 pending request、delivery、stale suppression
+- 产品可信度会显著下降
+
+所以 V1 必须坚持：
+
+- 同一时刻只允许一个表面作为当前写入口
+- 另一侧最多处于被动观察或等待接管状态
+
+### 2.5 V1 只承诺“同机”，不承诺“跨机”
+
+这份 spec 的连续性基础，是同一台机器上的：
+
+- 同一个 assistant desk
+- 同一个 `CODEX_HOME`
+- 同一个 workspace root
+- 同一份官方 Codex thread 存储边界
+
+跨机器迁移、云端统一会话托管、异地接续，不属于本期范围。
+
+## 3. 背景
+
+当前仓库已经具备一些关键基础：
+
+- `work-ally` 已经接入官方 `codex app-server`
+- 当前主路径已经围绕 `thread/start`、`thread/resume`、`thread/read(includeTurns=true)` 工作
+- bridge 稳定性问题的主因，已经越来越清楚地收口到我们自己的协议理解和产品处理逻辑，而不再应简单归因于“官方不稳定”
+- 现有渠道连续性已经可以在同一外部 conversation 中持续复用同一条 Codex thread
+
+但产品层仍有一个明显缺口：
+
+- `work-ally` 内部连续性已经存在
+- 官方 Codex 本地侧连续性也存在
+- 但两者之间还没有被定义成同一个正式产品能力
+
+结果就是：
+
+- 从 `work-ally` 去官方 Codex，仍像“导出一个恢复命令”
+- 从官方 Codex 回到 `work-ally`，还没有正式、可审计、可验证的接续路径
+- 团队容易把它做成补丁式功能，而不是稳定产品边界
+
+## 3.1 术语表
+
+为避免开发过程继续混用概念，本文术语固定如下：
+
+- `assistant desk`
+  - 命名 assistant 的长期家目录，包含 desk 可见资产与 `.system/` 运行资产
+- `delivery conversation`
+  - 外部聊天入口，例如一个 Feishu 单聊会话
+- `runtime thread`
+  - 官方 Codex / App Server 持有的连续上下文对象
+- `cli resume ref`
+  - 官方 `codex resume ...` 可直接消费的恢复句柄，可能是 `SESSION_ID`，也可能是 `thread name`
+- `work_session`
+  - `work-ally` 自己持有的产品级连续工作对象，用于把 assistant、workspace、delivery conversation 与 runtime thread 绑定起来
+- `surface`
+  - 用户当前工作的表面。V1 只有 `work_ally_channel` 与 `official_codex_cli`
+- `owner`
+  - 当前被系统承认为“允许继续写入这条 work_session”的 surface
+- `linked session`
+  - 已经存在正式 `work_session` 记录，并已与当前 assistant / delivery conversation 建立绑定的会话
+- `unmanaged CLI thread`
+  - 在 assistant 对应 `CODEX_HOME` 中真实存在，但尚未被 `work-ally` 建立 `work_session` 记录的官方 Codex thread
+
+硬规则：
+
+- 本文后续不再允许把 `delivery conversation`、`runtime thread`、`cli resume ref`、`work_session` 混称为“session”。
+- 工程实现中的类型、注释、文档也应对齐这套术语，避免继续出现“session 其实指 thread / conversation / work session”的混写。
+
+## 4. 问题定义
+
+本专题要解决 5 个问题。
+
+### 4.1 当前“连续工作”的边界被渠道切断了
+
+用户今天能连续地在 Feishu 里聊下去，但不能把同一条工作线程自然切到官方 Codex，再自然切回来。
+
+这与产品目标不一致。
+
+### 4.2 旧的“backup/resume”心智太窄
+
+旧 spec 把需求理解成单向兜底：
+
+- `work-ally` 出问题时
+- 用户回到 CLI
+- 继续同一个会话
+
+这会导致设计天然偏向：
+
+- 单向导出
+- 事故补救
+- 不覆盖 Codex-originated 工作
+
+而现在真正要做的是：
+
+- 正常工作场景下的双向接续
+- `work-ally` 与官方 Codex 作为同一连续工作流的两个表面
+
+### 4.3 当前缺少一个正式的产品级会话对象来承载 handoff
+
+如果没有产品级会话对象，系统就很容易继续把这些对象混在一起：
+
+- Feishu conversation
+- bridge 当前 session
+- Codex runtime thread
+- CLI resume 句柄
+
+这会直接造成：
+
+- 实现边界模糊
+- 命名不稳定
+- 开发者继续 freestyle
+
+### 4.4 当前没有被讲清楚的 ownership 规则
+
+如果 spec 不明确规定“哪一侧当前能写”，开发实现很容易走向两种错误：
+
+- 静默双写
+- 静默抢占
+
+这两种都会让用户失去对系统真相的信任。
+
+### 4.5 当前没有覆盖官方 Codex 发起场景
+
+如果用户先在官方 `Codex CLI` 里工作，再想切回手机侧继续，系统目前没有正式的 attach/import 模型。
+
+这意味着“官方 Codex -> work-ally”这个方向仍然是不完整的。
+
+## 5. 目标
+
+本 feature 必须达成以下目标：
+
+1. 让用户可以从 `work-ally` 渠道侧切到官方 `Codex CLI`，继续同一条真实工作线程。
+2. 让用户可以从官方 `Codex CLI` 切回 `work-ally` 渠道侧，继续同一条真实工作线程。
+3. 让 `work-ally` 持有正式的产品级会话对象，用来管理 handoff，而不是继续拿外部 conversation 或 runtime 临时状态凑合。
+4. 在产品层明确 single-active ownership，避免双写和静默抢占。
+5. 明确区分 runtime thread identity 与 CLI 可恢复句柄，禁止实现层偷懒把它们写成一个概念。
+6. 对由官方 Codex 直接启动、但尚未纳入 `work-ally` 管理的线程，提供一次性本地 attach/import 路径。
+7. 给出清晰、可测、不会让开发者靠猜的主路径、拒绝路径和完成标准。
+
+## 5.1 产品成功标准
+
+这件事完成后，产品层要成立的不是“多了几个命令”，而是下面 4 条用户体验事实：
+
+1. 用户从 Feishu 切到官方 Codex 时，不需要重新解释上下文，也不会被系统偷偷开新会话。
+2. 用户从官方 Codex 切回 Feishu 时，能继续同一条真实工作线程，而不是一条摘要复制后的伪连续对话。
+3. 当系统无法安全接续时，会明确拒绝并说明原因，而不是猜测、隐式 attach、隐式抢占。
+4. 开发者和维护者能稳定回答“当前哪条 work_session 在工作、它归谁写、为什么现在不能接过去”。
+
+## 6. 非目标
+
+本期明确不做：
+
+1. 不做跨机器、跨设备的 thread 迁移或云同步。
+2. 不做 Feishu 与官方 Codex 的并发双端协作。
+3. 不承诺所有表面都实时镜像完整转录。
+4. 不把 `work-ally` 做成官方 Codex 会话存储的替代品。
+5. 不在 V1 支持群聊里的 `/codex`、`/takeover`。
+6. 不支持自动接管任意历史 Codex thread；涉及歧义时必须显式 attach。
+7. 不把 VS Code extension、Codex desktop app 一起纳入 V1 正式合同。
+
+说明：
+
+- V1 的官方本地表面，以 `Codex CLI` 作为唯一正式支持对象。
+- 未来如果要扩到其他官方表面，应在本 spec 基础上加专题，不要在本期偷扩 scope。
+
+## 6.1 术语表
+
+为避免开发过程继续混用概念，本文术语固定如下：
+
+- `assistant desk`
+  - 命名 assistant 的长期家目录，包含 desk 可见资产与 `.system/` 运行资产。
+- `delivery conversation`
+  - 外部聊天入口，例如一个 Feishu 单聊会话。
+- `runtime thread`
+  - 官方 Codex / App Server 持有的连续上下文对象。
+- `cli resume ref`
+  - 官方 `codex resume ...` 可直接消费的恢复句柄，可能是 `SESSION_ID`，也可能是 `thread name`。
+- `work_session`
+  - `work-ally` 自己持有的产品级连续工作对象，用于把 assistant、workspace、delivery conversation 与 runtime thread 绑定起来。
+- `surface`
+  - 用户当前工作的表面。V1 只有 `work_ally_channel` 与 `official_codex_cli`。
+- `owner`
+  - 当前被系统承认为“允许继续写入这条 work_session”的 surface。
+- `linked session`
+  - 已经存在正式 `work_session` 记录，并已与当前 assistant / delivery conversation 建立绑定的会话。
+- `unmanaged CLI thread`
+  - 在 assistant 对应 `CODEX_HOME` 中真实存在，但尚未被 `work-ally` 建立 `work_session` 记录的官方 Codex thread。
+
+硬规则：
+
+- 本文后续不再允许把 `delivery conversation`、`runtime thread`、`cli resume ref`、`work_session` 混称为“session”。
+- 工程实现中的类型、注释、文档也应对齐这套术语，避免继续出现“session 其实指 thread / conversation / work session”的混写。
+
+## 7. 产品定义与用户路径
+
+### 7.1 一句话产品定义
+
+`Codex 同机双向会话接续` 是一种产品能力：
+
+> 在同一台机器上，把 `work-ally` 渠道侧与官方 `Codex CLI` 接成同一条连续工作流，用户可以双向切换而不重建上下文。
+
+### 7.2 V1 正式支持的两个表面
+
+#### A. `work_ally_channel`
+
+V1 以 Feishu 单聊为主。
+
+用户通过命名 assistant 的常规聊天入口与 `/codex`、`/takeover`、`/new` 等命令触发连续性能力。
+
+#### B. `official_codex_cli`
+
+V1 只正式支持官方 `Codex CLI`。
+
+原因：
+
+- 它已有稳定 `resume` 能力
+- 它是同机场景中最确定、最可验证、最容易自动化测试的官方表面
+- 它与当前 `work-ally` 的本地运行边界天然一致
+
+### 7.2.1 为什么 V1 不支持其他官方表面
+
+这次不要让开发者自行扩大范围。
+
+V1 不把以下对象纳入正式合同：
+
+- Codex desktop app
+- VS Code 扩展
+- 任何第三方 shell 包装层
+
+原因不是它们永远不支持，而是：
+
+- 当前 spec 的关键边界在于 same-machine handoff、ownership、attach、resume ref 与可自动化验证。
+- `Codex CLI` 是最小且最确定的官方本地表面。
+- 如果把其他表面一起拉进来，开发者很容易提前引入额外存储假设、额外入口判断与额外 UI 语义。
+
+结论：
+
+- V1 代码命名允许保留扩展空间。
+- 但产品语义、测试与验收只对 `official_codex_cli` 成立。
+
+### 7.3 主路径 A：`work-ally -> Codex CLI`
+
+场景：
+
+- 用户原本在 Feishu 或 `work-ally` 侧工作
+- 现在想回到本机官方 Codex 继续
+
+路径：
+
+1. 用户在单聊中发送 `/codex`，或在本机执行 `./ally.sh handoff codex <assistant>`。
+2. 系统找到当前 assistant 对应的 active `work_session`。
+3. 系统返回**精确可执行**的官方 Codex 接续方式：
+   - 优先是可直接执行的 `codex resume` 命令
+   - 若当前只能打印 handoff 元信息，也必须明确说明为什么还不能 resume
+4. 用户在本机进入官方 `Codex CLI` 后，继续同一条 runtime thread。
+5. 此后该 `work_session` 的 owner 可切到 `official_codex_cli`。
+
+关键约束：
+
+- `/codex` 是 handoff 出口，不是开新会话。
+- 如果当前没有可恢复句柄，系统必须明确返回 `not_ready`，不能拿不确定 id 硬凑。
+
+### 7.4 主路径 B：`Codex CLI -> work-ally`（已链接会话）
+
+场景：
+
+- 当前线程原本就属于 `work-ally` 管理下的 `work_session`
+- 用户中途切到官方 `Codex CLI` 继续工作
+- 之后想回到手机侧继续
+
+路径：
+
+1. 用户在 Feishu 单聊里发送 `/takeover`。
+2. 系统找到当前 assistant 已链接的 active `work_session`。
+3. 系统用该 `work_session` 的 `runtimeThreadId` 继续回到同一条 Codex thread。
+4. 该 `work_session` 的 owner 切回 `work_ally_channel`。
+5. 后续普通自然语言继续沿这条 thread 工作。
+
+关键约束：
+
+- `/takeover` 是“把当前已链接工作线程接回这里”，不是新建 thread。
+- 如果没有已链接 `work_session`，必须明确失败原因，而不是偷偷 `/new`。
+
+### 7.5 主路径 C：`Codex CLI -> work-ally`（未链接线程，先 attach）
+
+场景：
+
+- 用户先直接在官方 `Codex CLI` 里开工
+- 这条 thread 还没有被 `work-ally` 纳入管理
+- 之后用户希望手机侧也能继续
+
+路径：
+
+1. 用户在本机执行 `./ally.sh handoff attach <assistant> --last`，或显式指定 `--thread <runtimeThreadId>` / `--resume-ref <cliResumeRef>`。
+2. 系统在该 assistant desk 的 `CODEX_HOME` 边界内，发现候选官方 Codex thread。
+3. 如果候选唯一且 workspace 匹配，系统创建新的 `work_session`，并把它绑定到这个 assistant 的渠道连续性入口。
+4. 之后用户可在 Feishu 中发送 `/takeover`，继续同一条 thread。
+
+关键约束：
+
+- `attach` 是显式本地动作。
+- 如果候选不唯一，系统必须拒绝并要求用户明确指定，不能猜。
+
+### 7.6 主路径 D：`/new`
+
+场景：
+
+- 用户不想继续当前线程，而是要开一条新的工作上下文
+
+路径：
+
+1. 用户在 `work-ally` 侧执行 `/new`。
+2. 系统创建新的 `work_session` 与新的 runtime thread。
+3. 旧 `work_session` 保留为历史，不被覆盖。
+
+### 7.7 拒绝路径
+
+V1 至少要明确以下拒绝行为：
+
+1. 群聊内的 `/codex`、`/takeover` 直接拒绝。
+2. 当前 owner 在 `official_codex_cli` 时，用户在渠道里发普通文本，不得静默抢占；系统应提示先 `/takeover` 或 `/new`。
+3. `attach --last` 命中多个候选 thread 时，直接拒绝，要求显式指定。
+4. workspace 不匹配时，拒绝 attach。
+5. `cliResumeRef` 尚未可用时，`/codex` 返回 `not_ready`，不得拿 `runtimeThreadId` 假冒官方 CLI resume 句柄。
+6. 当前 assistant 没有 active `work_session` 时，`/codex` 明确返回“当前没有可接续的工作线程”，不得隐式创建。
+7. `/takeover` 发现 linked `work_session` 已归 `work_ally_channel` 所有时，应直接返回“当前已在这里继续”，而不是重复执行状态切换。
+
+## 8. 机制设计
+
+### 8.1 新的产品对象：`work_session`
+
+V1 引入正式产品对象 `work_session`。
+
+定义：
+
+> 一条由 `work-ally` 管理、绑定单个 assistant desk 与单个 workspace、映射到单条官方 Codex runtime thread、并可在不同表面之间 handoff 的连续工作单元。
+
+### 8.2 关系模型
+
+- 一个 assistant 可以有多条历史 `work_session`
+- V1 中，一条 `work_session` 对应一条 Codex `runtime_thread`
+- 一个 Feishu 单聊入口在任一时刻只指向一条当前 active `work_session`
+- 一条 `work_session` 在任一时刻只允许一个写表面 owner
+
+额外约束：
+
+- 一个 `work_session` 只绑定一个 assistant，不能在 assistant 之间横向复用。
+- 一个 `work_session` 创建后，`assistantCodexHome` 与 `workspaceRoot` 视为不可变主绑定。
+- 若用户换项目或换 assistant，正确动作是 `/new` 或新的 attach，而不是改写旧 `work_session`。
+
+### 8.3 `work_session` 最小字段
+
+每条 `work_session` 至少包含：
+
+- `workSessionId`
+- `assistantName`
+- `assistantCodexHome`
+- `workspaceRoot`
+- `runtime`
+  - 固定为 `codex`
+- `runtimeThreadId`
+- `cliResumeRef`
+  - 可空
+- `cliResumeRefType`
+  - `session_id` / `thread_name` / `unknown` / `null`
+- `threadName`
+  - 可空
+- `origin`
+  - `work_ally` / `codex_cli_attach`
+- `deliveryChannel`
+  - 例如 `feishu`
+- `deliveryConversationKey`
+  - 可空；用于渠道绑定
+- `activeSurface`
+  - `work_ally_channel` / `official_codex_cli` / `idle` / `closed`
+- `ownershipSource`
+  - `explicit_channel_takeover` / `explicit_codex_launch` / `observed_external_activity` / `manual_attach` / `new_session`
+- `resumeCapability`
+  - `ready` / `not_ready`
+- `lastRuntimeActivityAt`
+- `lastSurfaceSwitchAt`
+- `createdAt`
+- `updatedAt`
+- `archivedAt`
+  - 可空
+
+补充字段约束：
+
+- `assistantName`、`assistantCodexHome`、`workspaceRoot`、`runtime`、`runtimeThreadId` 一经创建后不可被普通更新流程改写。
+- `deliveryConversationKey` 可空，但一旦绑定后，除非显式迁移专题，不允许在 V1 中被静默改绑到另一条 delivery conversation。
+- `activeSurface` 与 `ownershipSource` 必须始终成对更新。
+- `resumeCapability=ready` 的前提是 `cliResumeRef` 非空且可直接导出给用户。
+
+建议但非强制字段：
+
+- `lastTurnId`
+- `lastPromptPreview`
+- `lastReplyPreview`
+- `lastHandoffExportAt`
+- `lastAttachAt`
+
+### 8.4 `runtimeThreadId` 与 `cliResumeRef` 必须逻辑分离
+
+这是本 spec 的硬边界。
+
+两者分别表示：
+
+- `runtimeThreadId`
+  - 给 App Server 的 `thread/read`、`thread/resume`、`turn/start` 使用
+- `cliResumeRef`
+  - 给用户执行 `codex resume ...` 使用
+
+禁止实现层做这几件事：
+
+- 默认假设两者永远相同
+- 在 `cliResumeRef` 缺失时，直接拿 `runtimeThreadId` 冒充
+- 把 CLI resume 能力是否可用，写成“只要有 thread id 就行”
+
+如果当前官方能力只能稳定拿到其中之一，系统必须把“不知道”写清楚，而不是硬补推断。
+
+### 8.5 ownership 规则
+
+V1 采用 single-active ownership。
+
+规则如下：
+
+1. 任一时刻，`work_session.activeSurface` 只能有一个当前 owner。
+2. 当 owner 为 `work_ally_channel` 时：
+   - 渠道侧可以正常发起新 turn
+   - 官方 Codex 侧若继续输入，系统无法强行阻止，但会在后续观测到该行为时把 owner 更新为 `official_codex_cli`
+3. 当 owner 为 `official_codex_cli` 时：
+   - `work-ally` 不得静默代用户继续发起普通文本 turn
+   - 用户若要切回渠道侧，必须显式 `/takeover`
+4. `/new` 永远创建新 `work_session`，不接管旧线程。
+
+说明：
+
+- `work-ally` 只能约束自己，不可能从产品外部阻止用户在官方 CLI 里继续输入。
+- 因此 V1 的正确策略是：**严管自己，不伪造并发安全。**
+
+### 8.5.1 ownership 状态解释
+
+为防止实现层把 `activeSurface` 当作随便写的标签，V1 明确规定：
+
+- `work_ally_channel`
+  - 当前允许由渠道侧继续发起 turn。
+- `official_codex_cli`
+  - 当前系统认为这条 `work_session` 的主动写入口在官方 CLI。
+- `idle`
+  - 当前没有明确 owner，通常只允许显式 `/takeover` 或显式本机 handoff 命令推进，不允许普通渠道文本直接抢占。
+- `closed`
+  - 该 `work_session` 已封存，不再承接新 turn。
+
+V1 建议：
+
+- 新建 `work_session` 后默认进入 `work_ally_channel`。
+- attach 成功后的 imported `work_session` 默认进入 `official_codex_cli`。
+- 不要为了省事完全不使用 `idle`；当系统确实无法安全断言当前 owner 时，宁可落到 `idle` 也不要乱猜。
+
+### 8.6 owner 切换条件
+
+以下动作会改变 `activeSurface`：
+
+1. `work-ally` 侧 `/takeover` 成功：
+   - 切为 `work_ally_channel`
+2. `work-ally` 侧 `/new`：
+   - 新建 `work_session`
+   - 新会话 owner 为 `work_ally_channel`
+3. 本机执行 `./ally.sh handoff codex <assistant> --open`：
+   - 进入官方 Codex 启动路径
+   - owner 可立即切为 `official_codex_cli`
+4. 已导出 handoff 句柄后，若系统观测到 linked thread 出现外部活动：
+   - owner 可切为 `official_codex_cli`
+   - `ownershipSource=observed_external_activity`
+5. 本机执行 `./ally.sh handoff attach ...`：
+   - attach 完成后，该会话初始 owner 为 `official_codex_cli`
+
+不允许作为 owner 切换依据的事件：
+
+- 单纯收到 delivery conversation 的一条普通文本
+- 单次 transport reconnect
+- 单次 `thread/read` 成功
+- 开发者主观推断“用户现在大概率想切回来了”
+
+### 8.7 渠道侧命令合同
+
+V1 新增并收口以下语义：
+
+#### `/codex`
+
+作用：
+
+- 导出当前 `work_session` 的官方 Codex handoff 方式
+
+规则：
+
+- 仅单聊支持
+- 若 `resumeCapability=ready`，返回精确 handoff 命令
+- 若 `resumeCapability=not_ready`，返回明确原因
+- 不创建新 session
+- 不自动切 owner，除非后续检测到本地官方 Codex 活动
+
+用户文案要求：
+
+- 若成功，必须让用户一眼看出“这是继续当前工作线程，不是新开会话”。
+- 若失败，必须明确失败属于哪一类：
+  - 没有 active `work_session`
+  - 当前 work_session 尚未具备 CLI 可恢复句柄
+  - 当前入口不允许导出
+
+#### `/takeover`
+
+作用：
+
+- 把当前已链接 `work_session` 接回当前渠道侧
+
+规则：
+
+- 仅单聊支持
+- 若存在 linked active `work_session`，则继续同一 runtime thread
+- 若不存在 linked session，但 assistant 有可 attach 的 unmanaged CLI thread，不自动猜；提示先在本机执行 `ally.sh handoff attach`
+- 不隐式 `/new`
+
+用户文案要求：
+
+- 若成功，必须明确提示“已接回当前工作线程”。
+- 若失败，必须区分：
+  - 没有 linked `work_session`
+  - 有 unmanaged CLI thread，但尚未 attach
+  - 当前会话已是 `work_ally_channel`
+
+#### `/new`
+
+作用：
+
+- 新开一条工作上下文
+
+规则：
+
+- 永远创建新的 `work_session`
+- 不覆盖旧 `work_session`
+
+### 8.8 本机命令入口合同
+
+为保证产品用户入口仍统一在 `./ally.sh`，V1 增加本机 handoff 子命令。
+
+建议命令面：
+
+#### `./ally.sh handoff codex <assistant>`
+
+职责：
+
+- 读取当前 assistant 的 active `work_session`
+- 输出精确的官方 `codex resume` 方式
+
+可扩展模式：
+
+- `--print`
+  - 只打印命令
+- `--open`
+  - 直接以该命令进入官方 Codex，本地 owner 立即切换为 `official_codex_cli`
+
+实现要求：
+
+- `--print` 与默认输出的结构必须稳定，便于后续 shell 测试和桌面端复用。
+- 如果未来桌面端要加“Continue in Codex”按钮，应调用同一后端能力，而不是复制命令拼接逻辑。
+
+#### `./ally.sh handoff attach <assistant>`
+
+职责：
+
+- 把官方 `Codex CLI` 直接启动的一条 thread 纳入 `work-ally` 管理
+
+建议参数：
+
+- `--last`
+- `--thread <runtimeThreadId>`
+- `--resume-ref <cliResumeRef>`
+
+规则：
+
+- 若 `--last` 命中多个候选，必须拒绝
+- attach 后创建正式 `work_session`
+
+实现要求：
+
+- attach 结果必须可机读，便于后续脚本、桌面端或测试消费。
+- attach 失败时要返回稳定错误类型，而不是只打印自由文案。
+
+### 8.9 unmanaged CLI thread 的 attach 规则
+
+attach 过程至少满足：
+
+1. 只在目标 assistant 对应的 `CODEX_HOME` 边界内发现候选线程。
+2. 候选线程必须与 assistant 当前 workspace root 精确匹配。
+3. `--last` 只能在候选唯一时成立。
+4. attach 成功后，要生成正式 `work_session` 记录，而不是只改一条临时指针。
+5. attach 只是把线程纳管，不代表立即切回渠道侧；切回渠道仍由 `/takeover` 完成。
+
+V1 不允许的 attach 简化：
+
+- 不允许扫描全局所有 `CODEX_HOME` 后拿最近线程直接绑到当前 assistant。
+- 不允许只按“最近修改时间”就忽略 workspace 校验。
+- 不允许 attach 成功后自动替用户把 delivery conversation 改绑到一条完全不同的 assistant 会话。
+
+### 8.10 work-ally 对官方 Codex 活动的观察边界
+
+V1 必须支持“知道 linked thread 还在同一条线上”，但不要求做完整 live transcript 镜像。
+
+因此 V1 只要求：
+
+- 能在 handoff 后继续识别同一条 runtime thread
+- 能在 `/takeover` 时继续回到同一条 runtime thread
+- 能基于 thread 真相更新 ownership 与基本状态
+
+V1 不要求：
+
+- 把官方 CLI 里发生的每一轮输出实时镜像回 Feishu
+- 把所有历史 turn 逐条补写回渠道档案
+
+### 8.11 持久化建议
+
+本专题不能继续只挂在 `conversationRef` 下。
+
+建议新增稳定目录：
+
+- `.system/runtime/work-sessions/<workSessionId>/meta.json`
+
+并新增最小索引：
+
+- `.system/runtime/work-sessions/by-assistant/<assistantName>.json`
+- `.system/runtime/work-sessions/by-delivery/<channel>--<conversationKey>.json`
+
+最小要求：
+
+- 每条 `work_session` 有独立 durable meta
+- assistant 当前指向哪条 `work_session` 可单独查询
+- delivery conversation 当前指向哪条 `work_session` 可单独查询
+
+### 8.12 真相源边界
+
+本专题的真相源分工必须明确：
+
+#### 官方 Codex / App Server 持有
+
+- runtime thread 真正连续性
+- thread 生命周期
+- turn 历史与 runtime 状态
+
+#### `work-ally` 持有
+
+- `work_session` 产品对象
+- assistant / workspace / delivery conversation 绑定
+- owner / handoff 状态
+- attach 与导出可用性
+- 审计与用户入口
+
+## 9. 明确禁止的实现方向
+
+为了避免实现偏航，本专题明确禁止以下做法：
+
+1. 禁止把“同一条工作线程”实现成“复制摘要到另一边再新开会话”。
+2. 禁止继续把外部 Feishu conversation id 当作连续工作会话的主键。
+3. 禁止在 `cliResumeRef` 不确定时，偷用 `runtimeThreadId` 冒充官方 CLI resume 句柄。
+4. 禁止在 owner 为 `official_codex_cli` 时，渠道普通文本静默抢占会话。
+5. 禁止自动 attach 多个候选中的“看起来最像”的官方 CLI thread。
+6. 禁止把 V1 做成“Feishu 与官方 Codex 同时在线双写同一线程”的产品承诺。
+7. 禁止把“实时镜像完整 transcript”错误提升为本专题的必交项。
+
+## 10. 验收标准
+
+满足以下条件，才算完成。
+
+### 10.1 `work-ally -> Codex CLI`
+
+1. 当 assistant 当前存在 active `work_session` 且 `resumeCapability=ready` 时，`/codex` 与 `./ally.sh handoff codex <assistant>` 都能返回精确可执行的官方接续方式。
+2. 该接续方式必须显式包含正确的 assistant `CODEX_HOME` 与 `workspaceRoot` 语义。
+3. 当 `resumeCapability=not_ready` 时，系统返回明确原因，不猜测、不硬补。
+
+### 10.2 `Codex CLI -> work-ally`（已链接）
+
+1. 对一条原本由 `work-ally` 创建的 `work_session`，用户切到官方 `Codex CLI` 工作后，再在 Feishu 单聊中执行 `/takeover`，系统会继续同一条 `runtimeThreadId`。
+2. `/takeover` 之后，后续普通渠道输入继续进入同一条 thread，而不是新建 thread。
+
+### 10.3 `Codex CLI -> work-ally`（attach）
+
+1. 对一条先由官方 `Codex CLI` 直接创建、但尚未纳管的线程，`./ally.sh handoff attach <assistant> --last` 在候选唯一时可成功创建正式 `work_session`。
+2. 若候选不唯一，attach 失败并要求显式指定，不允许猜。
+3. attach 成功后，用户可在 Feishu 单聊中通过 `/takeover` 继续同一条 thread。
+
+### 10.4 ownership
+
+1. 当 `activeSurface=official_codex_cli` 时，用户在渠道发送普通文本，系统必须拒绝静默抢占，并明确提示 `/takeover` 或 `/new`。
+2. `/new` 必须创建新的 `work_session`，历史会话不被覆盖。
+
+### 10.5 数据合同
+
+1. `runtimeThreadId` 与 `cliResumeRef` 在数据模型中必须独立持久化。
+2. `work_session` 必须是独立 durable 对象，不能只存在于内存或 conversation 临时状态里。
+3. assistant 当前 active `work_session` 与 delivery conversation 当前 active `work_session` 都必须可稳定查询。
+
+### 10.6 测试最低要求
+
+至少覆盖：
+
+- `tests/unit/session/` 中的 `work_session` 模型与 ownership 规则
+- `tests/integration/session/` 中的 handoff 主路径与拒绝路径
+- 必要的真实 `codex app-server` / `codex resume` smoke 验证
+- shell 层 `./ally.sh handoff ...` 命令语义验证
+
+## 10.1 开发者自测清单
+
+实现完成前，开发者至少要能自己验证下面这些事实：
+
+1. 从 `work-ally` 创建的 active `work_session` 能正确导出官方 Codex handoff 命令。
+2. 从该 handoff 命令进入官方 CLI 后，再执行 `/takeover`，不会新建 thread。
+3. 一个未纳管的官方 CLI thread，只有在显式 attach 且 workspace 匹配时才能被纳入管理。
+4. owner 为 `official_codex_cli` 时，渠道普通文本会被明确拒绝，而不是被桥层吞掉或偷偷继续。
+5. `runtimeThreadId` 与 `cliResumeRef` 在任何持久化文件中都不是同一字段的别名。
+
+如果自动化无法完整覆盖其中某一项，交付时必须明确写出缺口。
+
+## 11. 风险、假设、待决问题
+
+### 11.1 假设
+
+1. 同一 assistant desk 对应稳定的 `CODEX_HOME`，这是同机会话连续性的前提。
+2. 官方 `Codex CLI` 的 thread 存储与 `app-server` 可观察边界足以支撑 same-machine attach / resume。
+3. 用户理解“切回这里”需要显式动作；V1 不追求完全无确认的隐式抢占。
+
+### 11.2 风险
+
+1. `cliResumeRef` 的实际可得性，可能仍会受到官方实现版本差异影响；因此 V1 必须允许 `resumeCapability=not_ready` 的真实存在。
+2. 对 unmanaged CLI thread 的自动发现，如果候选很多，attach UX 可能不够轻；但这比错误 attach 更可接受。
+3. 如果实现团队把 transcript 镜像误当成必做项，范围会显著膨胀。
+
+### 11.3 待决问题
+
+1. `./ally.sh handoff codex <assistant> --open` 是否在 V1 就直接拉起官方 Codex，还是先只打印命令。
+2. `/status` 是否在本专题内补充展示 `activeSurface` 与 handoff readiness。
+3. desktop control plane 未来若要加“继续到 Codex”按钮，应复用本 spec 的同一 handoff service，而不是重做一套桌面私有逻辑。
+
+## 12. 实施建议
+
+建议实现顺序按用户价值切，而不是按工程模块切。
+
+### 阶段 1：把 `work_session` 与 ownership 合同落稳
+
+交付用户价值：
+
+- 连续工作对象正式成立
+- 渠道侧不会再静默乱抢会话
+
+### 阶段 2：打通 `work-ally -> Codex CLI`
+
+交付用户价值：
+
+- 用户可从渠道侧精确切回官方 Codex 继续同一条工作线程
+
+### 阶段 3：打通 `Codex CLI -> work-ally`
+
+交付用户价值：
+
+- 用户可把官方 Codex 中的工作接回手机侧继续
+
+### 阶段 4：补齐 attach、拒绝路径与真实回归
+
+交付用户价值：
+
+- CLI 直启线程也可纳管
+- 产品在歧义和异常场景下不会乱猜
+
+## 13. 给开发者的硬边界
+
+如果你是接手实现的人，这几条必须直接当成约束，而不是建议：
+
+1. 这次做的是“同一条真实工作线程的双向接续”，不是“把摘要复制到另一边继续聊”。
+2. `work_session` 是新的产品对象；如果你的实现里仍主要围绕 `conversationRef -> threadId` 做临时映射，说明你还没按 spec 重构到位。
+3. `runtimeThreadId` 与 `cliResumeRef` 必须分开；任何“当前版本看起来一样，所以先共用一个字段”的实现，都是不合格实现。
+4. 当 spec 没允许你自动猜的时候，就必须拒绝，不要帮用户脑补。
+5. owner 规则比“看起来方便”更重要；不能为了流畅表象把 single-active 做成静默双写。
+6. 本专题不是 transcript 镜像工程；不要把 scope 擅自扩成“官方 CLI 所有输出实时同步回 Feishu”。
+
+## 14. 进入实现后的文档纪律
+
+本文件是灯塔，不承担实时施工记录。
+
+一旦进入实现：
+
+- 必须在工程根目录维护 `TASK.md`
+- `TASK.md` 必须逐步拆成可执行任务，并为每个任务写清 DoD
+- 实施者每完成一个阶段，都要先更新 `TASK.md`，再进入下一步
+- 若实现过程中发现 spec 失效或边界变化，先回写本 spec，再继续开发
+
+换句话说：
+
+- `SPEC` 是灯塔
+- `TASK.md` 是路径
+- 两者缺一不可