work-ally 0.2.0-alpha.1

package/README.md

@@ -0,0 +1,403 @@
+# work-ally
+
+`work-ally` 是一个把**当前项目**接到**命名 assistant 办公桌 + 官方 Codex runtime**上的薄编排层。
+
+一句话：
+
+> `work-ally` 负责让 assistant 带着自己的办公桌进项目工作，但项目本身仍然是项目自己的地盘。
+
+这份 `README.md` 站在**工程维护者 / 后续产品开发者**视角写。
+
+如果你是：
+
+- 普通使用者（CLI）：先看 `docs/user-quickstart.md`
+- 产品同事：先看 `docs/product-onboarding.md`
+- 日常开发者：再看 `docs/developer-workflow.md`
+- 值班排障：再看 `docs/ops-runbook.md` 与 `docs/troubleshooting.md`
+
+## 文档地图
+
+项目级文档都留在仓库里，不放进 assistant desk。当前可以按这张地图理解：
+
+- 门面性文档：只描述当前 shipped model，不记录演进过程。包括 `PRODUCT.md`、`README.md`、`DASHBOARD.md`、`docs/user-quickstart.md`、`docs/product-onboarding.md`
+- 过程性文档：可以保留专题、阶段、取舍与演进轨迹，但不能保留已经失效的现状描述。包括 `docs/implementation/`、`docs/planning/`、`docs/completed/`
+
+- `PRODUCT.md`：产品介绍页、边界文档、长期灯塔，回答“这个产品到底是什么、不是什么、为什么存在”。
+- `README.md`：产品定位、当前 shipped model、仓库结构、运行边界、维护入口。
+- `DASHBOARD.md`：产品负责人 / 项目负责人的轻量驾驶舱，回答“现在在做什么、接下来派什么、哪些已经完成”。
+- `docs/architecture/`：灯塔文档与长期架构边界，回答“为什么这样做”。
+- `docs/implementation/`：实施主线、阶段进度、已完成范围，回答“已经做到哪里”。
+- `docs/implementation/test-coverage-map.md`：测试金字塔、MECE 测试域与门禁入口，回答“哪些链路已被自动化覆盖”。
+- `docs/completed/`：已完成专题与已落地 spec，回答“哪些专题已经收口”。
+- `docs/planning/`：feature spec、专项设计稿、下一阶段规划，回答“后面准备做什么”或“哪些点仍待确认”。
+- `docs/product-onboarding.md`：产品同事入场指引，回答“先看什么、按什么顺序看”。
+- `docs/user-quickstart.md`：CLI 用户从零到启动的主路径。
+- `docs/developer-workflow.md`：研发联调、验证入口、日常改动路径。
+- `docs/ops-runbook.md` 与 `docs/troubleshooting.md`：运行、恢复、值班和排障口径。
+- `docs/manual-acceptance.md`：人工验收清单。
+
+## 产品同事先看什么
+
+如果新同事更偏产品、先不看代码，推荐阅读顺序：
+
+1. `PRODUCT.md`：先建立产品边界、存在理由和长期灯塔。
+2. `README.md`：再建立当前结构、shipped model 与维护入口。
+3. `DASHBOARD.md`：再快速进入当前工作状态，确认在做什么、谁在做、下一步派什么。
+4. `docs/architecture/codex-feishu-bridge-proposal.md`：再理解这条产品线的第一性原理与长期架构。
+5. `docs/implementation/work-ally-implementation-guide.md`：再确认当前主线做到哪一步、哪些已经 shipped。
+6. `docs/completed/`：先看哪些专题已经收口，再避免重复规划。
+7. `docs/planning/`：最后看后续规划、存疑点和待推进专题。
+8. `docs/user-quickstart.md`：最后从当前 CLI 用户路径反看体验和产品暴露面。
+
+阅读旧文档时，若看到和当前实现不一致的历史表述，优先以本 `README.md`、项目 `AGENTS.md`，以及相关文档开头声明的 shipped model 为准。
+
+## 维护者先看什么
+
+先建立这张脑图：
+
+- 用户入口只有 `ally.sh`
+- shell 编排主干在 `internal/`
+- bridge 主干在 `bridge/src/`
+- 产品级 Skill 包在 `skills/`
+- 默认安装与升级走 npm（install-first）
+- 官方 Codex runtime 包装在 `runtime/`
+- assistant 长期资产在 `~/.work-ally/assistants/<name>/`
+- 运行期状态、日志、会话都在 assistant desk 的 `.system/`
+
+最常用的维护入口：
+
+- 命令分发：`internal/dispatch.sh`
+- 通用路径/状态/Git/锁：`internal/lib/common.sh`
+- assistant setup/remove/config 生成：`internal/modules/assistant/manage.sh`
+- 生命周期控制：`internal/modules/runtime/start.sh`、`internal/modules/runtime/stop.sh`、`internal/modules/runtime/supervisor.sh`、`internal/modules/runtime/status.sh`
+- bridge 启动入口：`bridge/src/server.ts`
+- 入站消息主流程：`bridge/src/receiver.ts`
+- 消息翻译与系统文案：`bridge/src/translator.ts`、`bridge/src/system-notify.ts`
+- Feishu 通道适配：`bridge/src/channels/feishu/adapter.ts`
+- 产品级 skills：`skills/`
+
+当前维护侧常用的工程 Skill：
+
+- `skills/product-spec/`：spec draft / refine / review / score
+- `skills/issue-to-spec-triage/`：把需求、问题、抱怨、想法先分诊，再决定是否进入 spec 流
+- `skills/post-implementation-closure/`：实现后做 review、回归、文档同步、状态回写与 commit readiness 收口
+- `skills/feishu-production-debug/`：按生产链路顺序排查 Feishu 消息问题
+
+维护时的默认检查顺序：
+
+1. 先看 `ally status`
+2. 再看 `ally logs bridge` / `ally logs runtime` / `ally logs supervisor`
+3. 再确认 assistant desk 的 `.system/runtime/` 与 `.system/archive/` 是否符合预期
+4. 最后才看 Codex 自己的 `codex-home/` 内部文件
+
+## CLI 用户主路径
+
+```bash
+ally setup <assistant-name> --workspace /path/to/project
+ally start --assistant <assistant-name>
+ally status --assistant <assistant-name>
+```
+
+这里的 `<assistant-name>` 是你给这位 assistant 起的本机名字，例如 `pm`、`reviewer`、`ally`；它不是固定值。
+
+`ally setup <assistant-name> --workspace /path/to/project` 会自动完成：
+
+- 创建 assistant 办公桌：`~/.work-ally/assistants/<assistant-name>/`
+- 在办公桌根目录初始化独立 Git 仓库
+- 生成最小配置：`~/.work-ally/assistants/<assistant-name>/.system/config.env`
+- 按默认模板生成 `SOUL.md`
+- 建立项目到 assistant 的绑定记录
+- 准备 assistant 自己的 `CODEX_HOME`
+
+如果后续要调整 assistant 的人格或表达风格，当前稳定公开路径下，直接打开 desk 里的 `SOUL.md` 手动编辑。
+
+用户默认只需要填写：
+
+- `FEISHU_APP_ID`
+- `FEISHU_APP_SECRET`
+- 可选：`WORK_ALLY_ALLOWED_USER_IDS`（逗号分隔；留空表示不限制，填写后按白名单严格限制）
+- 可选：`WORK_ALLY_ASSISTANT_GIT_REMOTE`
+
+模型 provider、模型选择、MCP、界面偏好等会参考系统全局 `~/.codex/config.toml` 生成 assistant 自己的初始 `config.toml`；API key 继续走系统环境变量，不写进 assistant 配置文件。
+另外，assistant 专属 `config.toml` 不会继承全局里其他项目的 trusted 列表，而是强制收敛成当前这一个项目根 `trusted` + 当前这个 assistant desk 根 `trusted`，并固定写入：`sandbox_mode = "workspace-write"`、`approval_policy = "on-request"`、以及 `sandbox_workspace_write.writable_roots = ["<assistant desk>"]`。
+
+命令审批这条链路当前也遵循“优先复用官方能力，不在中间层重造一套”的原则：
+
+- `work-ally` 会先自动放行当前项目根 / assistant desk 根内的低风险本地验证动作，例如常见的 `cmake` / `ctest` / `pytest` / `flutter analyze` / `dart test`
+- 若不属于这条本地验证 lane，再去读取官方 Codex 的 `~/.codex/rules/*.rules` 与 assistant-local `<assistant-codex-home>/rules/*.rules`
+- assistant-local rules 只做覆盖层，本地优先于全局
+- 当前实现是只读继承，不维护第二份 remembered-approval 数据库，也不在 bridge 里写 rules
+- rules 采用启动快照；如果你改了全局或 assistant-local rules，重启 assistant 后生效
+
+也就是说，`config.toml` 里通过 `env_key` 引用的 provider 环境变量，必须在你执行 `ally start` 的那个 shell 里可见；缺失时启动会直接失败。
+
+实现本身现在也区分两层：
+
+- `ally.sh` 所在源码树：开发态，可随时改动
+- npm 全局安装路径：install-first 运行入口（`ally`）
+
+也就是说，日常开发时你可以直接改仓库源码并联调；对外可安装版本通过 npm alpha 发布与升级，不再依赖本机 stable release 副本。
+
+另外，如果当前 Feishu 机器人还没有发消息权限，或仍处在审核 / 未发布状态，`ally start` 现在会直接失败。
+这是中间层的显式启动探测，不把“消息都发不出去”的状态误报成已经启动成功。
+
+## 当前 Shipped Model
+
+当前主线已经收口到这几个稳定点：
+
+- assistant desk 模型已经落地：`AGENTS.md`、`SOUL.md`、`NOW.md`、`MEMORY.md`、`MISTAKES.md`、`journal/`、`conversations/`
+- 黑匣子稳定原材料已经落到 `.system/archive/`，对话可读视图已经落到 `conversations/`
+- session 运行态已经固定收敛到 `.system/runtime/sessions/`
+- routine / scheduler 底座当前保留给产品内核；暂不把通用“定时任务”作为普通用户主打能力继续外推
+- nightly memory digest 当前只产出 `journal/` 与 `MEMORY.md`，不改写 `NOW.md`
+- nightly memory digest 完成后，如存在可用 Feishu 投递目标，会把本次提炼摘要作为系统消息主动通知用户
+- 新增 capability 已进入 `skill-first` 判断口径：可作为 Skill 包成立的能力，不优先长进 bridge / internal 核心
+- 当前长期边界采用 `Core / Hybrid / Skill` 三分法：桥接真相留 core，内容工作流优先走 Skill 或 Hybrid
+- `ally setup` 会自动准备 desk Git、最小配置文件、assistant 专属 `CODEX_HOME` 与 trusted project 条目
+- managed thread continuity baseline 已通过产品验收：单聊 `/codex`、`/takeover [handle]`、`/threads` 与本机 `ally new|continue|attach|threads --assistant <name>` 围绕独立 `work_session` 工作；严格区分 `runtimeThreadId` 与 `cliResumeRef`，不做摘要复制式伪连续
+- 真实 Codex runtime smoke 在当前环境仍受上游网络请求影响，因此这条线记为“主合同成立”，不记为“真实链路全绿”
+- managed thread continuity 仍保持显式接续语义：如果你要接回官方 Codex CLI 那条独立 work-session，请显式使用 `/takeover`；普通自然语言主路径不再读取 work-session owner
+- 会话降噪与协议对齐已落地：正常路径默认只保留 reaction ack 与真实 runtime 进度，不再补“已收到，开始处理。”或通用 heartbeat；普通自然语言 follow-up 会优先沿 `turn/steer` 进入当前 active turn，只有已对用户可见的审批 / 补充信息阻塞才会在桥层先拦住
+- bridge core thinning V2 已完成：普通自然语言主路径已不再读取 work-session ownership / attached session；work-session 目前只保留在 `/new`、`/takeover`、`/threads`、`/codex` 等显式控制命令路径；session / turn ledger / status surface 已删去一批厚状态字段，bridge core 进一步收回到“最小桥接真相”，且当前 `npm run test:bridge` 已全绿
+- 审批自治边界已落地：当前项目根与 assistant desk 根内的低风险本地验证、自测、改动与提交动作默认自动放行；assistant desk 不只 `.system/`，根目录长期资产也在默认自治边界内
+- 中间层异常透明化已落地：delivery unavailable 与最终仍无法确认的 turn 会明确告知；短暂 recovery、旧 turn 清理与内部 reconciliation 默认继续收回后台
+- 上一轮结果若已产生但当时未稳定送达，bridge 会在下一条 inbound 到来时优先自动补发上一轮结果
+
+当前 runtime 模型固定为：
+
+- `supervisor` 常驻托管 `bridge` 与 `assistant-autosave`
+- `bridge` 在本地按需拉起官方 `codex app-server --listen stdio://`
+- `bridge <-> Codex App Server` 之间不再使用独立 listen URL、端口分配或 `runtime-host` 独立后台服务
+- 最终结果以 `thread/read(includeTurns=true)` 与 session / turn ledger 为真相源
+
+推荐继续阅读顺序：
+
+1. 本 README：先建立产品边界、命令口径、目录结构与运行模型
+2. `docs/developer-workflow.md`：再看研发工作流与常规改动路径
+3. `docs/ops-runbook.md`：再看启动、重启、恢复、值班处理
+4. `docs/troubleshooting.md`：最后看典型故障与排查分支
+
+## 核心边界
+
+- `ally.sh` 是唯一用户入口
+- `skills/` 承接机制性 workflow，不承接主身份；不要把它们继续写回 bridge core
+- 发布入口为 npm alpha：`npm publish --tag alpha`（由 `npm run release:alpha` 统一执行）
+- 当前项目目录只承载项目代码与项目级 `AGENTS.md`
+- assistant 的身份、记忆、对话、运行态都进入 assistant 办公桌
+- 项目目录默认不会生成 `.work-ally/` 运行目录
+- 一个运行中的 ally 进程对应一个 assistant 办公桌
+- 同一个 assistant 不能同时跑在两个项目中
+- 同一个 Feishu bot/app 不能同时被两个项目占用
+- Feishu 普通最终回复默认走 Markdown-rich 渲染（普通内容走 `post`，表格/系统消息走 `interactive`）
+- Feishu reply 消息会自动提取被回复消息正文，并以 best-effort 方式带入 prompt 上下文
+- Feishu 群聊现已支持极简闭环：依赖飞书平台正确权限配置，仅处理群里显式 `@` 机器人的消息；如果配置了 allowlist，则只接受白名单内用户
+- 同一 assistant 在 Feishu 私聊与项目群里 `@` 是同一个角色入口，但会按 `conversationId` 落到两条独立 thread
+- 飞书平台最小权限前提已收口为三项：开启“读取用户发给机器人的单聊消息”、开启“接收群聊中@机器人消息事件”、不要开启“获取群组中所有消息（敏感权限）”
+- Skill 第一阶段只信任仓库内或用户自管的本地内容；当前不做远程 Skill market，不自造第二套插件平台
+
+## 办公桌结构
+
+默认目录：
+
+- `~/.work-ally/assistants/<name>/`
+
+用户可见内容：
+
+- `AGENTS.md`
+- `SOUL.md`
+- `NOW.md`
+- `MEMORY.md`
+- `MISTAKES.md`
+- `journal/`
+- `conversations/`
+
+内部系统目录：
+
+- `.system/config.env`
+- `.system/codex-home/`
+- `.system/runtime/`
+- `.system/logs/`
+- `.system/runs/`
+- `.system/cache/`
+- `.system/routines/`
+- `.system/archive/`
+
+说明：
+
+- `AGENTS.md` 是 desk 侧稳定规则与加载器
+- `SOUL.md` 是助理的人格、名字、风格和做事方式
+- `ally setup` 会预填一版通用 `SOUL.md`：中文优先、亲切直接、IM 短回复、先结论后补充、像给领导过目的简洁汇报；后续如果你要改人格，直接编辑 desk 里的 `SOUL.md`
+- `NOW.md` 是当前态便签，由 assistant 工作中主动更新
+- `MEMORY.md` 是长期记忆
+- `MISTAKES.md` 是错题本
+- `journal/` 是按天整理的工作日记
+- `conversations/` 是对话可读视图层
+- `.system/archive/` 是稳定原材料层，不是默认阅读界面
+- `.system/` 只放实现层与运行层所需的内部材料
+
+## Git 自动存档
+
+assistant 办公桌默认开启 Git：
+
+- 初始化时 `git init`
+- `ally start` 时 checkpoint
+- 后台 autosave 定时 checkpoint
+- `ally stop` 时 checkpoint
+- 配置远端后才会自动 push
+
+这套 Git 仓库位于 assistant 办公桌根目录，不在项目仓库里面，因此不会和宿主项目的 Git 冲突。
+
+默认会进入版本历史的是 assistant 的可见长期资产，以及 `.system/archive/` / `.system/routines/` 这类稳定材料；`.system/runtime/`、`.system/logs/`、`.system/cache/`、`.system/runs/`、`config.env`、以及 Codex 生成的 SQLite / snapshot / skills / tmp 内部文件不会进入版本库。
+
+## Feishu 侧当前默认行为
+
+- 普通最终回复：默认发送 Markdown-rich 消息，而不是纯文本降级
+- 表格 / 系统消息：继续走 card 路径
+- 用户输入提示 / 补充信息请求：仍保持纯文本，避免交互噪音
+- 用户在 Feishu 里直接“回复某条 AI 消息”时：ally 会尝试抓取被回复消息正文，再把这段正文带进本轮上下文
+- 在 Feishu 群聊里：只支持显式 `@` 机器人触发；普通群聊消息、reply assistant、以及裸控制命令都不作为正式支持路径
+- 长耗时处理中，如果 runtime 有中间进度文本，会优先按 Codex 的完整 item 边界回传“工作进展”弱提示卡；正常路径默认不再频繁补“正在处理 / 正在思考中”这类通用噪音，只有确有必要时才保留最小兜底
+- 需要审批时，Feishu 会发审批卡，里面会写清楚审批类型、动作、影响范围与原因；当前项目根与 assistant desk 根内的低风险本地验证、自测、改动和提交动作默认静默放行，高风险边界才继续要求人工拍板；当会话正在等审批时，你下一条消息若严格等于 `OK` / `同意` / `NO` / `拒绝`，会直接作为审批处理，不需要特地 reply 某张卡；若同一轮出现多项审批，前台会默认合并成一张卡；也仍可用 `/approve <id>` / `/deny <id>` 兜底
+- 最终结果默认由 `bridge` 主动对账 turn 终态；如果某一轮状态暂时无法确认，用户侧看到的是任务语义文案，而不是实现层的断开 / 重连术语
+- 如果上一轮结果其实已经产生但当时未稳定送达，bridge 会在你下一条消息到来时优先自动补发上一轮结果
+- 后台默认由 `supervisor` 常驻托管 `bridge` 与 `assistant-autosave`；Codex runtime 由 `bridge` 在本地以 stdio child-process 方式按需拉起并托管
+
+群聊使用口径可以直接理解为：
+
+- `@ally ...`：会触发
+- 普通群聊消息：不会触发
+- reply assistant 后继续追问：当前不作为支持路径
+- 群里裸 `/status`：当前不作为支持路径
+- reply 其他人的消息：不会触发
+
+另外：
+
+- 一个 assistant 对应一个独立飞书机器人身份
+- 私聊和群聊 `@` 都是在找同一位 assistant，但会进入各自独立的 thread
+- 飞书平台最小权限必须配对：开启“读取用户发给机器人的单聊消息”、开启“接收群聊中@机器人消息事件”、不要开启“获取群组中所有消息（敏感权限）”
+
+如果 `WORK_ALLY_ALLOWED_USER_IDS` 为空，则不额外限制发送者；一旦填写，就只接受列表里的用户。
+
+## 启动后先看什么
+
+建议 `ally start --assistant <name>` 后立刻跑一次：
+
+```bash
+ally status --assistant <name>
+```
+
+至少确认这些字段正常：
+
+- `assistant: <你的名字>`
+- `assistant home: ...`
+- `assistant codex home: ...`
+- `assistant lock status: owned`
+- `supervisor: running (...)`
+- `bridge: running (...)`
+- `assistant autosave: running (...)`
+
+## 命令作用域口径
+
+建议把命令分成两类来理解：
+
+- **assistant 作用域命令**：显式控制某个命名 assistant，可在任意目录执行
+- **机器作用域命令**：查看或控制“这台机器上所有正在运行的 ally 实例”
+
+assistant 作用域命令包括：
+
+- `ally start --assistant <name>`
+- `ally stop --assistant <name>`
+- `ally restart --assistant <name>`
+- `ally status --assistant <name>`
+- `ally logs ... --assistant <name>`
+- `ally mcp ... --assistant <name>`
+- `ally routine ... --assistant <name>`
+
+当某个 workspace 只绑定了一个 assistant 时，仍可保留最小隐式推断；但一旦同一项目绑定了多个 assistant，就必须显式带 `--assistant`。
+
+机器作用域命令目前主要是：
+
+- `ally global list`
+- `ally global stop --assistant <name>`
+- `ally global stop --pid <pid>`
+
+## 查看 assistant
+
+如果你要看“这台电脑上已经建过 / 注册过哪些 assistant”，先用：
+
+```bash
+ally assistant list
+```
+
+如果你要看“当前有几个 assistant 正在运行”，再用：
+
+```bash
+ally global list
+```
+
+也就是说：
+
+- `assistant list` 看已注册 assistant
+- `global list` 看当前运行中的 assistant 实例
+
+## 维护改动最容易漏什么
+
+后续维护时，优先记住这几个同步点：
+
+- 改命令语义：同步 `README.md`、`docs/user-quickstart.md`
+- 改 bridge 行为：至少补对应 unit / integration test，并回看 `docs/implementation/test-coverage-map.md` 的对应测试域
+- 改 shell 生命周期：至少跑 `bash -n` 和 `tests/shell/assistant.sh`
+- 改 assistant desk 结构：同步 README 里的“办公桌结构”与相关 quickstart / troubleshooting
+- 改审批、心跳、恢复、系统提示：同步用户文案与排障文档
+
+## 常用命令
+
+```bash
+ally setup <assistant-name> --workspace /path/to/project
+ally start --assistant <assistant-name>
+ally status --assistant <assistant-name>
+npm run release:alpha
+ally stop --assistant <assistant-name>
+ally restart --assistant <assistant-name>
+ally assistant list
+ally assistant show <name>
+ally assistant rename <old> <new>
+ally assistant remove <name>
+ally logs timeline --assistant <assistant-name>
+ally routine list --assistant <assistant-name>
+ally global list
+```
+
+## `ally status` 重点项
+
+至少应看到：
+
+- `assistant`
+- `assistant home`
+- `assistant codex home`
+- `assistant autosave`
+- `assistant lock status`
+- `channel lock status`
+- `workspace`
+- `supervisor`
+- `bridge`
+
+## Assistant 改名
+
+```bash
+ally assistant rename <old> <new>
+```
+
+这是一次受控迁移：会同步更新 assistant registry、project registry、desk 路径、`.system/config.env`、runtime `assistant.env`、stale lock，以及 managed thread continuity 使用的 work-session 索引与元数据。rename 完成后，旧名字不再是正式控制入口。
+
+rename 只会在 assistant 已停止，且没有被外部 surface 持有 active work session 时成功。
+
+## 删除 assistant
+
+```bash
+ally assistant remove <name>
+```
+
+这个命令会同时删除 assistant 办公桌、assistant 注册记录，以及所有指向该 assistant 的项目映射。
+
+这是危险操作，必须连续输入三次 `YES`。如果 assistant 仍在运行，删除会被拒绝。

package/ally.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+resolve_script_path() {
+  local source="$1"
+  while [ -h "$source" ]; do
+    local dir target
+    dir=$(cd -P "$(dirname "$source")" && pwd)
+    target=$(readlink "$source")
+    case "$target" in
+      /*)
+        source="$target"
+        ;;
+      *)
+        source="$dir/$target"
+        ;;
+    esac
+  done
+
+  local dir
+  dir=$(cd -P "$(dirname "$source")" && pwd)
+  printf '%s/%s\n' "$dir" "$(basename "$source")"
+}
+
+discover_workspace_root() {
+  if [ -n "${WORK_ALLY_WORKSPACE_ROOT:-}" ]; then
+    (cd "$WORK_ALLY_WORKSPACE_ROOT" && pwd)
+    return 0
+  fi
+
+  local start dir stop_at
+  start=$(cd "$PWD" && pwd)
+  dir="$start"
+  stop_at="${LOCAL_IMPLEMENTATION_ROOT:-}"
+
+  while :; do
+    if [ "$dir" != "$stop_at" ] && [ -d "$dir/.git" ]; then
+      printf '%s\n' "$dir"
+      return 0
+    fi
+
+    if [ "$dir" = "/" ]; then
+      break
+    fi
+
+    if [ -n "$stop_at" ] && [ "$dir" = "$stop_at" ]; then
+      break
+    fi
+
+    dir=$(dirname "$dir")
+  done
+
+  printf '%s\n' "$start"
+}
+
+SCRIPT_PATH=$(resolve_script_path "${BASH_SOURCE[0]}")
+SCRIPT_DIR=$(cd "$(dirname "$SCRIPT_PATH")" && pwd)
+INVOKED_NAME=$(basename "$0")
+BOOTSTRAP_ENV_FILE="${WORK_ALLY_BOOTSTRAP_ENV_FILE:-$SCRIPT_DIR/.ally-dev.env}"
+
+if [ -f "$BOOTSTRAP_ENV_FILE" ]; then
+  set -a
+  # shellcheck disable=SC1090
+  . "$BOOTSTRAP_ENV_FILE"
+  set +a
+fi
+
+IMPL_SUBDIR_DEFAULT="work-ally"
+IMPL_SUBDIR="${WORK_ALLY_IMPLEMENTATION_SUBDIR:-$IMPL_SUBDIR_DEFAULT}"
+SOURCE_DIR="${WORK_ALLY_SOURCE_DIR:-}"
+DEV_SOURCE_DIR="${WORK_ALLY_DEV_SOURCE_DIR:-}"
+LOCAL_DISPATCH="$SCRIPT_DIR/internal/dispatch.sh"
+LOCAL_IMPLEMENTATION_ROOT=""
+
+if [ -x "$LOCAL_DISPATCH" ]; then
+  LOCAL_IMPLEMENTATION_ROOT="$SCRIPT_DIR"
+fi
+
+WORKSPACE_ROOT="${WORK_ALLY_WORKSPACE_ROOT:-$(discover_workspace_root)}"
+STATE_DIR="${WORK_ALLY_STATE_DIR:-}"
+CMD_NAME="${WORK_ALLY_CMD_NAME:-$INVOKED_NAME}"
+
+usage() {
+  cat <<USAGE
+Usage: $CMD_NAME <command> [args]
+
+Commands:
+  setup              [assistant scope] Create or bind an assistant to a project path
+  assistant <subcmd> [global scope] Manage named assistant profiles
+  start              [assistant scope] Start a named assistant from anywhere
+  stop               [assistant scope] Stop a named assistant from anywhere
+  restart            [assistant scope] Restart a named assistant from anywhere
+  status             [assistant scope] Show status for a named assistant
+  logs [timeline|bridge|runtime|routine] [follow|print|--tail N]
+                     [assistant scope] View logs for a named assistant
+  update             [assistant scope] Show npm-based update guidance
+  codex              [assistant scope] Launch official Codex CLI with assistant-bound profile
+  new                [assistant scope] Start a new managed Codex thread in the assistant desk
+  continue           [assistant scope] Continue a managed Codex thread from the assistant desk
+  attach             [assistant scope] Attach an existing assistant-scoped Codex thread
+  threads            [assistant scope] List managed threads for an assistant
+  handoff <subcmd>   [assistant scope] Compatibility wrapper for Codex thread handoff commands
+  mcp <subcmd>       [assistant scope] Manage Codex MCP integrations (currently Feishu docs)
+  routine <subcmd>   [assistant scope] Manage proactive routines for a named assistant
+  thread-sync        [assistant scope] Pull full conversation history from active thread(s)
+  global <subcmd>    [machine scope] Show/stop running ally instances across assistants
+  help               Show this help
+USAGE
+}
+
+resolve_impl_dir() {
+  local root="$1"
+  if [ -x "$root/internal/dispatch.sh" ]; then
+    printf '%s\n' "$root"
+    return 0
+  fi
+  if [ -n "$IMPL_SUBDIR" ] && [ -x "$root/$IMPL_SUBDIR/internal/dispatch.sh" ]; then
+    printf '%s\n' "$root/$IMPL_SUBDIR"
+    return 0
+  fi
+  return 1
+}
+
+ensure_implementation() {
+  local source_override resolved_source
+  source_override="${SOURCE_DIR:-${DEV_SOURCE_DIR:-}}"
+
+  if [ -n "$source_override" ]; then
+    resolved_source=$(resolve_impl_dir "$source_override") || {
+      echo "✗ WORK_ALLY_SOURCE_DIR does not contain a valid implementation: $source_override" >&2
+      exit 1
+    }
+    export WORK_ALLY_INSTALL_ROOT="$source_override"
+    export WORK_ALLY_IMPLEMENTATION_DIR="$resolved_source"
+    export WORK_ALLY_INSTALL_CHANNEL="source"
+    return 0
+  fi
+
+  if [ -x "$LOCAL_DISPATCH" ]; then
+    export WORK_ALLY_INSTALL_ROOT="$SCRIPT_DIR"
+    export WORK_ALLY_IMPLEMENTATION_DIR="$SCRIPT_DIR"
+    export WORK_ALLY_INSTALL_CHANNEL="source_checkout"
+    return 0
+  fi
+
+  resolved_source=$(resolve_impl_dir "$SCRIPT_DIR") || {
+    echo "✗ work-ally implementation not found beside this entrypoint." >&2
+    echo "  Reinstall from npm or run with WORK_ALLY_SOURCE_DIR=<repo-root>." >&2
+    exit 1
+  }
+  export WORK_ALLY_INSTALL_ROOT="$SCRIPT_DIR"
+  export WORK_ALLY_IMPLEMENTATION_DIR="$resolved_source"
+  export WORK_ALLY_INSTALL_CHANNEL="installed"
+}
+
+CMD="${1:-help}"
+case "$CMD" in
+  help|-h|--help)
+    usage
+    exit 0
+    ;;
+  global|handoff|codex|new|continue|attach|threads|thread-sync)
+    export WORK_ALLY_SKIP_STATE_BOOTSTRAP=1
+    ;;
+esac
+
+ensure_implementation
+export WORK_ALLY_CMD_NAME="$CMD_NAME"
+export WORK_ALLY_WORKSPACE_ROOT="$WORKSPACE_ROOT"
+export WORK_ALLY_STATE_DIR="$STATE_DIR"
+exec "$WORK_ALLY_IMPLEMENTATION_DIR/internal/dispatch.sh" "$@"