chore: release v0.0.25

This reverts commit 4f8df12fb0.

.gitea/workflows/hub-check.yml

@@ -93,8 +93,8 @@ jobs:
 
       - name: Prove real Claude SDK Bash sandbox boundary
         run: |
-          sudo install -d -o "$(id -u)" -g "$(id -g)" -m 0700 /var/lib/cph-test
-          CPH_SANDBOX_TEST_ROOT=/var/lib/cph-test \
+          sudo install -d -o "$(id -u)" -g "$(id -g)" -m 0700 /w/t
+          CPH_SANDBOX_TEST_ROOT=/w/t \
             /usr/bin/setpriv --no-new-privs \
             npx vitest run test/integration/agent-sandbox-linux.test.ts
 

AGENTS.md

@@ -28,6 +28,19 @@
   service identity、workspace、keyring 与 Feishu/provider connection；进程必须由
   `HUB_SILO_ORGANIZATION_ID` fail-closed 绑定唯一 org，平台后台不开放。共享 SaaS
   控制面与 Docker adapter 后置(见 ADR-0025)。
+- Agent role 与 skill 是 Organization-scoped 动态运行配置：role 组合 model、system prompt、
+  tools 与已安装 skill；skill 版本进入 content-addressed 持久存储，run 只读加载所选快照。
+  每个 Organization 必须且只能有一个启用中的默认 role；新建群绑定从该默认值初始化，之后
+  `ProjectGroupBinding` 持久化群内当前 role，run 在接纳时冻结该 role。飞书公开 slash 协议只含
+  `/project`、`/usage`、`/help`；role、会话、目录操作走 `/project` 卡片，Claude 原生
+  `/compact` 只能由卡片动作以未经包装的精确 prompt 转发。
+  `settingSources: []` 继续禁用项目/用户配置加载，不得把任意 workspace `.claude` 配置变成
+  运行时能力(见 ADR-0018)。
+- 项目发现由 `ProjectDiscovery` 模块统一承载：PostgreSQL `pg_trgm` 搜索派生文档、项目编号
+  归一化、完整 Folder breadcrumb、MANAGE 授权过滤与分页都在该模块内；飞书卡片只是 adapter。
+  `Project`/`Folder` 仍是事实来源，搜索文档必须可重建且由数据库触发器同步，禁止调用方双写。
+  系统 `Inbox` 只作为未分类项目的内部落点，不作为业务 folder 暴露；已绑定群通过
+  `@bot /project` 随时打开项目管理卡片，重命名仍走 org-scoped MANAGE 授权与审计。
 
 ## 纪律
 

docs/adr/0017-agent-session-is-provider-bound.md

@@ -34,8 +34,36 @@ provider runtime cursor needed to continue a conversation. For Claude Code SDK,
 that cursor is the `result.session_id`; store it in `AgentSession.metadata` as
 `claudeSessionId` and pass it back to the next `query()` call as
 `options.resume`. Role is part of the session binding because role prompts and
-tool surfaces can differ even when the underlying model is the same; `/draft`
-and `/review` must not resume the same Claude runtime cursor by accident.
+tool surfaces can differ even when the underlying model is the same. A Feishu
+project group's active binding selects one Organization role for ordinary
+messages. Switching that selection routes future messages to the selected
+role's own session; it never mutates or merges provider cursors across roles.
+Work freezes the selected role when accepted so queued requests cannot drift
+after a later switch.
+
+Role definitions are Organization-scoped runtime data. A role bundle selects
+its default model, system prompt, tool allowlist and installed Agent skill
+versions. PostgreSQL is authoritative for role composition and skill metadata;
+skill bytes live in a content-addressed persistent store selected only by the
+recorded SHA-256 digest. Updating a role or binding skills takes effect without
+a Hub release or process restart. A change to the role's execution surface
+(model, prompt, tools, selected skill content) archives its active sessions so
+the next run cannot resume a provider context created under stale instructions;
+label and ordering-only changes preserve conversational continuity.
+
+Exactly one active role per Organization is the default used when a project
+group is first bound. The default is configuration data, not a hard-coded role
+name. Roles are selected through the Hub project console; role ids are not
+public slash commands. A project participant may change the group's shared
+selection only when both `agent.trigger` for the project and `role.trigger` for
+the target role authorize that actor. The selection affects every participant's
+future messages, while already accepted work keeps its frozen role.
+
+Hub slash commands are a closed control-plane protocol. Unknown commands fail
+explicitly and are never downgraded to Agent text. Claude SDK session commands
+are invoked only through typed Hub actions. In particular, compaction resumes
+the selected role session and sends the exact `/compact` prompt without
+prepending Feishu context.
 
 Environment variables:
 ```

docs/adr/0018-agent-execution-surface-bounded-by-workspace.md

@@ -93,22 +93,26 @@ The boundary is enforced by the Claude Code SDK's built-in sandbox
   its Bash subprocesses run sandboxed; if the sandbox can't start, `query()`
   emits an error and exits rather than running unsandboxed.
 - `sandbox.allowUnsandboxedCommands: false` — a tool cannot opt out with the
-  SDK's `dangerouslyDisableSandbox` input.
+  SDK's `dangerouslyDisableSandbox` input. Claude Code 2.1.202 does not enforce
+  that option reliably, so a host-side `PreToolUse` hook also denies every
+  Bash request whose input explicitly sets `dangerouslyDisableSandbox: true`
+  before a process can start.
 - `sandbox.filesystem.denyRead: ["/"]` with `allowRead` for the canonical
   current workspace and a small named system-runtime set — normal reads stay
   in the run's workspace while `/bin`, shared libraries, CA certificates,
   fonts and the configured `cph` executable remain available as the external
   tool exception described above.
-- `sandbox.filesystem.allowWrite: [workspaceDir]` confines every write to the
-  canonical ADR-0007 workspace. Config/cache/home stay beneath
-  `.cph/agent-runtime/`. `TMPDIR`, `TMP`, and `TEMP` use the absolute
-  workspace-local `.cph/t/` path so tools remain anchored after `cd`;
-  `CLAUDE_CODE_TMPDIR` uses the short relative `.cph/t` prefix, resolved from
-  the canonical workspace cwd, because the SDK's socat bridge otherwise falls
-  back to a host temp directory when its Unix-socket prefix is too long.
-  Root is denied for writes and only the canonical workspace is re-opened, so
-  `/tmp`, `/var/tmp`, sibling projects and every other host path are rejected.
-  There is no writable scratch exception outside the project directory.
+- `sandbox.filesystem.allowWrite: [workspaceDir]` confines persistent host
+  effects to the canonical ADR-0007 workspace. Config/cache/home stay beneath
+  `.cph/agent-runtime/`; `TMPDIR`, `TMP`, `TEMP`, and `CLAUDE_CODE_TMPDIR` all
+  point at the workspace-local `.cph/t`. The workspace allocator uses stable
+  compact Organization/Project path segments, deployment requires a short
+  workspace root, and the canonical temp prefix fails fast above 56 bytes so
+  the SDK can append randomized `socat` bridge socket names without exceeding
+  Linux `sockaddr_un.sun_path`. Bubblewrap shadows non-allowlisted host trees
+  with disposable tmpfs mounts: a shell write there may succeed inside that
+  private namespace, but it cannot mutate the corresponding host path. The
+  Linux proof checks host state after the sandbox exits.
 - The SDK subprocess environment replaces rather than spreads `process.env`.
   Only provider protocol variables and non-secret runtime variables cross the
   boundary; database, Feishu and Hub session credentials never enter it.
@@ -118,6 +122,16 @@ The boundary is enforced by the Claude Code SDK's built-in sandbox
 - `settingSources: []` and strict MCP configuration prevent an untrusted
   workspace or service-user config from widening tools, hooks, MCP servers, or
   sandbox paths.
+- Agent skills are Organization-scoped runtime configuration, not Hub release
+  assets. A controlled host-console installer imports each version into a
+  content-addressed persistent store and records its digest in PostgreSQL. A
+  role selects enabled Organization skills alongside its model, system prompt
+  and tool allowlist. Each run copies only those selected immutable versions
+  into a run-scoped plugin outside the project workspace; the sandbox exposes
+  that snapshot read-only and deletes it after the run. SDK-bundled skills and
+  filesystem setting sources remain disabled, so project `.claude` content
+  cannot register skills or widen tools. Requested skill versions are recorded
+  on `run.created`; SDK initialization remains authoritative loading evidence.
 - Network: open (see Open Questions).
 
 `bypassPermissions` is kept (headless server — no interactive prompts); the

docs/para-26071100-feishu-setup.md

@@ -1,81 +1,221 @@
-# para-26071100 飞书应用配置清单
+# Educraft 组织接入与飞书应用配置指南
 
-本文供 `para-26071100` 的飞书企业管理员操作。不要把 App Secret 粘贴到群聊、工单或本文档中；请通过约定的安全渠道交给平台部署人员。
+本文供准备接入 Educraft Alpha Silo 的学校、教培机构和组织管理员使用。完成本文后，请把末尾的“部署信息交付单”交给 Educraft 部署人员；我们会为组织创建独立的服务账号、数据库、运行目录和域名入口。
 
-## 1. 创建企业自建应用
+> **安全提醒：** App Secret、模型 Provider Token 属于密钥，禁止粘贴到飞书群、普通云文档、工单正文或截图中。请只通过双方约定的安全渠道传递。
 
-1. 打开飞书开放平台开发者后台。
-2. 在目标企业下创建“企业自建应用”。
-3. 应用名称可填写 `Educraft para-26071100`。
-4. 在“凭证与基础信息”记录：
-   - App ID（通常以 `cli_` 开头）
-   - App Secret
-5. 添加并启用“机器人”能力。
+## 1. 双方分别负责什么
 
-Bot Open ID 不需要管理员手工寻找。平台部署人员会使用 App ID/App Secret 调用飞书 Bot Info API 获取，并在 bootstrap 时校验它确实属于这一个应用。
+| 角色 | 负责事项 |
+| --- | --- |
+| 组织管理员 | 创建企业自建应用、启用机器人、开通最小权限、配置事件、回调和 OAuth 重定向 URL、发布应用、提供 OWNER 身份 |
+| Educraft 部署人员 | 分配组织 slug 和域名、部署独立 Silo、加密保存应用及模型密钥、初始化 OWNER、联调和验收 |
+| 试点 OWNER | 把机器人加入试点群、创建或绑定项目、组织首轮验收 |
 
-## 2. 开通权限
+## 2. 创建企业自建应用
 
-在“权限管理”中搜索并申请下列能力。飞书控制台的中文名称可能随版本调整；如控制台同时显示 scope，可优先核对括号中的 scope。
+1. 打开[飞书开放平台开发者后台](https://open.feishu.cn/app)。
+2. 在目标企业下点击“创建企业自建应用”。应用名称建议填写“Educraft + 组织简称”。
+3. 进入“凭证与基础信息”，记录 App ID 和 App Secret。
+4. 进入“添加应用能力”，添加并启用“机器人”。
 
-- 接收群聊中 @ 机器人的消息（`im:message.group_at_msg:readonly`）
-- 以应用身份发送消息（`im:message:send_as_bot`）
-- 获取消息内容，用于读取触发消息和线程上下文（`im:message:readonly`）
-- 获取与上传图片或文件资源（`im:resource`）
-- 添加、删除消息表情回复（`im:message.reactions:write_only`）
-- 获取用户基本信息（`contact:user.base:readonly`）
+![凭证与基础信息页面；App Secret 默认以星号隐藏](assets/feishu-setup/01-credentials.png)
 
-如果飞书 API 调试台提示某个上述操作缺少更细粒度权限，请把提示截图交给平台部署人员，不要直接勾选通讯录全量读取或其他超出清单的权限。
+App ID 通常以 `cli_` 开头，可以写入交付单。App Secret 必须通过安全渠道单独发送。Bot Open ID 不需要管理员手工查找；部署程序会用 App ID/App Secret 调用 Bot Info API 获取并校验归属。
 
-## 3. 配置事件与卡片回调
+## 3. 开通最小权限
 
-1. 进入“事件与回调”。
-2. 订阅方式选择“使用长连接接收事件”。
-3. 添加事件 `im.message.receive_v1`（接收消息）。
-4. 启用卡片交互回调 `card.action.trigger`，用于审批、中断运行和群聊建项目按钮。
-5. 不需要填写公网 Event Callback URL；Hub 使用飞书长连接。
+进入“权限管理”，点击“开通权限”，搜索并申请以下应用身份权限。控制台中文名称可能调整，请优先核对 scope。
 
-## 4. 配置 OAuth 回调
+| 用途 | Scope |
+| --- | --- |
+| 接收群聊中 @ 机器人的消息 | `im:message.group_at_msg:readonly` |
+| 以应用身份发送消息 | `im:message:send_as_bot` |
+| 读取触发消息和线程上下文 | `im:message:readonly` |
+| 获取与上传图片或文件 | `im:resource` |
+| 添加、删除消息表情回复 | `im:message.reactions:write_only` |
+| 获取用户基本信息 | `contact:user.base:readonly` |
+| 获取用户基本资料 | `contact:user.basic_profile:readonly` |
+| 通过手机号或邮箱查询 OWNER Open ID | `contact:user.id:readonly` |
 
-域名 DNS 和 TLS 生效后，在安全设置/重定向 URL 中添加：
+### 批量导入权限（推荐）
 
-```text
-https://para-26071100.educraft.paradigm-edu.net/auth/feishu/callback
+在“权限管理”页面点击“批量处理 → 导入”，粘贴以下 JSON 后确认。导入只会新增本次列出的权限，不会删除或影响应用已经申请、开通的其他权限。
+
+```json
+{
+  "scopes": {
+    "tenant": [
+      "im:message.group_at_msg:readonly",
+      "im:message:send_as_bot",
+      "im:message:readonly",
+      "im:resource",
+      "im:message.reactions:write_only",
+      "contact:user.base:readonly",
+      "contact:user.basic_profile:readonly",
+      "contact:user.id:readonly"
+    ],
+    "user": []
+  }
+}
 ```
 
-该回调用于 OWNER 登录受控的 Host Console。飞书群机器人长连接本身不依赖这个 URL。
+Educraft 机器人以应用身份调用上述 API，因此这些 scope 全部放在 `tenant`，不要为了省事把相同权限重复放进 `user`。
 
-## 5. 发布并安装应用
+![权限管理入口与已开通权限列表](assets/feishu-setup/02-permissions.png)
 
-1. 创建应用版本并提交企业管理员审核。
-2. 将应用可用范围至少包含试点 OWNER 和试点群成员。
-3. 发布版本。
-4. 将机器人加入准备试用的飞书群。
+如果 API 调试台提示缺少更细粒度权限，请把错误提示和发生时间截图给部署人员。不要自行开通通讯录全量读取等超出本表的权限。
 
-## 6. 获取首位 OWNER 身份
+## 4. 配置事件与卡片回调
 
-平台 bootstrap 需要 OWNER 的飞书 Open ID 和显示名称。可通过飞书 API 调试台的用户信息接口查询；Open ID 通常以 `ou_` 开头。Union ID 可选，不影响首次部署。
+进入“事件与回调”。
 
-请把以下结果通过安全渠道交给平台部署人员：
+1. 在“事件配置”中将订阅方式设为“使用长连接接收事件”。
+2. 添加事件“接收消息” `im.message.receive_v1`。
+3. 添加事件“解散群” `im.chat.disbanded_v1`，用于立即归档该群的项目绑定。
+4. 添加事件“机器人被移出群” `im.chat.member.bot.deleted_v1`，用于立即归档该群的项目绑定。
+5. 在“回调配置”中同样选择长连接。
+6. 添加回调“卡片回传交互” `card.action.trigger`，用于审批、运行中断和项目创建/绑定按钮。
+
+![长连接与消息事件配置](assets/feishu-setup/03-events.png)
+
+![卡片交互回调配置](assets/feishu-setup/04-callbacks.png)
+
+这里不需要填写公网 Event Callback URL。Educraft Hub 使用飞书官方 SDK 的长连接模式。
+
+## 5. 配置用户 OAuth 重定向 URL（必需）
+
+普通群成员首次使用前，需要通过飞书 OAuth 建立其在本应用下的用户身份。进入“安全设置 → 重定向 URL”，添加组织专属 callback：
 
 ```text
-Organization: para-26071100
-App ID: cli_...
-App Secret: （安全渠道发送）
-OWNER Open ID: ou_...
-OWNER 显示名称:
-OWNER Union ID: （可选）
-试点群名称: （可选，便于验收）
+https://<organization-slug>.educraft.paradigm-edu.net/auth/feishu/callback
 ```
 
-## 7. 验收动作
+例如组织 slug 为 `example-school`：
 
-平台通知部署完成后：
+```text
+https://example-school.educraft.paradigm-edu.net/auth/feishu/callback
+```
 
-1. OWNER 打开 Host Console，完成飞书 OAuth 登录。
-2. 在试点群中 @机器人发送一条纯文本消息。
-3. 如果群尚未绑定项目，机器人应返回项目创建/绑定卡片。
-4. 创建项目后再次 @机器人，确认出现处理状态、流式卡片和最终回答。
-5. 再测试一个小文件附件，以及运行中断按钮。
+![在安全设置中添加组织专属 OAuth 重定向 URL](assets/feishu-setup/05-security.png)
 
-任何一步失败时，请保留发生时间、群名、消息截图和飞书 request/log ID；不要在截图中包含 App Secret 或 Provider token。
+必须使用 Educraft 部署人员最终确认的 slug；不要直接照抄示例。该 URL 用于 OAuth 返回并创建应用作用域下的飞书用户身份，不代表当前已经开放组织管理台。
+
+组织专属 OAuth 同时完成身份建立和入组：首次成功登录的用户会自动成为当前 Organization 的 `MEMBER`，回到群聊即可使用。`OWNER` 和 `ADMIN` 仍只能由部署人员或管理员显式授予；曾被移除的成员重新登录不会自动恢复资格。
+
+## 6. 发布并安装应用
+
+1. 进入“版本管理与发布”，点击“创建版本”。
+2. 将应用可用范围至少覆盖试点 OWNER 和试点群成员。
+3. 提交企业管理员审核并发布。
+4. 发布成功后，将机器人加入准备试用的群。
+
+![版本管理与发布页面](assets/feishu-setup/06-publish.png)
+
+仅保存开发配置但未发布时，新增权限、事件和可用范围通常不会对试点用户生效。
+
+## 7. 获取首位 OWNER 身份
+
+首次部署必须指定一位组织 OWNER。OWNER 是 Educraft 组织内的初始管理员，不等同于飞书应用所有者；两者可以是同一个人，也可以不同。部署所需的 Open ID 必须由本次创建的企业自建应用查询，因为同一用户在不同应用下的 Open ID 不同，不能复用其他应用查到的值。
+
+### 7.1 确认 OWNER
+
+先确认哪一位企业成员将担任 OWNER。记录其飞书显示名称，并准备在飞书的成员选择器中按姓名找到本人。若企业内有同名成员，选择前须通过部门等信息核对身份。
+
+### 7.2 开通查询权限和数据范围
+
+确认应用已开通上文列出的用户基本信息和用户 ID 权限。如果使用上文的批量导入 JSON，这些权限已包含在内。
+
+应用的通讯录数据范围还必须覆盖这位 OWNER。最小做法是把 OWNER 加入应用可用范围；不需要为此开放全企业通讯录。
+
+### 7.3 在官方接口页面获取 Open ID
+
+1. 打开飞书开放平台的[“获取单个用户信息”接口页面](https://open.feishu.cn/document/server-docs/contact-v3/user/get)。如果使用带 `appId` 参数的页面链接，可以直接进入对应应用；本文不提供固定 App ID，请在页面顶部选择本组织刚创建的企业自建应用，并核对 App ID 与交付单一致。
+2. 找到路径参数 `user_id`，点击参数输入框旁的“获取”。
+3. 在成员选择器中找到并选择 OWNER；如有同名成员，依据部门等信息确认本人。
+4. ID 类型选择 `open_id`。将选择器返回的值填入 `user_id`，并保持查询参数 `user_id_type=open_id`。
+5. 以应用身份（`tenant_access_token`）调用接口，核对成功响应中 `data.user.name` 与 OWNER 本人一致。
+6. 复制完整的 `data.user.open_id` 交给 Educraft 部署人员。Open ID 通常以 `ou_` 开头。
+
+参数旁的“获取”是飞书文档调试台提供的成员选择功能，不是要求管理员预先知道 Open ID。不要复用其他应用查到的 Open ID；同一用户在不同应用下的 Open ID 不同。若无法选择成员或接口调用失败，依次检查：页面当前选择的 App ID、应用可用范围和通讯录数据范围是否覆盖 OWNER、用户基本信息与用户 ID 权限是否已开通并随应用版本发布。
+
+### 7.4 核对并交付
+
+交付前完成以下检查：
+
+- 返回用户的姓名与 OWNER 本人一致；
+- Open ID 来自本次组织的这一个 App ID；
+- Open ID 完整复制，没有空格或省略号；
+- 显示名称使用组织希望在 Educraft 中展示的姓名；
+- Union ID 不是必填项，查不到可以留空。
+
+最终向部署人员提供：
+
+```text
+OWNER Open ID：ou_...
+OWNER 显示名称：
+OWNER Union ID：（可选）
+用于查询的 App ID：cli_...
+```
+
+Open ID 和显示名称可以放在普通交付单中；不要把 App Secret 一起粘贴进去。
+
+## 8. 部署信息交付单
+
+请复制下面的模板填写。标注“安全渠道”的字段不要与普通字段放在同一条群消息或云文档中。
+
+```text
+【组织信息】
+组织正式名称：
+组织简称：
+期望 organization slug：（小写字母、数字和连字符，例如 example-school）
+期望机器人显示名称：
+
+【飞书应用】
+App ID：cli_...
+App Secret：（通过安全渠道单独发送）
+应用已发布：是 / 否
+机器人能力已启用：是 / 否
+消息事件（含解散群、机器人被移出群）和卡片回调已配置：是 / 否
+OAuth 重定向 URL 已配置：是 / 否
+
+【首位 OWNER】
+OWNER Open ID：ou_...
+OWNER 显示名称：
+OWNER Union ID：（可选）
+
+【试点范围】
+试点群名称：（可选，用于验收定位）
+初始 Team 名称：（可选；没有 Team 不影响首次部署）
+预计试用人数：
+
+【模型配置】
+Provider 名称：（例如 OpenRouter）
+Provider Base URL：
+Provider Token：（通过安全渠道单独发送）
+启用的模型 ID：
+```
+
+Educraft 部署人员收到信息后，会回传最终 organization slug、访问域名、部署窗口和验收时间。若期望 slug 已被占用或不符合命名规则，会在部署前协调调整。
+
+## 9. 上线验收
+
+部署人员通知服务就绪后，由 OWNER 完成：
+
+1. OWNER 在试点群中 @机器人发送一条纯文本消息。
+2. 如果群尚未绑定项目，确认机器人返回项目创建/绑定卡片。
+3. 创建项目后再次 @机器人，确认出现处理状态、流式卡片和最终回答。
+4. 选择一位非 OWNER 试点成员完成 OAuth 登录，确认其自动以 MEMBER 身份加入组织。
+5. 该成员在同一群中 @机器人，确认能够进入已绑定项目。
+6. 测试一个小文件附件、一次运行中断，以及一个需要生成文档的任务。
+
+出现问题时，请保留发生时间、群名、消息截图和飞书 request/log ID。截图前确认其中不包含 App Secret、Provider Token 或其他密钥。
+
+## 10. Alpha 阶段边界
+
+- 每个组织运行在独立的系统用户、服务实例、数据库和持久化目录中。
+- 组织的 role、system prompt、tools 和 skills 是运行时配置，不需要跟随版本发布。
+- 同一项目同一时间只执行一个任务，避免并发修改同一个 workspace；组织级并发上限由部署配置决定。
+- 当前由 Educraft 人工创建组织、OWNER、Provider Connection 和初始 Team，并通过服务器上的受控管理命令运维；组织管理台尚未开放。
+- 非 OWNER 试点成员通过组织专属 OAuth 首次登录后自动成为 MEMBER；OWNER/ADMIN 提权和被移除成员的恢复仍需人工操作。
+- Alpha 不提供开放注册、自助密钥管理或跨组织资源共享。

hub/deploy/NEW_SILO_RUNBOOK.md

@@ -0,0 +1,133 @@
+# New Alpha Silo runbook
+
+Use this runbook for a new Organization. A Silo is not merely another row in
+the existing database: it has an independent PostgreSQL role/database, Linux
+service identity, systemd unit, secret directory/keyring, workspace, skill
+store, loopback port, domain, Feishu app and provider credential.
+
+The repeatable entry point is:
+
+```sh
+bash hub/deploy/new_silo.sh
+```
+
+After collecting the Organization inputs, the wizard shows the assigned
+resources and asks once before applying them directly over SSH. The generated
+bundle is only a root-secret-safe retry and audit checkpoint; the operator does
+not execute it manually during the normal path.
+
+It gathers values and writes a private deployment bundle below
+`~/.cph-silo-plans/<instance-id>/`. The directory and all generated files are
+mode `0700`/`0600`. Never commit, paste into chat, or copy that directory into
+an immutable release. Run the wizard once per Organization; do not edit a copy
+from another Organization.
+
+## Inputs to collect
+
+The wizard derives the instance/Organization id from the slug, uses the current
+release and managed Alpha defaults, connects to the managed host (currently
+`39.107.254.4`), derives
+`https://<organization-slug>.educraft.paradigm-edu.net` from the wildcard DNS,
+and allocates an unused loopback port plus short workspace path by inspecting
+existing Silo environments, listening sockets and workspace paths over
+read-only SSH. The Organization administrator supplies:
+
+- Organization display name and slug;
+- Feishu App ID and App Secret (the wizard resolves the bot Open ID);
+- the first OWNER's Open ID and display name;
+- an Organization-exclusive OpenRouter token.
+
+Everything else is platform-managed or derived: instance/Organization id,
+server, SSH settings, release, resource ceilings, database coordinates and
+generated password, domain, port, workspace, provider/base URL, model/role,
+curated skills, concurrency, request/file limits and the managed Mihomo proxy
+environment. `NODE_USE_ENV_PROXY=1` is required on Node.js 24 so Hub's built-in
+`fetch` actually uses that proxy; merely setting `HTTP_PROXY`/`HTTPS_PROXY` is
+not sufficient.
+
+The Feishu app is scoped to this Silo. OAuth users authenticated by that app are
+automatically admitted to this Organization; OWNER remains the initial
+privileged membership used for controlled administration and bootstrap. An
+empty initial team list does not block the Alpha.
+
+To target a replacement platform-managed host, the platform operator may set
+`CPH_ALPHA_HOST`, `CPH_ALPHA_DEPLOY_USER`, `CPH_ALPHA_SSH_PORT` and
+`CPH_ALPHA_BASE_DOMAIN` before running the wizard. These are fleet controls,
+not Organization setup questions.
+
+Obtain a person's Open ID from the Feishu user-get documentation page by
+clicking the `user_id` value picker and selecting the person. Configure the
+redirect URL shown by the generated `OPERATE.md`; it is required for first-time
+OAuth admission.
+
+## Host prerequisites
+
+Before the first Silo on a host, install Node.js 24+, npm, rsync, PostgreSQL
+server/client, `pg_isready`, systemd, bubblewrap, socat, `runuser`, `setpriv`,
+`pg_dump`, tar, sha256sum, Nginx, Certbot, Typst and a compatible `cph` binary.
+Configure outbound proxying independently at host/service level and verify both
+GitHub and the selected model provider through it. The wizard does not install
+or select proxy nodes.
+
+Use a deployment account with only the required passwordless sudo operations.
+The application itself always runs as the installer-created non-root
+`cph-<instance-id>` user. PostgreSQL must have a separate login role and logical
+database per Silo even when all Silo databases share one PostgreSQL server.
+
+## Execute a generated bundle
+
+Open the bundle's `OPERATE.md` and perform its numbered gates in order:
+
+1. DNS, Feishu redirect URL, permissions and event subscription.
+2. Dedicated PostgreSQL role and database.
+3. Immutable release publication. Exit 78 is expected only when the first
+   installer call seeds this instance's keyring and environment template.
+4. Root-owned secret installation and off-host keyring recovery copy.
+5. Prisma migration, stopped service installation and idempotent bootstrap.
+6. Explicit runtime role/skill installation.
+7. Nginx/TLS, service start, internal/external health and Feishu acceptance.
+8. First off-host backup.
+
+Every command must fail fast. Do not add `|| true` around install, migration,
+bootstrap, Nginx validation, health, or backup checks. If a check fails, retain
+the unit logs and the exact failed stage before changing configuration.
+
+## Default runtime role and skills
+
+Roles and skills are dynamic Silo state, not release contents. The release
+contains only the management CLI. Stage approved skill directories on the host
+and install them with `agent_config.sh`; PostgreSQL records role definitions and
+skill selections while the versioned skill content lives in the Silo state
+directory and is included in backups.
+
+For the current Alpha, upsert the default role with the agreed education
+assistant system prompt, model selection, tools policy and approved skill list.
+Keep the prompt in a root-controlled staging file, pass it via
+`--system-prompt-file`, then verify with `agent_config.sh list`. Do not sync an
+operator's entire personal skill directory: each enabled skill must be reviewed
+and named explicitly. Typst being installed on the host and the Typst skill
+being enabled are separate gates.
+
+## Acceptance gate
+
+A Silo is ready only when all of the following pass:
+
+- its systemd service is active and both loopback and TLS health endpoints pass;
+- startup preflight sees exactly the configured Organization plus active Feishu
+  and provider connections;
+- OWNER completes OAuth and can interact with the bot;
+- a non-OWNER completes OAuth and can interact with the same app/Organization;
+- two Feishu groups bind distinct projects/sessions;
+- a restart preserves persisted session cursor behavior;
+- the configured provider/model succeeds through the host proxy;
+- every enabled skill is listed, and a Typst task succeeds if Typst is enabled;
+- the first business backup and separate recovery backup are stored off-host.
+
+## Rollback boundary
+
+For a failed code release, point only this instance back to the previous
+immutable release and rerun its installer with the same instance parameters.
+Do not roll back a database after migrations unless that release's documented
+database compatibility permits it. Preserve the environment, keyring, database,
+workspace and skill store. For destructive recovery, stop traffic and use the
+separate restore procedure; never substitute another Silo's state.

hub/deploy/README.md

@@ -1,5 +1,16 @@
 # Alpha Silo service installation
 
+For a brand-new Organization, start with the repeatable wizard and end-to-end
+operator runbook:
+
+```sh
+bash hub/deploy/new_silo.sh
+```
+
+See [NEW_SILO_RUNBOOK.md](NEW_SILO_RUNBOOK.md). The remainder of this document
+describes the individual installer and maintenance primitives used by the
+generated bundle.
+
 The supervised alpha runs one Organization per named Silo. The supported host
 has systemd, PostgreSQL, Node.js 24+, `pg_isready`, `runuser`, `setpriv`,
 bubblewrap, `socat`, `pg_dump`, `tar`, `sha256sum`, and a compatible `cph`.
@@ -15,6 +26,7 @@ Application code lives in immutable versioned directories under
 sudo BASE=/srv/curriculum-project-hub \
   HUB_DIR=/srv/curriculum-project-hub/releases/<release-id>/hub \
   INSTANCE_ID=org-a \
+  WORKSPACE_ROOT=/w/997 \
   PORT=8788 \
   MEMORY_MAX=16G CPU_QUOTA=400% TASKS_MAX=512 \
   bash /srv/curriculum-project-hub/releases/<release-id>/hub/deploy/install_service.sh
@@ -49,10 +61,38 @@ Default state paths are:
 ```text
 /var/lib/cph-hub/org-a/home
 /var/lib/cph-hub/org-a/state
-/var/lib/cph-hub/org-a/workspaces
+/w/997
 /var/cache/cph-hub/org-a
 ```
 
+Organization Agent roles and skills are runtime configuration. Skill versions
+are stored below the Silo state directory (`state/skills`) and are included in
+`backup_silo.sh` as `agent-skills.tar`; PostgreSQL stores role bundles, skill
+metadata and role-to-skill selection. Operate them as the Silo service user so
+content ownership remains correct:
+
+```sh
+sudo INSTANCE_ID=org-a \
+  ENV_FILE=/srv/curriculum-project-hub/.secrets/org-a/platform.env \
+  bash hub/deploy/agent_config.sh install-skill \
+  --organization org-a --source /staging/typst --version 1
+sudo INSTANCE_ID=org-a \
+  ENV_FILE=/srv/curriculum-project-hub/.secrets/org-a/platform.env \
+  bash hub/deploy/agent_config.sh upsert-role \
+  --organization org-a --role draft --label 草稿 --tools-json null
+sudo INSTANCE_ID=org-a \
+  ENV_FILE=/srv/curriculum-project-hub/.secrets/org-a/platform.env \
+  bash hub/deploy/agent_config.sh set-role-skills \
+  --organization org-a --role draft --skills outline,lesson-project,typst
+sudo INSTANCE_ID=org-a \
+  ENV_FILE=/srv/curriculum-project-hub/.secrets/org-a/platform.env \
+  bash hub/deploy/agent_config.sh list --organization org-a
+```
+
+`--tools-json null` means the full registered tool surface; `[]` means no
+ordinary tools. SDK-bundled skills and workspace/user setting sources remain
+disabled regardless of runtime configuration.
+
 ## Bootstrap the only Organization
 
 Prepare a root-owned `0600` JSON file containing
@@ -128,16 +168,24 @@ sudo INSTANCE_ID=org-a \
   bash hub/deploy/backup_silo.sh
 ```
 
-The business set contains the PostgreSQL custom dump and workspace archive. The
+The business set contains the PostgreSQL custom dump, workspace archive and
+`agent-skills.tar`. The
 separate recovery set contains the keyring and environment. Both include
 checksums; neither destination may be the live host's only disk.
 
-Restore into a separate drill database/workspace, verify checksums, then run:
+Restore into a separate drill database, workspace and skill-store directory;
+verify checksums before extracting both tar archives, then run:
 
 ```sh
 set -a; . /path/to/restored/platform.env; set +a
+mkdir -p "$HUB_PROJECT_WORKSPACE_ROOT" "$HUB_SKILL_STORE_ROOT"
+tar -xf /path/to/business/workspaces.tar -C "$HUB_PROJECT_WORKSPACE_ROOT"
+tar -xf /path/to/business/agent-skills.tar -C "$HUB_SKILL_STORE_ROOT"
 node hub/dist/deployment/restore-preflight.js \
   --keyring-file /path/to/restored/secret-keyring.json
+sudo INSTANCE_ID=org-a ENV_FILE=/path/to/restored/platform.env \
+  HUB_DIR=/path/to/restored/release/hub \
+  bash hub/deploy/agent_config.sh verify-store --organization org-a
 ```
 
 Traffic stays disabled until the sole Organization and every Feishu/provider

hub/deploy/agent_config.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+INSTANCE_ID="${INSTANCE_ID:?INSTANCE_ID required}"
+ENV_FILE="${ENV_FILE:?ENV_FILE required}"
+SERVICE_USER="${SERVICE_USER:-cph-$INSTANCE_ID}"
+HUB_DIR="${HUB_DIR:-/srv/curriculum-project-hub/current/hub}"
+
+[ "$(id -u)" -eq 0 ] || { echo "agent config console must run as root" >&2; exit 1; }
+[ -r "$ENV_FILE" ] || { echo "environment file is not readable: $ENV_FILE" >&2; exit 1; }
+[ -f "$HUB_DIR/dist/deployment/agent-config-cli.js" ] || { echo "Agent config CLI missing below $HUB_DIR" >&2; exit 1; }
+id "$SERVICE_USER" >/dev/null 2>&1 || { echo "service user missing: $SERVICE_USER" >&2; exit 1; }
+
+set -a
+# shellcheck disable=SC1090
+. "$ENV_FILE"
+set +a
+: "${DATABASE_URL:?DATABASE_URL missing from ENV_FILE}"
+: "${HUB_SILO_ORGANIZATION_ID:?HUB_SILO_ORGANIZATION_ID missing from ENV_FILE}"
+
+exec runuser --user "$SERVICE_USER" -- \
+  env -i \
+    DATABASE_URL="$DATABASE_URL" \
+    HUB_SILO_ORGANIZATION_ID="$HUB_SILO_ORGANIZATION_ID" \
+    HUB_SKILL_STORE_ROOT="${HUB_SKILL_STORE_ROOT:-/var/lib/cph-hub/$INSTANCE_ID/state/skills}" \
+    XDG_STATE_HOME="${XDG_STATE_HOME:-/var/lib/cph-hub/$INSTANCE_ID/state}" \
+    PATH="${PATH:-/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin}" \
+    node "$HUB_DIR/dist/deployment/agent-config-cli.js" "$@"

hub/deploy/apply_new_silo.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Apply a bundle produced by new_silo.sh to the managed Alpha host.
+set -euo pipefail
+
+BUNDLE="${1:?usage: apply_new_silo.sh BUNDLE_DIR}"
+ANSWERS="$BUNDLE/answers.env"
+[ -f "$ANSWERS" ] || { echo "missing $ANSWERS" >&2; exit 1; }
+
+value() { sed -n "s/^$1=//p" "$ANSWERS" | tail -n1; }
+INSTANCE_ID="$(value INSTANCE_ID)"
+ORG_ID="$(value ORGANIZATION_ID)"
+HOST="$(value DEPLOY_HOST)"
+SSH_USER="$(value DEPLOY_USER)"
+SSH_PORT="$(value DEPLOY_SSH_PORT)"
+SSH_KEY="$(value DEPLOY_SSH_KEY)"
+BASE="$(value DEPLOY_BASE)"
+RELEASE="$(value RELEASE_ID)"
+HUB_PORT="$(value HUB_PORT)"
+WORKSPACE="$(value WORKSPACE_ROOT)"
+MEMORY="$(value MEMORY_MAX)"
+CPU="$(value CPU_QUOTA)"
+TASKS="$(value TASKS_MAX)"
+DB_NAME="$(value DATABASE_NAME)"
+DB_USER="$(value DATABASE_USER)"
+DB_PASSWORD="$(value DATABASE_PASSWORD)"
+PUBLIC_URL="$(value PUBLIC_BASE_URL)"
+DOMAIN="${PUBLIC_URL#https://}"
+HUB_DIR="$BASE/releases/$RELEASE/hub"
+ENV_PATH="$BASE/.secrets/$INSTANCE_ID/platform.env"
+KEYRING_PATH="$BASE/.secrets/$INSTANCE_ID/secret-keyring.json"
+UNIT="cph-hub-$INSTANCE_ID.service"
+SSH=(ssh -i "$SSH_KEY" -p "$SSH_PORT" -o BatchMode=yes "$SSH_USER@$HOST")
+SCP=(scp -i "$SSH_KEY" -P "$SSH_PORT")
+
+for file in platform.env bootstrap.json default-role-prompt.md; do
+  [ -f "$BUNDLE/$file" ] || { echo "missing bundle file: $file" >&2; exit 1; }
+done
+
+echo "[1/8] Verify immutable release"
+"${SSH[@]}" "test -f '$BASE/releases/$RELEASE/.complete'"
+
+echo "[2/8] Create dedicated database"
+if ! "${SSH[@]}" "sudo -u postgres psql -Atqc \"select 1 from pg_database where datname='$DB_NAME'\"" | grep -qx 1; then
+  printf "CREATE ROLE %s LOGIN PASSWORD '%s';\nCREATE DATABASE %s OWNER %s;\n" \
+    "$DB_USER" "$DB_PASSWORD" "$DB_NAME" "$DB_USER" | "${SSH[@]}" sudo -u postgres psql -v ON_ERROR_STOP=1
+fi
+
+echo "[3/8] Seed instance keyring and service template"
+set +e
+"${SSH[@]}" "BASE='$BASE' HUB_DIR='$HUB_DIR' INSTANCE_ID='$INSTANCE_ID' WORKSPACE_ROOT='$WORKSPACE' PORT='$HUB_PORT' MEMORY_MAX='$MEMORY' CPU_QUOTA='$CPU' TASKS_MAX='$TASKS' bash '$HUB_DIR/deploy/install_service.sh'"
+status=$?
+set -e
+[ "$status" -eq 0 ] || [ "$status" -eq 78 ] || exit "$status"
+
+echo "[4/8] Upload root-only configuration"
+remote_stage="/root/.cph-bootstrap-$INSTANCE_ID"
+"${SSH[@]}" "install -d -o root -g root -m 0700 '$remote_stage'"
+"${SCP[@]}" "$BUNDLE/platform.env" "$BUNDLE/bootstrap.json" "$BUNDLE/default-role-prompt.md" "$SSH_USER@$HOST:$remote_stage/"
+"${SSH[@]}" "install -o root -g root -m 0600 '$remote_stage/platform.env' '$ENV_PATH'; chmod 0600 '$remote_stage/bootstrap.json' '$remote_stage/default-role-prompt.md'"
+
+echo "[5/8] Migrate, install, and bootstrap"
+"${SSH[@]}" "set -euo pipefail; set -a; . '$ENV_PATH'; set +a; node '$HUB_DIR/node_modules/prisma/build/index.js' migrate deploy --schema '$HUB_DIR/prisma/schema.prisma'; BASE='$BASE' HUB_DIR='$HUB_DIR' INSTANCE_ID='$INSTANCE_ID' WORKSPACE_ROOT='$WORKSPACE' PORT='$HUB_PORT' MEMORY_MAX='$MEMORY' CPU_QUOTA='$CPU' TASKS_MAX='$TASKS' bash '$HUB_DIR/deploy/install_service.sh'; node '$HUB_DIR/dist/deployment/bootstrap-silo-cli.js' --config-file '$remote_stage/bootstrap.json' --keyring-file '$KEYRING_PATH'"
+
+echo "[6/8] Copy curated skills and configure default role"
+"${SSH[@]}" "set -euo pipefail; stage='/var/lib/cph-hub/$INSTANCE_ID/state/operator-staging'; install -d -o cph-$INSTANCE_ID -g cph-$INSTANCE_ID -m 0700 \"\$stage/skills\"; install -o cph-$INSTANCE_ID -g cph-$INSTANCE_ID -m 0600 '$remote_stage/default-role-prompt.md' \"\$stage/default-role-prompt.md\"; for source in /var/lib/cph-hub/para-26071100/state/skills/versions/*; do name=\$(sed -n 's/^name: *//p' \"\$source/SKILL.md\" | head -n1); case \"\$name\" in outline|lesson-project|data-processing-spec|typst) cp -a \"\$source\" \"\$stage/skills/\$name\"; chown -R cph-$INSTANCE_ID:cph-$INSTANCE_ID \"\$stage/skills/\$name\";; esac; done; for name in outline lesson-project data-processing-spec typst; do INSTANCE_ID='$INSTANCE_ID' ENV_FILE='$ENV_PATH' HUB_DIR='$HUB_DIR' bash '$HUB_DIR/deploy/agent_config.sh' install-skill --organization '$ORG_ID' --source \"\$stage/skills/\$name\" --version 1; done; INSTANCE_ID='$INSTANCE_ID' ENV_FILE='$ENV_PATH' HUB_DIR='$HUB_DIR' bash '$HUB_DIR/deploy/agent_config.sh' upsert-role --organization '$ORG_ID' --role draft --label '智能助手' --system-prompt-file \"\$stage/default-role-prompt.md\" --tools-json null; INSTANCE_ID='$INSTANCE_ID' ENV_FILE='$ENV_PATH' HUB_DIR='$HUB_DIR' bash '$HUB_DIR/deploy/agent_config.sh' set-role-skills --organization '$ORG_ID' --role draft --skills outline,lesson-project,data-processing-spec,typst; rm -rf \"\$stage\""
+
+echo "[7/8] Configure Nginx and TLS"
+printf 'server { listen 80; listen [::]:80; server_name %s; client_max_body_size 2m; location / { proxy_pass http://127.0.0.1:%s; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_read_timeout 3600s; proxy_send_timeout 3600s; proxy_buffering off; } }\n' "$DOMAIN" "$HUB_PORT" | "${SSH[@]}" "install -o root -g root -m 0644 /dev/stdin '/etc/nginx/sites-available/$INSTANCE_ID'; ln -sfn '/etc/nginx/sites-available/$INSTANCE_ID' '/etc/nginx/sites-enabled/$INSTANCE_ID'; nginx -t; systemctl reload nginx; certbot --nginx --non-interactive --agree-tos --redirect --register-unsafely-without-email -d '$DOMAIN'"
+
+echo "[8/8] Start and verify"
+"${SSH[@]}" "systemctl enable --now '$UNIT'; systemctl is-active --quiet '$UNIT'; curl --fail --silent 'http://127.0.0.1:$HUB_PORT/api/healthz' >/dev/null; rm -f '$remote_stage/bootstrap.json'"
+curl --fail --silent --show-error "$PUBLIC_URL/api/healthz" >/dev/null
+echo "Deployed $INSTANCE_ID at $PUBLIC_URL"

hub/deploy/backup_silo.sh

@@ -9,6 +9,7 @@ KEYRING_FILE="${KEYRING_FILE:?KEYRING_FILE required}"
 BUSINESS_BACKUP_DIR="${BUSINESS_BACKUP_DIR:?BUSINESS_BACKUP_DIR required}"
 RECOVERY_BACKUP_DIR="${RECOVERY_BACKUP_DIR:?RECOVERY_BACKUP_DIR required}"
 SERVICE_UNIT="cph-hub-$INSTANCE_ID.service"
+SKILL_STORE_ROOT="${SKILL_STORE_ROOT:-/var/lib/cph-hub/$INSTANCE_ID/state/skills}"
 
 [ "$(id -u)" -eq 0 ] || { echo "backup must run as root" >&2; exit 1; }
 umask 077
@@ -37,12 +38,14 @@ set +a
 : "${DATABASE_URL:?DATABASE_URL missing from ENV_FILE}"
 : "${HUB_PROJECT_WORKSPACE_ROOT:?HUB_PROJECT_WORKSPACE_ROOT missing from ENV_FILE}"
 [ -d "$HUB_PROJECT_WORKSPACE_ROOT" ] || { echo "workspace root missing" >&2; exit 1; }
+[ -d "$SKILL_STORE_ROOT" ] || { echo "skill store root missing" >&2; exit 1; }
 
 install -d -o root -g root -m 0700 "$BUSINESS_BACKUP_DIR" "$RECOVERY_BACKUP_DIR"
 business_root="$(realpath -m "$BUSINESS_BACKUP_DIR")"
 recovery_root="$(realpath -m "$RECOVERY_BACKUP_DIR")"
 workspace_root="$(realpath -m "$HUB_PROJECT_WORKSPACE_ROOT")"
 secret_root="$(realpath -m "$(dirname "$KEYRING_FILE")")"
+skill_root="$(realpath -m "$SKILL_STORE_ROOT")"
 paths_overlap() {
   local left="$1" right="$2"
   [ "$left" = "$right" ] || [[ "$left/" == "$right/"* ]] || [[ "$right/" == "$left/"* ]]
@@ -58,6 +61,10 @@ for pair in \
     exit 1
   fi
 done
+if paths_overlap "$business_root" "$skill_root" || paths_overlap "$recovery_root" "$skill_root" || paths_overlap "$workspace_root" "$skill_root"; then
+  echo "backup destinations, workspace and skill store must not overlap: $skill_root" >&2
+  exit 1
+fi
 stamp="$(date -u +%Y%m%dT%H%M%SZ)"
 business="$business_root/$INSTANCE_ID-$stamp"
 recovery="$recovery_root/$INSTANCE_ID-$stamp"
@@ -65,13 +72,14 @@ install -d -o root -g root -m 0700 "$business" "$recovery"
 
 pg_dump --format=custom --file="$business/database.dump" "$DATABASE_URL"
 tar --create --file="$business/workspaces.tar" --directory="$HUB_PROJECT_WORKSPACE_ROOT" .
+tar --create --file="$business/agent-skills.tar" --directory="$SKILL_STORE_ROOT" .
 cp --preserve=mode,ownership,timestamps "$KEYRING_FILE" "$recovery/secret-keyring.json"
 cp --preserve=mode,ownership,timestamps "$ENV_FILE" "$recovery/platform.env"
 chmod 0600 "$recovery/secret-keyring.json" "$recovery/platform.env"
 
 (
   cd "$business"
-  sha256sum database.dump workspaces.tar > SHA256SUMS
+  sha256sum database.dump workspaces.tar agent-skills.tar > SHA256SUMS
 )
 (
   cd "$recovery"

hub/deploy/build_legacy_project_manifest.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import { readdir, readFile, realpath } from "node:fs/promises";
+import { dirname, relative, resolve, sep } from "node:path";
+
+const rootArgument = process.argv[2];
+if (!rootArgument) throw new Error("usage: build_legacy_project_manifest.mjs <legacy-workspaces-root>");
+const root = await realpath(rootArgument);
+const projectFiles = await findProjectFiles(root);
+const seenIds = new Set();
+const manifest = [];
+for (const projectFile of projectFiles) {
+  const metadata = JSON.parse(await readFile(projectFile, "utf8"));
+  if (typeof metadata.id !== "string" || metadata.id.trim() === "") {
+    throw new Error(`project metadata has no id: ${projectFile}`);
+  }
+  if (seenIds.has(metadata.id)) throw new Error(`duplicate project id: ${metadata.id}`);
+  seenIds.add(metadata.id);
+  if (typeof metadata.name !== "string" || metadata.name.trim() === "") {
+    throw new Error(`project metadata has no name: ${projectFile}`);
+  }
+  const projectRoot = dirname(projectFile);
+  const sourceRelativePath = relative(root, projectRoot).split(sep).join("/");
+  const physicalFolderPath = dirname(sourceRelativePath) === "."
+    ? []
+    : dirname(sourceRelativePath).split("/");
+  if (metadata.folderPath !== undefined && (
+    !Array.isArray(metadata.folderPath)
+    || metadata.folderPath.some((part) => typeof part !== "string")
+    || JSON.stringify(metadata.folderPath) !== JSON.stringify(physicalFolderPath)
+  )) {
+    process.stderr.write(`[legacy-manifest] stale metadata folderPath; using physical path: ${projectFile}\n`);
+  }
+  manifest.push({
+    legacyId: metadata.id,
+    name: metadata.name,
+    folderPath: physicalFolderPath,
+    sourceRelativePath,
+  });
+}
+manifest.sort((left, right) => left.sourceRelativePath.localeCompare(right.sourceRelativePath, "zh-CN"));
+process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
+
+async function findProjectFiles(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const projectMetadata = entries.find((entry) => entry.isFile() && entry.name === "project.json");
+  if (projectMetadata !== undefined) return [resolve(directory, projectMetadata.name)];
+  const found = [];
+  for (const entry of entries) {
+    if (entry.name === ".trash") continue;
+    const path = resolve(directory, entry.name);
+    if (entry.isSymbolicLink()) {
+      process.stderr.write(`[legacy-manifest] skip untracked symbolic link: ${path}\n`);
+      continue;
+    }
+    if (entry.isDirectory()) found.push(...await findProjectFiles(path));
+  }
+  return found;
+}

hub/deploy/cph-hub.service

@@ -18,6 +18,7 @@ EnvironmentFile=__ENV_FILE__
 Environment=HOME=__SERVICE_HOME__
 Environment=XDG_STATE_HOME=__STATE_DIR__
 Environment=XDG_CACHE_HOME=__CACHE_DIR__
+Environment=HUB_SKILL_STORE_ROOT=__SKILL_STORE_ROOT__
 Environment=PATH=__RUNTIME_PATH__
 # ADR-0024: the root-owned source remains unreadable by the service account;
 # systemd materializes a read-only per-unit credential at runtime.

hub/deploy/deploy_platform.sh

@@ -10,6 +10,7 @@
 #   PLATFORM_DEPLOY_BASE     optional, defaults to /srv/curriculum-project-hub
 #   PLATFORM_DEPLOY_RELEASE  optional immutable release id, defaults to git HEAD
 #   PLATFORM_DEPLOY_INSTANCE required, Silo instance id
+#   PLATFORM_DEPLOY_WORKSPACE_ROOT required short per-Silo path (for example /w/997)
 #   PLATFORM_DEPLOY_MEMORY_MAX / CPU_QUOTA / TASKS_MAX required ceilings
 #   PLATFORM_DEPLOY_HEALTH_URL optional, defaults to http://127.0.0.1:8788/api/healthz
 # The target host must have Node.js 24+, npm, rsync, PostgreSQL client tools
@@ -31,6 +32,7 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 RELEASE_ID="${PLATFORM_DEPLOY_RELEASE:-$(git -C "$REPO_ROOT" rev-parse --verify HEAD)}"
 [[ "$RELEASE_ID" =~ ^[A-Za-z0-9._-]+$ ]] || { echo "invalid PLATFORM_DEPLOY_RELEASE" >&2; exit 1; }
 INSTANCE_ID="${PLATFORM_DEPLOY_INSTANCE:?PLATFORM_DEPLOY_INSTANCE required}"
+WORKSPACE_ROOT="${PLATFORM_DEPLOY_WORKSPACE_ROOT:?PLATFORM_DEPLOY_WORKSPACE_ROOT required}"
 SERVICE_UNIT="cph-hub-$INSTANCE_ID.service"
 MEMORY_MAX="${PLATFORM_DEPLOY_MEMORY_MAX:?PLATFORM_DEPLOY_MEMORY_MAX required}"
 CPU_QUOTA="${PLATFORM_DEPLOY_CPU_QUOTA:?PLATFORM_DEPLOY_CPU_QUOTA required}"
@@ -67,11 +69,11 @@ fi
 ssh "${SSH_OPTS[@]}" "$DEPLOY_USER@$HOST" "
   set -euo pipefail
   if [ \"\$(id -u)\" = \"0\" ]; then
-    BASE='$BASE' HUB_DIR='$HUB_DIR' INSTANCE_ID='$INSTANCE_ID' PORT='$HUB_PORT' MEMORY_MAX='$MEMORY_MAX' CPU_QUOTA='$CPU_QUOTA' TASKS_MAX='$TASKS_MAX' bash '$HUB_DIR/deploy/install_service.sh'
+    BASE='$BASE' HUB_DIR='$HUB_DIR' INSTANCE_ID='$INSTANCE_ID' WORKSPACE_ROOT='$WORKSPACE_ROOT' PORT='$HUB_PORT' MEMORY_MAX='$MEMORY_MAX' CPU_QUOTA='$CPU_QUOTA' TASKS_MAX='$TASKS_MAX' bash '$HUB_DIR/deploy/install_service.sh'
     systemctl restart '$SERVICE_UNIT'
     systemctl is-active --quiet '$SERVICE_UNIT'
   else
-    sudo -n BASE='$BASE' HUB_DIR='$HUB_DIR' INSTANCE_ID='$INSTANCE_ID' PORT='$HUB_PORT' MEMORY_MAX='$MEMORY_MAX' CPU_QUOTA='$CPU_QUOTA' TASKS_MAX='$TASKS_MAX' bash '$HUB_DIR/deploy/install_service.sh'
+    sudo -n BASE='$BASE' HUB_DIR='$HUB_DIR' INSTANCE_ID='$INSTANCE_ID' WORKSPACE_ROOT='$WORKSPACE_ROOT' PORT='$HUB_PORT' MEMORY_MAX='$MEMORY_MAX' CPU_QUOTA='$CPU_QUOTA' TASKS_MAX='$TASKS_MAX' bash '$HUB_DIR/deploy/install_service.sh'
     sudo -n systemctl restart '$SERVICE_UNIT'
     sudo -n systemctl is-active --quiet '$SERVICE_UNIT'
   fi

hub/deploy/install_service.sh

@@ -23,7 +23,8 @@ SERVICE_GROUP="${SERVICE_GROUP:-$SERVICE_USER}"
 SERVICE_HOME="${SERVICE_HOME:-/var/lib/cph-hub/$INSTANCE_ID/home}"
 STATE_DIR="${STATE_DIR:-/var/lib/cph-hub/$INSTANCE_ID/state}"
 CACHE_DIR="${CACHE_DIR:-/var/cache/cph-hub/$INSTANCE_ID}"
-WORKSPACE_ROOT="${WORKSPACE_ROOT:-/var/lib/cph-hub/$INSTANCE_ID/workspaces}"
+SKILL_STORE_ROOT="${SKILL_STORE_ROOT:-$STATE_DIR/skills}"
+WORKSPACE_ROOT="${WORKSPACE_ROOT:?WORKSPACE_ROOT required (use a short per-Silo path such as /w/997)}"
 HOST="${HOST:-127.0.0.1}"
 PORT="${PORT:?PORT is required and must be unique on the host}"
 ENV_FILE="${ENV_FILE:-$BASE/.secrets/$INSTANCE_ID/platform.env}"
@@ -105,6 +106,7 @@ for pair in \
   "SERVICE_HOME:$SERVICE_HOME" \
   "STATE_DIR:$STATE_DIR" \
   "CACHE_DIR:$CACHE_DIR" \
+  "SKILL_STORE_ROOT:$SKILL_STORE_ROOT" \
   "WORKSPACE_ROOT:$WORKSPACE_ROOT" \
   "ENV_FILE:$ENV_FILE" \
   "KEYRING_FILE:$KEYRING_FILE" \
@@ -120,6 +122,7 @@ done
 [[ "$MEMORY_MAX" =~ ^[1-9][0-9]*[KMGT]$ ]] || fail "MEMORY_MAX must be a systemd byte size such as 16G"
 [[ "$CPU_QUOTA" =~ ^[1-9][0-9]*%$ ]] || fail "CPU_QUOTA must be a positive percentage such as 400%"
 [[ "$TASKS_MAX" =~ ^[1-9][0-9]*$ ]] || fail "TASKS_MAX must be a positive integer"
+[ "${#WORKSPACE_ROOT}" -le 16 ] || fail "WORKSPACE_ROOT must be at most 16 bytes for Agent sandbox sockets: $WORKSPACE_ROOT"
 
 KEYRING_CREATED=false
 if [ -L "$KEYRING_FILE" ]; then
@@ -280,6 +283,7 @@ provision_directory() {
 provision_directory "$SERVICE_HOME"
 provision_directory "$STATE_DIR"
 provision_directory "$CACHE_DIR"
+provision_directory "$SKILL_STORE_ROOT"
 provision_directory "$WORKSPACE_ROOT"
 
 # Resolve every provisioned path again and verify uid/gid/mode before writing
@@ -296,6 +300,7 @@ sed \
   -e "s|__SERVICE_HOME__|$SERVICE_HOME|g" \
   -e "s|__STATE_DIR__|$STATE_DIR|g" \
   -e "s|__CACHE_DIR__|$CACHE_DIR|g" \
+  -e "s|__SKILL_STORE_ROOT__|$SKILL_STORE_ROOT|g" \
   -e "s|__WORKSPACE_ROOT__|$WORKSPACE_ROOT|g" \
   -e "s|__HUB_DIR__|$HUB_DIR|g" \
   -e "s|__ENV_FILE__|$ENV_FILE|g" \
@@ -314,5 +319,5 @@ install -o root -g root -m 0644 "$TMP_UNIT" "$UNIT"
 systemctl daemon-reload
 systemctl enable "$SERVICE_UNIT"
 echo "[install] installed $SERVICE_UNIT for $SERVICE_USER:$SERVICE_GROUP"
-echo "[install] home=$SERVICE_HOME state=$STATE_DIR cache=$CACHE_DIR workspaces=$WORKSPACE_ROOT"
+echo "[install] home=$SERVICE_HOME state=$STATE_DIR cache=$CACHE_DIR skills=$SKILL_STORE_ROOT workspaces=$WORKSPACE_ROOT"
 echo "[install] start with: systemctl start $SERVICE_UNIT"

hub/deploy/new_silo.sh

@@ -0,0 +1,412 @@
+#!/usr/bin/env bash
+#
+# A wizard — walks a human through a manual procedure step by step.
+# Generated by the /wizard skill.
+#
+# Everything above the "STAGES" marker is the wizard library: do not hand-edit
+# it. Author the per-step stages below the marker.
+
+set -euo pipefail
+
+# ──────────────────────────────────────────────────────────────────────────
+# Wizard library — delightful, consistent UX. Identical across every wizard.
+# ──────────────────────────────────────────────────────────────────────────
+
+if [[ -t 1 ]] && command -v tput >/dev/null 2>&1 && [[ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]]; then
+  BOLD=$(tput bold); DIM=$(tput dim); RESET=$(tput sgr0)
+  BLUE=$(tput setaf 4); GREEN=$(tput setaf 2); YELLOW=$(tput setaf 3); RED=$(tput setaf 1)
+else
+  BOLD=""; DIM=""; RESET=""; BLUE=""; GREEN=""; YELLOW=""; RED=""
+fi
+
+# Author sets these two at the top of the stages section.
+TOTAL_STAGES=0
+TOTAL_MINUTES=0
+
+_STAGE_INDEX=0
+_MINUTES_ELAPSED=0
+ENV_FILE="${ENV_FILE:-.env}"
+WRITTEN_ENV=()    # KEYs written to ENV_FILE this run
+WRITTEN_SECRET=() # secret NAMEs set this run
+SKIPPED=()        # things we couldn't do (e.g. gh missing)
+
+# _clear — wipe the terminal so only the current step is on screen. No-op when
+# output isn't a terminal, so piped logs stay readable.
+_clear() {
+  [[ -t 1 ]] || return 0
+  if command -v tput >/dev/null 2>&1; then tput clear; else printf '\033[2J\033[3J\033[H'; fi
+}
+
+# banner "Title" — opening frame: what this wizard does and how long it takes.
+banner() {
+  _clear
+  printf '\n%s%s  %s%s\n' "$BOLD" "$BLUE" "$1" "$RESET"
+  printf '%s  %s stages · about %s minutes%s\n\n' \
+    "$DIM" "$TOTAL_STAGES" "$TOTAL_MINUTES" "$RESET"
+  printf '%s  You drive the browser; this wizard tells you exactly what to do and\n' "$DIM"
+  printf '  captures the values you copy back. Stop any time with Ctrl-C and re-run\n'
+  printf '  later — it remembers values already saved.%s\n' "$RESET"
+  pause "Ready to start?"
+}
+
+# stage "Name" <minutes> — clear the screen, then announce a stage and show
+# progress + time remaining. Clearing keeps only the current step on screen.
+stage() {
+  _clear
+  _STAGE_INDEX=$((_STAGE_INDEX + 1))
+  local remaining=$((TOTAL_MINUTES - _MINUTES_ELAPSED))
+  (( remaining < 0 )) && remaining=0
+  _MINUTES_ELAPSED=$((_MINUTES_ELAPSED + ${2:-0}))
+  printf '\n%s%s▸ Stage %s/%s · %s%s  %s(~%s min left)%s\n' \
+    "$BOLD" "$BLUE" "$_STAGE_INDEX" "$TOTAL_STAGES" "$1" "$RESET" "$DIM" "$remaining" "$RESET"
+}
+
+# say "..." — a plain instruction line.
+say()  { printf '  %s\n' "$1"; }
+# step "..." — a numbered-feeling action the human takes in the browser.
+step() { printf '  %s•%s %s\n' "$BLUE" "$RESET" "$1"; }
+note() { printf '  %s%s%s\n' "$DIM" "$1" "$RESET"; }
+warn() { printf '  %s⚠ %s%s\n' "$YELLOW" "$1" "$RESET"; }
+
+# open_url URL — open in the human's browser, cross-platform incl. WSL.
+open_url() {
+  local url="$1"
+  printf '  %s↗ opening%s %s\n' "$GREEN" "$RESET" "$url"
+  { if   command -v wslview     >/dev/null 2>&1; then wslview "$url"
+    elif command -v explorer.exe >/dev/null 2>&1; then explorer.exe "$url"
+    elif command -v xdg-open    >/dev/null 2>&1; then xdg-open "$url"
+    elif command -v open        >/dev/null 2>&1; then open "$url"
+    else warn "couldn't open a browser — visit it manually: $url"; fi
+  } >/dev/null 2>&1 || warn "couldn't open a browser — visit it manually: $url"
+}
+
+# pause "msg" — wait for the human to confirm they've done the manual part.
+pause() {
+  printf '  %s%s%s ' "$DIM" "${1:-Press Enter to continue}" "$RESET"
+  read -r _ || true
+}
+
+# confirm "question" — y/N gate; returns success on yes.
+confirm() {
+  local reply=""
+  printf '  %s? %s [y/N] ' "$YELLOW" "$1"
+  read -r reply || true
+  [[ "$reply" =~ ^[Yy] ]]
+}
+
+# _existing KEY — current value of KEY in ENV_FILE, if any.
+_existing() {
+  [[ -f "$ENV_FILE" ]] || return 1
+  local line; line=$(grep -E "^${1}=" "$ENV_FILE" | tail -n1) || return 1
+  printf '%s' "${line#*=}"
+}
+
+# ask KEY "Prompt" — read a value into $KEY. Offers the existing .env value as
+# a default on re-runs (Enter keeps it). Visible input (non-secret).
+ask() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -r input || true
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# ask_secret KEY "Prompt" — like ask, but input is hidden.
+ask_secret() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -rs input || true
+  printf '\n'
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# write_env KEY VALUE — upsert KEY=VALUE into ENV_FILE (creates it; replaces
+# any existing line). Idempotent.
+write_env() {
+  local key="$1" value="$2" tmp
+  touch "$ENV_FILE"
+  tmp=$(mktemp)
+  grep -vE "^${key}=" "$ENV_FILE" > "$tmp" || true
+  printf '%s=%s\n' "$key" "$value" >> "$tmp"
+  mv "$tmp" "$ENV_FILE"
+  WRITTEN_ENV+=("$key")
+  printf '  %s✓ wrote%s %s → %s\n' "$GREEN" "$RESET" "$key" "$ENV_FILE"
+}
+
+# set_secret NAME VALUE — set a GitHub Actions repo secret via gh. Falls back
+# to a warning (and records it) if gh is unavailable or unauthenticated.
+set_secret() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if printf '%s' "$value" | gh secret set "$name" >/dev/null 2>&1; then
+      WRITTEN_SECRET+=("$name")
+      printf '  %s✓ set%s GitHub secret %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub secret $name (set it manually: gh secret set $name)")
+  warn "skipped GitHub secret $name — gh not ready; set it later"
+}
+
+# set_var NAME VALUE — set a GitHub Actions repo variable (non-secret).
+set_var() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if gh variable set "$name" --body "$value" >/dev/null 2>&1; then
+      printf '  %s✓ set%s GitHub variable %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub variable $name")
+  warn "skipped GitHub variable $name — gh not ready; set it later"
+}
+
+# finish — clear, then a closing summary of everything configured.
+finish() {
+  _clear
+  printf '\n%s%s  ✓ Setup complete%s\n' "$BOLD" "$GREEN" "$RESET"
+  (( ${#WRITTEN_ENV[@]} ))    && note "wrote ${#WRITTEN_ENV[@]} value(s) to $ENV_FILE: ${WRITTEN_ENV[*]}"
+  (( ${#WRITTEN_SECRET[@]} )) && note "set ${#WRITTEN_SECRET[@]} GitHub secret(s): ${WRITTEN_SECRET[*]}"
+  if (( ${#SKIPPED[@]} )); then
+    printf '\n'; warn "still to do by hand:"
+    for s in "${SKIPPED[@]}"; do note "  - $s"; done
+  fi
+  printf '\n'
+}
+
+# ──────────────────────────────────────────────────────────────────────────
+# STAGES — author this section. One stage() per step the human takes.
+# Replace the example below. Set the two totals to match the stages you write.
+# ──────────────────────────────────────────────────────────────────────────
+
+TOTAL_STAGES=7
+TOTAL_MINUTES=35
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PLAN_ROOT="${CPH_SILO_PLAN_ROOT:-$HOME/.cph-silo-plans}"
+umask 077
+
+require_value() {
+  local key="$1" value="$2"
+  [[ -n "$value" ]] || { warn "$key is required"; exit 1; }
+  [[ "$value" != *$'\n'* && "$value" != *$'\r'* ]] || {
+    warn "$key must be a single line"
+    exit 1
+  }
+}
+
+seed_default() {
+  local key="$1" value="$2"
+  _existing "$key" >/dev/null 2>&1 || write_env "$key" "$value"
+}
+
+capture() {
+  local key="$1" prompt="$2"
+  ask "$key" "$prompt"
+  require_value "$key" "${!key}"
+  write_env "$key" "${!key}"
+}
+
+capture_secret() {
+  local key="$1" prompt="$2"
+  ask_secret "$key" "$prompt"
+  require_value "$key" "${!key}"
+  write_env "$key" "${!key}"
+}
+
+allocate_host_slot() {
+  local allocation local_reserved="" answers_file reserved_port
+  for answers_file in "$PLAN_ROOT"/*/answers.env; do
+    [ -f "$answers_file" ] || continue
+    reserved_port="$(sed -n 's/^HUB_PORT=//p' "$answers_file" | tail -n1)"
+    [[ "$reserved_port" =~ ^[0-9]+$ ]] || continue
+    local_reserved="${local_reserved:+$local_reserved,}$reserved_port"
+  done
+  allocation="$(ssh \
+    -i "$DEPLOY_SSH_KEY" \
+    -p "$DEPLOY_SSH_PORT" \
+    -o BatchMode=yes \
+    -o StrictHostKeyChecking=accept-new \
+    "$DEPLOY_USER@$DEPLOY_HOST" \
+    bash -s -- "$local_reserved" <<'REMOTE'
+      set -euo pipefail
+      local_reserved=",${1:-},"
+      for candidate in $(seq 8788 8999); do
+        reserved=false
+        if [[ "$local_reserved" == *",$candidate,"* ]]; then
+          continue
+        fi
+        for env_file in /srv/curriculum-project-hub/.secrets/*/platform.env; do
+          [ -f "$env_file" ] || continue
+          if [ "$(sed -n "s/^PORT=//p" "$env_file")" = "$candidate" ]; then
+            reserved=true
+            break
+          fi
+        done
+        workspace="/w/$candidate"
+        if [ "$reserved" = false ] && ! ss -H -ltn "sport = :$candidate" | grep -q . && [ ! -e "$workspace" ]; then
+          printf "%s %s\n" "$candidate" "$workspace"
+          exit 0
+        fi
+      done
+      echo "no free Alpha Silo slot in 8788..8999" >&2
+      exit 1
+REMOTE
+  )"
+  read -r HUB_PORT WORKSPACE_ROOT <<<"$allocation"
+  require_value HUB_PORT "$HUB_PORT"
+  require_value WORKSPACE_ROOT "$WORKSPACE_ROOT"
+  write_env HUB_PORT "$HUB_PORT"
+  write_env WORKSPACE_ROOT "$WORKSPACE_ROOT"
+}
+
+banner "New Alpha Silo"
+
+stage "Organization identity and private plan" 3
+say "One run creates one Organization's private deployment bundle."
+ask ORGANIZATION_SLUG "Organization slug (lowercase, max 24 chars; e.g. school-a):"
+require_value ORGANIZATION_SLUG "$ORGANIZATION_SLUG"
+[[ "$ORGANIZATION_SLUG" =~ ^[a-z0-9]([a-z0-9-]{0,22}[a-z0-9])?$ ]] || {
+  warn "invalid Organization slug"
+  exit 1
+}
+INSTANCE_ID="$ORGANIZATION_SLUG"
+ORGANIZATION_ID="$ORGANIZATION_SLUG"
+OUTPUT_DIR="$PLAN_ROOT/$INSTANCE_ID"
+mkdir -p "$OUTPUT_DIR"
+chmod 0700 "$OUTPUT_DIR"
+ENV_FILE="$OUTPUT_DIR/answers.env"
+touch "$ENV_FILE"
+chmod 0600 "$ENV_FILE"
+write_env INSTANCE_ID "$INSTANCE_ID"
+write_env ORGANIZATION_ID "$ORGANIZATION_ID"
+write_env ORGANIZATION_SLUG "$ORGANIZATION_SLUG"
+capture ORGANIZATION_NAME "Organization display name:"
+
+stage "Host, release, and isolation" 5
+say "The Alpha host is platform-managed. Port and short workspace path are allocated from live host state."
+DEPLOY_HOST="${CPH_ALPHA_HOST:-39.107.254.4}"
+DEPLOY_USER="${CPH_ALPHA_DEPLOY_USER:-root}"
+DEPLOY_SSH_PORT="${CPH_ALPHA_SSH_PORT:-22}"
+write_env DEPLOY_HOST "$DEPLOY_HOST"
+write_env DEPLOY_USER "$DEPLOY_USER"
+write_env DEPLOY_SSH_PORT "$DEPLOY_SSH_PORT"
+seed_default DEPLOY_BASE "/srv/curriculum-project-hub"
+seed_default DEPLOY_SSH_KEY "$HOME/.ssh/id_ed25519"
+write_env RELEASE_ID "v$(node -p 'require(process.argv[1]).version' "$REPO_ROOT/hub/package.json")"
+seed_default MEMORY_MAX "16G"
+seed_default CPU_QUOTA "400%"
+seed_default TASKS_MAX "512"
+seed_default CPH_BIN "/usr/local/bin/cph"
+note "Managed Alpha host: $DEPLOY_USER@$DEPLOY_HOST:$DEPLOY_SSH_PORT"
+DEPLOY_SSH_KEY="$(_existing DEPLOY_SSH_KEY)"
+MEMORY_MAX="$(_existing MEMORY_MAX)"
+CPU_QUOTA="$(_existing CPU_QUOTA)"
+TASKS_MAX="$(_existing TASKS_MAX)"
+[ -f "$DEPLOY_SSH_KEY" ] || { warn "managed SSH key is missing: $DEPLOY_SSH_KEY"; exit 1; }
+if [[ "$(_existing HUB_PORT || true)" =~ ^(878[8-9]|87[9][0-9]|8[89][0-9]{2})$ ]] && \
+   [ "$(_existing WORKSPACE_ROOT || true)" = "/w/$(_existing HUB_PORT)" ]; then
+  HUB_PORT="$(_existing HUB_PORT)"
+  WORKSPACE_ROOT="$(_existing WORKSPACE_ROOT)"
+  note "Keeping allocated host slot: port $HUB_PORT, workspace $WORKSPACE_ROOT"
+else
+  say "Checking existing Silo environments, listening sockets, and workspace paths..."
+  allocate_host_slot
+  note "Allocated host slot: port $HUB_PORT, workspace $WORKSPACE_ROOT"
+fi
+note "Platform ceilings: MemoryMax=$MEMORY_MAX, CPUQuota=$CPU_QUOTA, TasksMax=$TASKS_MAX"
+
+stage "Dedicated PostgreSQL database" 4
+say "A PostgreSQL server may be shared, but this Silo gets a distinct login role and database."
+seed_default DATABASE_HOST "127.0.0.1"
+seed_default DATABASE_PORT "5432"
+seed_default DATABASE_NAME "cph_${INSTANCE_ID//-/_}"
+seed_default DATABASE_USER "cph_${INSTANCE_ID//-/_}"
+DATABASE_NAME="$(_existing DATABASE_NAME)"
+if ! _existing DATABASE_PASSWORD >/dev/null 2>&1; then
+  DATABASE_PASSWORD="$(openssl rand -base64 36 | tr -d '\n')"
+  write_env DATABASE_PASSWORD "$DATABASE_PASSWORD"
+fi
+note "The generated OPERATE.md uses an interactive/protected SQL path; the password is never put in a command argument."
+
+stage "Public URL and Feishu app" 9
+open_url "https://open.feishu.cn/app"
+say "Create or open the Organization's own app. Copy credentials from Credentials & Basic Info."
+PUBLIC_BASE_URL="https://${ORGANIZATION_SLUG}.${CPH_ALPHA_BASE_DOMAIN:-educraft.paradigm-edu.net}"
+write_env PUBLIC_BASE_URL "$PUBLIC_BASE_URL"
+note "Platform-assigned public URL: $PUBLIC_BASE_URL"
+capture FEISHU_APP_ID "Feishu App ID:"
+capture_secret FEISHU_APP_SECRET "Feishu App Secret:"
+say "Resolving the bot Open ID from Feishu..."
+FEISHU_BOT_OPEN_ID="$(printf '%s\0%s\0' "$FEISHU_APP_ID" "$FEISHU_APP_SECRET" | node "$SCRIPT_DIR/resolve_feishu_bot.mjs")"
+write_env FEISHU_BOT_OPEN_ID "$FEISHU_BOT_OPEN_ID"
+note "Resolved bot identity: $FEISHU_BOT_OPEN_ID"
+open_url "https://open.feishu.cn/document/server-docs/contact-v3/user/get"
+step "In the user/get page, click the user_id value picker, select the first OWNER, and copy the returned open_id."
+capture OWNER_OPEN_ID "OWNER Open ID (ou_...):"
+capture OWNER_DISPLAY_NAME "OWNER display name:"
+write_env OWNER_UNION_ID ""
+say "The exact redirect URL and acceptance steps will be written to OPERATE.md."
+
+stage "Provider and Alpha limits" 5
+say "Use a provider credential exclusive to this Organization. Host proxy setup is a separate prerequisite."
+seed_default PROVIDER_ID "openrouter"
+seed_default PROVIDER_BASE_URL "https://openrouter.ai/api"
+seed_default DEFAULT_MODEL "anthropic/claude-sonnet-5"
+seed_default DEFAULT_ROLE_ID "draft"
+seed_default DEFAULT_ROLE_LABEL "智能助手"
+seed_default MAX_TURNS "25"
+seed_default MAX_CONCURRENT_RUNS "4"
+seed_default MAX_RUN_SECONDS "900"
+seed_default HTTP_BODY_LIMIT_BYTES "1048576"
+seed_default MAX_FILES_PER_MESSAGE "8"
+seed_default MAX_FILE_BYTES "26214400"
+seed_default HTTP_REQUESTS_PER_MINUTE "120"
+seed_default FEISHU_EVENTS_PER_MINUTE "120"
+capture_secret PROVIDER_AUTH_TOKEN "Provider auth token:"
+for key in PROVIDER_ID PROVIDER_BASE_URL DEFAULT_MODEL DEFAULT_ROLE_ID DEFAULT_ROLE_LABEL \
+  MAX_TURNS MAX_CONCURRENT_RUNS MAX_RUN_SECONDS HTTP_BODY_LIMIT_BYTES \
+  MAX_FILES_PER_MESSAGE MAX_FILE_BYTES HTTP_REQUESTS_PER_MINUTE FEISHU_EVENTS_PER_MINUTE; do
+  printf -v "$key" '%s' "$(_existing "$key")"
+done
+write_env APPROVED_SKILLS "outline,lesson-project,data-processing-spec,typst"
+note "Platform runtime: OpenRouter, concurrency 4, default education role, curated skills."
+if ! _existing HUB_SESSION_SECRET >/dev/null 2>&1; then
+  command -v openssl >/dev/null 2>&1 || { warn "openssl is required"; exit 1; }
+  HUB_SESSION_SECRET="$(openssl rand -hex 32)"
+  write_env HUB_SESSION_SECRET "$HUB_SESSION_SECRET"
+fi
+
+stage "Render the private deployment bundle" 2
+say "This renders platform.env, bootstrap.json, deploy.env, nginx.conf and OPERATE.md."
+command -v node >/dev/null 2>&1 || { warn "Node.js is required to render safely"; exit 1; }
+node "$SCRIPT_DIR/render_new_silo_bundle.mjs" "$ENV_FILE" "$OUTPUT_DIR"
+chmod 0700 "$OUTPUT_DIR"
+chmod 0600 "$OUTPUT_DIR"/*
+say "Bundle: $OUTPUT_DIR"
+warn "It contains database, Feishu, provider and session secrets. Never commit or paste it."
+
+stage "Operator handoff and gates" 7
+say "The deployment package is an internal retry/audit checkpoint; you do not operate it manually."
+step "Target: $PUBLIC_BASE_URL → $DEPLOY_HOST:$HUB_PORT"
+step "Resources: database $DATABASE_NAME, workspace $WORKSPACE_ROOT, service cph-hub-$INSTANCE_ID"
+warn "Confirmation will create server, database, TLS, and runtime state."
+if confirm "Deploy this Organization now?"; then
+  bash "$SCRIPT_DIR/apply_new_silo.sh" "$OUTPUT_DIR"
+else
+  warn "deployment skipped; rerun the wizard later and keep existing answers"
+fi
+
+finish

hub/deploy/render_new_silo_bundle.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const [answersPath, outputPath] = process.argv.slice(2);
+if (!answersPath || !outputPath) {
+  throw new Error("usage: render_new_silo_bundle.mjs ANSWERS_ENV OUTPUT_DIR");
+}
+
+function parseAnswers(source) {
+  const values = new Map();
+  for (const [index, line] of source.split("\n").entries()) {
+    if (!line || line.startsWith("#")) continue;
+    const separator = line.indexOf("=");
+    if (separator < 1) throw new Error(`invalid answers line ${index + 1}`);
+    const key = line.slice(0, separator);
+    const value = line.slice(separator + 1);
+    if (!/^[A-Z][A-Z0-9_]*$/.test(key)) {
+      throw new Error(`invalid answers key on line ${index + 1}: ${key}`);
+    }
+    if (value.includes("\r") || value.includes("\n")) {
+      throw new Error(`multiline value is not supported: ${key}`);
+    }
+    values.set(key, value);
+  }
+  return values;
+}
+
+function required(values, key) {
+  const value = values.get(key);
+  if (!value) throw new Error(`missing required answer: ${key}`);
+  return value;
+}
+
+function optional(values, key, fallback = "") {
+  return values.get(key) || fallback;
+}
+
+function assertMatch(label, value, pattern) {
+  if (!pattern.test(value)) throw new Error(`invalid ${label}: ${value}`);
+}
+
+function envLine(key, value) {
+  if (/[\r\n]/.test(value)) throw new Error(`unsafe newline in ${key}`);
+  return `${key}=${value}`;
+}
+
+const answers = parseAnswers(await readFile(resolve(answersPath), "utf8"));
+const instanceId = required(answers, "INSTANCE_ID");
+const orgId = required(answers, "ORGANIZATION_ID");
+const orgSlug = required(answers, "ORGANIZATION_SLUG");
+const port = required(answers, "HUB_PORT");
+const workspaceRoot = required(answers, "WORKSPACE_ROOT");
+const publicBaseUrl = required(answers, "PUBLIC_BASE_URL").replace(/\/$/, "");
+const domain = new URL(publicBaseUrl).hostname;
+const databasePassword = required(answers, "DATABASE_PASSWORD");
+const databaseUrl = `postgresql://${encodeURIComponent(required(answers, "DATABASE_USER"))}:${encodeURIComponent(databasePassword)}@${required(answers, "DATABASE_HOST")}:${required(answers, "DATABASE_PORT")}/${encodeURIComponent(required(answers, "DATABASE_NAME"))}`;
+
+assertMatch("INSTANCE_ID", instanceId, /^[a-z0-9](?:[a-z0-9-]{0,22}[a-z0-9])?$/);
+assertMatch("organization slug", orgSlug, /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/);
+assertMatch("port", port, /^[1-9][0-9]{1,4}$/);
+assertMatch("database name", required(answers, "DATABASE_NAME"), /^[a-z_][a-z0-9_]*$/);
+assertMatch("database user", required(answers, "DATABASE_USER"), /^[a-z_][a-z0-9_]*$/);
+assertMatch("default role id", required(answers, "DEFAULT_ROLE_ID"), /^[a-z][a-z0-9-]*$/);
+assertMatch("release id", required(answers, "RELEASE_ID"), /^[A-Za-z0-9._-]+$/);
+if (!publicBaseUrl.startsWith("https://")) throw new Error("PUBLIC_BASE_URL must use https");
+for (const [label, value] of [
+  ["WORKSPACE_ROOT", workspaceRoot],
+  ["DEPLOY_BASE", required(answers, "DEPLOY_BASE")],
+  ["DEPLOY_SSH_KEY", required(answers, "DEPLOY_SSH_KEY")],
+  ["CPH_BIN", required(answers, "CPH_BIN")],
+]) {
+  if (!value.startsWith("/") || /\s/.test(value)) {
+    throw new Error(`${label} must be an absolute path without whitespace: ${value}`);
+  }
+}
+if (Number(port) > 65535) throw new Error(`invalid port: ${port}`);
+if (Buffer.byteLength(workspaceRoot) > 16) {
+  throw new Error(`WORKSPACE_ROOT exceeds the 16-byte sandbox socket limit: ${workspaceRoot}`);
+}
+
+const outputDir = resolve(outputPath);
+await mkdir(outputDir, { recursive: true, mode: 0o700 });
+await chmod(outputDir, 0o700);
+
+const base = required(answers, "DEPLOY_BASE");
+const release = required(answers, "RELEASE_ID");
+const releaseHub = `${base}/releases/${release}/hub`;
+const secretDir = `${base}/.secrets/${instanceId}`;
+const envPath = `${secretDir}/platform.env`;
+const keyringPath = `${secretDir}/secret-keyring.json`;
+const unit = `cph-hub-${instanceId}.service`;
+
+const platformEnv = [
+  "# Generated by hub/deploy/new_silo.sh. Install root:root mode 0600.",
+  envLine("NODE_ENV", "production"),
+  envLine("DATABASE_URL", databaseUrl),
+  envLine("HUB_SILO_ORGANIZATION_ID", orgId),
+  envLine("HUB_SYSTEMD_UNIT", unit),
+  envLine("CPH_BIN", required(answers, "CPH_BIN")),
+  envLine("HOST", "127.0.0.1"),
+  envLine("PORT", port),
+  envLine("HUB_PROJECT_WORKSPACE_ROOT", workspaceRoot),
+  envLine("HUB_PUBLIC_BASE_URL", publicBaseUrl),
+  envLine("HUB_SESSION_SECRET", required(answers, "HUB_SESSION_SECRET")),
+  envLine("HUB_AGENT_MAX_TURNS", required(answers, "MAX_TURNS")),
+  envLine("HUB_AGENT_MAX_CONCURRENT_RUNS", required(answers, "MAX_CONCURRENT_RUNS")),
+  envLine("HUB_AGENT_MAX_RUN_SECONDS", required(answers, "MAX_RUN_SECONDS")),
+  envLine("HUB_HTTP_BODY_LIMIT_BYTES", required(answers, "HTTP_BODY_LIMIT_BYTES")),
+  envLine("HUB_MAX_FILES_PER_MESSAGE", required(answers, "MAX_FILES_PER_MESSAGE")),
+  envLine("HUB_MAX_FILE_BYTES", required(answers, "MAX_FILE_BYTES")),
+  envLine("HUB_HTTP_REQUESTS_PER_MINUTE", required(answers, "HTTP_REQUESTS_PER_MINUTE")),
+  envLine("HUB_FEISHU_EVENTS_PER_MINUTE", required(answers, "FEISHU_EVENTS_PER_MINUTE")),
+  envLine("HUB_FEISHU_LISTENER_ENABLED", "true"),
+  envLine("HTTP_PROXY", "http://127.0.0.1:7890"),
+  envLine("HTTPS_PROXY", "http://127.0.0.1:7890"),
+  envLine("ALL_PROXY", "socks5h://127.0.0.1:7890"),
+  envLine("NO_PROXY", "127.0.0.1,localhost,::1"),
+  envLine("NODE_USE_ENV_PROXY", "1"),
+  envLine("ANTHROPIC_DEFAULT_SONNET_MODEL", "anthropic/claude-sonnet-5"),
+  envLine("CPH_SANDBOX_EXTRA_DENY_READ", `${envPath}:${keyringPath}`),
+  "",
+].join("\n");
+
+const bootstrap = {
+  organization: {
+    id: orgId,
+    slug: orgSlug,
+    name: required(answers, "ORGANIZATION_NAME"),
+  },
+  owner: {
+    openId: required(answers, "OWNER_OPEN_ID"),
+    displayName: required(answers, "OWNER_DISPLAY_NAME"),
+  },
+  feishu: {
+    appId: required(answers, "FEISHU_APP_ID"),
+    appSecret: required(answers, "FEISHU_APP_SECRET"),
+    botOpenId: required(answers, "FEISHU_BOT_OPEN_ID"),
+  },
+  provider: {
+    providerId: required(answers, "PROVIDER_ID"),
+    baseUrl: required(answers, "PROVIDER_BASE_URL"),
+    authToken: required(answers, "PROVIDER_AUTH_TOKEN"),
+  },
+  teams: [],
+};
+const ownerUnionId = optional(answers, "OWNER_UNION_ID");
+if (ownerUnionId) bootstrap.owner.unionId = ownerUnionId;
+
+const deployEnv = [
+  "# Source this file locally before deploy_platform.sh (contains no app/provider secrets).",
+  envLine("PLATFORM_DEPLOY_HOST", required(answers, "DEPLOY_HOST")),
+  envLine("PLATFORM_DEPLOY_SSH_KEY", required(answers, "DEPLOY_SSH_KEY")),
+  envLine("PLATFORM_DEPLOY_USER", required(answers, "DEPLOY_USER")),
+  envLine("PLATFORM_DEPLOY_PORT", required(answers, "DEPLOY_SSH_PORT")),
+  envLine("PLATFORM_DEPLOY_HUB_PORT", port),
+  envLine("PLATFORM_DEPLOY_BASE", base),
+  envLine("PLATFORM_DEPLOY_RELEASE", release),
+  envLine("PLATFORM_DEPLOY_INSTANCE", instanceId),
+  envLine("PLATFORM_DEPLOY_WORKSPACE_ROOT", workspaceRoot),
+  envLine("PLATFORM_DEPLOY_MEMORY_MAX", required(answers, "MEMORY_MAX")),
+  envLine("PLATFORM_DEPLOY_CPU_QUOTA", required(answers, "CPU_QUOTA")),
+  envLine("PLATFORM_DEPLOY_TASKS_MAX", required(answers, "TASKS_MAX")),
+  envLine("PLATFORM_DEPLOY_HEALTH_URL", `http://127.0.0.1:${port}/api/healthz`),
+  "",
+].join("\n");
+
+const nginx = `# Install as /etc/nginx/conf.d/${instanceId}.conf after obtaining TLS certificates.\nserver {\n  listen 80;\n  server_name ${domain};\n  return 301 https://$host$request_uri;\n}\n\nserver {\n  listen 443 ssl http2;\n  server_name ${domain};\n\n  ssl_certificate /etc/letsencrypt/live/${domain}/fullchain.pem;\n  ssl_certificate_key /etc/letsencrypt/live/${domain}/privkey.pem;\n\n  location / {\n    proxy_pass http://127.0.0.1:${port};\n    proxy_http_version 1.1;\n    proxy_set_header Host $host;\n    proxy_set_header X-Real-IP $remote_addr;\n    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n    proxy_set_header X-Forwarded-Proto https;\n  }\n}\n`;
+
+const defaultRolePrompt = `你是一位教育机构智能助手，服务于学校和教培机构的日常管理与协作。
+## 核心能力
+**教务管理**：熟悉排课调课、班级管理、课时统计、师资调度等常见管理流程。
+**教研支持**：理解课程设计、教案编写、例题/变式题、定理证明、随堂练习、阶段性测验、知识点拆解、大纲对标等教学业务概念。
+**数字化操作**：熟练使用shell命令行进行文件管理、批量处理、脚本编写、文本处理（grep/sed/awk等）、自动化任务；能协助处理Markdown、Typst等文档、表格数据、格式转换等。
+## 行为准则
+- **实事求是**：不确定时明确说明，能力边界外的任务如实告知，不为完成目标而编造信息或勉强输出
+- **简洁优先**：直接给出答案或方案，省略铺垫和客套
+- **按需展开**：仅在问题复杂或用户明确要求时提供详细说明
+- **结构清晰**：多步骤内容使用编号，便于飞书阅读
+- **可操作性**：涉及操作时给出具体命令或步骤
+保持专业、高效，像一位熟悉业务的同事。
+`;
+
+const operate = `# ${instanceId} deployment commands\n\nThis file contains no application/provider secrets. Run commands deliberately; do not source answers.env.\n\n## 1. DNS and Feishu\n\n- Point \`${domain}\` to \`${required(answers, "DEPLOY_HOST")}\`.\n- In the Feishu app, configure redirect URL: \`${publicBaseUrl}/auth/feishu/callback\`.\n- Enable the required bot/message/contact permissions and event subscription described in the customer setup document.\n\n## 2. Database (run as the PostgreSQL administrator)\n\nCreate one role and one database for this Silo. The password is in \`answers.env\`; use an interactive client or a protected SQL file, never a command-line argument.\n\n\`\`\`sql\nCREATE ROLE ${required(answers, "DATABASE_USER")} LOGIN PASSWORD '<copy DATABASE_PASSWORD from answers.env>';\nCREATE DATABASE ${required(answers, "DATABASE_NAME")} OWNER ${required(answers, "DATABASE_USER")};\n\`\`\`\n\n## 3. Publish the immutable release\n\nThe normal deploy script seeds the first-instance secrets and exits 78. That exit is expected only on this first pass.\n\n\`\`\`sh\nset -a; . ./deploy.env; set +a\nbash hub/deploy/deploy_platform.sh\n\`\`\`\n\n## 4. Install the generated secrets\n\nCopy \`platform.env\` and \`bootstrap.json\` to the server through a protected channel. On the server:\n\n\`\`\`sh\ninstall -d -o root -g root -m 0700 '${secretDir}'\ninstall -o root -g root -m 0600 platform.env '${envPath}'\ninstall -o root -g root -m 0600 bootstrap.json '/root/${instanceId}-bootstrap.json'\n# Copy ${keyringPath} to separate off-host recovery storage before continuing.\n\`\`\`\n\n## 5. Migrate, install the stopped service, and bootstrap\n\n\`\`\`sh\nset -a; . '${envPath}'; set +a\nnode '${releaseHub}/node_modules/prisma/build/index.js' migrate deploy --schema '${releaseHub}/prisma/schema.prisma'\nBASE='${base}' HUB_DIR='${releaseHub}' INSTANCE_ID='${instanceId}' WORKSPACE_ROOT='${workspaceRoot}' PORT='${port}' MEMORY_MAX='${required(answers, "MEMORY_MAX")}' CPU_QUOTA='${required(answers, "CPU_QUOTA")}' TASKS_MAX='${required(answers, "TASKS_MAX")}' bash '${releaseHub}/deploy/install_service.sh'\nnode '${releaseHub}/dist/deployment/bootstrap-silo-cli.js' --config-file '/root/${instanceId}-bootstrap.json' --keyring-file '${keyringPath}'\nrm -f '/root/${instanceId}-bootstrap.json'\n\`\`\`\n\n## 6. Runtime role and skills\n\nRuntime role/skill configuration is intentionally separate from the release. Follow NEW_SILO_RUNBOOK.md, staging each approved skill directory outside the immutable release, then use \`agent_config.sh\`. Do not silently copy a local personal skill collection.\n\n## 7. Nginx, start, and acceptance\n\nInstall \`nginx.conf\`, run \`nginx -t\`, reload Nginx, then:\n\n\`\`\`sh\nsystemctl start '${unit}'\nsystemctl is-active '${unit}'\ncurl --fail --silent --show-error 'http://127.0.0.1:${port}/api/healthz'\ncurl --fail --silent --show-error '${publicBaseUrl}/api/healthz'\njournalctl -u '${unit}' --since '-10 min' --no-pager\n\`\`\`\n\nAcceptance requires: Feishu OAuth completes, OWNER and a non-OWNER can @bot, a second group creates a separate project/session, Typst works when that skill is enabled, and restart preserves session cursor. Then take the first off-host backup.\n\n## 8. Later releases\n\nAfter the instance exists, source \`deploy.env\` with the new release id and run \`deploy_platform.sh\`. Never reuse another org's database, secret directory, workspace root, port, service identity, domain, Feishu app, or provider credential.\n`;
+
+const selectedSkills = optional(answers, "APPROVED_SKILLS");
+const roleInstructions = `
+## Appendix: default runtime role
+
+Copy \`default-role-prompt.md\` to \`/root/${instanceId}-default-role-prompt.md\`.
+After installing each reviewed skill with \`agent_config.sh install-skill\`, run:
+
+\`\`\`sh
+INSTANCE_ID=${JSON.stringify(instanceId)} ENV_FILE=${JSON.stringify(envPath)} HUB_DIR=${JSON.stringify(releaseHub)} bash ${JSON.stringify(`${releaseHub}/deploy/agent_config.sh`)} upsert-role --organization ${JSON.stringify(orgId)} --role ${JSON.stringify(required(answers, "DEFAULT_ROLE_ID"))} --label ${JSON.stringify(required(answers, "DEFAULT_ROLE_LABEL"))} --model ${JSON.stringify(required(answers, "DEFAULT_MODEL"))} --system-prompt-file ${JSON.stringify(`/root/${instanceId}-default-role-prompt.md`)} --tools-json null
+${selectedSkills ? `INSTANCE_ID=${JSON.stringify(instanceId)} ENV_FILE=${JSON.stringify(envPath)} HUB_DIR=${JSON.stringify(releaseHub)} bash ${JSON.stringify(`${releaseHub}/deploy/agent_config.sh`)} set-role-skills --organization ${JSON.stringify(orgId)} --role ${JSON.stringify(required(answers, "DEFAULT_ROLE_ID"))} --skills ${JSON.stringify(selectedSkills)}
+` : "# No skills selected in the wizard; set-role-skills remains an explicit operator step.\n"}INSTANCE_ID=${JSON.stringify(instanceId)} ENV_FILE=${JSON.stringify(envPath)} HUB_DIR=${JSON.stringify(releaseHub)} bash ${JSON.stringify(`${releaseHub}/deploy/agent_config.sh`)} list --organization ${JSON.stringify(orgId)}
+\`\`\`
+
+Changing a role's model, system prompt, tools or skill selection archives that
+role's existing sessions by design. Finish this setup before inviting Alpha users.
+`;
+
+async function privateWrite(name, contents) {
+  const path = resolve(outputDir, name);
+  await writeFile(path, contents, { encoding: "utf8", mode: 0o600 });
+  await chmod(path, 0o600);
+}
+
+await privateWrite("platform.env", platformEnv);
+await privateWrite("bootstrap.json", `${JSON.stringify(bootstrap, null, 2)}\n`);
+await privateWrite("deploy.env", deployEnv);
+await privateWrite("nginx.conf", nginx);
+await privateWrite("default-role-prompt.md", defaultRolePrompt);
+await privateWrite("OPERATE.md", `${operate}${roleInstructions}`);
+
+console.log(`Rendered private Silo bundle: ${outputDir}`);

hub/deploy/resolve_feishu_bot.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+const chunks = [];
+for await (const chunk of process.stdin) chunks.push(chunk);
+const [appId, appSecret] = Buffer.concat(chunks).toString("utf8").split("\0");
+if (!appId || !appSecret) throw new Error("Feishu App ID and App Secret are required on stdin");
+
+const tokenResponse = await fetch("https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal", {
+  method: "POST",
+  headers: { "content-type": "application/json; charset=utf-8" },
+  body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+});
+if (!tokenResponse.ok) throw new Error(`Feishu token request failed: HTTP ${tokenResponse.status}`);
+const tokenPayload = await tokenResponse.json();
+if (tokenPayload.code !== 0 || typeof tokenPayload.tenant_access_token !== "string") {
+  throw new Error(`Feishu token request failed: ${JSON.stringify(tokenPayload)}`);
+}
+
+const botResponse = await fetch("https://open.feishu.cn/open-apis/bot/v3/info", {
+  headers: { authorization: `Bearer ${tokenPayload.tenant_access_token}` },
+});
+if (!botResponse.ok) throw new Error(`Feishu bot info request failed: HTTP ${botResponse.status}`);
+const botPayload = await botResponse.json();
+if (botPayload.code !== 0 || typeof botPayload.bot?.open_id !== "string" || !botPayload.bot.open_id) {
+  throw new Error(`Feishu bot info request failed: ${JSON.stringify(botPayload)}`);
+}
+process.stdout.write(botPayload.bot.open_id);

hub/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@paradigm/hub",
-  "version": "0.0.4",
+  "version": "0.0.25",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@paradigm/hub",
-      "version": "0.0.4",
+      "version": "0.0.25",
       "dependencies": {
         "@anthropic-ai/claude-agent-sdk": "^0.3.202",
         "@fastify/cookie": "^11.0.2",

hub/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigm/hub",
-  "version": "0.0.4",
+  "version": "0.0.25",
   "private": true,
   "type": "module",
   "engines": {
@@ -38,6 +38,7 @@
     "prisma:validate": "DATABASE_URL=${DATABASE_URL:-postgresql://stub:stub@127.0.0.1:5432/stub} prisma validate --schema prisma/schema.prisma",
     "prisma:migrate": "DATABASE_URL=${DATABASE_URL:-postgresql://paradigm:paradigm@127.0.0.1:5432/paradigm} prisma migrate deploy --schema prisma/schema.prisma",
     "secrets:rotate-kek": "node dist/deployment/rotate-secret-kek.js",
+    "agent-config": "node dist/deployment/agent-config-cli.js",
     "silo:bootstrap": "node dist/deployment/bootstrap-silo-cli.js",
     "silo:restore-preflight": "node dist/deployment/restore-preflight.js",
     "deploy": "bash deploy/deploy_platform.sh",

hub/prisma/migrations/20260711130000_dynamic_agent_roles_and_skills/migration.sql

@@ -0,0 +1,71 @@
+-- ADR-0017: Organization-scoped runtime role bundles and content-addressed
+-- skills. Composite foreign keys make cross-Organization role/skill bindings
+-- structurally impossible.
+CREATE TABLE "OrganizationAgentSkill" (
+    "id" TEXT NOT NULL,
+    "organizationId" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "version" TEXT NOT NULL,
+    "description" TEXT,
+    "contentDigest" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+    "disabledAt" TIMESTAMP(3),
+    CONSTRAINT "OrganizationAgentSkill_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "OrganizationAgentRole" (
+    "id" TEXT NOT NULL,
+    "organizationId" TEXT NOT NULL,
+    "roleId" TEXT NOT NULL,
+    "label" TEXT NOT NULL,
+    "defaultModel" TEXT,
+    "systemPrompt" TEXT,
+    "tools" JSONB,
+    "sortOrder" INTEGER NOT NULL DEFAULT 0,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+    "disabledAt" TIMESTAMP(3),
+    CONSTRAINT "OrganizationAgentRole_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "OrganizationAgentRoleSkill" (
+    "organizationId" TEXT NOT NULL,
+    "agentRoleId" TEXT NOT NULL,
+    "agentSkillId" TEXT NOT NULL,
+    "sortOrder" INTEGER NOT NULL DEFAULT 0,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT "OrganizationAgentRoleSkill_pkey" PRIMARY KEY ("organizationId", "agentRoleId", "agentSkillId")
+);
+
+CREATE UNIQUE INDEX "OrganizationAgentSkill_organizationId_name_key" ON "OrganizationAgentSkill"("organizationId", "name");
+CREATE UNIQUE INDEX "OrganizationAgentSkill_organizationId_id_key" ON "OrganizationAgentSkill"("organizationId", "id");
+CREATE INDEX "OrganizationAgentSkill_organizationId_disabledAt_idx" ON "OrganizationAgentSkill"("organizationId", "disabledAt");
+CREATE INDEX "OrganizationAgentSkill_contentDigest_idx" ON "OrganizationAgentSkill"("contentDigest");
+CREATE UNIQUE INDEX "OrganizationAgentRole_organizationId_roleId_key" ON "OrganizationAgentRole"("organizationId", "roleId");
+CREATE UNIQUE INDEX "OrganizationAgentRole_organizationId_id_key" ON "OrganizationAgentRole"("organizationId", "id");
+CREATE INDEX "OrganizationAgentRole_organizationId_disabledAt_sortOrder_idx" ON "OrganizationAgentRole"("organizationId", "disabledAt", "sortOrder");
+CREATE INDEX "OrganizationAgentRoleSkill_organizationId_agentRoleId_sortOrder_idx" ON "OrganizationAgentRoleSkill"("organizationId", "agentRoleId", "sortOrder");
+CREATE INDEX "OrganizationAgentRoleSkill_organizationId_agentSkillId_idx" ON "OrganizationAgentRoleSkill"("organizationId", "agentSkillId");
+
+ALTER TABLE "OrganizationAgentSkill" ADD CONSTRAINT "OrganizationAgentSkill_organizationId_fkey"
+  FOREIGN KEY ("organizationId") REFERENCES "Organization"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "OrganizationAgentRole" ADD CONSTRAINT "OrganizationAgentRole_organizationId_fkey"
+  FOREIGN KEY ("organizationId") REFERENCES "Organization"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "OrganizationAgentRoleSkill" ADD CONSTRAINT "OrganizationAgentRoleSkill_organizationId_agentRoleId_fkey"
+  FOREIGN KEY ("organizationId", "agentRoleId") REFERENCES "OrganizationAgentRole"("organizationId", "id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "OrganizationAgentRoleSkill" ADD CONSTRAINT "OrganizationAgentRoleSkill_organizationId_agentSkillId_fkey"
+  FOREIGN KEY ("organizationId", "agentSkillId") REFERENCES "OrganizationAgentSkill"("organizationId", "id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- Preserve current alpha behavior while moving role definitions into data.
+INSERT INTO "OrganizationAgentRole" (
+  "id", "organizationId", "roleId", "label", "sortOrder", "updatedAt"
+)
+SELECT "id" || ':agent-role:draft', "id", 'draft', '草稿', 10, CURRENT_TIMESTAMP
+FROM "Organization";
+
+INSERT INTO "OrganizationAgentRole" (
+  "id", "organizationId", "roleId", "label", "sortOrder", "updatedAt"
+)
+SELECT "id" || ':agent-role:review', "id", 'review', '审校', 20, CURRENT_TIMESTAMP
+FROM "Organization";

hub/prisma/migrations/20260712010000_project_discovery_search/migration.sql

@@ -0,0 +1,191 @@
+-- Derived project discovery projection. Project/Folder remain authoritative;
+-- triggers prevent index drift through ordinary database mutations.
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+
+CREATE TYPE "FolderKind" AS ENUM ('REGULAR', 'SYSTEM_INBOX');
+ALTER TABLE "Folder" ADD COLUMN "kind" "FolderKind" NOT NULL DEFAULT 'REGULAR';
+
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM "Folder"
+    WHERE "parentId" IS NULL AND "name" = 'Inbox' AND "archivedAt" IS NULL
+    GROUP BY "organizationId" HAVING count(*) > 1
+  ) THEN
+    RAISE EXCEPTION 'cannot identify system Inbox: organization has multiple active root Inbox folders';
+  END IF;
+END $$;
+
+UPDATE "Folder" f SET "kind" = 'SYSTEM_INBOX'
+WHERE f."parentId" IS NULL AND f."name" = 'Inbox' AND f."archivedAt" IS NULL;
+
+INSERT INTO "Folder" ("id", "organizationId", "parentId", "name", "kind", "sortKey", "createdAt", "updatedAt")
+SELECT o."id" || ':system-inbox', o."id", NULL, 'Inbox', 'SYSTEM_INBOX', '000000', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
+FROM "Organization" o
+WHERE NOT EXISTS (
+  SELECT 1 FROM "Folder" f
+  WHERE f."organizationId" = o."id" AND f."kind" = 'SYSTEM_INBOX' AND f."archivedAt" IS NULL
+);
+
+CREATE UNIQUE INDEX "Folder_one_active_system_inbox_per_org"
+  ON "Folder"("organizationId") WHERE "kind" = 'SYSTEM_INBOX' AND "archivedAt" IS NULL;
+
+CREATE OR REPLACE FUNCTION cph_protect_system_inbox() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF TG_OP = 'UPDATE' AND OLD."kind" = 'SYSTEM_INBOX' AND (
+    NEW."id" IS DISTINCT FROM OLD."id" OR
+    NEW."organizationId" IS DISTINCT FROM OLD."organizationId" OR
+    NEW."kind" IS DISTINCT FROM OLD."kind" OR
+    NEW."name" IS DISTINCT FROM OLD."name" OR
+    NEW."parentId" IS DISTINCT FROM OLD."parentId" OR
+    NEW."archivedAt" IS DISTINCT FROM OLD."archivedAt"
+  ) THEN
+    RAISE EXCEPTION 'system Inbox identity cannot be changed';
+  END IF;
+  IF TG_OP IN ('INSERT', 'UPDATE') AND NEW."kind" = 'SYSTEM_INBOX' AND (
+    NEW."name" <> 'Inbox' OR NEW."parentId" IS NOT NULL OR NEW."archivedAt" IS NOT NULL
+  ) THEN
+    RAISE EXCEPTION 'system Inbox must be an active root folder named Inbox';
+  END IF;
+  IF TG_OP = 'DELETE' AND OLD."kind" = 'SYSTEM_INBOX' AND EXISTS (
+    SELECT 1 FROM "Organization" WHERE "id" = OLD."organizationId"
+  ) THEN
+    RAISE EXCEPTION 'system Inbox cannot be deleted while its organization exists';
+  END IF;
+  RETURN CASE WHEN TG_OP = 'DELETE' THEN OLD ELSE NEW END;
+END;
+$$;
+
+CREATE TRIGGER cph_protect_system_inbox
+BEFORE INSERT OR UPDATE OR DELETE ON "Folder"
+FOR EACH ROW EXECUTE FUNCTION cph_protect_system_inbox();
+
+ALTER TABLE "Project" ADD COLUMN "code" TEXT;
+
+CREATE TABLE "ProjectSearchDocument" (
+    "projectId" TEXT NOT NULL,
+    "organizationId" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "code" TEXT,
+    "normalizedCode" TEXT NOT NULL,
+    "normalizedName" TEXT NOT NULL,
+    "breadcrumb" TEXT NOT NULL,
+    "normalizedBreadcrumb" TEXT NOT NULL,
+    "normalizedSearchText" TEXT NOT NULL,
+    "updatedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT "ProjectSearchDocument_pkey" PRIMARY KEY ("projectId")
+);
+
+CREATE INDEX "ProjectSearchDocument_organizationId_idx" ON "ProjectSearchDocument"("organizationId");
+CREATE INDEX "ProjectSearchDocument_normalizedName_trgm_idx"
+  ON "ProjectSearchDocument" USING GIN ("normalizedName" gin_trgm_ops);
+CREATE INDEX "ProjectSearchDocument_normalizedCode_trgm_idx"
+  ON "ProjectSearchDocument" USING GIN ("normalizedCode" gin_trgm_ops);
+CREATE INDEX "ProjectSearchDocument_normalizedBreadcrumb_trgm_idx"
+  ON "ProjectSearchDocument" USING GIN ("normalizedBreadcrumb" gin_trgm_ops);
+CREATE INDEX "ProjectSearchDocument_normalizedSearchText_trgm_idx"
+  ON "ProjectSearchDocument" USING GIN ("normalizedSearchText" gin_trgm_ops);
+
+ALTER TABLE "ProjectSearchDocument" ADD CONSTRAINT "ProjectSearchDocument_projectId_fkey"
+  FOREIGN KEY ("projectId") REFERENCES "Project"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "ProjectSearchDocument" ADD CONSTRAINT "ProjectSearchDocument_organizationId_fkey"
+  FOREIGN KEY ("organizationId") REFERENCES "Organization"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+CREATE OR REPLACE FUNCTION cph_project_search_normalize(value TEXT) RETURNS TEXT
+LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE AS $$
+  SELECT lower(regexp_replace(normalize(value, NFKC), '[[:space:]_.:/\\-]+', '', 'g'))
+$$;
+
+CREATE OR REPLACE FUNCTION cph_folder_breadcrumb(folder_id TEXT) RETURNS TEXT
+LANGUAGE sql STABLE PARALLEL SAFE AS $$
+  WITH RECURSIVE ancestors AS (
+    SELECT f."id", f."parentId", f."name", f."kind", 0 AS depth
+    FROM "Folder" f
+    WHERE f."id" = folder_id
+    UNION ALL
+    SELECT parent."id", parent."parentId", parent."name", parent."kind", child.depth + 1
+    FROM "Folder" parent
+    JOIN ancestors child ON parent."id" = child."parentId"
+  )
+  SELECT CASE
+    WHEN count(*) = 1 AND bool_and("kind" = 'SYSTEM_INBOX') THEN '未分类'
+    ELSE coalesce(string_agg("name", ' / ' ORDER BY depth DESC), '')
+  END
+  FROM ancestors
+$$;
+
+CREATE OR REPLACE FUNCTION cph_project_search_code(explicit_code TEXT, project_name TEXT) RETURNS TEXT
+LANGUAGE sql IMMUTABLE PARALLEL SAFE AS $$
+  SELECT CASE
+    WHEN explicit_code IS NOT NULL AND btrim(explicit_code) <> ''
+      THEN cph_project_search_normalize(explicit_code)
+    ELSE coalesce(substring(cph_project_search_normalize(project_name) FROM '^[a-z]+[0-9]+'), '')
+  END
+$$;
+
+CREATE OR REPLACE FUNCTION cph_refresh_project_search_document(target_project_id TEXT) RETURNS void
+LANGUAGE plpgsql AS $$
+BEGIN
+  INSERT INTO "ProjectSearchDocument" (
+    "projectId", "organizationId", "name", "code", "normalizedCode", "normalizedName",
+    "breadcrumb", "normalizedBreadcrumb", "normalizedSearchText", "updatedAt"
+  )
+  SELECT p."id", p."organizationId", p."name", p."code",
+    cph_project_search_code(p."code", p."name"),
+    cph_project_search_normalize(p."name"),
+    cph_folder_breadcrumb(p."folderId"),
+    cph_project_search_normalize(cph_folder_breadcrumb(p."folderId")),
+    cph_project_search_normalize(cph_folder_breadcrumb(p."folderId") || ' ' || p."name"),
+    CURRENT_TIMESTAMP
+  FROM "Project" p WHERE p."id" = target_project_id
+  ON CONFLICT ("projectId") DO UPDATE SET
+    "organizationId" = EXCLUDED."organizationId",
+    "name" = EXCLUDED."name",
+    "code" = EXCLUDED."code",
+    "normalizedCode" = EXCLUDED."normalizedCode",
+    "normalizedName" = EXCLUDED."normalizedName",
+    "breadcrumb" = EXCLUDED."breadcrumb",
+    "normalizedBreadcrumb" = EXCLUDED."normalizedBreadcrumb",
+    "normalizedSearchText" = EXCLUDED."normalizedSearchText",
+    "updatedAt" = CURRENT_TIMESTAMP;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION cph_project_search_project_trigger() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  PERFORM cph_refresh_project_search_document(NEW."id");
+  RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER cph_project_search_project_changed
+AFTER INSERT OR UPDATE OF "name", "code", "folderId", "organizationId", "archivedAt" ON "Project"
+FOR EACH ROW EXECUTE FUNCTION cph_project_search_project_trigger();
+
+CREATE OR REPLACE FUNCTION cph_project_search_folder_trigger() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE project_id TEXT;
+BEGIN
+  FOR project_id IN
+    WITH RECURSIVE descendants AS (
+      SELECT NEW."id"
+      UNION ALL
+      SELECT child."id" FROM "Folder" child
+      JOIN descendants parent ON child."parentId" = parent."id"
+    )
+    SELECT p."id" FROM "Project" p
+    WHERE p."folderId" IN (SELECT "id" FROM descendants)
+  LOOP
+    PERFORM cph_refresh_project_search_document(project_id);
+  END LOOP;
+  RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER cph_project_search_folder_changed
+AFTER UPDATE OF "name", "kind", "parentId", "archivedAt" ON "Folder"
+FOR EACH ROW EXECUTE FUNCTION cph_project_search_folder_trigger();
+
+SELECT cph_refresh_project_search_document("id") FROM "Project";

hub/prisma/migrations/20260713170000_project_group_selected_role/migration.sql

@@ -0,0 +1,65 @@
+-- ADR-0017: roles are selected through the project-group control plane, not
+-- through slash-command names. Existing alpha Organizations keep draft as
+-- their configured default during migration; runtime code no longer hard-codes it.
+ALTER TABLE "OrganizationAgentRole"
+  ADD COLUMN "isDefault" BOOLEAN NOT NULL DEFAULT false;
+
+-- An Organization without any role was valid in the previous schema (the
+-- runtime failed closed later). Preserve the old alpha baseline so every
+-- existing binding can acquire a selected role during this migration.
+INSERT INTO "OrganizationAgentRole" (
+  "id", "organizationId", "roleId", "label", "sortOrder", "isDefault", "updatedAt"
+)
+SELECT organization."id" || ':agent-role:draft', organization."id", 'draft', '草稿', 10, true, CURRENT_TIMESTAMP
+FROM "Organization" organization
+WHERE NOT EXISTS (
+  SELECT 1 FROM "OrganizationAgentRole" role
+  WHERE role."organizationId" = organization."id" AND role."disabledAt" IS NULL
+);
+
+WITH ranked AS (
+  SELECT "id", row_number() OVER (
+    PARTITION BY "organizationId"
+    ORDER BY CASE WHEN "roleId" = 'draft' THEN 0 ELSE 1 END, "sortOrder", "roleId", "id"
+  ) AS position
+  FROM "OrganizationAgentRole"
+  WHERE "disabledAt" IS NULL
+)
+UPDATE "OrganizationAgentRole" role
+SET "isDefault" = (ranked.position = 1)
+FROM ranked
+WHERE role."id" = ranked."id";
+
+CREATE UNIQUE INDEX "OrganizationAgentRole_one_active_default_per_org"
+  ON "OrganizationAgentRole"("organizationId")
+  WHERE "isDefault" = true AND "disabledAt" IS NULL;
+
+ALTER TABLE "ProjectGroupBinding"
+  ADD COLUMN "selectedAgentRoleId" TEXT;
+
+UPDATE "ProjectGroupBinding" binding
+SET "selectedAgentRoleId" = role."id"
+FROM "Project" project
+JOIN "OrganizationAgentRole" role
+  ON role."organizationId" = project."organizationId"
+ AND role."isDefault" = true
+ AND role."disabledAt" IS NULL
+WHERE binding."projectId" = project."id";
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM "ProjectGroupBinding" WHERE "selectedAgentRoleId" IS NULL) THEN
+    RAISE EXCEPTION 'cannot migrate project-group bindings without an active default Agent role';
+  END IF;
+END $$;
+
+ALTER TABLE "ProjectGroupBinding"
+  ALTER COLUMN "selectedAgentRoleId" SET NOT NULL;
+
+CREATE INDEX "ProjectGroupBinding_selectedAgentRoleId_idx"
+  ON "ProjectGroupBinding"("selectedAgentRoleId");
+
+ALTER TABLE "ProjectGroupBinding"
+  ADD CONSTRAINT "ProjectGroupBinding_selectedAgentRoleId_fkey"
+  FOREIGN KEY ("selectedAgentRoleId") REFERENCES "OrganizationAgentRole"("id")
+  ON DELETE RESTRICT ON UPDATE CASCADE;

hub/prisma/migrations/20260713173000_project_group_role_tenant_scope/migration.sql

@@ -0,0 +1,41 @@
+-- ADR-0017 / ADR-0020: enforce the selected role's Organization at the
+-- database boundary. A role primary key alone cannot prove tenant scope.
+ALTER TABLE "ProjectGroupBinding"
+  ADD COLUMN "organizationId" TEXT;
+
+UPDATE "ProjectGroupBinding" binding
+SET "organizationId" = project."organizationId"
+FROM "Project" project
+WHERE project."id" = binding."projectId";
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM "ProjectGroupBinding" WHERE "organizationId" IS NULL) THEN
+    RAISE EXCEPTION 'cannot tenant-scope project-group binding without a project Organization';
+  END IF;
+END $$;
+
+ALTER TABLE "ProjectGroupBinding"
+  ALTER COLUMN "organizationId" SET NOT NULL;
+
+CREATE UNIQUE INDEX "Project_organizationId_id_key"
+  ON "Project"("organizationId", "id");
+
+ALTER TABLE "ProjectGroupBinding"
+  DROP CONSTRAINT "ProjectGroupBinding_projectId_fkey",
+  DROP CONSTRAINT "ProjectGroupBinding_selectedAgentRoleId_fkey";
+
+ALTER TABLE "ProjectGroupBinding"
+  ADD CONSTRAINT "ProjectGroupBinding_organizationId_fkey"
+    FOREIGN KEY ("organizationId") REFERENCES "Organization"("id")
+    ON DELETE CASCADE ON UPDATE CASCADE,
+  ADD CONSTRAINT "ProjectGroupBinding_organizationId_projectId_fkey"
+    FOREIGN KEY ("organizationId", "projectId") REFERENCES "Project"("organizationId", "id")
+    ON DELETE CASCADE ON UPDATE CASCADE,
+  ADD CONSTRAINT "ProjectGroupBinding_organizationId_selectedAgentRoleId_fkey"
+    FOREIGN KEY ("organizationId", "selectedAgentRoleId")
+    REFERENCES "OrganizationAgentRole"("organizationId", "id")
+    ON DELETE RESTRICT ON UPDATE CASCADE;
+
+CREATE INDEX "ProjectGroupBinding_organizationId_idx"
+  ON "ProjectGroupBinding"("organizationId");

hub/prisma/migrations/20260713174500_agent_role_default_invariant/migration.sql

@@ -0,0 +1,31 @@
+-- ADR-0017: once an Organization starts configuring roles, every committed
+-- state must contain exactly one active default. The deferred trigger permits
+-- an atomic default switch while rejecting zero-default transitions.
+CREATE FUNCTION cph_enforce_agent_role_default() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE
+  target_organization_id TEXT := COALESCE(NEW."organizationId", OLD."organizationId");
+  active_default_count INTEGER;
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM "Organization" WHERE "id" = target_organization_id) THEN
+    RETURN NULL;
+  END IF;
+
+  SELECT count(*) INTO active_default_count
+  FROM "OrganizationAgentRole"
+  WHERE "organizationId" = target_organization_id
+    AND "isDefault" = true
+    AND "disabledAt" IS NULL;
+
+  IF active_default_count <> 1 THEN
+    RAISE EXCEPTION 'Organization % must have exactly one active default Agent role; found %',
+      target_organization_id, active_default_count;
+  END IF;
+  RETURN NULL;
+END;
+$$;
+
+CREATE CONSTRAINT TRIGGER "OrganizationAgentRole_exactly_one_active_default"
+AFTER INSERT OR UPDATE OR DELETE ON "OrganizationAgentRole"
+DEFERRABLE INITIALLY DEFERRED
+FOR EACH ROW EXECUTE FUNCTION cph_enforce_agent_role_default();

hub/prisma/migrations/20260713175000_agent_role_tenant_immutable/migration.sql

@@ -0,0 +1,30 @@
+-- Organization-owned role configuration cannot be re-parented. Besides being
+-- a tenant boundary, immutability ensures the deferred default-role invariant
+-- checks the same Organization before and after an update.
+CREATE OR REPLACE FUNCTION cph_enforce_agent_role_default() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE
+  target_organization_id TEXT := COALESCE(NEW."organizationId", OLD."organizationId");
+  active_default_count INTEGER;
+BEGIN
+  IF TG_OP = 'UPDATE' AND NEW."organizationId" <> OLD."organizationId" THEN
+    RAISE EXCEPTION 'OrganizationAgentRole.organizationId is immutable';
+  END IF;
+
+  IF NOT EXISTS (SELECT 1 FROM "Organization" WHERE "id" = target_organization_id) THEN
+    RETURN NULL;
+  END IF;
+
+  SELECT count(*) INTO active_default_count
+  FROM "OrganizationAgentRole"
+  WHERE "organizationId" = target_organization_id
+    AND "isDefault" = true
+    AND "disabledAt" IS NULL;
+
+  IF active_default_count <> 1 THEN
+    RAISE EXCEPTION 'Organization % must have exactly one active default Agent role; found %',
+      target_organization_id, active_default_count;
+  END IF;
+  RETURN NULL;
+END;
+$$;

hub/prisma/migrations/20260713175500_organization_requires_default_role/migration.sql

@@ -0,0 +1,25 @@
+-- ADR-0017's default-role function is total over Organizations. Enforce the
+-- other side of the invariant when an Organization itself is created.
+CREATE FUNCTION cph_enforce_organization_default_role() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE
+  active_default_count INTEGER;
+BEGIN
+  SELECT count(*) INTO active_default_count
+  FROM "OrganizationAgentRole"
+  WHERE "organizationId" = NEW."id"
+    AND "isDefault" = true
+    AND "disabledAt" IS NULL;
+
+  IF active_default_count <> 1 THEN
+    RAISE EXCEPTION 'Organization % must have exactly one active default Agent role; found %',
+      NEW."id", active_default_count;
+  END IF;
+  RETURN NULL;
+END;
+$$;
+
+CREATE CONSTRAINT TRIGGER "Organization_requires_active_default_role"
+AFTER INSERT ON "Organization"
+DEFERRABLE INITIALLY DEFERRED
+FOR EACH ROW EXECUTE FUNCTION cph_enforce_organization_default_role();

hub/prisma/schema.prisma

@@ -43,7 +43,11 @@ model Organization {
   externalDirectoryConnections ExternalDirectoryConnection[]
   providerConnections          OrganizationProviderConnection[]
   feishuApplicationConnection  OrganizationFeishuApplicationConnection?
+  agentSkills                  OrganizationAgentSkill[]
+  agentRoles                   OrganizationAgentRole[]
+  projectGroupBindings         ProjectGroupBinding[]
   auditEntries                 AuditEntry[]                             @relation("organizationAudit")
+  projectSearchDocuments       ProjectSearchDocument[]
 
   @@index([status])
 }
@@ -78,6 +82,72 @@ enum OrganizationMemberRole {
   MEMBER
 }
 
+/// Organization-scoped, content-addressed Agent skill registration. The DB is
+/// the runtime registry; `contentDigest` selects an immutable directory below
+/// the platform-controlled skill store and is never interpreted as a path.
+model OrganizationAgentSkill {
+  id             String    @id @default(cuid())
+  organizationId String
+  name           String
+  version        String
+  description    String?
+  contentDigest  String
+  createdAt      DateTime  @default(now())
+  updatedAt      DateTime  @updatedAt
+  disabledAt     DateTime?
+
+  organization Organization                 @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  roleBindings OrganizationAgentRoleSkill[]
+
+  @@unique([organizationId, name])
+  @@unique([organizationId, id])
+  @@index([organizationId, disabledAt])
+  @@index([contentDigest])
+}
+
+/// ADR-0017 runtime role bundle. Roles are Organization-owned data rather than
+/// a code enum: model, system prompt, tool allowlist and skill selection change
+/// without a Hub release or process restart.
+model OrganizationAgentRole {
+  id             String    @id @default(cuid())
+  organizationId String
+  roleId         String
+  label          String
+  defaultModel   String?
+  systemPrompt   String?
+  tools          Json?
+  sortOrder      Int       @default(0)
+  isDefault      Boolean   @default(false)
+  createdAt      DateTime  @default(now())
+  updatedAt      DateTime  @updatedAt
+  disabledAt     DateTime?
+
+  organization       Organization                 @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  skillBindings      OrganizationAgentRoleSkill[]
+  selectedByBindings ProjectGroupBinding[]        @relation("selectedAgentRole")
+
+  @@unique([organizationId, roleId])
+  @@unique([organizationId, id])
+  @@index([organizationId, disabledAt, sortOrder])
+}
+
+/// Same-Organization join enforced by both composite foreign keys. `sortOrder`
+/// gives stable skill listing and prompt discovery order for a role bundle.
+model OrganizationAgentRoleSkill {
+  organizationId String
+  agentRoleId    String
+  agentSkillId   String
+  sortOrder      Int      @default(0)
+  createdAt      DateTime @default(now())
+
+  role  OrganizationAgentRole  @relation(fields: [organizationId, agentRoleId], references: [organizationId, id], onDelete: Cascade)
+  skill OrganizationAgentSkill @relation(fields: [organizationId, agentSkillId], references: [organizationId, id], onDelete: Cascade)
+
+  @@id([organizationId, agentRoleId, agentSkillId])
+  @@index([organizationId, agentRoleId, sortOrder])
+  @@index([organizationId, agentSkillId])
+}
+
 /// ADR-0021: org-level project onboarding policy. Ordinary Feishu users can
 /// create projects from unbound chats only when membersCanCreateProjects=true.
 model OrganizationProjectSettings {
@@ -371,11 +441,17 @@ model ExternalPrincipalMembership {
 /// ADR-0021: transparent project explorer folder. Folders are org-scoped
 /// navigation/aggregation nodes, not permission resources; project grants stay
 /// attached to PROJECT resources.
+enum FolderKind {
+  REGULAR
+  SYSTEM_INBOX
+}
+
 model Folder {
   id             String     @id @default(cuid())
   organizationId String
   parentId       String?
   name           String
+  kind           FolderKind @default(REGULAR)
   sortKey        String     @default("")
   createdAt      DateTime   @default(now())
   updatedAt      DateTime   @updatedAt
@@ -394,6 +470,7 @@ model Project {
   id              String    @id @default(cuid())
   organizationId  String
   folderId        String?
+  code            String?
   name            String
   workspaceDir    String
   createdByUserId String?
@@ -411,29 +488,58 @@ model Project {
   roleTriggerGrants RoleTriggerGrant[]     @relation("projectRoleGrants")
   auditEntries      AuditEntry[]           @relation("projectAudit")
   fileChanges       AgentFileChange[]      @relation("projectFileChanges")
+  searchDocument    ProjectSearchDocument?
 
+  @@unique([organizationId, id])
   @@index([organizationId, archivedAt])
   @@index([folderId, archivedAt])
   @@index([archivedAt])
 }
 
+/// Derived, rebuildable search projection for project discovery. PostgreSQL
+/// triggers keep it synchronized with Project and Folder mutations; Project
+/// remains the source of truth and authorization remains outside this table.
+model ProjectSearchDocument {
+  projectId            String   @id
+  organizationId       String
+  name                 String
+  code                 String?
+  normalizedCode       String
+  normalizedName       String
+  breadcrumb           String
+  normalizedBreadcrumb String
+  normalizedSearchText String
+  updatedAt            DateTime @updatedAt
+
+  project      Project      @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+
+  @@index([organizationId])
+}
+
 /// ADR-0001 + ADR-0021: active bindings are one project ↔ one Feishu chat
 /// (1:1). Historical archived bindings are retained for audit; partial unique
 /// indexes in migrations enforce one active binding per project and per chat.
 model ProjectGroupBinding {
   id                  String    @id @default(cuid())
+  organizationId      String
   projectId           String
   chatId              String
   createdByUserId     String?
   createdAt           DateTime  @default(now())
   updatedAt           DateTime  @updatedAt
   archivedAt          DateTime?
+  selectedAgentRoleId String
 
-  project   Project @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  organization Organization          @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  project      Project               @relation(fields: [organizationId, projectId], references: [organizationId, id], onDelete: Cascade)
   createdBy    User?                 @relation("bindingCreator", fields: [createdByUserId], references: [id], onDelete: SetNull)
+  selectedRole OrganizationAgentRole @relation("selectedAgentRole", fields: [organizationId, selectedAgentRoleId], references: [organizationId, id], onDelete: Restrict)
 
+  @@index([organizationId])
   @@index([projectId, archivedAt])
   @@index([chatId, archivedAt])
+  @@index([selectedAgentRoleId])
 }
 
 // --- AgentRun, session, lock (ADR-0002, 0017) -----------------------------

hub/src/admin/routes/authRoutes.ts

@@ -5,7 +5,7 @@ import { randomBytes } from "node:crypto";
 import type { PrismaClient } from "@prisma/client";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import { resolveActiveFeishuApplication } from "../../connections/feishuApplicationConnections.js";
-import { upsertScopedFeishuIdentity } from "../../feishu/identityNamespace.js";
+import { upsertScopedFeishuIdentityInTransaction } from "../../feishu/identityNamespace.js";
 import type { LocalSecretEnvelope } from "../../security/secretEnvelope.js";
 import {
   buildAuthorizeUrl,
@@ -164,16 +164,54 @@ export async function registerAuthRoutes(app: FastifyInstance, config: AuthRoute
       const feishuUser = await exchangeCodeForUser(oauthConfig, code);
       let userId: string;
       if (statePayload.connectionId !== undefined && statePayload.organizationId !== undefined) {
-        const identity = await upsertScopedFeishuIdentity(config.prisma, {
-          connectionId: statePayload.connectionId,
+        const connectionId = statePayload.connectionId;
+        const organizationId = statePayload.organizationId;
+        const identity = await config.prisma.$transaction(async (tx) => {
+          const resolved = await upsertScopedFeishuIdentityInTransaction(tx, {
+            connectionId,
+            expectedOrganizationId: organizationId,
             openId: feishuUser.openId,
             ...(feishuUser.unionId !== undefined ? { unionId: feishuUser.unionId } : {}),
             displayName: feishuUser.displayName,
             ...(feishuUser.avatarUrl !== null ? { avatarUrl: feishuUser.avatarUrl } : {}),
           });
-        if (identity.organizationId !== statePayload.organizationId) {
-          throw new HttpError(400, "bad_request", "OAuth identity Organization scope mismatch");
+          const activeMembership = await tx.organizationMembership.findFirst({
+            where: {
+              organizationId,
+              userId: resolved.userId,
+              revokedAt: null,
+            },
+            select: { id: true },
+          });
+          if (activeMembership === null) {
+            const revokedMembership = await tx.organizationMembership.findFirst({
+              where: {
+                organizationId,
+                userId: resolved.userId,
+                revokedAt: { not: null },
+              },
+              select: { id: true },
+            });
+            if (revokedMembership === null) {
+              await tx.organizationMembership.create({
+                data: {
+                  organizationId,
+                  userId: resolved.userId,
+                  role: "MEMBER",
+                },
+              });
+              await tx.auditEntry.create({
+                data: {
+                  organizationId,
+                  actorUserId: resolved.userId,
+                  action: "organization_member.oauth_auto_joined",
+                  metadata: { connectionId: resolved.connectionId, role: "MEMBER" },
+                },
+              });
             }
+          }
+          return resolved;
+        });
         userId = identity.userId;
         setSessionCookie(reply, config, {
           userId,
@@ -235,6 +273,34 @@ export async function registerAuthRoutes(app: FastifyInstance, config: AuthRoute
     return reply.status(204).send();
   });
 
+  app.get("/auth/feishu/complete", async (request, reply) => {
+    const query = request.query as { org?: string };
+    const organizationName = typeof query.org === "string" && query.org.trim() !== ""
+      ? query.org.trim()
+      : "当前组织";
+    return reply.type("text/html").send(`<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1"/>
+  <title>Educraft 登录成功</title>
+  <style>
+    body{font-family:system-ui,sans-serif;display:flex;min-height:100vh;align-items:center;justify-content:center;margin:0;background:#f6f7f9;color:#1a1a1a}
+    .card{background:#fff;padding:2rem 2.5rem;border-radius:12px;box-shadow:0 8px 24px rgba(0,0,0,.08);max-width:25rem;text-align:center}
+    .ok{font-size:3rem;margin:0 0 .5rem}.hint{color:#646a73;line-height:1.6}
+  </style>
+</head>
+<body>
+  <main class="card">
+    <p class="ok">✅</p>
+    <h1>登录并加入组织成功</h1>
+    <p>你已加入 ${escapeHtml(organizationName)}。</p>
+    <p class="hint">现在可以关闭本页面，返回飞书群再次 @机器人继续使用。</p>
+  </main>
+</body>
+</html>`);
+  });
+
   app.get("/api/me", async (request, reply) => {
     try {
       const auth = await requireSession(request, reply, guardDeps);
@@ -363,10 +429,13 @@ async function resolvePostLoginRedirect(
         revokedAt: null,
         organization: { status: "ACTIVE" },
       },
-      select: { organization: { select: { slug: true } } },
+      select: { organization: { select: { slug: true, name: true } } },
     });
     if (intended === null) return "/admin?error=not_an_active_org_member";
     const orgRoot = `/admin/org/${intended.organization.slug}`;
+    if (returnTo === "/admin") {
+      return `/auth/feishu/complete?org=${encodeURIComponent(intended.organization.name)}`;
+    }
     return returnTo === orgRoot || returnTo.startsWith(`${orgRoot}/`) ? returnTo : orgRoot;
   }
   if (returnTo !== "/admin" && returnTo.startsWith("/admin")) {

hub/src/agent/configuration.ts

@@ -0,0 +1,297 @@
+import type { PrismaClient } from "@prisma/client";
+import { Prisma } from "@prisma/client";
+import { assertSupportedRoleTools } from "./roleTools.js";
+import { importSkillDirectory } from "./skillStore.js";
+
+const ROLE_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+/**
+ * Deep module for controlled host-console Agent configuration. It owns the
+ * filesystem/DB ordering, Organization checks and role-skill composition so
+ * callers never manipulate registry rows or content paths independently.
+ */
+export class OrganizationAgentConfiguration {
+  constructor(
+    private readonly prisma: PrismaClient,
+    private readonly skillStoreRoot: string,
+  ) {}
+
+  async installSkill(input: {
+    readonly organizationId: string;
+    readonly sourceDir: string;
+    readonly version: string;
+  }): Promise<{ readonly id: string; readonly name: string; readonly contentDigest: string }> {
+    await this.requireActiveOrganization(input.organizationId);
+    const version = nonEmpty(input.version, "skill version");
+    const imported = await importSkillDirectory({
+      sourceDir: input.sourceDir,
+      storeRoot: this.skillStoreRoot,
+    });
+    return this.prisma.$transaction(async (tx) => {
+      const previous = await tx.organizationAgentSkill.findUnique({
+        where: { organizationId_name: { organizationId: input.organizationId, name: imported.name } },
+        select: { contentDigest: true },
+      });
+      const skill = await tx.organizationAgentSkill.upsert({
+        where: {
+          organizationId_name: {
+            organizationId: input.organizationId,
+            name: imported.name,
+          },
+        },
+        create: {
+          organizationId: input.organizationId,
+          name: imported.name,
+          version,
+          description: imported.description ?? null,
+          contentDigest: imported.contentDigest,
+        },
+        update: {
+          version,
+          description: imported.description ?? null,
+          contentDigest: imported.contentDigest,
+          disabledAt: null,
+        },
+        select: {
+          id: true,
+          name: true,
+          contentDigest: true,
+          roleBindings: { select: { role: { select: { roleId: true } } } },
+        },
+      });
+      if (previous !== null && previous.contentDigest !== skill.contentDigest) {
+        await archiveRoleSessions(
+          tx,
+          input.organizationId,
+          skill.roleBindings.map((binding) => binding.role.roleId),
+        );
+      }
+      await tx.auditEntry.create({
+        data: {
+          organizationId: input.organizationId,
+          action: "agent_skill.installed",
+          metadata: {
+            name: skill.name,
+            version,
+            contentDigest: skill.contentDigest,
+          },
+        },
+      });
+      return { id: skill.id, name: skill.name, contentDigest: skill.contentDigest };
+    });
+  }
+
+  async upsertRole(input: {
+    readonly organizationId: string;
+    readonly roleId: string;
+    readonly label: string;
+    readonly defaultModel?: string | null | undefined;
+    readonly systemPrompt?: string | null | undefined;
+    readonly tools?: readonly string[] | null | undefined;
+    readonly sortOrder?: number | undefined;
+    readonly isDefault?: boolean | undefined;
+  }): Promise<{ readonly id: string; readonly roleId: string }> {
+    await this.requireActiveOrganization(input.organizationId);
+    if (!ROLE_ID_PATTERN.test(input.roleId)) throw new Error(`invalid role id: ${input.roleId}`);
+    const label = nonEmpty(input.label, "role label");
+    if (input.tools !== undefined && input.tools !== null) assertSupportedRoleTools([...input.tools]);
+    const sortOrder = input.sortOrder ?? 0;
+    if (!Number.isSafeInteger(sortOrder)) throw new Error("role sortOrder must be an integer");
+    const createTools = input.tools === undefined || input.tools === null
+      ? Prisma.DbNull
+      : [...input.tools];
+    const updateTools = input.tools === undefined
+      ? undefined
+      : input.tools === null
+        ? Prisma.DbNull
+        : [...input.tools];
+    return this.prisma.$transaction(async (tx) => {
+      const previous = await tx.organizationAgentRole.findUnique({
+        where: { organizationId_roleId: { organizationId: input.organizationId, roleId: input.roleId } },
+        select: { defaultModel: true, systemPrompt: true, tools: true, isDefault: true },
+      });
+      const currentDefault = await tx.organizationAgentRole.findFirst({
+        where: { organizationId: input.organizationId, isDefault: true, disabledAt: null },
+        select: { id: true },
+      });
+      const effectiveIsDefault = input.isDefault ?? previous?.isDefault ?? (currentDefault === null);
+      if (input.isDefault === false && previous?.isDefault === true) {
+        throw new Error("cannot unset the active default role without selecting a replacement");
+      }
+      if (effectiveIsDefault) {
+        await tx.organizationAgentRole.updateMany({
+          where: { organizationId: input.organizationId, isDefault: true },
+          data: { isDefault: false },
+        });
+      }
+      const role = await tx.organizationAgentRole.upsert({
+        where: {
+          organizationId_roleId: {
+            organizationId: input.organizationId,
+            roleId: input.roleId,
+          },
+        },
+        create: {
+          organizationId: input.organizationId,
+          roleId: input.roleId,
+          label,
+          defaultModel: normalizeOptionalText(input.defaultModel),
+          systemPrompt: normalizeOptionalText(input.systemPrompt),
+          tools: createTools,
+          sortOrder,
+          isDefault: effectiveIsDefault,
+        },
+        update: {
+          label,
+          ...(input.defaultModel !== undefined ? { defaultModel: normalizeOptionalText(input.defaultModel) } : {}),
+          ...(input.systemPrompt !== undefined ? { systemPrompt: normalizeOptionalText(input.systemPrompt) } : {}),
+          ...(updateTools !== undefined ? { tools: updateTools } : {}),
+          sortOrder,
+          isDefault: effectiveIsDefault,
+          disabledAt: null,
+        },
+        select: { id: true, roleId: true },
+      });
+      const executionSurfaceChanged = previous !== null && (
+        (input.defaultModel !== undefined && normalizeOptionalText(input.defaultModel) !== previous.defaultModel) ||
+        (input.systemPrompt !== undefined && normalizeOptionalText(input.systemPrompt) !== previous.systemPrompt) ||
+        (input.tools !== undefined && JSON.stringify(input.tools) !== JSON.stringify(previous.tools))
+      );
+      const activeDefaultCount = await tx.organizationAgentRole.count({
+        where: { organizationId: input.organizationId, isDefault: true, disabledAt: null },
+      });
+      if (activeDefaultCount !== 1) {
+        throw new Error(`organization ${input.organizationId} must have exactly one active default role`);
+      }
+      if (executionSurfaceChanged) await archiveRoleSessions(tx, input.organizationId, [input.roleId]);
+      await tx.auditEntry.create({
+        data: {
+          organizationId: input.organizationId,
+          action: "agent_role.upserted",
+          metadata: {
+            roleId: input.roleId,
+            label,
+            defaultModel: input.defaultModel === undefined ? "unchanged" : normalizeOptionalText(input.defaultModel),
+            systemPromptConfigured: input.systemPrompt === undefined
+              ? "unchanged"
+              : normalizeOptionalText(input.systemPrompt) !== null,
+            tools: input.tools === undefined ? "unchanged" : input.tools === null ? "all" : [...input.tools],
+            sortOrder,
+            isDefault: effectiveIsDefault,
+            defaultExplicit: input.isDefault !== undefined,
+          },
+        },
+      });
+      return role;
+    });
+  }
+
+  async setRoleSkills(input: {
+    readonly organizationId: string;
+    readonly roleId: string;
+    readonly skillNames: readonly string[];
+  }): Promise<void> {
+    const uniqueNames = new Set(input.skillNames);
+    if (uniqueNames.size !== input.skillNames.length) throw new Error("role skill names must be unique");
+    await this.prisma.$transaction(async (tx) => {
+      const role = await tx.organizationAgentRole.findUnique({
+        where: {
+          organizationId_roleId: {
+            organizationId: input.organizationId,
+            roleId: input.roleId,
+          },
+        },
+        select: { id: true, disabledAt: true },
+      });
+      if (role === null || role.disabledAt !== null) {
+        throw new Error(`active role not found in organization: ${input.roleId}`);
+      }
+      const skills = await tx.organizationAgentSkill.findMany({
+        where: {
+          organizationId: input.organizationId,
+          name: { in: [...input.skillNames] },
+          disabledAt: null,
+        },
+        select: { id: true, name: true },
+      });
+      if (skills.length !== input.skillNames.length) {
+        const found = new Set(skills.map((skill) => skill.name));
+        const missing = input.skillNames.filter((name) => !found.has(name));
+        throw new Error(`active skills not found in organization: ${missing.join(", ")}`);
+      }
+      const byName = new Map(skills.map((skill) => [skill.name, skill.id]));
+      await tx.organizationAgentRoleSkill.deleteMany({
+        where: { organizationId: input.organizationId, agentRoleId: role.id },
+      });
+      if (input.skillNames.length > 0) {
+        await tx.organizationAgentRoleSkill.createMany({
+          data: input.skillNames.map((name, index) => ({
+            organizationId: input.organizationId,
+            agentRoleId: role.id,
+            agentSkillId: byName.get(name)!,
+            sortOrder: index,
+          })),
+        });
+      }
+      await archiveRoleSessions(tx, input.organizationId, [input.roleId]);
+      await tx.auditEntry.create({
+        data: {
+          organizationId: input.organizationId,
+          action: "agent_role.skills_set",
+          metadata: { roleId: input.roleId, skillNames: [...input.skillNames] },
+        },
+      });
+    });
+  }
+
+  private async requireActiveOrganization(organizationId: string): Promise<void> {
+    const organization = await this.prisma.organization.findUnique({
+      where: { id: organizationId },
+      select: { status: true },
+    });
+    if (organization === null) throw new Error(`organization not found: ${organizationId}`);
+    if (organization.status !== "ACTIVE") {
+      throw new Error(`organization ${organizationId} is ${organization.status}`);
+    }
+  }
+}
+
+async function archiveRoleSessions(
+  tx: Prisma.TransactionClient,
+  organizationId: string,
+  roleIds: readonly string[],
+): Promise<void> {
+  if (roleIds.length === 0) return;
+  const sessions = await tx.agentSession.findMany({
+    where: {
+      roleId: { in: [...new Set(roleIds)] },
+      project: { organizationId },
+    },
+    select: { id: true, archivedAt: true, metadata: true },
+  });
+  const archivedAt = new Date();
+  for (const session of sessions) {
+    const metadata = typeof session.metadata === "object" && session.metadata !== null && !Array.isArray(session.metadata)
+      ? session.metadata as Prisma.JsonObject
+      : {};
+    await tx.agentSession.update({
+      where: { id: session.id },
+      data: {
+        ...(session.archivedAt === null ? { archivedAt } : {}),
+        metadata: { ...metadata, userResumable: false },
+      },
+    });
+  }
+}
+
+function nonEmpty(value: string, label: string): string {
+  const normalized = value.trim();
+  if (normalized === "") throw new Error(`${label} is required`);
+  return normalized;
+}
+
+function normalizeOptionalText(value: string | null | undefined): string | null {
+  if (value === undefined || value === null) return null;
+  const normalized = value.trim();
+  return normalized === "" ? null : normalized;
+}

hub/src/agent/models.ts

@@ -12,8 +12,8 @@
  * A named role preset — the full per-run agent bundle. Roles are **data**, not
  * a code enum: admin/teachers define them (ADR-0017: role-based routing is
  * product config, not a spec invariant). `roleId` is an opaque string and
- * doubles as the slash-command name (`/draft ...`) — the registry holds the
- * role set, so new roles are added by configuration, not by editing code.
+ * is selected through the project console — the registry holds the role set,
+ * so new roles are added by configuration, not by editing code.
  *
  * A role bundles everything that distinguishes one agent persona from another:
  * model, system prompt, and the tool surface (files / cph / feishu / skills /
@@ -40,6 +40,14 @@ export interface RoleEntry {
    * Invalid names fail fast when settings are loaded or the run is set up.
    */
   readonly tools?: readonly string[] | undefined;
+  /** Immutable skill versions selected by this role at runtime. */
+  readonly skills?: readonly RoleSkillEntry[] | undefined;
+}
+
+export interface RoleSkillEntry {
+  readonly name: string;
+  readonly version: string;
+  readonly contentDigest: string;
 }
 
 /** A model the admin has enabled for use by the Hub. */

hub/src/agent/runner.ts

@@ -29,10 +29,11 @@
  * `workspace.ts` `confine()` path validator as a tool wrapper — the OS sandbox
  * is the mechanism, the contract pins the invariant.
  */
-import { query, type McpServerConfig, type SDKMessage, type SDKAssistantMessage, type SDKUserMessage, type SDKResultMessage, type SDKPartialAssistantMessage } from "@anthropic-ai/claude-agent-sdk";
+import { query, type HookCallback, type McpServerConfig, type SDKMessage, type SDKAssistantMessage, type SDKUserMessage, type SDKResultMessage, type SDKPartialAssistantMessage, type SDKSystemMessage } from "@anthropic-ai/claude-agent-sdk";
 import type { PrismaClient } from "@prisma/client";
 import { claudeSdkToolConfigForRole } from "./roleTools.js";
 import { createAgentSecurityPolicy } from "./security.js";
+import type { RoleSkillEntry } from "./models.js";
 
 export interface ProjectContext {
   readonly projectId: string;
@@ -66,6 +67,7 @@ export interface RunRequest {
    * means no tools.
    */
   readonly tools?: readonly string[] | undefined;
+  readonly skills?: readonly RoleSkillEntry[] | undefined;
   readonly mcpServers?: Record<string, McpServerConfig> | undefined;
   readonly maxTurns?: number;
   readonly runId: string;
@@ -91,11 +93,29 @@ export interface RunResult {
   readonly costUsd?: number | undefined;
   readonly numTurns: number;
   readonly sdkSessionId?: string | undefined;
+  /** Skill ids reported by the SDK init event, not merely requested options. */
+  readonly initializedSkillIds?: readonly string[] | undefined;
   readonly error?: string;
 }
 
 const DEFAULT_MAX_TURNS = 25;
 
+const denyUnsandboxedBash: HookCallback = async (input) => {
+  if (input.hook_event_name !== "PreToolUse" || input.tool_name !== "Bash") return {};
+  const toolInput = input.tool_input;
+  if (
+    typeof toolInput !== "object" || toolInput === null ||
+    !("dangerouslyDisableSandbox" in toolInput) || toolInput.dangerouslyDisableSandbox !== true
+  ) return {};
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: "This deployment requires every Bash command to remain sandboxed.",
+    },
+  };
+};
+
 export async function runAgent(req: RunRequest): Promise<RunResult> {
   const onStream = req.onStream;
   const cap = req.maxTurns ?? DEFAULT_MAX_TURNS;
@@ -115,7 +135,9 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
   let costUsd: number | undefined;
   let numTurns = 0;
   let sdkSessionId: string | undefined;
+  let initializedSkillIds: readonly string[] | undefined;
   let error: string | undefined;
+  let cleanupSecurity = async (): Promise<void> => {};
   try {
     await persistAgentMessage(req, "user", req.prompt);
     const toolConfig = claudeSdkToolConfigForRole(req.tools);
@@ -124,15 +146,21 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
       throw new Error("Agent run requires the configured workspace root");
     }
     const security = await createAgentSecurityPolicy({
+      runId: req.runId,
       workspaceRoot,
       workspaceDir: req.project.workspaceDir,
+      skills: req.skills,
       providerProxyEnv: req.providerProxyEnv,
     });
+    cleanupSecurity = security.cleanup;
+    const hasSkills = security.skillIds.length > 0;
 
     type QueryOptions = NonNullable<Parameters<typeof query>[0]["options"]>;
     const options: QueryOptions = {
       cwd: security.cwd,
-      tools: [...toolConfig.tools],
+      // `skills` controls discovery/allowlisting, but an explicit `tools`
+      // list still has to expose the Skill dispatcher itself.
+      tools: [...toolConfig.tools, ...(hasSkills ? ["Skill"] : [])],
       allowedTools: [...toolConfig.allowedTools],
       maxTurns: cap,
       includePartialMessages: true,
@@ -150,7 +178,18 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
       // The project workspace is untrusted input. Do not load user/project
       // settings that could widen tools, hooks, MCP servers, or sandbox paths.
       settingSources: [],
+      settings: { disableBundledSkills: true },
+      ...(hasSkills && security.skillPluginRoot !== undefined
+        ? { plugins: [{ type: "local" as const, path: security.skillPluginRoot, skipMcpDiscovery: true }] }
+        : {}),
+      skills: [...security.skillIds],
       strictMcpConfig: true,
+      // Claude Code 2.1.202 can honor the per-call opt-out despite
+      // sandbox.allowUnsandboxedCommands=false. Enforce the invariant again at
+      // the PreToolUse boundary, before the Bash process can be spawned.
+      hooks: {
+        PreToolUse: [{ matcher: "Bash", hooks: [denyUnsandboxedBash] }],
+      },
     };
     if (req.systemPrompt !== undefined) options.systemPrompt = req.systemPrompt;
     if (req.model !== undefined) options.model = req.model;
@@ -169,6 +208,12 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
 
     for await (const message of conversation) {
       switch (message.type) {
+        case "system": {
+          if (message.subtype === "init") {
+            initializedSkillIds = [...(message as SDKSystemMessage).skills];
+          }
+          break;
+        }
         case "stream_event": {
           const evt = (message as SDKPartialAssistantMessage).event;
           if (evt.type === "content_block_delta" && evt.delta.type === "text_delta") {
@@ -248,6 +293,9 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
         case "result": {
           const result = message as SDKResultMessage;
           sdkSessionId = result.session_id;
+          if (result.subtype === "success" && fullText === "" && typeof result.result === "string") {
+            fullText = result.result;
+          }
           costUsd = Number.isFinite(result.total_cost_usd) ? result.total_cost_usd : undefined;
           if (result.subtype !== "success") {
             error = `result_${result.subtype}`;
@@ -265,6 +313,7 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
       ...(costUsd !== undefined ? { costUsd } : {}),
       numTurns,
       sdkSessionId,
+      ...(initializedSkillIds !== undefined ? { initializedSkillIds } : {}),
       ...(error !== undefined ? { error } : {}),
     };
   } catch (e) {
@@ -276,8 +325,11 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
       ...(costUsd !== undefined ? { costUsd } : {}),
       numTurns,
       sdkSessionId,
+      ...(initializedSkillIds !== undefined ? { initializedSkillIds } : {}),
       ...(aborted ? {} : { error: e instanceof Error ? e.message : String(e) }),
     };
+  } finally {
+    await cleanupSecurity();
   }
 }
 

hub/src/agent/security.ts

@@ -1,6 +1,8 @@
 import { chmod, lstat, mkdir, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
+import type { RoleSkillEntry } from "./models.js";
+import { prepareRunSkillPlugin, readSkillStoreRoot } from "./skillStore.js";
 
 const PROVIDER_ENV_KEYS = new Set([
   "ANTHROPIC_BASE_URL",
@@ -26,9 +28,16 @@ const SANDBOX_HIDDEN_ENV_KEYS = [
   "ANTHROPIC_API_KEY",
 ] as const;
 
+// Linux sockaddr_un.sun_path is 108 bytes including the terminator. Claude's
+// sandbox appends its own user directory and randomized bridge socket names,
+// so keep our prefix well below that hard limit.
+const MAX_AGENT_TMP_PREFIX_BYTES = 56;
+
 export interface AgentSecurityInput {
+  readonly runId: string;
   readonly workspaceRoot: string;
   readonly workspaceDir: string;
+  readonly skills?: readonly RoleSkillEntry[] | undefined;
   /** Run-scoped loopback proxy capability; customer provider secrets are forbidden here. */
   readonly providerProxyEnv?: Readonly<Record<string, string | undefined>> | undefined;
   readonly hostEnv?: Readonly<Record<string, string | undefined>> | undefined;
@@ -55,6 +64,9 @@ export interface AgentSecurityPolicy {
   readonly cwd: string;
   readonly workspaceRoot: string;
   readonly env: Record<string, string | undefined>;
+  readonly skillIds: readonly string[];
+  readonly skillPluginRoot?: string | undefined;
+  cleanup(): Promise<void>;
   readonly sandbox: AgentSandboxPolicy;
 }
 
@@ -72,10 +84,8 @@ export async function createAgentSecurityPolicy(input: AgentSecurityInput): Prom
   const agentCache = await ensureDirectoryTree(runtimeRoot, ["cache"]);
   const agentConfig = await ensureDirectoryTree(runtimeRoot, ["config"]);
   const agentState = await ensureDirectoryTree(runtimeRoot, ["state"]);
-  // Keep the SDK temp root both short enough for Linux AF_UNIX sockets and
-  // physically inside the project boundary pinned by AgentFileOp.Authorized.
   const agentTmp = await ensureDirectoryTree(cphRoot, ["t"]);
-  const claudeCodeTmp = join(".cph", "t");
+  assertShortAgentTemp(agentTmp);
 
   const path = hostEnv["PATH"]?.trim();
   if (path === undefined || path === "") {
@@ -91,14 +101,13 @@ export async function createAgentSecurityPolicy(input: AgentSecurityInput): Prom
   env.XDG_CACHE_HOME = agentCache;
   env.XDG_CONFIG_HOME = agentConfig;
   env.XDG_STATE_HOME = agentState;
-  // General subprocess temp paths stay absolute so tools continue to work
-  // after `cd`. Only the SDK's socket prefix is relative: Claude resolves it
-  // from the canonical workspace cwd before Bash commands can change cwd.
+  // All four variables must use the short path. Claude's sandbox bridge uses
+  // the ordinary temp variables, while other SDK paths use CLAUDE_CODE_TMPDIR.
   env.TMPDIR = agentTmp;
   env.TMP = agentTmp;
   env.TEMP = agentTmp;
   env.CLAUDE_CONFIG_DIR = agentConfig;
-  env.CLAUDE_CODE_TMPDIR = claudeCodeTmp;
+  env.CLAUDE_CODE_TMPDIR = agentTmp;
   env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1";
   env.DISABLE_TELEMETRY = "1";
   env.DO_NOT_TRACK = "1";
@@ -113,10 +122,21 @@ export async function createAgentSecurityPolicy(input: AgentSecurityInput): Prom
 
   const sensitiveReadPaths = hostSensitiveReadPaths(hostEnv);
   const runtimeReadPaths = hostRuntimeReadPaths(hostEnv);
+  const selectedSkills = input.skills ?? [];
+  const skillPlugin = selectedSkills.length === 0
+    ? null
+    : await prepareRunSkillPlugin({
+        storeRoot: readSkillStoreRoot(hostEnv),
+        runId: input.runId,
+        skills: selectedSkills,
+      });
   return {
     cwd: workspaceDir,
     workspaceRoot,
     env,
+    skillIds: skillPlugin?.skillIds ?? [],
+    ...(skillPlugin !== null ? { skillPluginRoot: skillPlugin.root } : {}),
+    cleanup: skillPlugin?.cleanup ?? (async () => {}),
     sandbox: {
       enabled: true,
       failIfUnavailable: true,
@@ -132,7 +152,7 @@ export async function createAgentSecurityPolicy(input: AgentSecurityInput): Prom
         // workspace plus the named system runtime needed to execute tools.
         // SDK allowRead takes precedence over matching denyRead paths.
         denyRead: ["/"],
-        allowRead: [workspaceDir, ...runtimeReadPaths],
+        allowRead: [workspaceDir, ...(skillPlugin !== null ? [skillPlugin.root] : []), ...runtimeReadPaths],
       },
       credentials: {
         files: sensitiveReadPaths.map((path) => ({ path, mode: "deny" as const })),
@@ -142,6 +162,15 @@ export async function createAgentSecurityPolicy(input: AgentSecurityInput): Prom
   };
 }
 
+function assertShortAgentTemp(agentTmp: string): void {
+  const prefixBytes = Buffer.byteLength(agentTmp);
+  if (prefixBytes > MAX_AGENT_TMP_PREFIX_BYTES) {
+    throw new Error(
+      `Agent temp path is too long for sandbox bridge sockets (${prefixBytes} > ${MAX_AGENT_TMP_PREFIX_BYTES} bytes): ${agentTmp}`,
+    );
+  }
+}
+
 function hostRuntimeReadPaths(env: Readonly<Record<string, string | undefined>>): string[] {
   const platformPaths = process.platform === "darwin"
     ? [
@@ -282,7 +311,7 @@ async function ensureDirectoryTree(root: string, components: readonly string[]):
   }
   const canonical = await realpath(current);
   if (canonical !== current || !isStrictDescendant(root, canonical)) {
-    throw new Error(`Agent runtime path escapes project workspace: ${current}`);
+    throw new Error(`Agent runtime path escapes its configured root: ${current}`);
   }
   await chmod(canonical, 0o700);
   return canonical;

hub/src/agent/skillStore.ts

@@ -0,0 +1,217 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  cp,
+  lstat,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import type { RoleSkillEntry } from "./models.js";
+
+const MAX_SKILL_FILES = 512;
+const MAX_SKILL_BYTES = 16 * 1024 * 1024;
+const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const DIGEST_PATTERN = /^[a-f0-9]{64}$/;
+const RUNTIME_PLUGIN_NAME = "cph-runtime";
+
+export interface ImportedSkillContent {
+  readonly name: string;
+  readonly description: string | undefined;
+  readonly contentDigest: string;
+}
+
+export interface RunSkillPlugin {
+  readonly root: string;
+  readonly skillIds: readonly string[];
+  cleanup(): Promise<void>;
+}
+
+export async function importSkillDirectory(input: {
+  readonly sourceDir: string;
+  readonly storeRoot: string;
+}): Promise<ImportedSkillContent> {
+  const source = await inspectSkillDirectory(input.sourceDir);
+  const versionsRoot = join(input.storeRoot, "versions");
+  await mkdir(versionsRoot, { recursive: true, mode: 0o750 });
+  const destination = join(versionsRoot, source.contentDigest);
+
+  try {
+    const existing = await inspectSkillDirectory(destination);
+    if (existing.contentDigest !== source.contentDigest || existing.name !== source.name) {
+      throw new Error(`stored skill content digest mismatch: ${source.name}`);
+    }
+    return source;
+  } catch (error) {
+    if (!isMissingPath(error)) throw error;
+  }
+
+  const temporary = join(versionsRoot, `.tmp-${randomUUID()}`);
+  try {
+    await cp(input.sourceDir, temporary, { recursive: true, force: false, errorOnExist: true });
+    const copied = await inspectSkillDirectory(temporary);
+    if (copied.contentDigest !== source.contentDigest || copied.name !== source.name) {
+      throw new Error(`skill changed while importing: ${source.name}`);
+    }
+    await rename(temporary, destination);
+  } catch (error) {
+    await rm(temporary, { recursive: true, force: true });
+    if (isDestinationExists(error)) {
+      const existing = await inspectSkillDirectory(destination);
+      if (existing.contentDigest === source.contentDigest && existing.name === source.name) return source;
+    }
+    throw error;
+  }
+  return source;
+}
+
+export async function prepareRunSkillPlugin(input: {
+  readonly storeRoot: string;
+  readonly runId: string;
+  readonly skills: readonly RoleSkillEntry[];
+}): Promise<RunSkillPlugin | null> {
+  if (input.skills.length === 0) return null;
+  const names = new Set<string>();
+  for (const skill of input.skills) {
+    requireSkillName(skill.name);
+    if (!DIGEST_PATTERN.test(skill.contentDigest)) {
+      throw new Error(`skill ${skill.name} has invalid content digest`);
+    }
+    if (names.has(skill.name)) throw new Error(`duplicate role skill: ${skill.name}`);
+    names.add(skill.name);
+  }
+
+  const runtimeRoot = join(input.storeRoot, "runtime");
+  await mkdir(runtimeRoot, { recursive: true, mode: 0o750 });
+  const pluginRoot = join(runtimeRoot, `run-${randomUUID()}`);
+  try {
+    await mkdir(join(pluginRoot, ".claude-plugin"), { recursive: true, mode: 0o750 });
+    await mkdir(join(pluginRoot, "skills"), { recursive: true, mode: 0o750 });
+    await writeFile(
+      join(pluginRoot, ".claude-plugin", "plugin.json"),
+      `${JSON.stringify({
+        name: RUNTIME_PLUGIN_NAME,
+        description: `Runtime skill snapshot for ${input.runId}`,
+        version: "1",
+      }, null, 2)}\n`,
+      { mode: 0o640 },
+    );
+
+    for (const skill of input.skills) {
+      const sourceDir = join(input.storeRoot, "versions", skill.contentDigest);
+      const stored = await inspectSkillDirectory(sourceDir);
+      if (stored.contentDigest !== skill.contentDigest) {
+        throw new Error(`skill ${skill.name} content digest mismatch`);
+      }
+      if (stored.name !== skill.name) {
+        throw new Error(`skill name mismatch: expected ${skill.name}, got ${stored.name}`);
+      }
+      await cp(sourceDir, join(pluginRoot, "skills", skill.name), {
+        recursive: true,
+        force: false,
+        errorOnExist: true,
+      });
+    }
+  } catch (error) {
+    await rm(pluginRoot, { recursive: true, force: true });
+    throw error;
+  }
+
+  return {
+    root: pluginRoot,
+    skillIds: input.skills.map((skill) => `${RUNTIME_PLUGIN_NAME}:${skill.name}`),
+    async cleanup() {
+      await rm(pluginRoot, { recursive: true, force: true });
+    },
+  };
+}
+
+export function readSkillStoreRoot(env: Readonly<Record<string, string | undefined>> = process.env): string {
+  const configured = env["HUB_SKILL_STORE_ROOT"]?.trim();
+  if (configured !== undefined && configured !== "") return resolve(configured);
+  const stateRoot = env["XDG_STATE_HOME"]?.trim();
+  if (stateRoot === undefined || stateRoot === "") {
+    throw new Error("HUB_SKILL_STORE_ROOT or XDG_STATE_HOME is required");
+  }
+  return resolve(stateRoot, "skills");
+}
+
+export async function verifyStoredSkill(input: {
+  readonly storeRoot: string;
+  readonly name: string;
+  readonly contentDigest: string;
+}): Promise<void> {
+  requireSkillName(input.name);
+  if (!DIGEST_PATTERN.test(input.contentDigest)) {
+    throw new Error(`skill ${input.name} has invalid content digest`);
+  }
+  const stored = await inspectSkillDirectory(join(input.storeRoot, "versions", input.contentDigest));
+  if (stored.name !== input.name || stored.contentDigest !== input.contentDigest) {
+    throw new Error(`stored skill verification failed: ${input.name}`);
+  }
+}
+
+async function inspectSkillDirectory(directory: string): Promise<ImportedSkillContent> {
+  const root = resolve(directory);
+  const rootStat = await lstat(root);
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+    throw new Error(`skill root must be a real directory: ${root}`);
+  }
+  const files: Array<{ readonly path: string; readonly bytes: Buffer }> = [];
+  await walk(root, root, files);
+  if (files.length > MAX_SKILL_FILES) throw new Error(`skill has too many files: ${files.length}`);
+  const totalBytes = files.reduce((sum, file) => sum + file.bytes.byteLength, 0);
+  if (totalBytes > MAX_SKILL_BYTES) throw new Error(`skill is too large: ${totalBytes} bytes`);
+  const manifest = files.find((file) => file.path === "SKILL.md");
+  if (manifest === undefined) throw new Error(`skill manifest missing: ${join(root, "SKILL.md")}`);
+  const frontmatter = manifest.bytes.toString("utf8");
+  const name = /^name:\s*['"]?([^'"\r\n]+)['"]?\s*$/m.exec(frontmatter)?.[1]?.trim();
+  if (name === undefined) throw new Error("skill manifest name missing");
+  requireSkillName(name);
+  const description = /^description:\s*['"]?([^'"\r\n]+)['"]?\s*$/m.exec(frontmatter)?.[1]?.trim();
+
+  const hash = createHash("sha256");
+  for (const file of files.sort((left, right) => left.path.localeCompare(right.path))) {
+    hash.update(`${Buffer.byteLength(file.path)}:`);
+    hash.update(file.path);
+    hash.update(`${file.bytes.byteLength}:`);
+    hash.update(file.bytes);
+  }
+  return { name, description, contentDigest: hash.digest("hex") };
+}
+
+async function walk(
+  root: string,
+  directory: string,
+  files: Array<{ readonly path: string; readonly bytes: Buffer }>,
+): Promise<void> {
+  const entries = await readdir(directory, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(directory, entry.name);
+    if (entry.isSymbolicLink()) throw new Error(`skill symlink is forbidden: ${fullPath}`);
+    if (entry.isDirectory()) {
+      await walk(root, fullPath, files);
+      continue;
+    }
+    if (!entry.isFile()) throw new Error(`skill contains unsupported filesystem entry: ${fullPath}`);
+    const relativePath = relative(root, fullPath);
+    files.push({ path: relativePath, bytes: await readFile(fullPath) });
+    if (files.length > MAX_SKILL_FILES) throw new Error(`skill has too many files: ${files.length}`);
+  }
+}
+
+function requireSkillName(name: string): void {
+  if (!SKILL_NAME_PATTERN.test(name)) throw new Error(`invalid skill name: ${name}`);
+}
+
+function isMissingPath(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+function isDestinationExists(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error &&
+    (error.code === "EEXIST" || error.code === "ENOTEMPTY");
+}

hub/src/deployment/agent-config-cli.ts

@@ -0,0 +1,165 @@
+import { readFile } from "node:fs/promises";
+import { prisma } from "../db.js";
+import { OrganizationAgentConfiguration } from "../agent/configuration.js";
+import { readSkillStoreRoot, verifyStoredSkill } from "../agent/skillStore.js";
+import { readSiloOrganizationId } from "./silo.js";
+
+async function main(argv: readonly string[]): Promise<void> {
+  const [command, ...args] = argv;
+  if (command === undefined || command === "help" || command === "--help") {
+    printHelp();
+    return;
+  }
+  const options = parseOptions(args);
+  const organizationId = required(options, "organization");
+  const siloOrganizationId = readSiloOrganizationId();
+  if (organizationId !== siloOrganizationId) {
+    throw new Error(`Silo Agent configuration is restricted to ${siloOrganizationId}`);
+  }
+  const configuration = new OrganizationAgentConfiguration(prisma, readSkillStoreRoot());
+
+  switch (command) {
+    case "install-skill": {
+      const installed = await configuration.installSkill({
+        organizationId,
+        sourceDir: required(options, "source"),
+        version: required(options, "version"),
+      });
+      console.log(JSON.stringify(installed));
+      return;
+    }
+    case "upsert-role": {
+      const systemPromptFile = options.get("system-prompt-file");
+      const toolsJson = options.get("tools-json");
+      const tools = toolsJson === undefined
+        ? undefined
+        : toolsJson === "null"
+          ? null
+          : parseTools(toolsJson);
+      const sortOrderRaw = options.get("sort-order");
+      const role = await configuration.upsertRole({
+        organizationId,
+        roleId: required(options, "role"),
+        label: required(options, "label"),
+        ...(options.has("model") ? { defaultModel: options.get("model") ?? null } : {}),
+        ...(systemPromptFile !== undefined
+          ? { systemPrompt: await readFile(systemPromptFile, "utf8") }
+          : {}),
+        ...(tools !== undefined ? { tools } : {}),
+        ...(sortOrderRaw !== undefined ? { sortOrder: integer(sortOrderRaw, "sort-order") } : {}),
+        ...(options.has("default") ? { isDefault: boolean(options.get("default")!, "default") } : {}),
+      });
+      console.log(JSON.stringify(role));
+      return;
+    }
+    case "set-role-skills": {
+      const skills = required(options, "skills").split(",").map((name) => name.trim()).filter(Boolean);
+      await configuration.setRoleSkills({
+        organizationId,
+        roleId: required(options, "role"),
+        skillNames: skills,
+      });
+      console.log(JSON.stringify({ roleId: required(options, "role"), skills }));
+      return;
+    }
+    case "list": {
+      const roles = await prisma.organizationAgentRole.findMany({
+        where: { organizationId },
+        orderBy: [{ sortOrder: "asc" }, { roleId: "asc" }],
+        include: {
+          skillBindings: {
+            orderBy: [{ sortOrder: "asc" }, { agentSkillId: "asc" }],
+            include: { skill: { select: { name: true, version: true, disabledAt: true } } },
+          },
+        },
+      });
+      console.log(JSON.stringify(roles.map((role) => ({
+        roleId: role.roleId,
+        label: role.label,
+        defaultModel: role.defaultModel,
+        systemPromptConfigured: role.systemPrompt !== null,
+        tools: role.tools,
+        disabled: role.disabledAt !== null,
+        default: role.isDefault,
+        skills: role.skillBindings.map((binding) => ({
+          name: binding.skill.name,
+          version: binding.skill.version,
+          disabled: binding.skill.disabledAt !== null,
+        })),
+      })), null, 2));
+      return;
+    }
+    case "verify-store": {
+      const skills = await prisma.organizationAgentSkill.findMany({
+        where: { organizationId, disabledAt: null },
+        select: { name: true, contentDigest: true },
+      });
+      for (const skill of skills) {
+        await verifyStoredSkill({ storeRoot: readSkillStoreRoot(), ...skill });
+      }
+      console.log(JSON.stringify({ verifiedSkills: skills.length }));
+      return;
+    }
+    default:
+      throw new Error(`unknown Agent configuration command: ${command}`);
+  }
+}
+
+function parseOptions(args: readonly string[]): Map<string, string> {
+  const options = new Map<string, string>();
+  for (let index = 0; index < args.length; index += 2) {
+    const flag = args[index];
+    const value = args[index + 1];
+    if (flag === undefined || !flag.startsWith("--") || value === undefined) {
+      throw new Error(`expected --name value, got: ${args.slice(index).join(" ")}`);
+    }
+    const name = flag.slice(2);
+    if (options.has(name)) throw new Error(`duplicate option: --${name}`);
+    options.set(name, value);
+  }
+  return options;
+}
+
+function required(options: ReadonlyMap<string, string>, name: string): string {
+  const value = options.get(name)?.trim();
+  if (value === undefined || value === "") throw new Error(`--${name} is required`);
+  return value;
+}
+
+function parseTools(raw: string): readonly string[] {
+  const parsed = JSON.parse(raw) as unknown;
+  if (!Array.isArray(parsed) || parsed.some((value) => typeof value !== "string")) {
+    throw new Error("--tools-json must be null or a JSON string array");
+  }
+  return parsed;
+}
+
+function integer(raw: string, name: string): number {
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value)) throw new Error(`--${name} must be an integer`);
+  return value;
+}
+
+function boolean(raw: string, name: string): boolean {
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  throw new Error(`--${name} must be true or false`);
+}
+
+function printHelp(): void {
+  console.log(`Usage:
+  agent-config install-skill --organization ORG --source DIR --version VERSION
+  agent-config upsert-role --organization ORG --role ID --label LABEL [--model MODEL] [--system-prompt-file FILE] [--tools-json JSON] [--sort-order N] [--default true|false]
+  agent-config set-role-skills --organization ORG --role ID --skills name,name
+  agent-config list --organization ORG
+  agent-config verify-store --organization ORG`);
+}
+
+main(process.argv.slice(2))
+  .catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  })
+  .finally(async () => {
+    await prisma.$disconnect();
+  });

hub/src/deployment/bootstrap-silo.ts

@@ -226,6 +226,23 @@ async function initializeSilo(
     const count = await tx.organization.count();
     if (count !== 0) throw new Error(`Silo bootstrap requires an empty Organization set; found ${count}`);
     await tx.organization.create({ data: { ...input.organization } });
+    await tx.organizationAgentRole.createMany({
+      data: [
+        {
+          organizationId: input.organization.id,
+          roleId: "draft",
+          label: "草稿",
+          sortOrder: 10,
+          isDefault: true,
+        },
+        {
+          organizationId: input.organization.id,
+          roleId: "review",
+          label: "审校",
+          sortOrder: 20,
+        },
+      ],
+    });
     await tx.organizationProjectSettings.create({
       data: { organizationId: input.organization.id, membersCanCreateProjects: true },
     });

hub/src/deployment/legacy-project-import-cli.ts

@@ -0,0 +1,48 @@
+import { readFile } from "node:fs/promises";
+import { prisma } from "../db.js";
+import { importLegacyProjects, type LegacyProjectManifestEntry } from "./legacyProjectImport.js";
+import { readSiloOrganizationId } from "./silo.js";
+
+async function main(argv: readonly string[]): Promise<void> {
+  const options = parseOptions(argv);
+  const organizationId = readSiloOrganizationId();
+  const manifest = JSON.parse(await readFile(required(options, "manifest"), "utf8")) as unknown;
+  if (!Array.isArray(manifest)) throw new Error("legacy import manifest must be a JSON array");
+  const state = await importLegacyProjects({
+    prisma,
+    organizationId,
+    actorFeishuOpenId: required(options, "actor-open-id"),
+    workspaceRoot: required(options, "workspace-root"),
+    sourceRoot: required(options, "source-root"),
+    stateFile: required(options, "state-file"),
+    projects: manifest as LegacyProjectManifestEntry[],
+    onProgress: (message) => console.error(`[legacy-import] ${message}`),
+  });
+  console.log(JSON.stringify({ imported: Object.keys(state.projects).length }));
+}
+
+function parseOptions(args: readonly string[]): Map<string, string> {
+  const options = new Map<string, string>();
+  for (let index = 0; index < args.length; index += 2) {
+    const flag = args[index];
+    const value = args[index + 1];
+    if (flag === undefined || !flag.startsWith("--") || value === undefined) {
+      throw new Error(`expected --name value, got: ${args.slice(index).join(" ")}`);
+    }
+    options.set(flag.slice(2), value);
+  }
+  return options;
+}
+
+function required(options: ReadonlyMap<string, string>, name: string): string {
+  const value = options.get(name)?.trim();
+  if (!value) throw new Error(`--${name} is required`);
+  return value;
+}
+
+main(process.argv.slice(2))
+  .catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  })
+  .finally(async () => prisma.$disconnect());

hub/src/deployment/legacyProjectImport.ts

@@ -0,0 +1,369 @@
+import { createHash } from "node:crypto";
+import { cp, lstat, mkdir, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import type { PrismaClient } from "@prisma/client";
+import { createFolder, createProjectFromOrgAdmin } from "../projectOnboarding.js";
+
+export interface LegacyProjectManifestEntry {
+  readonly legacyId: string;
+  readonly name: string;
+  readonly folderPath: readonly string[];
+  readonly sourceRelativePath: string;
+}
+
+export interface LegacyProjectImportState {
+  readonly version: 1;
+  readonly projects: Readonly<Record<string, {
+    readonly status: "PENDING" | "COMPLETED";
+    readonly projectId: string;
+    readonly workspaceDir: string;
+    readonly importedAt: string;
+    readonly sourceRelativePath: string;
+  }>>;
+}
+
+export async function importLegacyProjects(input: {
+  readonly prisma: PrismaClient;
+  readonly organizationId: string;
+  readonly actorFeishuOpenId: string;
+  readonly workspaceRoot: string;
+  readonly sourceRoot: string;
+  readonly stateFile: string;
+  readonly projects: readonly LegacyProjectManifestEntry[];
+  readonly onProgress?: (message: string) => void;
+}): Promise<LegacyProjectImportState> {
+  const sourceRoot = await realpath(input.sourceRoot);
+  const state = await readState(input.stateFile);
+  const projects = { ...state.projects };
+  const seen = new Set<string>();
+  for (const entry of input.projects) {
+    validateEntry(entry);
+    if (seen.has(entry.legacyId)) throw new Error(`duplicate legacy project id: ${entry.legacyId}`);
+    seen.add(entry.legacyId);
+    const sourceDir = await confinedSourceDir(sourceRoot, entry.sourceRelativePath);
+    const projectId = importedProjectId(input.organizationId, entry.legacyId);
+    const existing = await input.prisma.project.findUnique({ where: { id: projectId } });
+    const recorded = projects[entry.legacyId];
+    if (recorded !== undefined && (recorded.projectId !== projectId || recorded.sourceRelativePath !== entry.sourceRelativePath)) {
+      throw new Error(`legacy import state identity conflict: ${entry.legacyId}`);
+    }
+    if (recorded?.status === "COMPLETED" && existing === null) {
+      throw new Error(`legacy import state references missing project: ${entry.legacyId} -> ${recorded.projectId}`);
+    }
+    if (existing !== null) {
+      if (existing.organizationId !== input.organizationId || (recorded !== undefined && recorded.projectId !== existing.id)) {
+        throw new Error(`legacy import identity conflict: ${entry.legacyId} -> ${existing.id}`);
+      }
+      if (await hasCompletionMarker(existing.workspaceDir, entry)) {
+        await ensureImportAudit(input.prisma, existing.id, entry);
+        projects[entry.legacyId] = {
+          status: "COMPLETED",
+          projectId: existing.id,
+          workspaceDir: existing.workspaceDir,
+          importedAt: recorded?.importedAt || new Date().toISOString(),
+          sourceRelativePath: entry.sourceRelativePath,
+        };
+        await writeState(input.stateFile, { version: 1, projects });
+        input.onProgress?.(`skip ${entry.legacyId}: recovered completed import`);
+        continue;
+      }
+      if (recorded?.status !== "PENDING") {
+        throw new Error(`refusing to remove legacy project without a matching pending record: ${entry.legacyId}`);
+      }
+      input.onProgress?.(`recover ${entry.legacyId}: remove incomplete target`);
+      await removeIncompleteTarget(input.prisma, existing.id, existing.workspaceDir, input.workspaceRoot);
+    }
+    projects[entry.legacyId] = {
+      status: "PENDING",
+      projectId,
+      workspaceDir: "",
+      importedAt: "",
+      sourceRelativePath: entry.sourceRelativePath,
+    };
+    await writeState(input.stateFile, { version: 1, projects });
+    const folderId = await ensureFolderPath(input.prisma, input.organizationId, ["旧教学资产", ...entry.folderPath]);
+    input.onProgress?.(`import ${entry.legacyId}: ${entry.name}`);
+    const created = await createProjectFromOrgAdmin(input.prisma, {
+      organizationId: input.organizationId,
+      actorFeishuOpenId: input.actorFeishuOpenId,
+      name: entry.name,
+      workspaceRoot: input.workspaceRoot,
+      folderId,
+      projectId,
+    });
+    try {
+      await copyLegacyProject(sourceDir, created.workspaceDir, entry);
+    } catch (error) {
+      try {
+        await removeIncompleteTarget(input.prisma, created.projectId, created.workspaceDir, input.workspaceRoot);
+        delete projects[entry.legacyId];
+        await writeState(input.stateFile, { version: 1, projects });
+      } catch (cleanupError) {
+        throw new AggregateError(
+          [error, cleanupError],
+          `legacy project import and target cleanup failed: ${entry.legacyId}`,
+        );
+      }
+      throw new Error(`legacy project import failed: ${entry.legacyId}: ${errorMessage(error)}`, { cause: error });
+    }
+    await ensureImportAudit(input.prisma, created.projectId, entry);
+    projects[entry.legacyId] = {
+      status: "COMPLETED",
+      projectId: created.projectId,
+      workspaceDir: created.workspaceDir,
+      importedAt: new Date().toISOString(),
+      sourceRelativePath: entry.sourceRelativePath,
+    };
+    await writeState(input.stateFile, { version: 1, projects });
+  }
+  return { version: 1, projects };
+}
+
+async function ensureFolderPath(
+  prisma: PrismaClient,
+  organizationId: string,
+  parts: readonly string[],
+): Promise<string> {
+  let parentId: string | undefined;
+  for (const name of parts) {
+    const existing = await prisma.folder.findFirst({
+      where: { organizationId, parentId: parentId ?? null, name, archivedAt: null },
+      select: { id: true },
+    });
+    if (existing !== null) {
+      parentId = existing.id;
+      continue;
+    }
+    const created = await createFolder(prisma, {
+      organizationId,
+      name,
+      ...(parentId !== undefined ? { parentId } : {}),
+    });
+    parentId = created.id;
+  }
+  if (parentId === undefined) throw new Error("legacy import folder path is empty");
+  return parentId;
+}
+
+async function copyLegacyProject(
+  sourceDir: string,
+  workspaceDir: string,
+  entry: LegacyProjectManifestEntry,
+): Promise<void> {
+  const sourceWorkspace = join(sourceDir, "workspace");
+  await assertNoSymlinks(sourceWorkspace);
+  const names = await readdir(sourceWorkspace);
+  for (const name of names) {
+    if (name === ".claude" || name === ".cph") continue;
+    await cp(join(sourceWorkspace, name), join(workspaceDir, name), {
+      recursive: true,
+      force: false,
+      errorOnExist: true,
+      preserveTimestamps: true,
+      filter: (source) => {
+        const parts = relative(sourceWorkspace, source).split(sep);
+        return !parts.includes(".claude") && !parts.includes(".cph");
+      },
+    });
+  }
+  const legacyDir = join(workspaceDir, ".legacy-source");
+  await mkdir(legacyDir, { mode: 0o750 });
+  await cp(join(sourceDir, "project.json"), join(legacyDir, "project.json"), {
+    force: false,
+    errorOnExist: true,
+    preserveTimestamps: true,
+  });
+  const rawDir = join(sourceDir, "_raw");
+  await assertNoSymlinks(rawDir).catch((error: unknown) => {
+    if (isMissing(error)) return;
+    throw error;
+  });
+  await cp(rawDir, join(legacyDir, "raw"), {
+    recursive: true,
+    force: false,
+    errorOnExist: true,
+    preserveTimestamps: true,
+  }).catch((error: unknown) => {
+    if (isMissing(error)) return;
+    throw error;
+  });
+  await writeFile(join(legacyDir, "migration.json"), `${JSON.stringify({
+    source: "teaching-material-host-service",
+    legacyProjectId: entry.legacyId,
+    legacyPath: entry.sourceRelativePath,
+    migratedAt: new Date().toISOString(),
+  }, null, 2)}\n`, { mode: 0o640 });
+}
+
+function importedProjectId(organizationId: string, legacyId: string): string {
+  const digest = createHash("sha256")
+    .update("teaching-material-host-service\0")
+    .update(organizationId)
+    .update("\0")
+    .update(legacyId)
+    .digest("hex")
+    .slice(0, 32);
+  return `legacy_${digest}`;
+}
+
+async function hasCompletionMarker(
+  workspaceDir: string,
+  entry: LegacyProjectManifestEntry,
+): Promise<boolean> {
+  try {
+    const marker = JSON.parse(await readFile(join(workspaceDir, ".legacy-source", "migration.json"), "utf8")) as unknown;
+    return typeof marker === "object" && marker !== null
+      && "legacyProjectId" in marker && marker.legacyProjectId === entry.legacyId
+      && "legacyPath" in marker && marker.legacyPath === entry.sourceRelativePath;
+  } catch (error) {
+    if (isMissing(error)) return false;
+    if (error instanceof SyntaxError) {
+      throw new Error(`invalid legacy completion marker: ${workspaceDir}`, { cause: error });
+    }
+    throw error;
+  }
+}
+
+async function ensureImportAudit(
+  prisma: PrismaClient,
+  projectId: string,
+  entry: LegacyProjectManifestEntry,
+): Promise<void> {
+  const existing = await prisma.auditEntry.findFirst({
+    where: { projectId, action: "legacy_project.imported" },
+    select: { id: true },
+  });
+  if (existing !== null) return;
+  await prisma.auditEntry.create({
+    data: {
+      projectId,
+      action: "legacy_project.imported",
+      metadata: {
+        source: "teaching-material-host-service",
+        legacyProjectId: entry.legacyId,
+        legacyPath: entry.sourceRelativePath,
+      },
+    },
+  });
+}
+
+async function removeIncompleteTarget(
+  prisma: PrismaClient,
+  projectId: string,
+  workspaceDir: string,
+  workspaceRoot: string,
+): Promise<void> {
+  await assertConfinedExistingPath(workspaceRoot, workspaceDir);
+  const failures: unknown[] = [];
+  try {
+    await prisma.project.delete({ where: { id: projectId } });
+  } catch (error) {
+    failures.push(error);
+  }
+  try {
+    await rm(workspaceDir, { recursive: true, force: true });
+  } catch (error) {
+    failures.push(error);
+  }
+  if (failures.length > 0) throw new AggregateError(failures, `failed to remove incomplete legacy target: ${projectId}`);
+}
+
+async function assertConfinedExistingPath(root: string, path: string): Promise<void> {
+  const trustedRoot = await realpath(root);
+  const candidate = await realpath(path);
+  const rel = relative(trustedRoot, candidate);
+  if (rel === "" || rel === ".." || rel.startsWith("../") || isAbsolute(rel)) {
+    throw new Error(`refusing to remove path outside workspace root: ${path}`);
+  }
+}
+
+async function assertNoSymlinks(path: string): Promise<void> {
+  const metadata = await lstat(path);
+  if (metadata.isSymbolicLink()) throw new Error(`legacy import rejects symbolic link: ${path}`);
+  if (!metadata.isDirectory()) return;
+  for (const entry of await readdir(path)) await assertNoSymlinks(join(path, entry));
+}
+
+async function confinedSourceDir(sourceRoot: string, relativePath: string): Promise<string> {
+  const candidate = await realpath(resolve(sourceRoot, relativePath));
+  const rel = relative(sourceRoot, candidate);
+  if (rel === "" || rel === ".." || rel.startsWith("../") || isAbsolute(rel)) {
+    throw new Error(`legacy source path escapes source root: ${relativePath}`);
+  }
+  return candidate;
+}
+
+function validateEntry(entry: LegacyProjectManifestEntry): void {
+  if (typeof entry !== "object" || entry === null) throw new Error("invalid legacy project entry");
+  if (typeof entry.legacyId !== "string") throw new Error("legacy project id must be a string");
+  if (!/^[A-Za-z0-9_-]+$/.test(entry.legacyId)) throw new Error(`invalid legacy project id: ${entry.legacyId}`);
+  if (typeof entry.name !== "string") throw new Error(`legacy project name must be a string: ${entry.legacyId}`);
+  if (entry.name.trim() === "") throw new Error(`legacy project name is empty: ${entry.legacyId}`);
+  if (typeof entry.sourceRelativePath !== "string") {
+    throw new Error(`legacy source path must be a string: ${entry.legacyId}`);
+  }
+  if (entry.sourceRelativePath === "" || resolve("/", entry.sourceRelativePath) === "/") {
+    throw new Error(`invalid legacy source path: ${entry.legacyId}`);
+  }
+  if (!Array.isArray(entry.folderPath)) throw new Error(`legacy folder path must be an array: ${entry.legacyId}`);
+  for (const part of entry.folderPath) {
+    if (typeof part !== "string" || part.trim() === "" || part === "." || part === ".." || part.includes("/") || part.includes("\\")) {
+      throw new Error(`invalid legacy folder part for ${entry.legacyId}: ${part}`);
+    }
+  }
+}
+
+async function readState(path: string): Promise<LegacyProjectImportState> {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8")) as LegacyProjectImportState;
+    if (parsed.version !== 1 || typeof parsed.projects !== "object" || parsed.projects === null) {
+      throw new Error(`invalid legacy import state: ${path}`);
+    }
+    for (const [legacyId, record] of Object.entries(parsed.projects)) validateStateRecord(path, legacyId, record);
+    return parsed;
+  } catch (error) {
+    if (isMissing(error)) return { version: 1, projects: {} };
+    throw error;
+  }
+}
+
+function validateStateRecord(path: string, legacyId: string, record: unknown): void {
+  if (typeof record !== "object" || record === null || Array.isArray(record)) {
+    throw new Error(`invalid legacy import state record: ${path}#${legacyId}`);
+  }
+  const values = record as Record<string, unknown>;
+  const expectedKeys = ["importedAt", "projectId", "sourceRelativePath", "status", "workspaceDir"];
+  if (Object.keys(values).sort().join("\0") !== expectedKeys.join("\0")) {
+    throw new Error(`invalid legacy import state fields: ${path}#${legacyId}`);
+  }
+  if (values.status !== "PENDING" && values.status !== "COMPLETED") {
+    throw new Error(`invalid legacy import state status: ${path}#${legacyId}`);
+  }
+  for (const field of ["projectId", "workspaceDir", "importedAt", "sourceRelativePath"] as const) {
+    if (typeof values[field] !== "string") throw new Error(`invalid legacy import state ${field}: ${path}#${legacyId}`);
+  }
+  if (values.projectId === "" || values.sourceRelativePath === "") {
+    throw new Error(`invalid legacy import state identity: ${path}#${legacyId}`);
+  }
+  if (values.status === "PENDING" && (values.workspaceDir !== "" || values.importedAt !== "")) {
+    throw new Error(`invalid pending legacy import state: ${path}#${legacyId}`);
+  }
+  if (values.status === "COMPLETED" && (values.workspaceDir === "" || values.importedAt === "")) {
+    throw new Error(`invalid completed legacy import state: ${path}#${legacyId}`);
+  }
+}
+
+async function writeState(path: string, state: LegacyProjectImportState): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o750 });
+  const temporary = `${path}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, path);
+}
+
+function isMissing(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

hub/src/feishu/bindingLifecycle.ts

@@ -0,0 +1,101 @@
+import type { PrismaClient } from "@prisma/client";
+import {
+  requireActiveFeishuApplicationConnectionInTransaction,
+  scopedFeishuPrincipalId,
+} from "./identityNamespace.js";
+import { lockActiveOrganization } from "../org/status.js";
+
+export type FeishuBindingLifecycleReason = "chat_dissolved" | "bot_removed";
+
+/**
+ * Archive a project's active Feishu chat binding after Feishu has notified this
+ * bot that the chat dissolved or that the bot was removed. The event can be
+ * redelivered; only the first delivery changes state and writes an audit row.
+ */
+export async function archiveFeishuBindingForLifecycleEvent(
+  prisma: PrismaClient,
+  input: {
+    readonly chatId: string;
+    readonly eventId: string;
+    readonly reason: FeishuBindingLifecycleReason;
+  },
+): Promise<{ readonly archived: boolean; readonly projectId?: string | undefined }> {
+  const chatId = requireNonEmpty(input.chatId, "Feishu chat id");
+  const eventId = requireNonEmpty(input.eventId, "Feishu event id");
+  return prisma.$transaction(async (tx) => {
+    // Feishu WS delivery is at-least-once. Persist the receipt in the same
+    // transaction as the archive so a failed archive remains eligible for a
+    // retry, while an old redelivery cannot archive a later re-binding.
+    const receipt = await tx.feishuEventReceipt.createMany({
+      data: {
+        eventId,
+        eventType: lifecycleEventType(input.reason),
+      },
+      skipDuplicates: true,
+    });
+    if (receipt.count === 0) return { archived: false };
+
+    const binding = await tx.projectGroupBinding.findFirst({
+      where: { chatId, archivedAt: null },
+      select: { id: true, projectId: true, project: { select: { organizationId: true } } },
+    });
+    if (binding === null) return { archived: false };
+
+    await lockActiveOrganization(tx, binding.project.organizationId);
+    const connection = await tx.organizationFeishuApplicationConnection.findUnique({
+      where: { organizationId: binding.project.organizationId },
+      select: { id: true },
+    });
+    if (connection === null) {
+      throw new Error(`Feishu application connection not found for organization ${binding.project.organizationId}`);
+    }
+    const activeConnection = await requireActiveFeishuApplicationConnectionInTransaction(tx, connection.id);
+    if (activeConnection.organizationId !== binding.project.organizationId) {
+      throw new Error("Feishu application connection Organization scope mismatch");
+    }
+    const now = new Date();
+    const archived = await tx.projectGroupBinding.updateMany({
+      where: { id: binding.id, archivedAt: null },
+      data: { archivedAt: now },
+    });
+    if (archived.count === 0) return { archived: false };
+
+    await tx.permissionGrant.updateMany({
+      where: {
+        resourceType: "PROJECT",
+        resourceId: binding.projectId,
+        principalType: "FEISHU_CHAT",
+        // Bindings created before ADR-0024 used the raw chat id. Retire only
+        // that exact legacy principal alongside the current scoped principal.
+        principalId: {
+          in: [scopedFeishuPrincipalId("CHAT", connection.id, chatId), chatId],
+        },
+        revokedAt: null,
+      },
+      data: { revokedAt: now },
+    });
+    await tx.auditEntry.create({
+      data: {
+        organizationId: binding.project.organizationId,
+        projectId: binding.projectId,
+        action: "project.chat_binding_archived",
+        metadata: {
+          chatId,
+          reason: input.reason,
+          eventId,
+        },
+      },
+    });
+    return { archived: true, projectId: binding.projectId };
+  });
+}
+
+function lifecycleEventType(reason: FeishuBindingLifecycleReason): string {
+  return reason === "chat_dissolved" ? "im.chat.disbanded_v1" : "im.chat.member.bot.deleted_v1";
+}
+
+function requireNonEmpty(value: string, label: string): string {
+  const trimmed = value.trim();
+  if (trimmed === "") throw new Error(`${label} is required`);
+  return trimmed;
+}

hub/src/feishu/client.ts

@@ -100,11 +100,19 @@ export interface CardActionEvent {
     readonly value?: unknown;
     readonly tag?: string;
     readonly option?: string;
+    readonly form_value?: Readonly<Record<string, unknown>>;
   };
   readonly context?: { readonly open_message_id?: string; readonly open_chat_id?: string };
   readonly token?: string;
 }
 
+/** A binding-ending Feishu event delivered to this application's bot. */
+export interface FeishuBindingLifecycleEvent {
+  readonly eventId: string;
+  readonly chatId: string;
+  readonly reason: "chat_dissolved" | "bot_removed";
+}
+
 interface ContactBasicUser {
   readonly name?: string | undefined;
   readonly i18n_name?: {
@@ -921,6 +929,7 @@ export async function startFeishuListenerWithClient(
   onMessage: (event: MessageReceiveEvent, rt: FeishuRuntime) => Promise<void>,
   onCardAction?: (event: CardActionEvent, rt: FeishuRuntime) => Promise<void>,
   onTerminalError?: (error: Error) => void,
+  onBindingLifecycle?: (event: FeishuBindingLifecycleEvent) => Promise<void>,
 ): Promise<FeishuRuntime> {
   let state: "STARTING" | "READY" | "FAILED" = "STARTING";
   let resolveReady!: () => void;
@@ -962,6 +971,14 @@ export async function startFeishuListenerWithClient(
         .catch((e) => { logger.error({ err: e }, "feishu card action handler threw"); });
     };
   }
+  if (onBindingLifecycle !== undefined) {
+    handlers["im.chat.disbanded_v1"] = async (data) => {
+      await dispatchBindingLifecycleEvent(data, "chat_dissolved", onBindingLifecycle, logger);
+    };
+    handlers["im.chat.member.bot.deleted_v1"] = async (data) => {
+      await dispatchBindingLifecycleEvent(data, "bot_removed", onBindingLifecycle, logger);
+    };
+  }
   await wsClient.start({ eventDispatcher: new lark.EventDispatcher({}).register(handlers) });
   let timeout: ReturnType<typeof setTimeout> | undefined;
   const startupTimeout = new Promise<never>((_resolve, reject) => {
@@ -976,6 +993,36 @@ export async function startFeishuListenerWithClient(
   return rt;
 }
 
+async function dispatchBindingLifecycleEvent(
+  data: unknown,
+  reason: FeishuBindingLifecycleEvent["reason"],
+  onBindingLifecycle: (event: FeishuBindingLifecycleEvent) => Promise<void>,
+  logger: FastifyBaseLogger,
+): Promise<void> {
+  const event = bindingLifecycleEventFrom(data, reason);
+  if (event === null) {
+    logger.warn({ reason }, "feishu binding lifecycle event missing chat id");
+    return;
+  }
+  await onBindingLifecycle(event);
+}
+
+function bindingLifecycleEventFrom(
+  data: unknown,
+  reason: FeishuBindingLifecycleEvent["reason"],
+): FeishuBindingLifecycleEvent | null {
+  if (typeof data !== "object" || data === null) return null;
+  const event = data as { readonly chat_id?: unknown; readonly event_id?: unknown; readonly header?: { readonly event_id?: unknown } };
+  if (typeof event.chat_id !== "string" || event.chat_id.trim() === "") return null;
+  const eventId = typeof event.event_id === "string" && event.event_id !== ""
+    ? event.event_id
+    : typeof event.header?.event_id === "string" && event.header.event_id !== ""
+      ? event.header.event_id
+      : undefined;
+  if (eventId === undefined) return null;
+  return { chatId: event.chat_id, reason, eventId };
+}
+
 export async function startFeishuListener(
   config: FeishuConfig,
   logger: FastifyBaseLogger,

hub/src/feishu/fileDelivery.ts

@@ -1,4 +1,4 @@
-import { extname, isAbsolute, join } from "node:path";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import {
   WorkspaceFileBoundaryError,
   readWorkspaceFileNoFollow,
@@ -10,39 +10,21 @@ export interface DeliverableFile {
   readonly data: Buffer;
 }
 
-const DELIVERABLE_EXTENSIONS = new Set([
-  ".csv",
-  ".doc",
-  ".docx",
-  ".gif",
-  ".jpeg",
-  ".jpg",
-  ".md",
-  ".pdf",
-  ".png",
-  ".ppt",
-  ".pptx",
-  ".svg",
-  ".txt",
-  ".typ",
-  ".xls",
-  ".xlsx",
-  ".zip",
-]);
+const DELIVERABLE_CPH_DIRECTORY = "inbox";
 
 export async function resolveDeliverableFile(
   requestedPath: string,
   workspaceRoot: string,
   workspaceDir: string,
+  maxBytes?: number,
 ): Promise<DeliverableFile | null> {
   const token = requestedPath.trim();
-  if (token === "" || !DELIVERABLE_EXTENSIONS.has(extname(token).toLowerCase())) {
-    return null;
-  }
+  if (token === "") return null;
 
   for (const candidate of candidatePaths(token)) {
+    assertNotPlatformRuntimePath(candidate, workspaceDir);
     try {
-      return await readWorkspaceFileNoFollow(workspaceRoot, workspaceDir, candidate);
+      return await readWorkspaceFileNoFollow(workspaceRoot, workspaceDir, candidate, maxBytes);
     } catch (error) {
       if (!(error instanceof WorkspaceFileBoundaryError) || error.reason !== "not_found") {
         throw error;
@@ -54,6 +36,20 @@ export async function resolveDeliverableFile(
   return null;
 }
 
+function assertNotPlatformRuntimePath(candidate: string, workspaceDir: string): void {
+  const workspace = resolve(workspaceDir);
+  const target = isAbsolute(candidate) ? resolve(candidate) : resolve(workspace, candidate);
+  const rel = relative(workspace, target);
+  const components = rel.split(sep);
+  if (components[0] === ".cph" && components[1] !== DELIVERABLE_CPH_DIRECTORY) {
+    throw new WorkspaceFileBoundaryError(
+      `platform runtime files cannot be delivered: ${candidate}`,
+      candidate,
+      "boundary",
+    );
+  }
+}
+
 function candidatePaths(token: string): string[] {
   if (isAbsolute(token)) return [token];
   const candidates = [token];

hub/src/feishu/fileDeliveryTool.ts

@@ -15,6 +15,7 @@ export interface FileDeliveryToolOptions {
   readonly runId: string;
   readonly workspaceRoot?: string | undefined;
   readonly workspaceDir: string;
+  readonly maxFileBytes?: number | undefined;
   readonly sendOptions?: SendMessageOptions | undefined;
   readonly approvalManager: ApprovalManager;
   readonly onDelivered?: (path: string) => void;
@@ -29,7 +30,7 @@ export function createFileDeliveryMcpServer(options: FileDeliveryToolOptions): M
     tools.push(
       tool(
         "send_file",
-        "Upload an existing file from the current project workspace to the current Feishu chat. The path must point to a concrete no-symlink file, for example build/student.pdf or README.md.",
+        "Upload any existing regular file from the current project workspace to the current Feishu chat. The path must point to a concrete no-symlink file and must not be inside platform runtime directories.",
         {
           path: z.string().describe("Workspace-relative path, or an absolute path physically inside the current workspace."),
           name: z.string().optional().describe("Optional display filename. Defaults to the file's basename."),
@@ -46,12 +47,18 @@ export function createFileDeliveryMcpServer(options: FileDeliveryToolOptions): M
               content: [{ type: "text", text: "File delivery is unavailable because workspace isolation is not configured." }],
             };
           }
+          if (options.maxFileBytes === undefined) {
+            throw new Error("Agent file delivery requires a configured maximum file size");
+          }
           let file;
           try {
-            file = await resolveDeliverableFile(args.path, workspaceRoot, options.workspaceDir);
+            file = await resolveDeliverableFile(args.path, workspaceRoot, options.workspaceDir, options.maxFileBytes);
           } catch (error) {
             const boundaryViolation = error instanceof WorkspaceFileBoundaryError && error.reason === "boundary";
-            const log = boundaryViolation ? options.rt.logger.warn.bind(options.rt.logger) : options.rt.logger.error.bind(options.rt.logger);
+            const limitViolation = error instanceof WorkspaceFileBoundaryError && error.reason === "limit";
+            const log = boundaryViolation || limitViolation
+              ? options.rt.logger.warn.bind(options.rt.logger)
+              : options.rt.logger.error.bind(options.rt.logger);
             log(
               {
                 runId: options.runId,
@@ -61,12 +68,20 @@ export function createFileDeliveryMcpServer(options: FileDeliveryToolOptions): M
               },
               boundaryViolation
                 ? "Agent file delivery refused by workspace boundary"
+                : limitViolation
+                  ? "Agent file delivery refused by file size limit"
                   : "Agent file delivery failed during workspace file access",
             );
+            if (limitViolation) {
+              return {
+                isError: true,
+                content: [{ type: "text", text: `File exceeds the configured delivery limit: ${args.path}` }],
+              };
+            }
             if (!boundaryViolation) throw error;
             return {
               isError: true,
-              content: [{ type: "text", text: "File path is outside the current workspace or uses a symlink." }],
+              content: [{ type: "text", text: "File path is outside the current workspace, belongs to platform runtime, or uses a symlink." }],
             };
           }
           if (file === null) {

hub/src/feishu/identityNamespace.ts

@@ -66,7 +66,7 @@ export async function upsertScopedFeishuIdentityInTransaction(
   const principalId = scopedFeishuPrincipalId("USER", connectionId, openId);
   const userId = deterministicFeishuUserId(connectionId, openId);
 
-  const connection = await lockActiveConnection(prisma, connectionId);
+  const connection = await requireActiveFeishuApplicationConnectionInTransaction(prisma, connectionId);
   if (input.expectedOrganizationId !== undefined &&
       input.expectedOrganizationId !== connection.organizationId) {
     throw new Error("Feishu identity Organization scope mismatch");
@@ -114,7 +114,7 @@ export async function resolveScopedFeishuIdentity(
   const connectionId = nonEmpty(input.connectionId, "Feishu connectionId");
   const openId = nonEmpty(input.openId, "Feishu openId");
   return prisma.$transaction(async (tx) => {
-    const connection = await lockActiveConnection(tx, connectionId);
+    const connection = await requireActiveFeishuApplicationConnectionInTransaction(tx, connectionId);
     if (input.expectedOrganizationId !== undefined &&
         input.expectedOrganizationId !== connection.organizationId) {
       throw new Error("Feishu identity Organization scope mismatch");
@@ -127,7 +127,12 @@ export async function resolveScopedFeishuIdentity(
   });
 }
 
-async function lockActiveConnection(
+/**
+ * Lock and prove that a Feishu application connection is currently usable.
+ * Callers handling provider-originated data use this before trusting a
+ * connection-scoped identifier.
+ */
+export async function requireActiveFeishuApplicationConnectionInTransaction(
   prisma: Prisma.TransactionClient,
   connectionId: string,
 ): Promise<{ readonly organizationId: string }> {

hub/src/feishu/messageBatcher.ts

@@ -47,8 +47,8 @@ export class MessageBatcher {
     this.extendedDebounceMs = options.extendedDebounceMs ?? DEFAULT_OPTIONS.extendedDebounceMs;
   }
 
-  async enqueue(chatId: string, senderOpenId: string, text: string): Promise<void> {
-    const key = messageBatchKey(chatId, senderOpenId);
+  async enqueue(chatId: string, senderOpenId: string, text: string, discriminator?: string): Promise<void> {
+    const key = messageBatchKey(chatId, senderOpenId, discriminator);
     await this.runSerial(key, async () => {
       const existing = this.pending.get(key);
       const batch =
@@ -120,6 +120,8 @@ export class MessageBatcher {
   }
 }
 
-export function messageBatchKey(chatId: string, senderOpenId: string): string {
-  return `${chatId}:${senderOpenId}`;
+export function messageBatchKey(chatId: string, senderOpenId: string, discriminator?: string): string {
+  return discriminator === undefined
+    ? `${chatId}:${senderOpenId}`
+    : `${chatId}:${senderOpenId}:${discriminator}`;
 }

hub/src/feishu/projectConsole.ts

@@ -0,0 +1,381 @@
+import { Prisma, type PrismaClient } from "@prisma/client";
+import { lockActiveProjectOrganization } from "../org/status.js";
+
+export interface ProjectConsoleState {
+  readonly organizationId: string;
+  readonly projectId: string;
+  readonly projectName: string;
+  readonly folderId: string | null;
+  readonly breadcrumb: string;
+  readonly selectedRole: { readonly id: string; readonly roleId: string; readonly label: string };
+  readonly roles: readonly { readonly id: string; readonly roleId: string; readonly label: string }[];
+  readonly currentSession: {
+    readonly id: string;
+    readonly title: string | null;
+    readonly updatedAt: Date;
+    readonly runCount: number;
+    readonly sdkSessionReady: boolean;
+  } | null;
+}
+
+export interface FolderDestinationPage {
+  readonly folderId: string | null;
+  readonly parentFolderId: string | null;
+  readonly breadcrumb: string;
+  readonly childFolders: readonly { readonly id: string; readonly name: string }[];
+}
+
+export async function browseFolderDestinations(
+  prisma: PrismaClient,
+  input: { readonly organizationId: string; readonly folderId: string | null },
+): Promise<FolderDestinationPage> {
+  const folder = input.folderId === null ? null : await prisma.folder.findFirst({
+    where: { id: input.folderId, organizationId: input.organizationId, archivedAt: null },
+    select: { id: true, parentId: true },
+  });
+  if (input.folderId !== null && folder === null) throw new Error(`active folder not found: ${input.folderId}`);
+  const childFolders = await prisma.folder.findMany({
+    where: {
+      organizationId: input.organizationId,
+      parentId: input.folderId,
+      archivedAt: null,
+      kind: { not: "SYSTEM_INBOX" },
+    },
+    orderBy: [{ sortKey: "asc" }, { name: "asc" }, { id: "asc" }],
+    select: { id: true, name: true },
+  });
+  return {
+    folderId: input.folderId,
+    parentFolderId: folder?.parentId ?? null,
+    breadcrumb: input.folderId === null ? "根目录" : await folderBreadcrumb(prisma, input.folderId),
+    childFolders,
+  };
+}
+
+export async function createFolderAndMoveProject(
+  prisma: PrismaClient,
+  input: {
+    readonly organizationId: string;
+    readonly projectId: string;
+    readonly parentFolderId: string | null;
+    readonly name: string;
+    readonly actorUserId?: string | undefined;
+  },
+): Promise<{ readonly folderId: string; readonly folderName: string }> {
+  const name = input.name.trim();
+  if (name === "") throw new Error("folder name is required");
+  if (name.length > 100) throw new Error("folder name must not exceed 100 characters");
+  return prisma.$transaction(async (tx) => {
+    await lockActiveProjectOrganization(tx, input.projectId);
+    const project = await tx.project.findFirst({
+      where: { id: input.projectId, organizationId: input.organizationId, archivedAt: null },
+      select: { id: true, folderId: true },
+    });
+    if (project === null) throw new Error("active project not found in Organization");
+    if (input.parentFolderId !== null) {
+      const parent = await tx.folder.findFirst({
+        where: {
+          id: input.parentFolderId,
+          organizationId: input.organizationId,
+          archivedAt: null,
+          kind: { not: "SYSTEM_INBOX" },
+        },
+        select: { id: true },
+      });
+      if (parent === null) throw new Error("active destination folder not found in Organization");
+    }
+    const folder = await tx.folder.create({
+      data: {
+        organizationId: input.organizationId,
+        parentId: input.parentFolderId,
+        name,
+      },
+      select: { id: true, name: true },
+    });
+    await tx.project.update({ where: { id: project.id }, data: { folderId: folder.id } });
+    await tx.auditEntry.create({
+      data: {
+        organizationId: input.organizationId,
+        projectId: project.id,
+        ...(input.actorUserId !== undefined ? { actorUserId: input.actorUserId } : {}),
+        action: "folder.created_and_project_moved_from_feishu",
+        metadata: {
+          folderId: folder.id,
+          parentFolderId: input.parentFolderId,
+          previousFolderId: project.folderId,
+          name: folder.name,
+        },
+      },
+    });
+    return { folderId: folder.id, folderName: folder.name };
+  });
+}
+
+export async function loadProjectConsole(
+  prisma: PrismaClient,
+  input: { readonly projectId: string; readonly chatId: string },
+): Promise<ProjectConsoleState> {
+  const binding = await prisma.projectGroupBinding.findFirst({
+    where: { projectId: input.projectId, chatId: input.chatId, archivedAt: null },
+    select: {
+      selectedRole: { select: { id: true, roleId: true, label: true, disabledAt: true, organizationId: true } },
+      project: {
+        select: {
+          id: true,
+          name: true,
+          folderId: true,
+          organizationId: true,
+          archivedAt: true,
+          organization: {
+            select: {
+              status: true,
+              agentRoles: {
+                where: { disabledAt: null },
+                orderBy: [{ sortOrder: "asc" }, { roleId: "asc" }],
+                select: { id: true, roleId: true, label: true },
+              },
+            },
+          },
+        },
+      },
+    },
+  });
+  if (binding === null) throw new Error("project console requires an active binding to this chat");
+  const { project, selectedRole } = binding;
+  if (project.archivedAt !== null) throw new Error(`project ${project.id} is archived`);
+  if (project.organization.status !== "ACTIVE") {
+    throw new Error(`organization ${project.organizationId} is ${project.organization.status}`);
+  }
+  if (selectedRole.disabledAt !== null || selectedRole.organizationId !== project.organizationId) {
+    throw new Error("project group selected role is unavailable or cross-Organization");
+  }
+  const model = await selectedRoleModel(prisma, project.organizationId, selectedRole.id);
+  const currentSession = await prisma.agentSession.findFirst({
+    where: {
+      projectId: project.id,
+      roleId: selectedRole.roleId,
+      ...(model === null ? {} : { model }),
+      archivedAt: null,
+    },
+    orderBy: { updatedAt: "desc" },
+    select: { id: true, title: true, updatedAt: true, metadata: true, _count: { select: { runs: true } } },
+  });
+  return {
+    organizationId: project.organizationId,
+    projectId: project.id,
+    projectName: project.name,
+    folderId: project.folderId,
+    breadcrumb: project.folderId === null ? "根目录" : await folderBreadcrumb(prisma, project.folderId),
+    selectedRole: { id: selectedRole.id, roleId: selectedRole.roleId, label: selectedRole.label },
+    roles: project.organization.agentRoles,
+    currentSession: currentSession === null ? null : {
+      id: currentSession.id,
+      title: currentSession.title,
+      updatedAt: currentSession.updatedAt,
+      runCount: currentSession._count.runs,
+      sdkSessionReady: hasClaudeSessionId(currentSession.metadata),
+    },
+  };
+}
+
+function hasClaudeSessionId(metadata: unknown): boolean {
+  if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) return false;
+  const value = (metadata as Record<string, unknown>)["claudeSessionId"];
+  return typeof value === "string" && value !== "";
+}
+
+function isUserResumable(metadata: unknown): boolean {
+  return typeof metadata === "object" && metadata !== null && !Array.isArray(metadata) &&
+    (metadata as Record<string, unknown>)["userResumable"] === true;
+}
+
+function userResumableMetadata(metadata: unknown, value: boolean): Prisma.InputJsonObject {
+  const base = typeof metadata === "object" && metadata !== null && !Array.isArray(metadata)
+    ? metadata as Prisma.JsonObject
+    : {};
+  return { ...base, userResumable: value };
+}
+
+export async function selectProjectGroupRole(
+  prisma: PrismaClient,
+  input: {
+    readonly projectId: string;
+    readonly chatId: string;
+    readonly agentRoleId: string;
+    readonly actorUserId: string;
+  },
+): Promise<void> {
+  await prisma.$transaction(async (tx) => {
+    await lockActiveProjectOrganization(tx, input.projectId);
+    const binding = await tx.projectGroupBinding.findFirst({
+      where: { projectId: input.projectId, chatId: input.chatId, archivedAt: null },
+      select: { id: true, project: { select: { organizationId: true } } },
+    });
+    if (binding === null) throw new Error("role selection requires an active binding to this chat");
+    const role = await tx.organizationAgentRole.findFirst({
+      where: {
+        id: input.agentRoleId,
+        organizationId: binding.project.organizationId,
+        disabledAt: null,
+      },
+      select: { id: true, roleId: true },
+    });
+    if (role === null) throw new Error(`active role not found: ${input.agentRoleId}`);
+    await tx.projectGroupBinding.update({
+      where: { id: binding.id },
+      data: { selectedAgentRoleId: role.id },
+    });
+    await tx.auditEntry.create({
+      data: {
+        projectId: input.projectId,
+        actorUserId: input.actorUserId,
+        action: "project_group.role_selected",
+        metadata: { chatId: input.chatId, roleId: role.roleId },
+      },
+    });
+  });
+}
+
+export async function archiveCurrentRoleSession(
+  prisma: PrismaClient,
+  input: { readonly projectId: string; readonly chatId: string; readonly actorUserId: string },
+): Promise<boolean> {
+  return prisma.$transaction(async (tx) => {
+    await lockActiveProjectOrganization(tx, input.projectId);
+    const activeRun = await tx.agentRun.findFirst({
+      where: { projectId: input.projectId, status: { in: ["ACTIVE", "WAITING_FOR_USER"] } },
+      select: { id: true },
+    });
+    if (activeRun !== null) throw new Error(`cannot archive a session while run ${activeRun.id} is active`);
+    const binding = await tx.projectGroupBinding.findFirst({
+      where: { projectId: input.projectId, chatId: input.chatId, archivedAt: null },
+      select: { selectedRole: { select: { roleId: true } } },
+    });
+    if (binding === null) throw new Error("session operation requires an active binding to this chat");
+    const session = await tx.agentSession.findFirst({
+      where: { projectId: input.projectId, roleId: binding.selectedRole.roleId, archivedAt: null },
+      orderBy: { updatedAt: "desc" },
+      select: { id: true, metadata: true },
+    });
+    if (session !== null) {
+      await tx.agentSession.update({
+        where: { id: session.id },
+        data: { archivedAt: new Date(), metadata: userResumableMetadata(session.metadata, true) },
+      });
+    }
+    await tx.auditEntry.create({
+      data: {
+        projectId: input.projectId,
+        actorUserId: input.actorUserId,
+        action: "agent_session.new_requested",
+        metadata: { chatId: input.chatId, roleId: binding.selectedRole.roleId, archivedSessionId: session?.id ?? null },
+      },
+    });
+    return session !== null;
+  });
+}
+
+export async function listRoleSessionHistory(
+  prisma: PrismaClient,
+  input: { readonly projectId: string; readonly chatId: string },
+): Promise<readonly { readonly id: string; readonly title: string | null; readonly updatedAt: Date; readonly runCount: number }[]> {
+  const binding = await prisma.projectGroupBinding.findFirst({
+    where: { projectId: input.projectId, chatId: input.chatId, archivedAt: null },
+    select: { selectedRole: { select: { roleId: true } } },
+  });
+  if (binding === null) throw new Error("session history requires an active binding to this chat");
+  const sessions = await prisma.agentSession.findMany({
+    where: { projectId: input.projectId, roleId: binding.selectedRole.roleId, archivedAt: { not: null } },
+    orderBy: { updatedAt: "desc" },
+    take: 10,
+    select: { id: true, title: true, updatedAt: true, metadata: true, _count: { select: { runs: true } } },
+  });
+  return sessions.filter((session) => isUserResumable(session.metadata)).map((session) => ({
+    id: session.id,
+    title: session.title,
+    updatedAt: session.updatedAt,
+    runCount: session._count.runs,
+  }));
+}
+
+export async function resumeRoleSession(
+  prisma: PrismaClient,
+  input: {
+    readonly projectId: string;
+    readonly chatId: string;
+    readonly sessionId: string;
+    readonly actorUserId: string;
+  },
+): Promise<void> {
+  await prisma.$transaction(async (tx) => {
+    await lockActiveProjectOrganization(tx, input.projectId);
+    const activeRun = await tx.agentRun.findFirst({
+      where: { projectId: input.projectId, status: { in: ["ACTIVE", "WAITING_FOR_USER"] } },
+      select: { id: true },
+    });
+    if (activeRun !== null) throw new Error(`cannot resume a session while run ${activeRun.id} is active`);
+    const binding = await tx.projectGroupBinding.findFirst({
+      where: { projectId: input.projectId, chatId: input.chatId, archivedAt: null },
+      select: { selectedRole: { select: { roleId: true } } },
+    });
+    if (binding === null) throw new Error("session resume requires an active binding to this chat");
+    const target = await tx.agentSession.findFirst({
+      where: { id: input.sessionId, projectId: input.projectId, roleId: binding.selectedRole.roleId, archivedAt: { not: null } },
+      select: { id: true, provider: true, model: true, metadata: true },
+    });
+    if (target === null || !isUserResumable(target.metadata)) {
+      throw new Error("user-resumable archived session not found for the selected role");
+    }
+    const activeSessions = await tx.agentSession.findMany({
+      where: {
+        projectId: input.projectId,
+        roleId: binding.selectedRole.roleId,
+        provider: target.provider,
+        model: target.model,
+        archivedAt: null,
+      },
+      select: { id: true, metadata: true },
+    });
+    const archivedAt = new Date();
+    for (const session of activeSessions) {
+      await tx.agentSession.update({
+        where: { id: session.id },
+        data: { archivedAt, metadata: userResumableMetadata(session.metadata, true) },
+      });
+    }
+    await tx.agentSession.update({
+      where: { id: target.id },
+      data: { archivedAt: null, metadata: userResumableMetadata(target.metadata, false) },
+    });
+    await tx.auditEntry.create({
+      data: {
+        projectId: input.projectId,
+        actorUserId: input.actorUserId,
+        action: "agent_session.resumed",
+        metadata: { chatId: input.chatId, roleId: binding.selectedRole.roleId, sessionId: target.id },
+      },
+    });
+  });
+}
+
+async function selectedRoleModel(
+  prisma: PrismaClient,
+  organizationId: string,
+  roleId: string,
+): Promise<string | null> {
+  const role = await prisma.organizationAgentRole.findFirst({
+    where: { id: roleId, organizationId, disabledAt: null },
+    select: { defaultModel: true },
+  });
+  if (role === null) throw new Error(`selected role not found: ${roleId}`);
+  return role.defaultModel;
+}
+
+async function folderBreadcrumb(prisma: PrismaClient, folderId: string): Promise<string> {
+  const rows = await prisma.$queryRaw<Array<{ breadcrumb: string }>>(Prisma.sql`
+    SELECT cph_folder_breadcrumb(${folderId}) AS breadcrumb
+  `);
+  const breadcrumb = rows[0]?.breadcrumb;
+  if (breadcrumb === undefined) throw new Error(`failed to resolve folder breadcrumb: ${folderId}`);
+  return breadcrumb;
+}

hub/src/feishu/projectOnboardingCard.ts

@@ -1,89 +1,61 @@
-export interface OnboardingProjectOption {
-  readonly projectId: string;
-  readonly name: string;
-  readonly folderName?: string | undefined;
-}
+import type { ProjectDiscoveryPage, ProjectFolderPage } from "../projectDiscovery.js";
 
-export interface OnboardingFolderOption {
-  readonly folderId: string;
-  readonly name: string;
-}
+export type ProjectOnboardingView =
+  | { readonly mode: "search"; readonly result: ProjectDiscoveryPage }
+  | { readonly mode: "browse"; readonly result: ProjectFolderPage };
 
 export interface ProjectOnboardingActionValue {
-  readonly action: "create_project_from_chat" | "bind_project";
+  readonly action:
+    | "create_project_from_chat"
+    | "bind_project"
+    | "browse_folder"
+    | "search_page"
+    | "rename_project"
+    | "select_agent_role"
+    | "new_agent_session"
+    | "show_session_history"
+    | "resume_agent_session"
+    | "compact_agent_session"
+    | "browse_move_destination"
+    | "move_project"
+    | "create_folder";
   readonly organization_id: string;
   readonly project_id?: string | undefined;
   readonly folder_id?: string | undefined;
+  readonly search_query?: string | undefined;
+  readonly page?: number | undefined;
+  readonly agent_role_id?: string | undefined;
+  readonly session_id?: string | undefined;
 }
 
 export function buildUnboundChatOnboardingCard(params: {
   readonly organizationId: string;
   readonly organizationName: string;
-  readonly folders: readonly OnboardingFolderOption[];
-  readonly projects: readonly OnboardingProjectOption[];
   readonly canCreateProject: boolean;
+  readonly view: ProjectOnboardingView;
 }): Record<string, unknown> {
-  const actions: unknown[] = [];
-  if (params.canCreateProject) {
-    const folders = params.folders.length === 0 ? [{ folderId: undefined, name: "默认位置" }] : params.folders.slice(0, 3);
-    for (const folder of folders) {
-      actions.push({
-        tag: "button",
-        text: { tag: "plain_text", content: `新建到 ${buttonLabel(folder.name, 14)}` },
-        type: "primary",
-        value: {
-          project_onboarding: {
-            action: "create_project_from_chat",
-            organization_id: params.organizationId,
-            ...(folder.folderId !== undefined ? { folder_id: folder.folderId } : {}),
-          },
-        },
-      });
-    }
-  }
-
-  for (const project of params.projects.slice(0, 5)) {
-    actions.push({
-      tag: "button",
-      text: { tag: "plain_text", content: buttonProjectLabel(project) },
-      type: "default",
-      value: {
-        project_onboarding: {
-          action: "bind_project",
-          organization_id: params.organizationId,
-          project_id: project.projectId,
-        },
-      },
-    });
-  }
-
-  const elements: unknown[] = [
-    {
+  const elements: unknown[] = [{
     tag: "markdown",
-      content: [
-        `这个飞书群还没有绑定项目。`,
-        ``,
-        `组织: **${escapeMarkdown(params.organizationName)}**`,
-        `可以选择 folder 新建项目并绑定到本群，或绑定你已经有管理权限的未绑定项目。`,
-      ].join("\n"),
-    },
-  ];
+    content: onboardingSummary(params.organizationName, params.view),
+  }];
 
-  if (actions.length > 0) {
-    elements.push({ tag: "action", actions });
-  } else {
-    elements.push({
-      tag: "markdown",
-      content: "你当前没有可绑定项目，也没有新建项目权限。请联系组织管理员。",
-    });
+  if (params.view.mode === "browse") {
+    appendFolderNavigation(elements, params.organizationId, params.view.result);
   }
+  appendProjectResults(
+    elements,
+    params.organizationId,
+    params.view.mode === "search" ? params.view.result.items : params.view.result.projects,
+  );
+  appendPagination(elements, params.organizationId, params.view);
+  appendCreation(elements, params.organizationId, params.canCreateProject, params.view);
 
+  if (elements.length === 1) {
+    elements.push({ tag: "markdown", content: "当前目录没有可浏览内容。" });
+  }
   return {
     config: { wide_screen_mode: true },
-    header: {
-      title: { tag: "plain_text", content: "绑定项目" },
-      template: "blue",
-    },
+    header: { title: { tag: "plain_text", content: "绑定项目" }, template: "blue" },
     elements,
   };
 }
@@ -95,54 +67,461 @@ export function buildProjectOnboardingResolvedCard(params: {
 }): Record<string, unknown> {
   return {
     config: { wide_screen_mode: true },
-    header: {
-      title: { tag: "plain_text", content: params.title },
-      template: params.template,
-    },
+    header: { title: { tag: "plain_text", content: params.title }, template: params.template },
     elements: [{ tag: "markdown", content: params.body }],
   };
 }
 
+export function buildProjectManagementCard(params: {
+  readonly organizationId: string;
+  readonly projectId: string;
+  readonly projectName: string;
+  readonly title?: string | undefined;
+  readonly breadcrumb?: string | undefined;
+  readonly selectedRole?: { readonly id: string; readonly roleId: string; readonly label: string } | undefined;
+  readonly roles?: readonly { readonly id: string; readonly roleId: string; readonly label: string }[] | undefined;
+  readonly currentSession?: {
+    readonly id: string;
+    readonly title: string | null;
+    readonly updatedAt: Date;
+    readonly runCount: number;
+    readonly sdkSessionReady: boolean;
+  } | null | undefined;
+  readonly canManageProject?: boolean | undefined;
+}): Record<string, unknown> {
+  const elements: unknown[] = [{
+    tag: "markdown",
+    content: [
+      `当前项目: **${escapeMarkdown(params.projectName)}**`,
+      `所在目录: **${escapeMarkdown(params.breadcrumb ?? "根目录")}**`,
+      params.selectedRole === undefined
+        ? "当前角色: **未配置**"
+        : `当前角色: **${escapeMarkdown(params.selectedRole.label)}**`,
+      sessionSummary(params.currentSession),
+    ].join("\n"),
+  }];
+  const roles = params.roles ?? [];
+  if (roles.length > 0) {
+    elements.push({ tag: "markdown", content: "**切换角色**" });
+    for (let index = 0; index < roles.length; index += 5) {
+      elements.push({
+        tag: "action",
+        actions: roles.slice(index, index + 5).map((role) => actionButton(
+          role.id === params.selectedRole?.id ? `✓ ${role.label}` : role.label,
+          {
+            action: "select_agent_role",
+            organization_id: params.organizationId,
+            project_id: params.projectId,
+            agent_role_id: role.id,
+          },
+          role.id === params.selectedRole?.id ? "primary" : "default",
+        )),
+      });
+    }
+  }
+  const sessionActions = [
+    actionButton("新开会话", {
+      action: "new_agent_session", organization_id: params.organizationId, project_id: params.projectId,
+    }),
+    actionButton("历史会话", {
+      action: "show_session_history", organization_id: params.organizationId, project_id: params.projectId,
+    }),
+  ];
+  if (params.currentSession?.sdkSessionReady === true) {
+    sessionActions.push(actionButton("压缩上下文", {
+      action: "compact_agent_session", organization_id: params.organizationId, project_id: params.projectId,
+    }));
+  }
+  elements.push(
+    { tag: "markdown", content: "**当前角色会话**" },
+    { tag: "action", actions: sessionActions },
+  );
+  if (params.canManageProject === true) {
+    elements.push(
+      { tag: "markdown", content: "**项目管理**" },
+      { tag: "action", actions: [actionButton("移动项目", {
+        action: "browse_move_destination",
+        organization_id: params.organizationId,
+        project_id: params.projectId,
+        page: 1,
+      })] },
+      renameProjectForm(params),
+    );
+  }
+  return {
+    config: { wide_screen_mode: true },
+    header: {
+      title: { tag: "plain_text", content: params.title ?? "项目管理" },
+      template: "green",
+    },
+    elements,
+  };
+}
+
+export function buildSessionHistoryCard(params: {
+  readonly organizationId: string;
+  readonly projectId: string;
+  readonly roleLabel: string;
+  readonly sessions: readonly {
+    readonly id: string;
+    readonly title: string | null;
+    readonly updatedAt: Date;
+    readonly runCount: number;
+  }[];
+}): Record<string, unknown> {
+  const elements: unknown[] = [{ tag: "markdown", content: `角色: **${escapeMarkdown(params.roleLabel)}**` }];
+  if (params.sessions.length === 0) elements.push({ tag: "markdown", content: "没有可恢复的历史会话。" });
+  for (const session of params.sessions) {
+    elements.push(
+      {
+        tag: "markdown",
+        content: `**${escapeMarkdown(session.title ?? "未命名会话")}**\n${session.runCount} runs · ${formatDate(session.updatedAt)}`,
+      },
+      { tag: "action", actions: [actionButton("恢复此会话", {
+        action: "resume_agent_session",
+        organization_id: params.organizationId,
+        project_id: params.projectId,
+        session_id: session.id,
+      }, "primary")] },
+    );
+  }
+  return {
+    config: { wide_screen_mode: true },
+    header: { title: { tag: "plain_text", content: "历史会话" }, template: "blue" },
+    elements,
+  };
+}
+
+export function buildMoveProjectCard(params: {
+  readonly organizationId: string;
+  readonly projectId: string;
+  readonly projectName: string;
+  readonly folderId: string | null;
+  readonly parentFolderId: string | null;
+  readonly breadcrumb: string;
+  readonly childFolders: readonly { readonly id: string; readonly name: string }[];
+  readonly canCreateFolder: boolean;
+}): Record<string, unknown> {
+  const navigation: unknown[] = [];
+  if (params.folderId !== null) {
+    navigation.push(actionButton("⬆ 上一级", {
+      action: "browse_move_destination",
+      organization_id: params.organizationId,
+      project_id: params.projectId,
+      ...(params.parentFolderId !== null ? { folder_id: params.parentFolderId } : {}),
+    }));
+  }
+  for (const folder of params.childFolders) {
+    navigation.push(actionButton(`📁 ${buttonLabel(folder.name, 22)}`, {
+      action: "browse_move_destination",
+      organization_id: params.organizationId,
+      project_id: params.projectId,
+      folder_id: folder.id,
+    }));
+  }
+  const elements: unknown[] = [
+    { tag: "markdown", content: `移动 **${escapeMarkdown(params.projectName)}**\n当前位置: **${escapeMarkdown(params.breadcrumb)}**` },
+  ];
+  for (let index = 0; index < navigation.length; index += 5) {
+    elements.push({ tag: "action", actions: navigation.slice(index, index + 5) });
+  }
+  elements.push({ tag: "action", actions: [actionButton("移动到这里", {
+    action: "move_project",
+    organization_id: params.organizationId,
+    project_id: params.projectId,
+    ...(params.folderId !== null ? { folder_id: params.folderId } : {}),
+  }, "primary")] });
+  if (params.canCreateFolder) {
+    elements.push(createFolderAndMoveForm({
+      organizationId: params.organizationId,
+      projectId: params.projectId,
+      parentFolderId: params.folderId,
+    }));
+  }
+  return {
+    config: { wide_screen_mode: true },
+    header: { title: { tag: "plain_text", content: "移动项目" }, template: "blue" },
+    elements,
+  };
+}
+
 export function projectOnboardingActionFromValue(value: unknown): ProjectOnboardingActionValue | null {
   const raw = unwrapValue(value);
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
-  if (!("project_onboarding" in raw)) return null;
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw) || !("project_onboarding" in raw)) return null;
   const action = raw.project_onboarding;
   if (typeof action !== "object" || action === null || Array.isArray(action)) return null;
-  const rawAction = (action as { action?: unknown }).action;
-  const organizationId = (action as { organization_id?: unknown }).organization_id;
-  const projectId = (action as { project_id?: unknown }).project_id;
-  const folderId = (action as { folder_id?: unknown }).folder_id;
-  if ((rawAction !== "create_project_from_chat" && rawAction !== "bind_project") || typeof organizationId !== "string" || organizationId === "") {
-    return null;
-  }
-  if (rawAction === "bind_project" && (typeof projectId !== "string" || projectId === "")) {
-    return null;
-  }
-  if (folderId !== undefined && (typeof folderId !== "string" || folderId === "")) {
-    return null;
-  }
+  const fields = action as Record<string, unknown>;
+  const rawAction = fields.action;
+  const organizationId = fields.organization_id;
+  const projectId = fields.project_id;
+  const folderId = fields.folder_id;
+  const searchQuery = fields.search_query;
+  const page = fields.page;
+  const agentRoleId = fields.agent_role_id;
+  const sessionId = fields.session_id;
+  if (!isAction(rawAction) || typeof organizationId !== "string" || organizationId === "") return null;
+  if ((rawAction === "bind_project" || rawAction === "rename_project") && (typeof projectId !== "string" || projectId === "")) return null;
+  if (rawAction === "search_page" && (typeof searchQuery !== "string" || !validPage(page))) return null;
+  if (folderId !== undefined && (typeof folderId !== "string" || folderId === "")) return null;
+  if (page !== undefined && !validPage(page)) return null;
+  if (rawAction === "select_agent_role" && (typeof agentRoleId !== "string" || agentRoleId === "")) return null;
+  if (rawAction === "resume_agent_session" && (typeof sessionId !== "string" || sessionId === "")) return null;
   return {
     action: rawAction,
     organization_id: organizationId,
     ...(typeof projectId === "string" && projectId !== "" ? { project_id: projectId } : {}),
     ...(typeof folderId === "string" && folderId !== "" ? { folder_id: folderId } : {}),
+    ...(typeof searchQuery === "string" ? { search_query: searchQuery.slice(0, 100) } : {}),
+    ...(typeof page === "number" ? { page } : {}),
+    ...(typeof agentRoleId === "string" && agentRoleId !== "" ? { agent_role_id: agentRoleId } : {}),
+    ...(typeof sessionId === "string" && sessionId !== "" ? { session_id: sessionId } : {}),
   };
 }
 
+function onboardingSummary(organizationName: string, view: ProjectOnboardingView): string {
+  if (view.mode === "search") {
+    const result = view.result;
+    return [
+      "这个飞书群还没有绑定项目。",
+      "",
+      `组织: **${escapeMarkdown(organizationName)}**`,
+      `搜索: **${escapeMarkdown(result.query)}**`,
+      result.totalItems === 0
+        ? "没有匹配的可绑定项目，请换一个关键词。"
+        : `共 **${result.totalItems}** 个匹配结果 · 第 **${result.page}/${result.totalPages}** 页`,
+    ].join("\n");
+  }
+  const location = view.result.breadcrumb === "" ? "根目录" : view.result.breadcrumb;
+  return [
+    "这个飞书群还没有绑定项目。",
+    "",
+    `组织: **${escapeMarkdown(organizationName)}**`,
+    `当前位置: **${escapeMarkdown(location)}**`,
+    "可以进入 folder 浏览，或选择有管理权限的未绑定项目。",
+  ].join("\n");
+}
+
+function appendFolderNavigation(elements: unknown[], organizationId: string, result: ProjectFolderPage): void {
+  const navigation: unknown[] = [];
+  if (result.folderId !== null) {
+    navigation.push(actionButton("⬆ 上一级", {
+      action: "browse_folder",
+      organization_id: organizationId,
+      ...(result.parentFolderId !== null ? { folder_id: result.parentFolderId } : {}),
+      page: 1,
+    }));
+  }
+  for (const folder of result.childFolders) {
+    navigation.push(actionButton(`📁 ${buttonLabel(folder.name, 22)}`, {
+      action: "browse_folder",
+      organization_id: organizationId,
+      folder_id: folder.folderId,
+      page: 1,
+    }));
+  }
+  for (let index = 0; index < navigation.length; index += 5) {
+    elements.push({ tag: "action", actions: navigation.slice(index, index + 5) });
+  }
+}
+
+function appendProjectResults(
+  elements: unknown[],
+  organizationId: string,
+  projects: readonly ProjectDiscoveryPage["items"][number][],
+): void {
+  for (const project of projects) {
+    const path = project.breadcrumb === "" ? "根目录" : project.breadcrumb;
+    elements.push({
+      tag: "markdown",
+      content: `**${escapeMarkdown(project.name)}**\n${escapeMarkdown(path)}`,
+    });
+    elements.push({
+      tag: "action",
+      actions: [actionButton("绑定这个项目", {
+        action: "bind_project",
+        organization_id: organizationId,
+        project_id: project.projectId,
+      })],
+    });
+  }
+}
+
+function appendPagination(elements: unknown[], organizationId: string, view: ProjectOnboardingView): void {
+  const result = projectPage(view);
+  if (result.totalPages <= 1) return;
+  const actions: unknown[] = [];
+  if (result.page > 1) actions.push(pageButton("上一页", organizationId, view, result.page - 1));
+  if (result.page < result.totalPages) actions.push(pageButton("下一页", organizationId, view, result.page + 1));
+  elements.push({ tag: "action", actions });
+}
+
+function appendCreation(
+  elements: unknown[],
+  organizationId: string,
+  canCreateProject: boolean,
+  view: ProjectOnboardingView,
+): void {
+  if (!canCreateProject || view.mode !== "browse") return;
+  elements.push({
+    tag: "action",
+    actions: [actionButton(view.result.folderId === null ? "新建项目" : "在此 folder 新建项目", {
+      action: "create_project_from_chat",
+      organization_id: organizationId,
+      ...(view.result.folderId !== null ? { folder_id: view.result.folderId } : {}),
+    }, "primary")],
+  });
+}
+
+function pageButton(label: string, organizationId: string, view: ProjectOnboardingView, page: number): unknown {
+  if (view.mode === "search") {
+    return actionButton(label, {
+      action: "search_page",
+      organization_id: organizationId,
+      search_query: view.result.query,
+      page,
+    });
+  }
+  return actionButton(label, {
+    action: "browse_folder",
+    organization_id: organizationId,
+    ...(view.result.folderId !== null ? { folder_id: view.result.folderId } : {}),
+    page,
+  });
+}
+
+function projectPage(view: ProjectOnboardingView): ProjectDiscoveryPage {
+  if (view.mode === "search") return view.result;
+  return {
+    query: "",
+    page: view.result.page,
+    pageSize: view.result.pageSize,
+    totalItems: view.result.totalFolders + view.result.totalProjects,
+    totalPages: view.result.totalPages,
+    items: view.result.projects,
+  };
+}
+
+function renameProjectForm(params: {
+  readonly organizationId: string;
+  readonly projectId: string;
+  readonly projectName: string;
+}): unknown {
+  return {
+    tag: "form",
+    name: "project_rename_form",
+    fallback: {
+      tag: "fallback_text",
+      text: { tag: "plain_text", content: "请升级飞书客户端后修改项目名称。" },
+    },
+    elements: [
+      {
+        tag: "input",
+        name: "project_name",
+        required: true,
+        max_length: 100,
+        default_value: params.projectName,
+        placeholder: { tag: "plain_text", content: "请输入项目名称" },
+      },
+      {
+        tag: "button",
+        name: "project_rename_submit",
+        text: { tag: "plain_text", content: "保存项目名称" },
+        type: "primary",
+        complex_interaction: true,
+        action_type: "form_submit",
+        value: { project_onboarding: {
+          action: "rename_project",
+          organization_id: params.organizationId,
+          project_id: params.projectId,
+        } },
+      },
+    ],
+  };
+}
+
+function createFolderAndMoveForm(params: {
+  readonly organizationId: string;
+  readonly projectId: string;
+  readonly parentFolderId: string | null;
+}): unknown {
+  return {
+    tag: "form",
+    name: "folder_create_form",
+    elements: [
+      {
+        tag: "input",
+        name: "folder_name",
+        required: true,
+        max_length: 100,
+        placeholder: { tag: "plain_text", content: "在当前目标目录下新建 Folder" },
+      },
+      {
+        tag: "button",
+        name: "folder_create_submit",
+        text: { tag: "plain_text", content: "新建并移动" },
+        type: "default",
+        complex_interaction: true,
+        action_type: "form_submit",
+        value: { project_onboarding: {
+          action: "create_folder",
+          organization_id: params.organizationId,
+          project_id: params.projectId,
+          ...(params.parentFolderId !== null ? { folder_id: params.parentFolderId } : {}),
+        } },
+      },
+    ],
+  };
+}
+
+function sessionSummary(session: {
+  readonly title: string | null;
+  readonly updatedAt: Date;
+  readonly runCount: number;
+} | null | undefined): string {
+  if (session === null || session === undefined) return "当前会话: **尚未开始**";
+  return `当前会话: **${escapeMarkdown(session.title ?? "未命名会话")}** · ${session.runCount} runs · ${formatDate(session.updatedAt)}`;
+}
+
+function formatDate(value: Date): string {
+  return new Intl.DateTimeFormat("zh-CN", {
+    timeZone: "Asia/Shanghai",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  }).format(value);
+}
+
+function actionButton(
+  label: string,
+  value: ProjectOnboardingActionValue,
+  type: "default" | "primary" = "default",
+): unknown {
+  return {
+    tag: "button",
+    text: { tag: "plain_text", content: label },
+    type,
+    value: { project_onboarding: value },
+  };
+}
+
+function isAction(value: unknown): value is ProjectOnboardingActionValue["action"] {
+  return value === "create_project_from_chat" || value === "bind_project"
+    || value === "browse_folder" || value === "search_page" || value === "rename_project"
+    || value === "select_agent_role" || value === "new_agent_session"
+    || value === "show_session_history" || value === "resume_agent_session"
+    || value === "compact_agent_session" || value === "browse_move_destination"
+    || value === "move_project" || value === "create_folder";
+}
+
+function validPage(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1 && value <= 10_000;
+}
+
 function unwrapValue(value: unknown): unknown {
   if (typeof value !== "string") return value;
-  try {
-    return JSON.parse(value);
-  } catch {
-    return value;
-  }
-}
-
-function buttonProjectLabel(project: OnboardingProjectOption): string {
-  const folderPrefix = project.folderName === undefined ? "" : `${project.folderName} / `;
-  const label = `${folderPrefix}${project.name}`;
-  return buttonLabel(label, 24);
+  try { return JSON.parse(value); } catch { return value; }
 }
 
 function buttonLabel(label: string, maxLength: number): string {

hub/src/feishu/slashCommands.ts

@@ -1,11 +1,6 @@
 import type { PrismaClient } from "@prisma/client";
-import type { FastifyBaseLogger } from "fastify";
 import { decimalToNumberOrNull, formatInteger, formatUsd } from "../agent/cost.js";
-import type { ModelRegistry, RoleEntry } from "../agent/models.js";
-import type { RuntimeSettings } from "../settings/runtime.js";
-import { lockActiveProjectOrganization } from "../org/status.js";
 import { sendText, type FeishuRuntime, type SendMessageOptions } from "./client.js";
-import type { TriggerQueue } from "./triggerQueue.js";
 
 export interface SlashInvocation {
   readonly name: string;
@@ -21,20 +16,13 @@ export interface SlashCommandRunContext {
 }
 
 export interface SlashCommandDefinition {
-  readonly name: string;
+  readonly name: "help" | "project" | "usage";
   readonly usage: string;
   readonly summary: string;
   readonly details: readonly string[];
   run(context: SlashCommandRunContext): Promise<void>;
 }
 
-export interface SlashCommandRegistryDeps {
-  readonly prisma: PrismaClient;
-  readonly settings: RuntimeSettings;
-  readonly logger: FastifyBaseLogger;
-  readonly triggerQueue: TriggerQueue;
-}
-
 const TERMINAL_RUN_STATUSES = ["COMPLETED", "FAILED", "TIMED_OUT", "CANCELED"] as const;
 
 export function parseSlashInvocation(prompt: string): SlashInvocation | null {
@@ -43,166 +31,94 @@ export function parseSlashInvocation(prompt: string): SlashInvocation | null {
   const tokens = trimmed.split(/\s+/);
   const rawCommand = tokens[0];
   if (rawCommand === undefined || rawCommand.length <= 1) return null;
-  return {
-    name: rawCommand.slice(1),
-    args: tokens.slice(1),
-  };
+  return { name: rawCommand.slice(1), args: tokens.slice(1) };
 }
 
-export function parseSlashHelpSubcommand(invocation: SlashInvocation): string | null {
-  if (invocation.name === "help") return null;
-  return invocation.args.length === 1 && invocation.args[0] === "help"
-    ? invocation.name
-    : null;
-}
-
-export function createSlashCommandRegistry(deps: SlashCommandRegistryDeps): ReadonlyMap<string, SlashCommandDefinition> {
+export function createSlashCommandRegistry(
+  deps: { readonly prisma: PrismaClient },
+): ReadonlyMap<string, SlashCommandDefinition> {
   const commands = new Map<string, SlashCommandDefinition>();
   const add = (command: SlashCommandDefinition): void => {
-    if (commands.has(command.name)) {
-      throw new Error(`duplicate slash command definition: /${command.name}`);
-    }
+    if (commands.has(command.name)) throw new Error(`duplicate slash command definition: /${command.name}`);
     commands.set(command.name, command);
   };
 
   add({
     name: "help",
-    usage: "/help [command]",
-    summary: "查看可用 slash 命令或单个命令说明。",
-    details: [
-      "不创建 agent run,也不改变当前会话。",
-      "支持 /help new 和 /new help 两种写法。",
-    ],
+    usage: "/help [project|usage]",
+    summary: "查看 Hub 命令。",
+    details: ["未知 slash 命令会明确报错，不会发送给 Agent。"],
+    run: async ({ invocation, chatId, rt, sendOptions }) => {
+      if (invocation.args.length > 1) {
+        await sendText(rt, chatId, "用法: /help [project|usage]", sendOptions);
+        return;
+      }
+      const target = invocation.args[0];
+      await sendText(rt, chatId, target === undefined
+        ? formatSlashOverview(commands)
+        : formatSlashHelpTarget(target, commands), sendOptions);
+    },
+  });
+
+  add({
+    name: "project",
+    usage: "/project",
+    summary: "打开当前项目控制台，切换角色、管理会话和项目。",
+    details: ["不同区域按当前操作者的项目与组织权限显示。"],
+    run: async ({ chatId, rt, sendOptions }) => {
+      await sendText(rt, chatId, "请在绑定的项目群中使用 /project。", sendOptions);
+    },
+  });
+
+  add({
+    name: "usage",
+    usage: "/usage [current|project]",
+    summary: "查看 Hub 记录的真实 Agent 用量与成本。",
+    details: ["current 只统计当前角色的活跃会话；project 统计整个项目。"],
     run: async ({ invocation, projectId, chatId, rt, sendOptions }) => {
-      const registry = await deps.settings.modelRegistry({ projectId });
-      await sendText(rt, chatId, formatHelpCommandInvocation(invocation, registry, commands), sendOptions);
-    },
-  });
-
-  add({
-    name: "new",
-    usage: "/new",
-    summary: "开新会话,下次 @bot 将从头开始。",
-    details: [
-      "归档当前未归档的 agent session。",
-      "不会清空当前项目的等待队列。",
-    ],
-    run: async ({ projectId, chatId, rt, sendOptions }) => {
-      await deps.prisma.$transaction(async (tx) => {
-        await lockActiveProjectOrganization(tx, projectId);
-        await tx.agentSession.updateMany({
-          where: { projectId, archivedAt: null },
-          data: { archivedAt: new Date() },
-        });
-      });
-      await sendText(rt, chatId, "已开新会话,下次 @bot 将从头开始。", sendOptions);
-    },
-  });
-
-  add({
-    name: "resume",
-    usage: "/resume",
-    summary: "恢复最近一次已归档的会话。",
-    details: [
-      "只恢复当前项目最近归档的 agent session。",
-      "没有可恢复会话时只回复提示,不会创建 agent run。",
-    ],
-    run: async ({ projectId, chatId, rt, sendOptions }) => {
-      const resumed = await deps.prisma.$transaction(async (tx) => {
-        await lockActiveProjectOrganization(tx, projectId);
-        const latest = await tx.agentSession.findFirst({
-          where: { projectId, archivedAt: { not: null } },
-          orderBy: { archivedAt: "desc" },
-          select: { id: true },
-        });
-        if (latest === null) return false;
-        await tx.agentSession.update({
-          where: { id: latest.id },
-          data: { archivedAt: null },
-        });
-        return true;
-      });
-      if (!resumed) {
-        await sendText(rt, chatId, "没有可恢复的会话。", sendOptions);
+      const scope = invocation.args[0] ?? "current";
+      if (invocation.args.length > 1 || (scope !== "current" && scope !== "project")) {
+        await sendText(rt, chatId, "用法: /usage [current|project]", sendOptions);
         return;
       }
-      await sendText(rt, chatId, "已恢复上一个会话。", sendOptions);
-    },
-  });
-
-  add({
-    name: "cost",
-    usage: "/cost",
-    summary: "查看当前会话已记录的 agent 成本。",
-    details: [
-      "只读取当前项目未归档 agent session 下已经结束的 run,不创建 agent run。",
-      "只统计运行时真实记录到 AgentRun.costUsd 的成本;未记录成本的 run 会单独列出。",
-    ],
-    run: async ({ invocation, projectId, chatId, rt, sendOptions }) => {
-      if (invocation.args.length > 0) {
-        await sendText(rt, chatId, ["用法错误: /cost 暂不接受参数。", "", formatBuiltinSlashCommandHelp(commands.get("cost")!)].join("\n"), sendOptions);
-        return;
-      }
-
-      const sessions = await deps.prisma.agentSession.findMany({
-        where: { projectId, archivedAt: null },
-        orderBy: { updatedAt: "asc" },
-        select: { id: true },
-      });
-      if (sessions.length === 0) {
-        await sendText(rt, chatId, "当前会话还没有 agent session。", sendOptions);
-        return;
-      }
-
+      const sessionIds = scope === "project"
+        ? undefined
+        : await currentRoleSessionIds(deps.prisma, projectId, chatId);
       const runs = await deps.prisma.agentRun.findMany({
         where: {
           projectId,
-          sessionId: { in: sessions.map((session) => session.id) },
+          ...(sessionIds === undefined ? {} : { sessionId: { in: sessionIds } }),
           status: { in: [...TERMINAL_RUN_STATUSES] },
           finishedAt: { not: null },
         },
         orderBy: { finishedAt: "asc" },
-        select: {
-          model: true,
-          provider: true,
-          inputTokens: true,
-          outputTokens: true,
-          costUsd: true,
-        },
+        select: { model: true, provider: true, inputTokens: true, outputTokens: true, costUsd: true },
       });
-
-      await sendText(rt, chatId, formatCostReport(runs), sendOptions);
-    },
-  });
-
-  add({
-    name: "reset",
-    usage: "/reset",
-    summary: "重置当前会话并清空等待队列。",
-    details: [
-      "归档当前未归档的 agent session。",
-      "清空当前项目已经排队、尚未开始的触发请求。",
-    ],
-    run: async ({ projectId, chatId, rt, sendOptions }) => {
-      await deps.prisma.$transaction(async (tx) => {
-        await lockActiveProjectOrganization(tx, projectId);
-        await tx.agentSession.updateMany({
-          where: { projectId, archivedAt: null },
-          data: { archivedAt: new Date() },
-        });
-      });
-      const cleared = deps.triggerQueue.clear(projectId);
-      if (cleared > 0) {
-        deps.logger.info({ projectId, cleared }, "feishu trigger: cleared queued triggers on reset");
-      }
-      await sendText(rt, chatId, "已重置,下次 @bot 将从头开始。", sendOptions);
+      await sendText(rt, chatId, formatUsageReport(runs, scope), sendOptions);
     },
   });
 
   return commands;
 }
 
-interface CostReportRun {
+async function currentRoleSessionIds(
+  prisma: PrismaClient,
+  projectId: string,
+  chatId: string,
+): Promise<string[]> {
+  const binding = await prisma.projectGroupBinding.findFirst({
+    where: { projectId, chatId, archivedAt: null },
+    select: { selectedRole: { select: { roleId: true } } },
+  });
+  if (binding === null) throw new Error("active project-group binding not found");
+  const sessions = await prisma.agentSession.findMany({
+    where: { projectId, roleId: binding.selectedRole.roleId, archivedAt: null },
+    select: { id: true },
+  });
+  return sessions.map((session) => session.id);
+}
+
+interface UsageRun {
   readonly model: string;
   readonly provider: string;
   readonly inputTokens: number | null;
@@ -210,215 +126,66 @@ interface CostReportRun {
   readonly costUsd: unknown;
 }
 
-interface CostReportBucket {
-  readonly provider: string;
-  readonly model: string;
-  runs: number;
-  inputTokens: number;
-  outputTokens: number;
-  costUsd: number;
-}
-
-function formatCostReport(runs: readonly CostReportRun[]): string {
-  if (runs.length === 0) {
-    return "当前会话还没有已结束的 agent run。";
-  }
-
-  const buckets = new Map<string, CostReportBucket>();
+function formatUsageReport(runs: readonly UsageRun[], scope: "current" | "project"): string {
+  if (runs.length === 0) return `${scope === "current" ? "当前角色会话" : "当前项目"}还没有已结束的 Agent run。`;
+  const buckets = new Map<string, {
+    provider: string; model: string; runs: number; inputTokens: number; outputTokens: number; costUsd: number;
+  }>();
   let recordedRuns = 0;
   let unrecordedRuns = 0;
   let totalInputTokens = 0;
   let totalOutputTokens = 0;
   let totalCostUsd = 0;
-
   for (const run of runs) {
     const costUsd = decimalToNumberOrNull(run.costUsd);
-    if (costUsd === null) {
-      unrecordedRuns++;
-      continue;
-    }
-
+    if (costUsd === null) { unrecordedRuns++; continue; }
     recordedRuns++;
-    const inputTokens = run.inputTokens ?? 0;
-    const outputTokens = run.outputTokens ?? 0;
-    totalInputTokens += inputTokens;
-    totalOutputTokens += outputTokens;
-    totalCostUsd += costUsd;
-
     const key = `${run.provider}\u0000${run.model}`;
-    let bucket = buckets.get(key);
-    if (bucket === undefined) {
-      bucket = {
-        provider: run.provider,
-        model: run.model,
-        runs: 0,
-        inputTokens: 0,
-        outputTokens: 0,
-        costUsd: 0,
+    const bucket = buckets.get(key) ?? {
+      provider: run.provider, model: run.model, runs: 0, inputTokens: 0, outputTokens: 0, costUsd: 0,
     };
-      buckets.set(key, bucket);
-    }
     bucket.runs++;
-    bucket.inputTokens += inputTokens;
-    bucket.outputTokens += outputTokens;
+    bucket.inputTokens += run.inputTokens ?? 0;
+    bucket.outputTokens += run.outputTokens ?? 0;
     bucket.costUsd += costUsd;
+    buckets.set(key, bucket);
+    totalInputTokens += run.inputTokens ?? 0;
+    totalOutputTokens += run.outputTokens ?? 0;
+    totalCostUsd += costUsd;
   }
-
-  if (recordedRuns === 0) {
-    return [
-      "当前会话已有已结束 agent run,但还没有任何 run 记录到真实成本。",
-      `未记录成本: ${formatInteger(unrecordedRuns)} runs。`,
-      "后续 run 需要 SDK 返回 total_cost_usd 才会进入 /cost 合计。",
-    ].join("\n");
-  }
-
   const lines = [
-    "当前会话已记录 agent 成本:",
-    `总计: ${formatUsd(totalCostUsd)}`,
-    `Runs: ${formatInteger(recordedRuns)} 已记录${unrecordedRuns > 0 ? ` / ${formatInteger(unrecordedRuns)} 未记录` : ""}`,
+    `${scope === "current" ? "当前角色会话" : "当前项目"}用量`,
+    `已记录成本: ${formatInteger(recordedRuns)} runs · ${formatUsd(totalCostUsd)}`,
     `Tokens: input ${formatInteger(totalInputTokens)} / output ${formatInteger(totalOutputTokens)}`,
-    "",
-    "按模型:",
   ];
-
-  const sortedBuckets = [...buckets.values()].sort((a, b) => b.costUsd - a.costUsd);
-  for (const bucket of sortedBuckets) {
-    lines.push(
-      `- ${bucket.provider} / ${bucket.model}: ${formatInteger(bucket.runs)} runs, ${formatUsd(bucket.costUsd)}, input ${formatInteger(bucket.inputTokens)} / output ${formatInteger(bucket.outputTokens)}`,
-    );
+  if (unrecordedRuns > 0) lines.push(`另有 ${formatInteger(unrecordedRuns)} 个 run 未记录成本。`);
+  for (const bucket of buckets.values()) {
+    lines.push(`- ${bucket.provider} / ${bucket.model}: ${formatInteger(bucket.runs)} runs, ${formatUsd(bucket.costUsd)}`);
   }
-
   return lines.join("\n");
 }
 
-function formatHelpCommandInvocation(
-  invocation: SlashInvocation,
-  registry: ModelRegistry,
-  slashCommands: ReadonlyMap<string, SlashCommandDefinition>,
-): string {
-  if (invocation.args.length > 1) {
-    const helpCommand = slashCommands.get("help");
-    if (helpCommand === undefined) {
-      throw new Error("slash command registry is missing /help");
-    }
-    return [
-      "用法错误: /help 只接受一个命令名。",
-      "",
-      formatBuiltinSlashCommandHelp(helpCommand),
-    ].join("\n");
-  }
-
-  const target = invocation.args[0];
-  if (target === undefined) return formatSlashOverview(registry, slashCommands);
-  const normalizedTarget = normalizeHelpTarget(target);
-  if (normalizedTarget === "") return formatSlashOverview(registry, slashCommands);
-  return formatSlashHelpTarget(normalizedTarget, registry, slashCommands);
-}
-
 export function formatSlashHelpTarget(
   target: string,
-  registry: ModelRegistry,
-  slashCommands: ReadonlyMap<string, SlashCommandDefinition>,
+  commands: ReadonlyMap<string, SlashCommandDefinition>,
 ): string {
-  const normalizedTarget = normalizeHelpTarget(target);
-  if (normalizedTarget === "") return formatSlashOverview(registry, slashCommands);
-  return formatSlashCommandHelp(normalizedTarget, registry, slashCommands) ?? formatUnknownSlashHelp(normalizedTarget, registry, slashCommands);
-}
-
-function normalizeHelpTarget(target: string): string {
-  return target.trim().replace(/^\/+/, "");
-}
-
-function formatSlashOverview(
-  registry: ModelRegistry,
-  slashCommands: ReadonlyMap<string, SlashCommandDefinition>,
-): string {
-  const lines = [
-    "可用 slash 命令:",
-    ...[...slashCommands.values()].map((command) => `/${command.name} - ${command.summary}`),
-  ];
-  const roles = visibleRoleCommands(registry, slashCommands);
-  if (roles.length > 0) {
-    lines.push("", "角色命令:");
-    for (const role of roles) {
-      lines.push(`/${role.id} <需求> - 使用“${role.label}”角色发起请求。`);
-    }
-  } else {
-    lines.push("", "当前没有配置角色命令。");
-  }
-  lines.push("", "查看单个命令: /help new 或 /new help。");
-  return lines.join("\n");
-}
-
-function formatSlashCommandHelp(
-  commandName: string,
-  registry: ModelRegistry,
-  slashCommands: ReadonlyMap<string, SlashCommandDefinition>,
-): string | null {
-  const normalizedName = normalizeHelpTarget(commandName);
-  const slashCommand = slashCommands.get(normalizedName);
-  if (slashCommand !== undefined) return formatBuiltinSlashCommandHelp(slashCommand);
-
-  const role = registry.role(normalizedName);
-  if (role === undefined) return null;
-  if (slashCommands.has(role.id)) return null;
-  return formatRoleSlashCommandHelp(role);
-}
-
-function formatBuiltinSlashCommandHelp(command: SlashCommandDefinition): string {
-  const helpUsage = command.name === "help"
-    ? "帮助: /help help"
-    : `帮助: /help ${command.name} 或 /${command.name} help`;
+  const normalized = target.trim().replace(/^\/+/, "");
+  const command = commands.get(normalized);
+  if (command === undefined) return [`未知 slash 命令 /${normalized}。`, "", formatSlashOverview(commands)].join("\n");
   return [
     `/${command.name}`,
     command.summary,
     "",
     `用法: ${command.usage}`,
     ...command.details.map((detail) => `- ${detail}`),
-    "",
-    helpUsage,
   ].join("\n");
 }
 
-function formatRoleSlashCommandHelp(role: RoleEntry): string {
-  const lines = [
-    `/${role.id}`,
-    `使用“${role.label}”角色发起一次 agent run。`,
-    "",
-    `用法: /${role.id} <需求>`,
-    "- 真正运行时仍会按当前项目的 role.trigger 授权检查。",
-  ];
-  if (role.defaultModel !== undefined) {
-    lines.push(`- 默认模型: ${role.defaultModel}`);
-  }
-  lines.push(`- 工具范围: ${roleToolsDescription(role)}`, "", `帮助: /help ${role.id} 或 /${role.id} help`);
-  return lines.join("\n");
-}
-
-function roleToolsDescription(role: RoleEntry): string {
-  if (role.tools === undefined) return "全部已注册工具";
-  if (role.tools.length === 0) return "无";
-  return role.tools.join(", ");
-}
-
-function formatUnknownSlashHelp(
-  commandName: string,
-  registry: ModelRegistry,
-  slashCommands: ReadonlyMap<string, SlashCommandDefinition>,
-): string {
-  const normalizedName = normalizeHelpTarget(commandName);
+function formatSlashOverview(commands: ReadonlyMap<string, SlashCommandDefinition>): string {
   return [
-    `未知 slash 命令 /${normalizedName}。`,
+    "可用 slash 命令:",
+    ...[...commands.values()].map((command) => `/${command.name} - ${command.summary}`),
     "",
-    formatSlashOverview(registry, slashCommands),
+    "普通消息会使用 /project 中选定的当前角色。",
   ].join("\n");
 }
-
-function visibleRoleCommands(
-  registry: ModelRegistry,
-  slashCommands: ReadonlyMap<string, SlashCommandDefinition>,
-): readonly RoleEntry[] {
-  return registry
-    .listRoles()
-    .filter((role) => !slashCommands.has(role.id));
-}

hub/src/feishu/trigger.ts

@@ -35,7 +35,6 @@ import type { RuntimeSettings } from "../settings/runtime.js";
 import { currentLockRunId, releaseLock } from "../lock.js";
 import { createPermissionAuthorizer, type AuthorizationDecision, type PermissionAuthorizer } from "../permission.js";
 import { writeAudit } from "../audit.js";
-import { formatRunCostLine } from "../agent/cost.js";
 import { createAgentSdkStderrSink } from "../agent/diagnostics.js";
 import { InactiveOrganizationError, lockActiveOrganization } from "../org/status.js";
 import { StreamingAgentCard } from "./card/streaming-card.js";
@@ -53,22 +52,36 @@ import {
   type StagedMessageResourceBatch,
 } from "./resourceStaging.js";
 import { TriggerQueue, triggerQueue as defaultTriggerQueue, type QueuedTrigger } from "./triggerQueue.js";
-import { createSlashCommandRegistry, formatSlashHelpTarget, parseSlashHelpSubcommand, parseSlashInvocation } from "./slashCommands.js";
+import { createSlashCommandRegistry, parseSlashInvocation } from "./slashCommands.js";
 import { cphHubMcpToolsForRole, roleToolsAllow } from "../agent/roleTools.js";
 import {
   bindFeishuChatToProject,
   createProjectFromFeishuChat,
   ensureOrganizationProjectSettings,
+  moveProjectToFolder,
+  renameProjectForActor,
 } from "../projectOnboarding.js";
 import {
+  buildProjectManagementCard,
+  buildMoveProjectCard,
+  buildSessionHistoryCard,
   buildProjectOnboardingResolvedCard,
   buildUnboundChatOnboardingCard,
   projectOnboardingActionFromValue,
-  type OnboardingFolderOption,
-  type OnboardingProjectOption,
   type ProjectOnboardingActionValue,
+  type ProjectOnboardingView,
 } from "./projectOnboardingCard.js";
+import {
+  archiveCurrentRoleSession,
+  browseFolderDestinations,
+  createFolderAndMoveProject,
+  listRoleSessionHistory,
+  loadProjectConsole,
+  resumeRoleSession,
+  selectProjectGroupRole,
+} from "./projectConsole.js";
 import { SiloFixedWindowRateLimiter } from "../deployment/siloRateLimit.js";
+import { browseBindableFolder, discoverBindableProjects } from "../projectDiscovery.js";
 
 export { ApprovalManager } from "./approval.js";
 export type { ApprovalResult, PendingApproval } from "./approval.js";
@@ -85,6 +98,10 @@ interface TriggerDeps {
   readonly messageBatcherOptions?: MessageBatcherOptions | undefined;
   readonly triggerQueue?: TriggerQueue | undefined;
   readonly projectWorkspaceRoot: string;
+  /** Public origin used to build the Silo Organization's Feishu OAuth entrypoint. */
+  readonly publicBaseUrl: string;
+  /** The single Organization this Alpha Silo is fail-closed to serve. */
+  readonly siloOrganizationId: string;
   /** Alpha Silo policy: never acknowledge work into the process-local queue. */
   readonly rejectWhenBusy?: boolean | undefined;
   readonly resourceLimits?: {
@@ -108,6 +125,7 @@ interface TriggerRunContext {
   readonly projectId: string;
   readonly senderOpenId: string;
   readonly actor: TriggerActor;
+  readonly roleId: string;
 }
 
 type StartAgentRunOutcome = "started" | "queued" | "rejected" | "locked" | "skipped";
@@ -133,6 +151,9 @@ export interface TriggerHandler {
 export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
   const projectWorkspaceRoot = deps.projectWorkspaceRoot.trim();
   if (projectWorkspaceRoot === "") throw new Error("projectWorkspaceRoot is required");
+  const publicBaseUrl = parsePublicBaseUrl(deps.publicBaseUrl);
+  const siloOrganizationId = deps.siloOrganizationId.trim();
+  if (siloOrganizationId === "") throw new Error("siloOrganizationId is required");
   const authorizer = deps.authorizer ?? createPermissionAuthorizer(deps.prisma);
   const runAgent = deps.runAgent ?? defaultRunAgent;
   const approvalManager = new ApprovalManager();
@@ -142,9 +163,6 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
     : new SiloFixedWindowRateLimiter(deps.maxFeishuEventsPerMinute, 60_000);
   const slashCommands = createSlashCommandRegistry({
     prisma: deps.prisma,
-    settings: deps.settings,
-    logger: deps.logger,
-    triggerQueue,
   });
   const batchContexts = new Map<string, TriggerRunContext>();
   // runId → AbortController for live runs. Registered when a run starts,
@@ -170,10 +188,47 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
     }
   }, deps.messageBatcherOptions);
 
+  async function projectConsoleCard(
+    projectId: string,
+    chatId: string,
+    actorOpenId: string,
+    title?: string,
+  ): Promise<Record<string, unknown>> {
+    const state = await loadProjectConsole(deps.prisma, { projectId, chatId });
+    const actor = { feishuOpenId: actorOpenId, chatId };
+    const [manageDecision, organization, roleDecisions] = await Promise.all([
+      authorizer.can({ actor, action: "collaborator.manage", resource: { type: "PROJECT", id: projectId } }),
+      resolveSingleActiveOrganizationForFeishuUser(actorOpenId),
+      Promise.all(state.roles.map(async (role) => ({
+        role,
+        decision: await authorizer.can({
+          actor,
+          action: "role.trigger",
+          resource: { type: "PROJECT", id: projectId },
+          roleId: role.roleId,
+        }),
+      }))),
+    ]);
+    const visibleRoles = roleDecisions.filter(({ decision }) => decision.allowed).map(({ role }) => role);
+    const isOrgAdmin = organization.status === "ok" &&
+      organization.organizationId === state.organizationId && isOrgAdminRole(organization.role);
+    return buildProjectManagementCard({
+      organizationId: state.organizationId,
+      projectId: state.projectId,
+      projectName: state.projectName,
+      breadcrumb: state.breadcrumb,
+      selectedRole: state.selectedRole,
+      roles: visibleRoles,
+      currentSession: state.currentSession,
+      canManageProject: manageDecision.allowed || isOrgAdmin,
+      ...(title !== undefined ? { title } : {}),
+    });
+  }
+
   async function startAgentRun(
     context: TriggerRunContext,
     cleanPrompt: string,
-    options: { readonly queueIfLocked?: boolean } = {},
+    options: { readonly queueIfLocked?: boolean; readonly nativeSlash?: boolean } = {},
   ): Promise<StartAgentRunOutcome> {
     const { msg, rt, chatId, projectId, senderOpenId, actor } = context;
     const sendOptions = sendOptionsForTriggerMessage(msg);
@@ -187,7 +242,7 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
         return "rejected";
       }
       if (!queueIfLocked) return "locked";
-      return enqueueLockedTrigger(context, cleanPrompt);
+      return enqueueLockedTrigger(context, cleanPrompt, options.nativeSlash === true ? "native_compact" : "conversation");
     }
 
     const project = await deps.prisma.project.findUnique({
@@ -199,15 +254,11 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
       return "skipped";
     }
 
-    // ADR-0017: role-as-data. Parse a leading `/<role>` command; unknown
-    // slashes are left as literal text (extractRole returns null). Falls back
-    // to "draft" when no role is named — the registry degrades gracefully.
     const models = await deps.settings.modelRegistry({ projectId });
-    const { roleId: parsedRole, prompt: parsedAgentPrompt } = extractRole(cleanPrompt, models);
-    const roleId = parsedRole ?? "draft";
+    const roleId = context.roleId;
     // ADR-0019: role trigger is the second gate after project agent.trigger.
-    // Unconfigured roles remain open for back-compat; configured roles require
-    // a matching active RoleTriggerGrant for any resolved principal.
+    // Configured roles require a matching active RoleTriggerGrant for any
+    // resolved principal; otherwise the role remains open within the project.
     const roleDecision = await authorizer.can({
       actor,
       action: "role.trigger",
@@ -254,8 +305,10 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
       projectWorkspaceRoot,
       deps.resourceLimits,
     );
-    const agentPrompt = appendStagedResourcePaths(parsedAgentPrompt, stagedResources, project.workspaceDir);
-    const promptForAgent = withFeishuTriggerContext(agentPrompt, feishuTriggerContext);
+    const agentPrompt = appendStagedResourcePaths(cleanPrompt, stagedResources, project.workspaceDir);
+    const promptForAgent = options.nativeSlash === true
+      ? cleanPrompt
+      : withFeishuTriggerContext(agentPrompt, feishuTriggerContext);
 
     // Linearization point for org lifecycle + session/run/lock admission.
     // FOR SHARE on the Organization row conflicts with a concurrent status
@@ -405,6 +458,11 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
       metadata: {
         roleId,
         model,
+        requestedSkills: (role?.skills ?? []).map((skill) => ({
+          name: skill.name,
+          version: skill.version,
+          contentDigest: skill.contentDigest,
+        })),
         prompt: agentPrompt.slice(0, 200),
         sender: senderMetadata,
         feishuTriggerContext,
@@ -444,6 +502,7 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
       runId: run.id,
       workspaceRoot: projectWorkspaceRoot,
       workspaceDir: project.workspaceDir,
+      maxFileBytes: deps.resourceLimits?.maxBytesPerFile,
       sendOptions,
       approvalManager,
       tools: cphHubMcpToolsForRole(roleTools),
@@ -479,6 +538,7 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
           providerProxyEnv: { ...providerLease.sdkEnv },
           resumeSessionId: sessionMetadata.claudeSessionId,
           tools: roleTools,
+          skills: role?.skills,
           mcpServers: { cph_hub: fileDeliveryMcpServer },
           maxTurns: runPolicy.maxTurns,
           runId: run.id,
@@ -536,7 +596,7 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
             : result.status === "failed" && result.error !== undefined
               ? `\u5904\u7406\u5931\u8D25: ${result.error}`
               : result.text;
-        await card.finish(finalText, { interrupted, footerText: formatRunCostLine(result.costUsd) });
+        await card.finish(finalText, { interrupted });
         const metadataPatch = sessionMetadataPatch(result.sdkSessionId);
         if (metadataPatch !== null) {
           await deps.prisma.agentSession.update({
@@ -567,7 +627,11 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
           runId: run.id,
           projectId,
           action: "run.finished",
-          metadata: { status: result.status, deliveredFiles },
+          metadata: {
+            status: result.status,
+            deliveredFiles,
+            initializedSkills: [...(result.initializedSkillIds ?? [])],
+          },
         });
         await removeProcessingReaction();
       })
@@ -604,10 +668,16 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
     return "started";
   }
 
-  async function enqueueLockedTrigger(context: TriggerRunContext, cleanPrompt: string): Promise<StartAgentRunOutcome> {
+  async function enqueueLockedTrigger(
+    context: TriggerRunContext,
+    cleanPrompt: string,
+    executionKind: QueuedTrigger["executionKind"] = "conversation",
+  ): Promise<StartAgentRunOutcome> {
     const position = triggerQueue.enqueue(context.projectId, {
       chatId: context.chatId,
       prompt: cleanPrompt,
+      roleId: context.roleId,
+      executionKind,
       msg: context.msg,
       senderOpenId: context.senderOpenId,
       actor: context.actor,
@@ -645,7 +715,10 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
 
       const next = triggerQueue.dequeue(projectId);
       if (next === null) return;
-      const outcome = await startAgentRun(contextFromQueuedTrigger(next, rt), next.prompt, { queueIfLocked: false });
+      const outcome = await startAgentRun(contextFromQueuedTrigger(next, rt), next.prompt, {
+        queueIfLocked: false,
+        nativeSlash: next.executionKind === "native_compact",
+      });
       if (outcome === "started") return;
       if (outcome === "locked") {
         requeueTrigger(next);
@@ -662,6 +735,7 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
       projectId: trigger.projectId,
       senderOpenId: trigger.senderOpenId,
       actor: trigger.actor,
+      roleId: trigger.roleId,
     };
   }
 
@@ -669,6 +743,8 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
     const position = triggerQueue.enqueue(trigger.projectId, {
       chatId: trigger.chatId,
       prompt: trigger.prompt,
+      roleId: trigger.roleId,
+      executionKind: trigger.executionKind,
       msg: trigger.msg,
       senderOpenId: trigger.senderOpenId,
       actor: trigger.actor,
@@ -737,21 +813,257 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
     }
 
     try {
+      const organization = await resolveSingleActiveOrganizationForFeishuUser(operatorOpenId);
+      if (organization.status !== "ok") throw new Error(organization.message);
+      if (organization.organizationId !== action.organization_id) {
+        throw new Error("project onboarding organization mismatch");
+      }
+      if (
+        action.action === "select_agent_role" ||
+        action.action === "new_agent_session" ||
+        action.action === "show_session_history" ||
+        action.action === "resume_agent_session" ||
+        action.action === "compact_agent_session"
+      ) {
+        const projectId = action.project_id;
+        if (projectId === undefined) throw new Error(`${action.action} requires project_id`);
+        const binding = await deps.prisma.projectGroupBinding.findFirst({
+          where: { projectId, chatId, archivedAt: null },
+          select: { id: true },
+        });
+        if (binding === null) throw new Error("project console action requires the project to be bound to this chat");
+        const state = await loadProjectConsole(deps.prisma, { projectId, chatId });
+        const targetRole = action.action === "select_agent_role"
+          ? state.roles.find((role) => role.id === action.agent_role_id)
+          : state.selectedRole;
+        if (targetRole === undefined) throw new Error("selected Agent role is unavailable");
+        const actor = { feishuOpenId: operatorOpenId, chatId };
+        const [triggerDecision, roleDecision] = await Promise.all([
+          authorizer.can({ actor, action: "agent.trigger", resource: { type: "PROJECT", id: projectId } }),
+          authorizer.can({
+            actor,
+            action: "role.trigger",
+            resource: { type: "PROJECT", id: projectId },
+            roleId: targetRole.roleId,
+          }),
+        ]);
+        if (!triggerDecision.allowed || !roleDecision.allowed || roleDecision.actorUserId === undefined) {
+          throw new Error(`not authorized for Agent role ${targetRole.roleId}`);
+        }
+
+        if (action.action === "select_agent_role") {
+          await selectProjectGroupRole(deps.prisma, {
+            projectId,
+            chatId,
+            agentRoleId: targetRole.id,
+            actorUserId: roleDecision.actorUserId,
+          });
+          if (messageId === undefined) throw new Error("role selection requires message id");
+          await patchCard(rt, messageId, await projectConsoleCard(
+            projectId,
+            chatId,
+            operatorOpenId,
+            `已切换至 ${targetRole.label}`,
+          ));
+          return;
+        }
+        if (action.action === "new_agent_session") {
+          await archiveCurrentRoleSession(deps.prisma, {
+            projectId,
+            chatId,
+            actorUserId: roleDecision.actorUserId,
+          });
+          if (messageId === undefined) throw new Error("new session requires message id");
+          await patchCard(rt, messageId, await projectConsoleCard(projectId, chatId, operatorOpenId, "已新开会话"));
+          return;
+        }
+        if (action.action === "show_session_history") {
+          const sessions = await listRoleSessionHistory(deps.prisma, { projectId, chatId });
+          if (messageId === undefined) throw new Error("session history requires message id");
+          await patchCard(rt, messageId, buildSessionHistoryCard({
+            organizationId: state.organizationId,
+            projectId,
+            roleLabel: state.selectedRole.label,
+            sessions,
+          }));
+          return;
+        }
+        if (action.action === "resume_agent_session") {
+          if (action.session_id === undefined) throw new Error("resume_agent_session requires session_id");
+          await resumeRoleSession(deps.prisma, {
+            projectId,
+            chatId,
+            sessionId: action.session_id,
+            actorUserId: roleDecision.actorUserId,
+          });
+          if (messageId === undefined) throw new Error("session resume requires message id");
+          await patchCard(rt, messageId, await projectConsoleCard(projectId, chatId, operatorOpenId, "已恢复历史会话"));
+          return;
+        }
+        if (state.currentSession === null || !state.currentSession.sdkSessionReady) {
+          throw new Error("当前角色还没有可压缩的 Claude 会话");
+        }
+        const commandMessage: MessageReceiveEvent["message"] = {
+          message_id: messageId ?? randomUUID(),
+          chat_id: chatId,
+          chat_type: "group",
+          message_type: "text",
+          content: JSON.stringify({ text: "/compact" }),
+          mentions: [],
+        };
+        await startAgentRun({
+          msg: commandMessage,
+          rt,
+          chatId,
+          projectId,
+          senderOpenId: operatorOpenId,
+          actor,
+          roleId: state.selectedRole.roleId,
+        }, "/compact", { nativeSlash: true });
+        return;
+      }
+      if (
+        action.action === "browse_move_destination" ||
+        action.action === "move_project" ||
+        action.action === "create_folder"
+      ) {
+        const projectId = action.project_id;
+        if (projectId === undefined) throw new Error(`${action.action} requires project_id`);
+        const state = await loadProjectConsole(deps.prisma, { projectId, chatId });
+        const isOrgAdmin = isOrgAdminRole(organization.role);
+        const manageDecision = await authorizer.can({
+          actor: { feishuOpenId: operatorOpenId, chatId },
+          action: "collaborator.manage",
+          resource: { type: "PROJECT", id: projectId },
+        });
+        if (!isOrgAdmin && !manageDecision.allowed) throw new Error("project MANAGE permission is required");
+
+        if (action.action === "browse_move_destination") {
+          const page = await browseFolderDestinations(deps.prisma, {
+            organizationId: state.organizationId,
+            folderId: action.folder_id ?? null,
+          });
+          if (messageId === undefined) throw new Error("folder navigation requires message id");
+          await patchCard(rt, messageId, buildMoveProjectCard({
+            organizationId: state.organizationId,
+            projectId,
+            projectName: state.projectName,
+            canCreateFolder: isOrgAdmin,
+            ...page,
+          }));
+          return;
+        }
+        if (action.action === "move_project") {
+          await moveProjectToFolder(deps.prisma, { projectId, folderId: action.folder_id ?? null });
+          await writeAudit(deps.prisma, {
+            projectId,
+            ...(manageDecision.actorUserId !== undefined ? { actorUserId: manageDecision.actorUserId } : {}),
+            action: "project.moved_from_feishu",
+            metadata: { folderId: action.folder_id ?? null },
+          });
+          if (messageId === undefined) throw new Error("project move requires message id");
+          await patchCard(rt, messageId, await projectConsoleCard(projectId, chatId, operatorOpenId, "项目已移动"));
+          return;
+        }
+        if (!isOrgAdmin) throw new Error("creating an Organization folder requires OWNER or ADMIN");
+        const folderName = event.action.form_value?.["folder_name"];
+        if (typeof folderName !== "string") throw new Error("create folder form is missing folder_name");
+        const folder = await createFolderAndMoveProject(deps.prisma, {
+          organizationId: state.organizationId,
+          projectId,
+          parentFolderId: action.folder_id ?? null,
+          name: folderName.slice(0, 100),
+          ...(manageDecision.actorUserId !== undefined ? { actorUserId: manageDecision.actorUserId } : {}),
+        });
+        if (messageId === undefined) throw new Error("folder creation requires message id");
+        await patchCard(rt, messageId, await projectConsoleCard(
+          projectId,
+          chatId,
+          operatorOpenId,
+          `已新建目录“${folder.folderName}”并移动项目`,
+        ));
+        return;
+      }
+      if (action.action === "rename_project") {
+        const projectId = action.project_id;
+        if (projectId === undefined) throw new Error("rename_project action requires project_id");
+        const binding = await deps.prisma.projectGroupBinding.findFirst({
+          where: { chatId, projectId, archivedAt: null },
+          select: { id: true },
+        });
+        if (binding === null) throw new Error("project rename requires the project to be bound to this chat");
+        const submittedName = event.action.form_value?.["project_name"];
+        if (typeof submittedName !== "string") throw new Error("project rename form is missing project_name");
+        const renamed = await renameProjectForActor(deps.prisma, {
+          organizationId: organization.organizationId,
+          projectId,
+          actorFeishuOpenId: operatorOpenId,
+          name: submittedName.slice(0, 100),
+        });
+        if (messageId === undefined) throw new Error("project rename requires message id");
+        await patchCard(rt, messageId, await projectConsoleCard(
+          renamed.projectId,
+          chatId,
+          operatorOpenId,
+          "项目名称已更新",
+        ));
+        deps.logger.info({ chatId, projectId, operatorOpenId }, "project onboarding: project renamed");
+        return;
+      }
+      if (action.action === "browse_folder" || action.action === "search_page") {
+        const activeBinding = await deps.prisma.projectGroupBinding.findFirst({
+          where: { chatId, archivedAt: null },
+          select: { projectId: true },
+        });
+        if (activeBinding !== null) throw new Error(`chat is already bound to project ${activeBinding.projectId}`);
+        const settings = await ensureOrganizationProjectSettings(deps.prisma, organization.organizationId);
+        const view = action.action === "search_page"
+          ? await searchOnboardingView({
+              organizationId: organization.organizationId,
+              actorFeishuOpenId: operatorOpenId,
+              isOrgAdmin: isOrgAdminRole(organization.role),
+              query: action.search_query ?? "",
+              page: action.page ?? 1,
+            })
+          : await browseOnboardingView({
+              organizationId: organization.organizationId,
+              actorFeishuOpenId: operatorOpenId,
+              isOrgAdmin: isOrgAdminRole(organization.role),
+              folderId: action.folder_id ?? null,
+              page: action.page ?? 1,
+            });
+        if (messageId === undefined) throw new Error("project onboarding navigation requires message id");
+        await patchCard(rt, messageId, buildUnboundChatOnboardingCard({
+          organizationId: organization.organizationId,
+          organizationName: organization.organizationName,
+          canCreateProject: settings.membersCanCreateProjects || isOrgAdminRole(organization.role),
+          view,
+        }));
+        deps.logger.info(
+          { chatId, operatorOpenId, action: action.action, folderId: action.folder_id, page: action.page },
+          "project onboarding: navigated discovery card",
+        );
+        return;
+      }
+
       if (action.action === "create_project_from_chat") {
         const name = defaultProjectNameForChat(chatId);
         const project = await createProjectFromFeishuChat(deps.prisma, {
-          organizationId: action.organization_id,
+          organizationId: organization.organizationId,
           actorFeishuOpenId: operatorOpenId,
           chatId,
           name,
           workspaceRoot: projectWorkspaceRoot,
           folderId: action.folder_id,
         });
-        await resolveProjectOnboardingCard(rt, messageId, {
-          title: "已创建并绑定项目",
-          body: `项目 **${escapeCardMarkdown(name)}** 已绑定到本群。后续 @bot 会进入这个项目的 session。`,
-          template: "green",
-        });
+        if (messageId !== undefined) {
+          await patchCard(rt, messageId, await projectConsoleCard(
+            project.projectId,
+            chatId,
+            operatorOpenId,
+            "已创建并绑定项目",
+          ));
+        }
         deps.logger.info({ chatId, projectId: project.projectId, operatorOpenId }, "project onboarding: created project from chat");
         return;
       }
@@ -760,16 +1072,27 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
       if (projectId === undefined) {
         throw new Error("bind_project action requires project_id");
       }
+      const target = await deps.prisma.project.findUnique({
+        where: { id: projectId },
+        select: { organizationId: true },
+      });
+      if (target === null) throw new Error(`project not found: ${projectId}`);
+      if (target.organizationId !== organization.organizationId) {
+        throw new Error("project onboarding project organization mismatch");
+      }
       const project = await bindFeishuChatToProject(deps.prisma, {
         projectId,
         actorFeishuOpenId: operatorOpenId,
         chatId,
       });
-      await resolveProjectOnboardingCard(rt, messageId, {
-        title: "已绑定项目",
-        body: `本群已绑定到项目 \`${project.projectId}\`。后续 @bot 会进入这个项目的 session。`,
-        template: "green",
-      });
+      if (messageId !== undefined) {
+        await patchCard(rt, messageId, await projectConsoleCard(
+          project.projectId,
+          chatId,
+          operatorOpenId,
+          "已绑定项目",
+        ));
+      }
       deps.logger.info({ chatId, projectId: project.projectId, operatorOpenId }, "project onboarding: bound existing project");
     } catch (e) {
       const reason = e instanceof Error ? e.message : String(e);
@@ -801,7 +1124,7 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
     }
     const binding = await deps.prisma.projectGroupBinding.findFirst({
       where: { chatId, archivedAt: null },
-      select: { projectId: true },
+      select: { projectId: true, selectedRole: { select: { roleId: true } } },
     });
     if (binding === null) {
       deps.logger.debug({ chatId }, "feishu interrupt: chat not bound to any project");
@@ -906,7 +1229,7 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
     // ADR-0001: resolve chat → project. Unknown chat ⇒ not a project group.
     const binding = await deps.prisma.projectGroupBinding.findFirst({
       where: { chatId, archivedAt: null },
-      select: { projectId: true },
+      select: { projectId: true, selectedRole: { select: { roleId: true } } },
     });
     if (binding === null) {
       deps.logger.debug({ chatId }, "feishu trigger: chat not bound to any project");
@@ -925,6 +1248,15 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
       await sendText(rt, chatId, "无法识别发送者,拒绝触发。", sendOptionsForTriggerMessage(msg));
       return;
     }
+    const organizationResolution = await resolveSingleActiveOrganizationForFeishuUser(senderOpenId);
+    if (organizationResolution.status === "error" && organizationResolution.reason !== "organization_unavailable") {
+      deps.logger.info(
+        { projectId, senderOpenId, reason: organizationResolution.reason },
+        "feishu trigger: actor onboarding required before project authorization",
+      );
+      await sendText(rt, chatId, organizationResolution.message, sendOptionsForTriggerMessage(msg));
+      return;
+    }
     const actor = { feishuOpenId: senderOpenId, chatId };
     const triggerDecision = await authorizer.can({
       actor,
@@ -969,22 +1301,35 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
       }
     }
     if (cleanPrompt === null) return;
-    const runContext: TriggerRunContext = { msg, rt, chatId, projectId, senderOpenId, actor };
+    const runContext: TriggerRunContext = {
+      msg,
+      rt,
+      chatId,
+      projectId,
+      senderOpenId,
+      actor,
+      roleId: binding.selectedRole.roleId,
+    };
 
-    // Slash commands: session management, not agent runs. These bypass the
-    // batcher. Session commands bypass the lock because they don't create runs;
-    // role/unknown slash prompts still use the normal run path and queue if locked.
+    // Hub owns a closed slash-command protocol. Unknown commands fail visibly;
+    // they are never downgraded to Agent text or forwarded to the SDK.
     if (cleanPrompt.startsWith("/")) {
       const invocation = parseSlashInvocation(cleanPrompt);
-      const helpSubcommandTarget = invocation === null ? null : parseSlashHelpSubcommand(invocation);
-      if (helpSubcommandTarget !== null) {
-        // Help is generated on demand because role/tool configuration is runtime data.
-        const models = await deps.settings.modelRegistry({ projectId });
-        await sendText(rt, chatId, formatSlashHelpTarget(helpSubcommandTarget, models, slashCommands), sendOptionsForTriggerMessage(msg));
+      if (invocation !== null) {
+        if (invocation.name === "project") {
+          if (invocation.args.length > 0) {
+            await sendText(rt, chatId, "用法: /project", sendOptionsForTriggerMessage(msg));
+            return;
+          }
+          await sendCard(
+            rt,
+            chatId,
+            await projectConsoleCard(projectId, chatId, senderOpenId),
+            sendOptionsForTriggerMessage(msg),
+          );
+          deps.logger.info({ chatId, projectId, senderOpenId }, "feishu project console opened");
           return;
         }
-
-      if (invocation !== null) {
         const slashCommand = slashCommands.get(invocation.name);
         if (slashCommand !== undefined) {
           try {
@@ -1000,8 +1345,8 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
           return;
         }
       }
-
-      await startAgentRun(runContext, cleanPrompt);
+      const name = invocation?.name ?? cleanPrompt.slice(1).trim();
+      await sendText(rt, chatId, `未知 slash 命令 /${name}。使用 /help 查看可用命令。`, sendOptionsForTriggerMessage(msg));
       return;
     }
 
@@ -1015,11 +1360,20 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
         await enqueueLockedTrigger(runContext, cleanPrompt);
         return;
       }
-      const key = messageBatchKey(chatId, senderOpenId);
+      const key = messageBatchKey(chatId, senderOpenId, runContext.roleId);
+      for (const [pendingKey, pendingContext] of batchContexts) {
+        if (
+          pendingKey !== key &&
+          pendingContext.chatId === chatId &&
+          pendingContext.senderOpenId === senderOpenId
+        ) {
+          await messageBatcher.flushNow(pendingKey);
+        }
+      }
       if (!batchContexts.has(key)) {
         batchContexts.set(key, runContext);
       }
-      await messageBatcher.enqueue(chatId, senderOpenId, cleanPrompt);
+      await messageBatcher.enqueue(chatId, senderOpenId, cleanPrompt, runContext.roleId);
       return;
     }
 
@@ -1044,12 +1398,22 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
 
     const settings = await ensureOrganizationProjectSettings(deps.prisma, organization.organizationId);
     const canCreateProject = settings.membersCanCreateProjects || isOrgAdminRole(organization.role);
-    const projects = await listBindableProjectsForActor({
+    const searchQuery = (extractPrompt(msg) ?? "").trim().slice(0, 100);
+    const view = searchQuery === ""
+      ? await browseOnboardingView({
           organizationId: organization.organizationId,
           actorFeishuOpenId: senderOpenId,
           isOrgAdmin: isOrgAdminRole(organization.role),
+          folderId: null,
+          page: 1,
+        })
+      : await searchOnboardingView({
+          organizationId: organization.organizationId,
+          actorFeishuOpenId: senderOpenId,
+          isOrgAdmin: isOrgAdminRole(organization.role),
+          query: searchQuery,
+          page: 1,
         });
-    const folders = await listCreatableRootFolders(organization.organizationId);
 
     await sendCard(
       rt,
@@ -1057,9 +1421,8 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
       buildUnboundChatOnboardingCard({
         organizationId: organization.organizationId,
         organizationName: organization.organizationName,
-        folders,
-        projects,
         canCreateProject,
+        view,
       }),
       sendOptionsForTriggerMessage(msg),
     );
@@ -1072,17 +1435,33 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
         readonly organizationName: string;
         readonly role: "OWNER" | "ADMIN" | "MEMBER";
       }
-    | { readonly status: "error"; readonly message: string }
+    | {
+        readonly status: "error";
+        readonly reason: "identity_missing" | "membership_missing" | "organization_unavailable";
+        readonly message: string;
+      }
   > {
+    const siloOrganization = await deps.prisma.organization.findFirst({
+      where: { id: siloOrganizationId, status: "ACTIVE" },
+      select: { id: true, slug: true },
+    });
+    if (siloOrganization === null) {
+      return {
+        status: "error",
+        reason: "organization_unavailable",
+        message: "组织当前不可用，请联系 Educraft 运维人员。",
+      };
+    }
     const identity = await deps.prisma.feishuUserIdentity.findFirst({
       where: {
         openId: feishuOpenId,
-        connection: { status: "ACTIVE", organization: { status: "ACTIVE" } },
+        connection: { status: "ACTIVE", organizationId: siloOrganization.id },
       },
       select: {
         user: { select: { organizationMemberships: {
           where: {
             revokedAt: null,
+            organizationId: siloOrganization.id,
             organization: { status: "ACTIVE" },
           },
           select: {
@@ -1098,19 +1477,34 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
       where: { feishuOpenId },
       select: {
         organizationMemberships: {
-          where: { revokedAt: null, organization: { status: "ACTIVE" } },
+          where: {
+            revokedAt: null,
+            organizationId: siloOrganization.id,
+            organization: { status: "ACTIVE" },
+          },
           select: { role: true, organization: { select: { id: true, name: true } } },
           orderBy: { createdAt: "asc" },
         },
       },
       })
       : null);
-    if (user === null) return { status: "error", message: "请先登录并加入组织后，再绑定项目。" };
-    if (user.organizationMemberships.length === 0) {
-      return { status: "error", message: "你还不属于任何可用组织，请联系组织管理员。" };
+    if (user === null) {
+      const loginUrl = new URL(
+        `/auth/feishu/${encodeURIComponent(siloOrganization.slug)}`,
+        publicBaseUrl,
+      ).toString();
+      return {
+        status: "error",
+        reason: "identity_missing",
+        message: `请先通过飞书登录并加入组织：${loginUrl}\n完成后返回群聊重试。`,
+      };
     }
-    if (user.organizationMemberships.length > 1) {
-      return { status: "error", message: "你属于多个组织。请先从组织后台选择项目绑定，或等待多组织选择入口。" };
+    if (user.organizationMemberships.length === 0) {
+      return {
+        status: "error",
+        reason: "membership_missing",
+        message: "你尚未加入该组织，或成员资格已被移除。请联系组织管理员。",
+      };
     }
     const membership = user.organizationMemberships[0]!;
     return {
@@ -1121,58 +1515,62 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
     };
   }
 
-  async function listBindableProjectsForActor(input: {
+  async function searchOnboardingView(input: {
     readonly organizationId: string;
     readonly actorFeishuOpenId: string;
     readonly isOrgAdmin: boolean;
-  }): Promise<readonly OnboardingProjectOption[]> {
-    const candidates = await deps.prisma.project.findMany({
-      where: {
+    readonly query: string;
+    readonly page: number;
+  }): Promise<ProjectOnboardingView> {
+    return {
+      mode: "search",
+      result: await discoverBindableProjects({
+        prisma: deps.prisma,
         organizationId: input.organizationId,
-        archivedAt: null,
-        groupBindings: { none: { archivedAt: null } },
-      },
-      select: {
-        id: true,
-        name: true,
-        folder: { select: { name: true } },
-      },
-      orderBy: { updatedAt: "desc" },
-      take: 20,
-    });
-    const allowed: OnboardingProjectOption[] = [];
-    for (const project of candidates) {
-      if (!input.isOrgAdmin) {
-        const decision = await authorizer.can({
-          actor: { feishuOpenId: input.actorFeishuOpenId },
-          action: "collaborator.manage",
-          resource: { type: "PROJECT", id: project.id },
-        });
-        if (!decision.allowed) continue;
-      }
-      allowed.push({
-        projectId: project.id,
-        name: project.name,
-        ...(project.folder?.name !== undefined ? { folderName: project.folder.name } : {}),
-      });
-      if (allowed.length >= 5) break;
-    }
-    return allowed;
+        actorFeishuOpenId: input.actorFeishuOpenId,
+        isOrgAdmin: input.isOrgAdmin,
+        query: input.query,
+        page: input.page,
+      }),
+    };
   }
 
-  async function listCreatableRootFolders(organizationId: string): Promise<readonly OnboardingFolderOption[]> {
-    const folders = await deps.prisma.folder.findMany({
-      where: { organizationId, parentId: null, archivedAt: null },
-      select: { id: true, name: true },
-      orderBy: [{ sortKey: "asc" }, { name: "asc" }],
-      take: 3,
-    });
-    return folders.map((folder) => ({ folderId: folder.id, name: folder.name }));
+  async function browseOnboardingView(input: {
+    readonly organizationId: string;
+    readonly actorFeishuOpenId: string;
+    readonly isOrgAdmin: boolean;
+    readonly folderId: string | null;
+    readonly page: number;
+  }): Promise<ProjectOnboardingView> {
+    return {
+      mode: "browse",
+      result: await browseBindableFolder({
+        prisma: deps.prisma,
+        organizationId: input.organizationId,
+        actorFeishuOpenId: input.actorFeishuOpenId,
+        isOrgAdmin: input.isOrgAdmin,
+        folderId: input.folderId,
+        page: input.page,
+      }),
+    };
   }
 
   return Object.assign(onMessage, { onCardAction, approvalManager });
 }
 
+function parsePublicBaseUrl(raw: string): URL {
+  const value = raw.trim();
+  if (value === "") throw new Error("publicBaseUrl is required");
+  const url = new URL(value);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("publicBaseUrl must use http or https");
+  }
+  if (url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "" || url.pathname !== "/") {
+    throw new Error("publicBaseUrl must be an origin without credentials, path, query, or fragment");
+  }
+  return url;
+}
+
 interface SessionMetadata {
   readonly claudeSessionId?: string | undefined;
 }
@@ -1418,10 +1816,6 @@ function shortId(value: string): string {
   return value.length <= 8 ? value : value.slice(-8);
 }
 
-function escapeCardMarkdown(value: string): string {
-  return value.replace(/([`*_{}[\]<>])/g, "\\$1");
-}
-
 /** Lark text-message content: `{"text":"@_user_1 do something"}`. */
 const TextMessageContentSchema = z.object({ text: z.string() });
 
@@ -1564,27 +1958,3 @@ async function compensateFailedResourceAdmission(
     );
   }
 }
-
-/**
- * Parse a leading `/<role>` command from a prompt (e.g. `/draft 帮我写教案`).
- * Returns the role id and the remaining prompt with the command stripped.
- * Control/help commands already handled upstream are ignored here — they never
- * reach this function.
- *
- * Unknown `/foo` that isn't a registered role: returns `null` role and the
- * original prompt unchanged (the slash is treated as literal text). Role
- * resolution still happens via the registry's fallback.
- */
-export function extractRole(
-  prompt: string,
-  registry: { role(id: string): unknown },
-): { roleId: string | null; prompt: string } {
-  const m = /^\/(\S+)\s*/.exec(prompt);
-  if (m === null || m[1] === undefined) return { roleId: null, prompt };
-  const roleId = m[1];
-  if (registry.role(roleId) === undefined) {
-    // Unknown slash command — leave the prompt as-is (no silent role switch).
-    return { roleId: null, prompt };
-  }
-  return { roleId, prompt: prompt.slice(m[0].length) };
-}

hub/src/feishu/triggerQueue.ts

@@ -4,6 +4,9 @@ export interface QueuedTrigger {
   readonly projectId: string;
   readonly chatId: string;
   readonly prompt: string;
+  /** Role frozen when the message was accepted; later group switches cannot change it. */
+  readonly roleId: string;
+  readonly executionKind: "conversation" | "native_compact";
   readonly msg: MessageReceiveEvent["message"];
   readonly senderOpenId: string;
   readonly actor: { readonly feishuOpenId: string; readonly chatId: string };

hub/src/hub.ts

@@ -2,6 +2,7 @@ import Fastify from "fastify";
 import { registerAdminPlugin } from "./admin/plugin.js";
 import { prisma } from "./db.js";
 import { createLarkClient, startFeishuListenerWithClient } from "./feishu/client.js";
+import { archiveFeishuBindingForLifecycleEvent } from "./feishu/bindingLifecycle.js";
 import { makeTriggerHandler } from "./feishu/trigger.js";
 import { removeAbandonedMessageResourceStages } from "./feishu/resourceStaging.js";
 import { triggerQueue } from "./feishu/triggerQueue.js";
@@ -160,6 +161,8 @@ export async function startHub(): Promise<void> {
       settings: runtimeSettings,
       logger: app.log,
       projectWorkspaceRoot,
+      publicBaseUrl,
+      siloOrganizationId: siloOrganization.id,
       rejectWhenBusy: true,
       resourceLimits: { maxFilesPerMessage, maxBytesPerFile },
       allowLegacyFeishuIdentity: false,
@@ -175,6 +178,10 @@ export async function startHub(): Promise<void> {
         process.exitCode = 1;
         void app.close().catch((error) => app.log.error({ err: error }, "Hub close after Feishu failure failed"));
       },
+      async (event) => {
+        const result = await archiveFeishuBindingForLifecycleEvent(prisma, event);
+        app.log.info({ ...event, archived: result.archived, projectId: result.projectId }, "feishu binding lifecycle event handled");
+      },
     );
   } else {
     app.log.info("feishu listener disabled by HUB_FEISHU_LISTENER_ENABLED");

hub/src/org/explorer.ts

@@ -4,7 +4,7 @@
  * Folders are transparent navigation nodes (not ACL resources). Project grants
  * stay on PROJECT. Archive folder refuses when active children/projects remain.
  */
-import type { Prisma, PrismaClient } from "@prisma/client";
+import { Prisma, type PrismaClient } from "@prisma/client";
 import {
   archiveFeishuChatBinding,
   createFolder,
@@ -123,11 +123,25 @@ export async function renameFolder(
   return prisma.$transaction(async (tx) => {
     await lockActiveOrganization(tx, input.organizationId);
     const folder = await requireActiveFolder(tx, input.folderId, input.organizationId);
+    if (folder.kind === "SYSTEM_INBOX" && (input.name !== undefined || input.parentId !== undefined)) {
+      throw new Error("system Inbox cannot be renamed or moved");
+    }
     if (input.parentId !== undefined && input.parentId !== null) {
       if (input.parentId === folder.id) {
         throw new Error("folder cannot be its own parent");
       }
       await requireActiveFolder(tx, input.parentId, input.organizationId);
+      const descendant = await tx.$queryRaw<Array<{ found: boolean }>>(Prisma.sql`
+        WITH RECURSIVE descendants AS (
+          SELECT "id" FROM "Folder" WHERE "parentId" = ${folder.id} AND "archivedAt" IS NULL
+          UNION ALL
+          SELECT child."id" FROM "Folder" child
+          JOIN descendants parent ON child."parentId" = parent."id"
+          WHERE child."archivedAt" IS NULL
+        )
+        SELECT EXISTS(SELECT 1 FROM descendants WHERE "id" = ${input.parentId}) AS found
+      `);
+      if (descendant[0]?.found === true) throw new Error("folder cannot be moved below its descendant");
     }
     const name =
       input.name !== undefined ? requireNonEmpty(input.name, "folder name") : undefined;
@@ -152,6 +166,7 @@ export async function archiveFolder(
   return prisma.$transaction(async (tx) => {
     await lockActiveOrganization(tx, input.organizationId);
     const folder = await requireActiveFolder(tx, input.folderId, input.organizationId);
+    if (folder.kind === "SYSTEM_INBOX") throw new Error("system Inbox cannot be archived");
     const childFolders = await tx.folder.count({
       where: { parentId: folder.id, archivedAt: null },
     });
@@ -324,10 +339,10 @@ async function requireActiveFolder(
   prisma: PrismaClient | Prisma.TransactionClient,
   folderId: string,
   organizationId: string,
-): Promise<{ readonly id: string; readonly organizationId: string }> {
+): Promise<{ readonly id: string; readonly organizationId: string; readonly kind: "REGULAR" | "SYSTEM_INBOX" }> {
   const folder = await prisma.folder.findUnique({
     where: { id: folderId },
-    select: { id: true, organizationId: true, archivedAt: true },
+    select: { id: true, organizationId: true, kind: true, archivedAt: true },
   });
   if (folder === null || folder.archivedAt !== null || folder.organizationId !== organizationId) {
     throw new Error(`active folder not found: ${folderId}`);

hub/src/projectDiscovery.ts

@@ -0,0 +1,315 @@
+import { Prisma, type PrismaClient } from "@prisma/client";
+import { PrismaPrincipalResolver } from "./permission.js";
+
+const DEFAULT_PAGE_SIZE = 8;
+const MAX_PAGE_SIZE = 10;
+
+export interface ProjectDiscoveryItem {
+  readonly projectId: string;
+  readonly name: string;
+  readonly breadcrumb: string;
+}
+
+export interface ProjectDiscoveryPage {
+  readonly query: string;
+  readonly page: number;
+  readonly pageSize: number;
+  readonly totalItems: number;
+  readonly totalPages: number;
+  readonly items: readonly ProjectDiscoveryItem[];
+}
+
+export interface ProjectFolderPage {
+  readonly folderId: string | null;
+  readonly parentFolderId: string | null;
+  readonly breadcrumb: string;
+  readonly page: number;
+  readonly pageSize: number;
+  readonly totalPages: number;
+  readonly totalFolders: number;
+  readonly totalProjects: number;
+  readonly childFolders: readonly { readonly folderId: string; readonly name: string }[];
+  readonly projects: readonly ProjectDiscoveryItem[];
+}
+
+interface DiscoveryCandidate extends ProjectDiscoveryItem {
+  readonly updatedAt: Date;
+}
+
+export function normalizeProjectSearchQuery(value: string): string {
+  return value.normalize("NFKC").toLocaleLowerCase("und").replace(/[\s_.:/\\-]+/gu, "");
+}
+
+export async function discoverBindableProjects(input: {
+  readonly prisma: PrismaClient;
+  readonly organizationId: string;
+  readonly actorFeishuOpenId: string;
+  readonly isOrgAdmin: boolean;
+  readonly query: string;
+  readonly page?: number | undefined;
+  readonly pageSize?: number | undefined;
+}): Promise<ProjectDiscoveryPage> {
+  const query = input.query.trim().slice(0, 100);
+  const normalizedQuery = normalizeProjectSearchQuery(query);
+  const manageableIds = input.isOrgAdmin
+    ? null
+    : await listManageableProjectIds(input.prisma, input.organizationId, input.actorFeishuOpenId);
+  const pageSize = normalizedPageSize(input.pageSize);
+  const totalItems = await countSearchCandidates(
+    input.prisma,
+    input.organizationId,
+    normalizedQuery,
+    searchTokens(query),
+    manageableIds,
+  );
+  const totalPages = Math.max(1, Math.ceil(totalItems / pageSize));
+  const page = normalizedPage(input.page, totalPages);
+  const items = await searchCandidates(
+    input.prisma,
+    input.organizationId,
+    normalizedQuery,
+    searchTokens(query),
+    manageableIds,
+    page,
+    pageSize,
+  );
+  return { query, page, pageSize, totalItems, totalPages, items };
+}
+
+export async function browseBindableFolder(input: {
+  readonly prisma: PrismaClient;
+  readonly organizationId: string;
+  readonly actorFeishuOpenId: string;
+  readonly isOrgAdmin: boolean;
+  readonly folderId: string | null;
+  readonly page?: number | undefined;
+  readonly pageSize?: number | undefined;
+}): Promise<ProjectFolderPage> {
+  const folder = input.folderId === null
+    ? null
+    : await input.prisma.folder.findFirst({
+        where: { id: input.folderId, organizationId: input.organizationId, archivedAt: null },
+        select: { id: true, parentId: true },
+      });
+  if (input.folderId !== null && folder === null) throw new Error(`folder not found: ${input.folderId}`);
+
+  const manageableIds = input.isOrgAdmin
+    ? null
+    : await listManageableProjectIds(input.prisma, input.organizationId, input.actorFeishuOpenId);
+  const inbox = input.folderId === null
+    ? await input.prisma.folder.findFirst({
+        where: { organizationId: input.organizationId, kind: "SYSTEM_INBOX", archivedAt: null },
+        select: { id: true },
+      })
+    : null;
+  const projectWhere: Prisma.ProjectSearchDocumentWhereInput = {
+    organizationId: input.organizationId,
+    ...(manageableIds === null ? {} : { projectId: { in: [...manageableIds] } }),
+    project: {
+      ...(input.folderId === null
+        ? { OR: [{ folderId: null }, ...(inbox === null ? [] : [{ folderId: inbox.id }])] }
+        : { folderId: input.folderId }),
+      archivedAt: null,
+      groupBindings: { none: { archivedAt: null } },
+    },
+  };
+  const folderWhere: Prisma.FolderWhereInput = {
+    organizationId: input.organizationId,
+    parentId: input.folderId,
+    archivedAt: null,
+    ...(input.folderId === null ? { kind: { not: "SYSTEM_INBOX" } } : {}),
+  };
+  const [breadcrumb, totalFolders, totalProjects] = await Promise.all([
+    input.folderId === null ? Promise.resolve("") : folderBreadcrumb(input.prisma, input.folderId),
+    input.prisma.folder.count({ where: folderWhere }),
+    input.prisma.projectSearchDocument.count({ where: projectWhere }),
+  ]);
+  const pageSize = normalizedPageSize(input.pageSize);
+  const totalPages = Math.max(1, Math.ceil((totalFolders + totalProjects) / pageSize));
+  const page = normalizedPage(input.page, totalPages);
+  const offset = (page - 1) * pageSize;
+  const folderSkip = Math.min(offset, totalFolders);
+  const folderTake = Math.min(pageSize, Math.max(0, totalFolders - folderSkip));
+  const projectSkip = Math.max(0, offset - totalFolders);
+  const projectTake = pageSize - folderTake;
+  const [childFolders, candidates] = await Promise.all([
+    folderTake === 0 ? Promise.resolve([]) : input.prisma.folder.findMany({
+      where: folderWhere,
+      select: { id: true, name: true },
+      orderBy: [{ sortKey: "asc" }, { name: "asc" }, { id: "asc" }],
+      skip: folderSkip,
+      take: folderTake,
+    }),
+    projectTake === 0 ? Promise.resolve([]) : input.prisma.projectSearchDocument.findMany({
+      where: projectWhere,
+      select: { projectId: true, name: true, breadcrumb: true },
+      orderBy: [{ name: "asc" }, { projectId: "asc" }],
+      skip: projectSkip,
+      take: projectTake,
+    }),
+  ]);
+  return {
+    folderId: input.folderId,
+    parentFolderId: folder?.parentId ?? null,
+    breadcrumb,
+    page,
+    pageSize,
+    totalPages,
+    totalFolders,
+    totalProjects,
+    childFolders: childFolders.map((child) => ({ folderId: child.id, name: child.name })),
+    projects: candidates,
+  };
+}
+
+async function searchCandidates(
+  prisma: PrismaClient,
+  organizationId: string,
+  normalizedQuery: string,
+  tokens: readonly string[],
+  manageableIds: readonly string[] | null,
+  page: number,
+  pageSize: number,
+): Promise<readonly DiscoveryCandidate[]> {
+  const access = accessPredicate(manageableIds);
+  const offset = (page - 1) * pageSize;
+  if (normalizedQuery === "") {
+    return prisma.$queryRaw<DiscoveryCandidate[]>(Prisma.sql`
+      SELECT d."projectId", d."name", d."breadcrumb", p."updatedAt"
+      FROM "ProjectSearchDocument" d
+      JOIN "Project" p ON p."id" = d."projectId"
+      WHERE d."organizationId" = ${organizationId}
+        AND p."archivedAt" IS NULL
+        AND NOT EXISTS (
+          SELECT 1 FROM "ProjectGroupBinding" b
+          WHERE b."projectId" = p."id" AND b."archivedAt" IS NULL
+        )
+        ${access}
+      ORDER BY p."updatedAt" DESC, p."id" DESC
+      LIMIT ${pageSize} OFFSET ${offset}
+    `);
+  }
+  const matches = searchPredicate(normalizedQuery, tokens);
+  return prisma.$queryRaw<DiscoveryCandidate[]>(Prisma.sql`
+    SELECT d."projectId", d."name", d."breadcrumb", p."updatedAt"
+    FROM "ProjectSearchDocument" d
+    JOIN "Project" p ON p."id" = d."projectId"
+    WHERE d."organizationId" = ${organizationId}
+      AND p."archivedAt" IS NULL
+      AND NOT EXISTS (
+        SELECT 1 FROM "ProjectGroupBinding" b
+        WHERE b."projectId" = p."id" AND b."archivedAt" IS NULL
+      )
+      ${access}
+      AND ${matches}
+    ORDER BY
+      CASE
+        WHEN d."normalizedCode" = ${normalizedQuery} THEN 0
+        WHEN d."normalizedName" = ${normalizedQuery} THEN 1
+        WHEN strpos(d."normalizedCode", ${normalizedQuery}) = 1 THEN 2
+        WHEN strpos(d."normalizedName", ${normalizedQuery}) = 1 THEN 3
+        WHEN strpos(d."normalizedName", ${normalizedQuery}) > 0 THEN 4
+        WHEN strpos(d."normalizedBreadcrumb", ${normalizedQuery}) > 0 THEN 5
+        ELSE 6
+      END,
+      similarity(d."normalizedName", ${normalizedQuery}) DESC,
+      p."updatedAt" DESC,
+      p."id" ASC
+    LIMIT ${pageSize} OFFSET ${offset}
+  `);
+}
+
+async function countSearchCandidates(
+  prisma: PrismaClient,
+  organizationId: string,
+  normalizedQuery: string,
+  tokens: readonly string[],
+  manageableIds: readonly string[] | null,
+): Promise<number> {
+  const access = accessPredicate(manageableIds);
+  const queryPredicate = normalizedQuery === "" ? Prisma.empty : Prisma.sql`AND ${searchPredicate(normalizedQuery, tokens)}`;
+  const rows = await prisma.$queryRaw<Array<{ count: number }>>(Prisma.sql`
+    SELECT count(*)::int AS count
+    FROM "ProjectSearchDocument" d
+    JOIN "Project" p ON p."id" = d."projectId"
+    WHERE d."organizationId" = ${organizationId}
+      AND p."archivedAt" IS NULL
+      AND NOT EXISTS (
+        SELECT 1 FROM "ProjectGroupBinding" b
+        WHERE b."projectId" = p."id" AND b."archivedAt" IS NULL
+      )
+      ${access}
+      ${queryPredicate}
+  `);
+  return rows[0]?.count ?? 0;
+}
+
+async function listManageableProjectIds(
+  prisma: PrismaClient,
+  organizationId: string,
+  actorFeishuOpenId: string,
+): Promise<readonly string[]> {
+  const resolution = await new PrismaPrincipalResolver(prisma).resolveActor(
+    { feishuOpenId: actorFeishuOpenId },
+    { organizationId },
+  );
+  const grants = await prisma.permissionGrant.findMany({
+    where: {
+      resourceType: "PROJECT",
+      role: "MANAGE",
+      revokedAt: null,
+      OR: resolution.principals.map((principal) => ({
+        principalType: principal.type,
+        principalId: principal.id,
+      })),
+    },
+    select: { resourceId: true },
+  });
+  const projectIds = [...new Set(grants.map((grant) => grant.resourceId))];
+  if (projectIds.length === 0) return [];
+  const projects = await prisma.project.findMany({
+    where: { id: { in: projectIds }, organizationId, archivedAt: null },
+    select: { id: true },
+  });
+  return projects.map((project) => project.id);
+}
+
+function searchPredicate(normalizedQuery: string, tokens: readonly string[]): Prisma.Sql {
+  const tokenMatch = tokens.length <= 1
+    ? Prisma.sql`FALSE`
+    : Prisma.sql`(${Prisma.join(tokens.map((token) => Prisma.sql`strpos(d."normalizedSearchText", ${token}) > 0`), " AND ")})`;
+  return Prisma.sql`(
+    strpos(d."normalizedCode", ${normalizedQuery}) > 0
+    OR strpos(d."normalizedName", ${normalizedQuery}) > 0
+    OR strpos(d."normalizedBreadcrumb", ${normalizedQuery}) > 0
+    OR d."normalizedName" % ${normalizedQuery}
+    OR ${tokenMatch}
+  )`;
+}
+
+function accessPredicate(manageableIds: readonly string[] | null): Prisma.Sql {
+  if (manageableIds === null) return Prisma.empty;
+  if (manageableIds.length === 0) return Prisma.sql`AND FALSE`;
+  return Prisma.sql`AND p."id" IN (${Prisma.join(manageableIds)})`;
+}
+
+function searchTokens(query: string): readonly string[] {
+  return query.normalize("NFKC").trim().split(/\s+/u).map(normalizeProjectSearchQuery).filter(Boolean);
+}
+
+function normalizedPageSize(value = DEFAULT_PAGE_SIZE): number {
+  return Math.min(MAX_PAGE_SIZE, Math.max(1, Math.trunc(value)));
+}
+
+function normalizedPage(value: number | undefined, totalPages: number): number {
+  return Math.min(totalPages, Math.max(1, Math.trunc(value ?? 1)));
+}
+
+async function folderBreadcrumb(prisma: PrismaClient, folderId: string): Promise<string> {
+  const rows = await prisma.$queryRaw<Array<{ breadcrumb: string }>>(Prisma.sql`
+    SELECT cph_folder_breadcrumb(${folderId}) AS breadcrumb
+  `);
+  const breadcrumb = rows[0]?.breadcrumb;
+  if (breadcrumb === undefined) throw new Error(`failed to resolve folder breadcrumb: ${folderId}`);
+  return breadcrumb;
+}

hub/src/projectOnboarding.ts

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { mkdir, rm } from "node:fs/promises";
 import { dirname, relative, resolve } from "node:path";
 import type { Folder, OrganizationMemberRole, PermissionRole, Prisma, PrismaClient } from "@prisma/client";
@@ -27,6 +27,8 @@ export interface CreateOrgAdminProjectInput {
   readonly workspaceRoot: string;
   readonly folderId?: string | undefined;
   readonly sortKey?: string | undefined;
+  /** Stable internal identifier for resumable imports; ordinary callers must omit it. */
+  readonly projectId?: string | undefined;
 }
 
 export interface CreateFeishuChatProjectInput {
@@ -51,6 +53,13 @@ export interface ArchiveFeishuChatBindingInput {
   readonly actorFeishuOpenId: string;
 }
 
+export interface RenameProjectForActorInput {
+  readonly organizationId: string;
+  readonly projectId: string;
+  readonly actorFeishuOpenId: string;
+  readonly name: string;
+}
+
 export interface CreateFolderInput {
   readonly organizationId: string;
   readonly name: string;
@@ -129,6 +138,45 @@ export async function moveProjectToFolder(
   });
 }
 
+export async function renameProjectForActor(
+  prisma: PrismaClient,
+  input: RenameProjectForActorInput,
+): Promise<{ readonly projectId: string; readonly name: string }> {
+  const name = requireNonEmpty(input.name, "project name");
+  const project = await prisma.project.findUnique({
+    where: { id: input.projectId },
+    select: { id: true, organizationId: true, name: true },
+  });
+  if (project === null) throw new Error(`project not found: ${input.projectId}`);
+  if (project.organizationId !== input.organizationId) {
+    throw new Error(`project ${project.id} does not belong to organization ${input.organizationId}`);
+  }
+  const actor = await requireProjectManager(prisma, project.id, project.organizationId, input.actorFeishuOpenId);
+  const updated = await prisma.$transaction(async (tx) => {
+    await lockActiveOrganization(tx, project.organizationId);
+    const current = await tx.project.findUniqueOrThrow({
+      where: { id: project.id },
+      select: { name: true },
+    });
+    const renamed = await tx.project.update({
+      where: { id: project.id },
+      data: { name },
+      select: { id: true, name: true },
+    });
+    await tx.auditEntry.create({
+      data: {
+        organizationId: project.organizationId,
+        projectId: project.id,
+        actorUserId: actor.userId,
+        action: "project.renamed",
+        metadata: { oldName: current.name, newName: name, actorVia: actor.via },
+      },
+    });
+    return renamed;
+  });
+  return { projectId: updated.id, name: updated.name };
+}
+
 export async function createProjectFromOrgAdmin(
   prisma: PrismaClient,
   input: CreateOrgAdminProjectInput,
@@ -147,6 +195,7 @@ export async function createProjectFromOrgAdmin(
     workspaceRoot: input.workspaceRoot,
     folderId: input.folderId,
     sortKey: input.sortKey,
+    projectId: input.projectId,
     chatId: undefined,
   });
 }
@@ -195,6 +244,7 @@ export async function bindFeishuChatToProject(
   const actor = await requireProjectManager(prisma, project.id, project.organizationId, input.actorFeishuOpenId);
   await prisma.$transaction(async (tx) => {
     await requireActiveOrganizationTx(tx, project.organizationId);
+    const defaultRole = await requireDefaultAgentRole(tx, project.organizationId);
     const activeProjectBinding = await tx.projectGroupBinding.findFirst({
       where: { projectId: project.id, archivedAt: null },
       select: { chatId: true },
@@ -210,7 +260,13 @@ export async function bindFeishuChatToProject(
       throw new Error(`Feishu chat ${chatId} is already bound to project ${activeChatBinding.projectId}`);
     }
     await tx.projectGroupBinding.create({
-      data: { projectId: project.id, chatId, createdByUserId: actor.userId },
+      data: {
+        organizationId: project.organizationId,
+        projectId: project.id,
+        chatId,
+        createdByUserId: actor.userId,
+        selectedAgentRoleId: defaultRole.id,
+      },
     });
     await replaceProjectGrant(tx, {
       projectId: project.id,
@@ -291,6 +347,7 @@ async function createManagedProject(
     readonly workspaceRoot: string;
     readonly folderId: string | undefined;
     readonly sortKey?: string | undefined;
+    readonly projectId?: string | undefined;
     readonly chatId: string | undefined;
   },
 ): Promise<ProjectOnboardingResult> {
@@ -301,7 +358,7 @@ async function createManagedProject(
   if (organization === null) throw new Error(`organization not found: ${input.organizationId}`);
   requireActiveOrganizationStatus(organization.id, organization.status);
 
-  const projectId = createProjectId();
+  const projectId = input.projectId ?? createProjectId();
   const workspaceDir = projectWorkspaceDir({
     workspaceRoot: input.workspaceRoot,
     organizationSlug: organization.slug,
@@ -341,8 +398,15 @@ async function createManagedProject(
         createdByUserId: input.actorUserId,
       });
       if (input.chatId !== undefined) {
+        const defaultRole = await requireDefaultAgentRole(tx, organization.id);
         await tx.projectGroupBinding.create({
-          data: { projectId: created.id, chatId: input.chatId, createdByUserId: input.actorUserId },
+          data: {
+            organizationId: organization.id,
+            projectId: created.id,
+            chatId: input.chatId,
+            createdByUserId: input.actorUserId,
+            selectedAgentRoleId: defaultRole.id,
+          },
         });
         await replaceProjectGrant(tx, {
           projectId: created.id,
@@ -490,12 +554,12 @@ async function ensureOrganizationProjectSettingsTx(
 
 async function ensureInboxFolder(prisma: Prisma.TransactionClient, organizationId: string): Promise<{ readonly id: string }> {
   const existing = await prisma.folder.findFirst({
-    where: { organizationId, parentId: null, name: "Inbox", archivedAt: null },
+    where: { organizationId, kind: "SYSTEM_INBOX", archivedAt: null },
     select: { id: true },
   });
   if (existing !== null) return existing;
   return prisma.folder.create({
-    data: { organizationId, name: "Inbox", sortKey: "000000" },
+    data: { organizationId, name: "Inbox", kind: "SYSTEM_INBOX", sortKey: "000000" },
     select: { id: true },
   });
 }
@@ -517,6 +581,21 @@ async function assertFolderInOrganization(
   }
 }
 
+async function requireDefaultAgentRole(
+  tx: Prisma.TransactionClient,
+  organizationId: string,
+): Promise<{ readonly id: string }> {
+  const roles = await tx.organizationAgentRole.findMany({
+    where: { organizationId, isDefault: true, disabledAt: null },
+    select: { id: true },
+    take: 2,
+  });
+  if (roles.length !== 1) {
+    throw new Error(`organization ${organizationId} must have exactly one active default Agent role`);
+  }
+  return roles[0]!;
+}
+
 async function requireActiveOrganization(prisma: PrismaClient, organizationId: string): Promise<void> {
   const organization = await prisma.organization.findUnique({
     where: { id: organizationId },
@@ -595,7 +674,11 @@ function projectWorkspaceDir(input: {
   readonly projectId: string;
 }): string {
   const root = resolve(requireNonEmpty(input.workspaceRoot, "workspace root"));
-  const dir = resolve(root, safePathSegment(input.organizationSlug, "organization slug"), safePathSegment(input.projectId, "project id"));
+  const dir = resolve(
+    root,
+    compactWorkspaceSegment("o", input.organizationSlug, "organization slug"),
+    compactWorkspaceSegment("p", input.projectId, "project id"),
+  );
   const rel = relative(root, dir);
   if (rel === "" || rel.startsWith("..")) {
     throw new Error(`allocated workspace escapes root: ${dir}`);
@@ -603,6 +686,12 @@ function projectWorkspaceDir(input: {
   return dir;
 }
 
+function compactWorkspaceSegment(prefix: "o" | "p", value: string, label: string): string {
+  const normalized = safePathSegment(value, label);
+  const digest = createHash("sha256").update(normalized).digest("base64url").slice(0, 16);
+  return `${prefix}_${digest}`;
+}
+
 function safePathSegment(value: string, label: string): string {
   const segment = requireNonEmpty(value, label).replace(/[^A-Za-z0-9._-]+/g, "_");
   if (segment === "." || segment === ".." || segment === "") {

hub/src/security/workspaceFiles.ts

@@ -37,6 +37,7 @@ export async function readWorkspaceFileNoFollow(
   workspaceRoot: string,
   workspaceDir: string,
   requestedPath: string,
+  maxBytes?: number,
 ): Promise<WorkspaceFileSnapshot> {
   const workspace = await canonicalWorkspace(workspaceRoot, workspaceDir);
   const components = fileComponents(workspace, requestedPath);
@@ -53,8 +54,15 @@ export async function readWorkspaceFileNoFollow(
     if (!metadata.isFile()) {
       throw new WorkspaceFileBoundaryError(`deliverable is not a regular file: ${requestedPath}`, requestedPath);
     }
+    if (maxBytes !== undefined && metadata.size > maxBytes) {
+      throw new WorkspaceFileBoundaryError(
+        `workspace file exceeds ${maxBytes} bytes: ${requestedPath}`,
+        requestedPath,
+        "limit",
+      );
+    }
     await assertNameStillReferences(parent, name, metadata.dev, metadata.ino, requestedPath);
-    const data = await file.readFile();
+    const data = await readFileSnapshot(file, maxBytes, requestedPath);
     result = { path: join(workspace, ...components), name, data };
   } catch (error) {
     failure = boundaryError(error, requestedPath, "cannot read workspace file without following symlinks");
@@ -67,6 +75,33 @@ export async function readWorkspaceFileNoFollow(
   return result!;
 }
 
+async function readFileSnapshot(
+  file: FileHandle,
+  maxBytes: number | undefined,
+  requestedPath: string,
+): Promise<Buffer> {
+  if (maxBytes === undefined) return file.readFile();
+  const chunks: Buffer[] = [];
+  let total = 0;
+  let position = 0;
+  while (true) {
+    const remainingWithSentinel = maxBytes - total + 1;
+    const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, remainingWithSentinel));
+    const { bytesRead } = await file.read(chunk, 0, chunk.length, position);
+    if (bytesRead === 0) return Buffer.concat(chunks, total);
+    total += bytesRead;
+    if (total > maxBytes) {
+      throw new WorkspaceFileBoundaryError(
+        `workspace file exceeds ${maxBytes} bytes: ${requestedPath}`,
+        requestedPath,
+        "limit",
+      );
+    }
+    chunks.push(chunk.subarray(0, bytesRead));
+    position += bytesRead;
+  }
+}
+
 /**
  * Create one inbound file exclusively below the workspace and stream into its
  * already-open descriptor. Linux uses /proc/self/fd-relative traversal so a

hub/src/settings/runtime.ts

@@ -1,5 +1,5 @@
 import type { Prisma, PrismaClient } from "@prisma/client";
-import { InMemoryModelRegistry, type ModelRegistry } from "../agent/models.js";
+import { InMemoryModelRegistry, type ModelRegistry, type RoleEntry, type RoleSkillEntry } from "../agent/models.js";
 import { lockActiveOrganization } from "../org/status.js";
 import { decryptStoredProviderCredential } from "../connections/providerConnections.js";
 import { openProviderProxyLease, type AgentProviderLease, type ProviderUpstreamCredential } from "../connections/providerProxy.js";
@@ -141,8 +141,76 @@ export class DatabaseRuntimeSettings implements RuntimeSettings {
     };
   }
 
-  modelRegistry(scope?: RuntimeScope): Promise<ModelRegistry> {
-    return this.envSettings.modelRegistry(scope);
+  async modelRegistry(scope?: RuntimeScope): Promise<ModelRegistry> {
+    const projectId = scope?.projectId?.trim();
+    if (projectId === undefined || projectId === "") {
+      throw new Error("projectId is required to resolve Agent runtime configuration");
+    }
+    const project = await this.prisma.project.findUnique({
+      where: { id: projectId },
+      select: {
+        archivedAt: true,
+        organization: {
+          select: {
+            id: true,
+            status: true,
+            agentRoles: {
+              where: { disabledAt: null },
+              orderBy: [{ sortOrder: "asc" }, { roleId: "asc" }],
+              include: {
+                skillBindings: {
+                  orderBy: [{ sortOrder: "asc" }, { agentSkillId: "asc" }],
+                  include: { skill: true },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+    if (project === null || project.archivedAt !== null) {
+      throw new Error(`active project not found: ${projectId}`);
+    }
+    if (project.organization.status !== "ACTIVE") {
+      throw new Error(`organization ${project.organization.id} is ${project.organization.status}`);
+    }
+    if (project.organization.agentRoles.length === 0) {
+      throw new Error(`no active Agent roles configured for organization ${project.organization.id}`);
+    }
+    const defaultRoles = project.organization.agentRoles.filter((role) => role.isDefault);
+    if (defaultRoles.length !== 1) {
+      throw new Error(`organization ${project.organization.id} must have exactly one active default Agent role`);
+    }
+
+    const defaults = await this.envSettings.modelRegistry(scope);
+    const enabledModels = new Set(defaults.listModels().map((model) => model.id));
+    const roles: RoleEntry[] = project.organization.agentRoles.map((role) => ({
+      id: role.roleId,
+      label: role.label,
+      defaultModel: validateRoleModel(role.roleId, role.defaultModel, enabledModels),
+      ...(role.systemPrompt !== null ? { systemPrompt: role.systemPrompt } : {}),
+      ...(role.tools !== null ? { tools: roleToolsFromJson(role.roleId, role.tools) } : {}),
+      skills: role.skillBindings.map((binding): RoleSkillEntry => {
+        if (binding.skill.disabledAt !== null) {
+          throw new Error(`role ${role.roleId} selects disabled skill ${binding.skill.name}`);
+        }
+        if (!/^[a-f0-9]{64}$/.test(binding.skill.contentDigest)) {
+          throw new Error(`skill ${binding.skill.name} has invalid content digest`);
+        }
+        if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(binding.skill.name)) {
+          throw new Error(`skill has invalid name: ${binding.skill.name}`);
+        }
+        if (binding.skill.version.trim() === "") {
+          throw new Error(`skill ${binding.skill.name} has empty version`);
+        }
+        return {
+          name: binding.skill.name,
+          version: binding.skill.version,
+          contentDigest: binding.skill.contentDigest,
+        };
+      }),
+    }));
+    return new InMemoryModelRegistry(defaults.listModels(), roles);
   }
 
   runPolicy(input: RunPolicyInput): Promise<RunPolicy> {
@@ -150,6 +218,23 @@ export class DatabaseRuntimeSettings implements RuntimeSettings {
   }
 }
 
+function roleToolsFromJson(roleId: string, value: Prisma.JsonValue): readonly string[] {
+  if (!Array.isArray(value) || value.some((tool) => typeof tool !== "string")) {
+    throw new Error(`role ${roleId} tools must be a JSON string array`);
+  }
+  return value as string[];
+}
+
+function validateRoleModel(
+  roleId: string,
+  model: string | null,
+  enabledModels: ReadonlySet<string>,
+): string | undefined {
+  if (model === null) return undefined;
+  if (!enabledModels.has(model)) throw new Error(`role ${roleId} selects unavailable model ${model}`);
+  return model;
+}
+
 async function loadActiveProviderSecret(
   tx: Prisma.TransactionClient,
   projectId: string,

hub/test/integration/admin-auth.test.ts

@@ -267,9 +267,6 @@ describe("admin auth + org API guards", () => {
       openId: "ou_scoped_user",
       displayName: "Invited User",
     });
-    await prisma.organizationMembership.create({
-      data: { organizationId: DEFAULT_ORG_ID, userId: identity.userId, role: "ADMIN" },
-    });
     await seedTestOrganization("org_scoped_other", "scoped-other");
     await prisma.organizationMembership.create({
       data: { organizationId: "org_scoped_other", userId: identity.userId, role: "ADMIN" },
@@ -317,7 +314,7 @@ describe("admin auth + org API guards", () => {
       expect(me.statusCode).toBe(200);
       expect(me.json()).toMatchObject({
         user: { id: identity.userId, displayName: "Scoped User" },
-        organizations: [expect.objectContaining({ slug: "test-default", role: "ADMIN" })],
+        organizations: [expect.objectContaining({ slug: "test-default", role: "MEMBER" })],
       });
       expect((me.json() as { organizations: unknown[] }).organizations).toHaveLength(1);
       const crossOrganization = await app.inject({
@@ -331,6 +328,32 @@ describe("admin auth + org API guards", () => {
         where: { id: identity.identityId },
         select: { unionId: true },
       })).resolves.toEqual({ unionId: "on_scoped_union" });
+      await expect(prisma.auditEntry.count({
+        where: {
+          organizationId: DEFAULT_ORG_ID,
+          actorUserId: identity.userId,
+          action: "organization_member.oauth_auto_joined",
+        },
+      })).resolves.toBe(1);
+
+      const defaultStart = await app.inject({ method: "GET", url: "/auth/feishu/test-default" });
+      const defaultAuthorize = new URL(String(defaultStart.headers.location));
+      const defaultState = defaultAuthorize.searchParams.get("state");
+      expect(defaultState).not.toBeNull();
+      const defaultCallback = await app.inject({
+        method: "GET",
+        url: `/auth/feishu/callback?code=ok&state=${encodeURIComponent(defaultState!)}`,
+        headers: { cookie: cookiePair(defaultStart.headers["set-cookie"], OAUTH_STATE_COOKIE_NAME) },
+      });
+      expect(defaultCallback.statusCode).toBe(302);
+      expect(defaultCallback.headers.location).toBe(
+        "/auth/feishu/complete?org=Test%20Default%20Organization",
+      );
+      const complete = await app.inject({ method: "GET", url: defaultCallback.headers.location! });
+      expect(complete.statusCode).toBe(200);
+      expect(complete.headers["content-type"]).toContain("text/html");
+      expect(complete.body).toContain("登录并加入组织成功");
+      expect(complete.body).toContain("Test Default Organization");
 
       await connections.disable({ organizationId: DEFAULT_ORG_ID, actorUserId: "scoped-owner" });
       const revoked = await app.inject({ method: "GET", url: "/api/me", headers: { cookie: sessionCookie } });
@@ -340,6 +363,65 @@ describe("admin auth + org API guards", () => {
     }
   });
 
+  it("does not restore a revoked Organization membership during scoped OAuth", async () => {
+    await seedUser("revoked-owner", "legacy_revoked_owner", "OWNER");
+    const connections = new FeishuApplicationConnectionService(prisma, testSecretEnvelope, async () => {});
+    const connection = await connections.rotateCustomerApplication({
+      organizationId: DEFAULT_ORG_ID,
+      actorUserId: "revoked-owner",
+      appId: "cli_revoked_oauth",
+      appSecret: "revoked-oauth-secret",
+      botOpenId: "ou_revoked_bot",
+    });
+    const identity = await upsertScopedFeishuIdentity(prisma, {
+      connectionId: connection.id,
+      openId: "ou_revoked_user",
+      displayName: "Revoked User",
+    });
+    await prisma.organizationMembership.create({
+      data: {
+        organizationId: DEFAULT_ORG_ID,
+        userId: identity.userId,
+        role: "MEMBER",
+        revokedAt: new Date(),
+      },
+    });
+    const fetchImpl = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes("/oauth/token")) {
+        return Response.json({ code: 0, access_token: "revoked-user-token" });
+      }
+      if (url.includes("/user_info")) {
+        return Response.json({
+          code: 0,
+          data: { open_id: "ou_revoked_user", name: "Revoked User" },
+        });
+      }
+      throw new Error(`unexpected ${url}`);
+    });
+    const app = await buildApp(fetchImpl as unknown as typeof fetch);
+    try {
+      const start = await app.inject({ method: "GET", url: "/auth/feishu/test-default" });
+      const authorize = new URL(String(start.headers.location));
+      const state = authorize.searchParams.get("state");
+      expect(state).not.toBeNull();
+      const callback = await app.inject({
+        method: "GET",
+        url: `/auth/feishu/callback?code=ok&state=${encodeURIComponent(state!)}`,
+        headers: { cookie: cookiePair(start.headers["set-cookie"], OAUTH_STATE_COOKIE_NAME) },
+      });
+      expect(callback.statusCode).toBe(302);
+      await expect(prisma.organizationMembership.count({
+        where: { organizationId: DEFAULT_ORG_ID, userId: identity.userId, revokedAt: null },
+      })).resolves.toBe(0);
+      await expect(prisma.auditEntry.count({
+        where: { action: "organization_member.oauth_auto_joined", actorUserId: identity.userId },
+      })).resolves.toBe(0);
+    } finally {
+      await app.close();
+    }
+  });
+
   it("unknown org slug returns 404 for admin", async () => {
     await seedUser("u-admin", "ou_admin", "ADMIN");
     const app = await buildApp();

hub/test/integration/admin-explorer.test.ts

@@ -206,7 +206,12 @@ describe("admin explorer API", () => {
   it("blocks cross-org project access by id", async () => {
     const token = await seedAdmin();
     await prisma.organization.create({
-      data: { id: "org_other", slug: "other", name: "Other" },
+      data: {
+        id: "org_other",
+        slug: "other",
+        name: "Other",
+        agentRoles: { create: { roleId: "draft", label: "草稿", isDefault: true } },
+      },
     });
     await prisma.project.create({
       data: {
@@ -284,4 +289,59 @@ describe("admin explorer API", () => {
       });
     },
   );
+
+  it("rejects moving a folder below one of its descendants", async () => {
+    const parent = await prisma.folder.create({
+      data: { id: "folder-cycle-parent", organizationId: DEFAULT_ORG_ID, name: "Parent" },
+    });
+    const child = await prisma.folder.create({
+      data: { id: "folder-cycle-child", organizationId: DEFAULT_ORG_ID, parentId: parent.id, name: "Child" },
+    });
+
+    await expect(renameFolder(prisma, {
+      organizationId: DEFAULT_ORG_ID,
+      folderId: parent.id,
+      parentId: child.id,
+    })).rejects.toThrow("folder cannot be moved below its descendant");
+  });
+
+  it("keeps the system Inbox identity immutable", async () => {
+    const inbox = await prisma.folder.findFirstOrThrow({
+      where: { organizationId: DEFAULT_ORG_ID, kind: "SYSTEM_INBOX" },
+    });
+
+    await expect(renameFolder(prisma, {
+      organizationId: DEFAULT_ORG_ID,
+      folderId: inbox.id,
+      name: "课程",
+    })).rejects.toThrow("system Inbox cannot be renamed or moved");
+    await expect(renameFolder(prisma, {
+      organizationId: DEFAULT_ORG_ID,
+      folderId: inbox.id,
+      parentId: null,
+    })).rejects.toThrow("system Inbox cannot be renamed or moved");
+    await expect(archiveFolder(prisma, {
+      organizationId: DEFAULT_ORG_ID,
+      folderId: inbox.id,
+    })).rejects.toThrow("system Inbox cannot be archived");
+
+    await expect(prisma.folder.update({
+      where: { id: inbox.id },
+      data: { kind: "REGULAR" },
+    })).rejects.toThrow("system Inbox identity cannot be changed");
+    await expect(prisma.folder.update({
+      where: { id: inbox.id },
+      data: { id: `${inbox.id}-moved` },
+    })).rejects.toThrow("system Inbox identity cannot be changed");
+    await expect(prisma.folder.delete({ where: { id: inbox.id } }))
+      .rejects.toThrow("system Inbox cannot be deleted while its organization exists");
+    await expect(prisma.folder.create({
+      data: {
+        organizationId: DEFAULT_ORG_ID,
+        name: "Malformed",
+        kind: "SYSTEM_INBOX",
+        parentId: inbox.id,
+      },
+    })).rejects.toThrow("system Inbox must be an active root folder named Inbox");
+  });
 });

hub/test/integration/agent-configuration.test.ts

@@ -0,0 +1,127 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeEach, describe, expect, it } from "vitest";
+import { OrganizationAgentConfiguration } from "../../src/agent/configuration.js";
+import { DEFAULT_ORG_ID, prisma, resetDb, seedTestOrganization } from "./helpers.js";
+
+describe("Organization Agent configuration management", () => {
+  let root: string;
+  let configuration: OrganizationAgentConfiguration;
+
+  beforeEach(async () => {
+    await resetDb();
+    root = await mkdtemp(join(tmpdir(), "cph-agent-config-"));
+    configuration = new OrganizationAgentConfiguration(prisma, join(root, "store"));
+  });
+
+  afterAll(async () => {
+    await prisma.$disconnect();
+  });
+
+  it("installs versioned skills and selects them as part of a dynamic role bundle", async () => {
+    const typst = await makeSkill(root, "typst");
+    const outline = await makeSkill(root, "outline");
+    await configuration.installSkill({ organizationId: DEFAULT_ORG_ID, sourceDir: typst, version: "0.15.0" });
+    await configuration.installSkill({ organizationId: DEFAULT_ORG_ID, sourceDir: outline, version: "1" });
+    await configuration.upsertRole({
+      organizationId: DEFAULT_ORG_ID,
+      roleId: "draft",
+      label: "课程草稿",
+      defaultModel: "anthropic/claude-sonnet-5",
+      systemPrompt: "write carefully",
+      tools: ["read_file", "write_file", "cph_build"],
+      sortOrder: 10,
+    });
+    await prisma.project.create({
+      data: { id: "project-a", organizationId: DEFAULT_ORG_ID, name: "A", workspaceDir: "/tmp/a" },
+    });
+    await prisma.agentSession.create({
+      data: {
+        id: "session-old-role-config",
+        projectId: "project-a",
+        provider: "openrouter",
+        roleId: "draft",
+        model: "anthropic/claude-sonnet-5",
+        metadata: {},
+      },
+    });
+    await configuration.setRoleSkills({
+      organizationId: DEFAULT_ORG_ID,
+      roleId: "draft",
+      skillNames: ["outline", "typst"],
+    });
+
+    const role = await prisma.organizationAgentRole.findUniqueOrThrow({
+      where: { organizationId_roleId: { organizationId: DEFAULT_ORG_ID, roleId: "draft" } },
+      include: { skillBindings: { orderBy: { sortOrder: "asc" }, include: { skill: true } } },
+    });
+    expect(role).toMatchObject({ label: "课程草稿", systemPrompt: "write carefully" });
+    expect(role.tools).toEqual(["read_file", "write_file", "cph_build"]);
+    expect(role.skillBindings.map((binding) => binding.skill.name)).toEqual(["outline", "typst"]);
+    await expect(prisma.agentSession.findUniqueOrThrow({ where: { id: "session-old-role-config" } }))
+      .resolves.toMatchObject({
+        archivedAt: expect.any(Date),
+        metadata: expect.objectContaining({ userResumable: false }),
+      });
+  });
+
+  it("rejects unknown, disabled and cross-Organization skills", async () => {
+    await seedTestOrganization("org_other", "other");
+    const typst = await makeSkill(root, "typst");
+    await configuration.installSkill({ organizationId: "org_other", sourceDir: typst, version: "1" });
+    await configuration.upsertRole({
+      organizationId: DEFAULT_ORG_ID,
+      roleId: "draft",
+      label: "Draft",
+      tools: [],
+    });
+
+    await expect(configuration.setRoleSkills({
+      organizationId: DEFAULT_ORG_ID,
+      roleId: "draft",
+      skillNames: ["typst"],
+    })).rejects.toThrow("active skills not found in organization");
+  });
+
+  it("switches the Organization default role atomically", async () => {
+    await configuration.upsertRole({
+      organizationId: DEFAULT_ORG_ID,
+      roleId: "review",
+      label: "审校",
+      tools: ["read_file"],
+      isDefault: true,
+    });
+
+    await expect(prisma.organizationAgentRole.findMany({
+      where: { organizationId: DEFAULT_ORG_ID, isDefault: true, disabledAt: null },
+      select: { roleId: true },
+    })).resolves.toEqual([{ roleId: "review" }]);
+    await expect(configuration.upsertRole({
+      organizationId: DEFAULT_ORG_ID,
+      roleId: "review",
+      label: "审校",
+      isDefault: false,
+    })).rejects.toThrow("cannot unset the active default role without selecting a replacement");
+  });
+
+  it("rejects a zero-default committed state at the database boundary", async () => {
+    await expect(prisma.organizationAgentRole.updateMany({
+      where: { organizationId: DEFAULT_ORG_ID, isDefault: true, disabledAt: null },
+      data: { isDefault: false },
+    })).rejects.toThrow("must have exactly one active default Agent role");
+  });
+
+  it("rejects creating an Organization without its default role in the same transaction", async () => {
+    await expect(prisma.organization.create({
+      data: { id: "org_without_role", slug: "without-role", name: "Without Role" },
+    })).rejects.toThrow("must have exactly one active default Agent role");
+  });
+
+  async function makeSkill(parent: string, name: string): Promise<string> {
+    const source = join(parent, "sources", name);
+    await mkdir(source, { recursive: true });
+    await writeFile(join(source, "SKILL.md"), `---\nname: ${name}\ndescription: ${name} skill\n---\n# ${name}\n`);
+    return source;
+  }
+});

hub/test/integration/agent-runtime-config.test.ts

@@ -0,0 +1,117 @@
+import { afterAll, beforeEach, describe, expect, it } from "vitest";
+import { DatabaseRuntimeSettings } from "../../src/settings/runtime.js";
+import { DEFAULT_ORG_ID, prisma, resetDb, seedTestOrganization, testSecretEnvelope } from "./helpers.js";
+
+describe("Organization-scoped Agent runtime configuration", () => {
+  beforeEach(async () => {
+    await resetDb();
+  });
+
+  afterAll(async () => {
+    await prisma.$disconnect();
+  });
+
+  it("resolves role prompt, model, tools and skills from the project Organization", async () => {
+    await seedTestOrganization("org_other", "other");
+    await Promise.all([
+      prisma.project.create({
+        data: { id: "project-a", organizationId: DEFAULT_ORG_ID, name: "A", workspaceDir: "/tmp/a" },
+      }),
+      prisma.project.create({
+        data: { id: "project-b", organizationId: "org_other", name: "B", workspaceDir: "/tmp/b" },
+      }),
+    ]);
+    const [skillA, skillB] = await Promise.all([
+      prisma.organizationAgentSkill.create({
+        data: {
+          id: "skill-a",
+          organizationId: DEFAULT_ORG_ID,
+          name: "typst",
+          version: "0.15.0",
+          contentDigest: "a".repeat(64),
+        },
+      }),
+      prisma.organizationAgentSkill.create({
+        data: {
+          id: "skill-b",
+          organizationId: "org_other",
+          name: "typst",
+          version: "other",
+          contentDigest: "b".repeat(64),
+        },
+      }),
+    ]);
+    const [roleA, roleB] = await Promise.all([
+      prisma.organizationAgentRole.update({
+        where: { organizationId_roleId: { organizationId: DEFAULT_ORG_ID, roleId: "draft" } },
+        data: {
+          label: "A Draft",
+          defaultModel: "anthropic/claude-sonnet-5",
+          systemPrompt: "prompt-a",
+          tools: ["read_file", "cph_build"],
+        },
+      }),
+      prisma.organizationAgentRole.update({
+        where: { organizationId_roleId: { organizationId: "org_other", roleId: "draft" } },
+        data: {
+          label: "B Draft",
+          systemPrompt: "prompt-b",
+          tools: [],
+        },
+      }),
+    ]);
+    await Promise.all([
+      prisma.organizationAgentRoleSkill.create({
+        data: { organizationId: DEFAULT_ORG_ID, agentRoleId: roleA.id, agentSkillId: skillA.id },
+      }),
+      prisma.organizationAgentRoleSkill.create({
+        data: { organizationId: "org_other", agentRoleId: roleB.id, agentSkillId: skillB.id },
+      }),
+    ]);
+    const settings = new DatabaseRuntimeSettings(prisma, testSecretEnvelope, {});
+
+    const registryA = await settings.modelRegistry({ projectId: "project-a" });
+    const registryB = await settings.modelRegistry({ projectId: "project-b" });
+
+    expect(registryA.role("draft")).toMatchObject({
+      label: "A Draft",
+      systemPrompt: "prompt-a",
+      tools: ["read_file", "cph_build"],
+      skills: [{ name: "typst", version: "0.15.0", contentDigest: "a".repeat(64) }],
+    });
+    expect(registryB.role("draft")).toMatchObject({
+      label: "B Draft",
+      systemPrompt: "prompt-b",
+      tools: [],
+      skills: [{ name: "typst", version: "other", contentDigest: "b".repeat(64) }],
+    });
+  });
+
+  it("fails closed for missing scope and disabled role skills", async () => {
+    await prisma.project.create({
+      data: { id: "project-a", organizationId: DEFAULT_ORG_ID, name: "A", workspaceDir: "/tmp/a" },
+    });
+    const skill = await prisma.organizationAgentSkill.create({
+      data: {
+        id: "skill-disabled",
+        organizationId: DEFAULT_ORG_ID,
+        name: "typst",
+        version: "0.15.0",
+        contentDigest: "c".repeat(64),
+        disabledAt: new Date(),
+      },
+    });
+    const role = await prisma.organizationAgentRole.findUniqueOrThrow({
+      where: { organizationId_roleId: { organizationId: DEFAULT_ORG_ID, roleId: "draft" } },
+    });
+    await prisma.organizationAgentRoleSkill.create({
+      data: { organizationId: DEFAULT_ORG_ID, agentRoleId: role.id, agentSkillId: skill.id },
+    });
+    const settings = new DatabaseRuntimeSettings(prisma, testSecretEnvelope, {});
+
+    await expect(settings.modelRegistry()).rejects.toThrow("projectId is required");
+    await expect(settings.modelRegistry({ projectId: "project-a" })).rejects.toThrow(
+      "role draft selects disabled skill typst",
+    );
+  });
+});

hub/test/integration/agent-sandbox-linux.test.ts

@@ -7,6 +7,7 @@ import { join } from "node:path";
 import { promisify } from "node:util";
 import { afterEach, describe, expect, it } from "vitest";
 import { runAgent, type StreamEvent } from "../../src/agent/runner.js";
+import { importSkillDirectory } from "../../src/agent/skillStore.js";
 
 const execFileAsync = promisify(execFile);
 const originalEnv = new Map<string, string | undefined>();
@@ -36,23 +37,25 @@ describe("real Claude SDK sandbox boundary", () => {
     const cphBin = cphPathOutput.trim();
     await access(cphBin, constants.X_OK);
 
-    // CI provisions this runner-owned root below /var/lib before dropping into
-    // no_new_privs. Keeping the fixture out of /tmp proves that an SDK-wide
-    // temp exception cannot make a cross-project escape look contained.
+    // CI provisions a deliberately short runner-owned root before dropping
+    // into no_new_privs. Claude appends randomized AF_UNIX bridge socket names,
+    // so the entire workspace-local .cph/t prefix must stay within its budget.
     const configuredTestRoot = process.env["CPH_SANDBOX_TEST_ROOT"]?.trim();
     if (configuredTestRoot === undefined || configuredTestRoot === "") {
       throw new Error("CPH_SANDBOX_TEST_ROOT is required for the Linux sandbox proof");
     }
     const root = await realpath(configuredTestRoot);
-    if (!root.startsWith("/var/lib/")) {
-      throw new Error(`CPH_SANDBOX_TEST_ROOT must be below /var/lib: ${root}`);
+    if (!root.startsWith("/") || Buffer.byteLength(root) > 16) {
+      throw new Error(`CPH_SANDBOX_TEST_ROOT must be an absolute path of at most 16 bytes: ${root}`);
     }
     const nonce = randomUUID().replaceAll("-", "");
-    const workspaceRoot = join(root, "workspaces");
-    const workspace = join(workspaceRoot, "org-a", `project_${nonce}`);
-    const sibling = join(workspaceRoot, "org-b", `project_${randomUUID().replaceAll("-", "")}`);
-    const serviceSecret = join(root, `service-secret-${nonce}`);
-    roots.push(workspace, sibling, serviceSecret);
+    const workspaceRoot = join(root, "w");
+    const workspace = join(workspaceRoot, "a", `p_${nonce.slice(0, 8)}`);
+    const sibling = join(workspaceRoot, "b", `p_${nonce.slice(8, 16)}`);
+    const serviceSecret = join(root, `s_${nonce.slice(16, 24)}`);
+    const skillSource = join(root, `k_${nonce.slice(24, 28)}`);
+    const skillStore = join(root, `ks_${nonce.slice(28, 32)}`);
+    roots.push(workspace, sibling, serviceSecret, skillSource, skillStore);
     await Promise.all([
       mkdir(workspace, { recursive: true }),
       mkdir(sibling, { recursive: true }),
@@ -62,6 +65,12 @@ describe("real Claude SDK sandbox boundary", () => {
       writeFile(join(sibling, "secret.txt"), "sibling-secret\n"),
       writeFile(serviceSecret, "platform-secret\n"),
     ]);
+    await mkdir(skillSource, { recursive: true });
+    await writeFile(join(skillSource, "SKILL.md"), "---\nname: outline\ndescription: Outline\n---\n");
+    const installedSkill = await importSkillDirectory({ sourceDir: skillSource, storeRoot: skillStore });
+    const untrustedSkill = join(workspace, ".claude", "skills", "untrusted");
+    await mkdir(untrustedSkill, { recursive: true });
+    await writeFile(join(untrustedSkill, "SKILL.md"), "---\nname: untrusted\ndescription: must never load\n---\n");
     // macOS tmpdir is reached through /var -> /private/var. Exercise the
     // sandbox with canonical paths, matching the canonical cwd returned by
     // createAgentSecurityPolicy rather than relying on a host symlink alias.
@@ -70,8 +79,7 @@ describe("real Claude SDK sandbox boundary", () => {
     const canonicalServiceSecret = await realpath(serviceSecret);
     const resultPath = join(canonicalWorkspace, "sandbox-result.txt");
     const cphVersionPath = join(canonicalWorkspace, "cph-version.txt");
-    const effectiveTempProbePath = join(canonicalWorkspace, ".cph", "t", "effective-temp.txt");
-    const denialLogPath = join(canonicalWorkspace, ".cph", "t", "denials.log");
+    const denialLogPath = join(canonicalWorkspace, ".cph", "denials.log");
     const siblingEscapePath = join(canonicalSibling, "escape.txt");
     const unsandboxedEscapePath = join(root, `unsandboxed-escape-${nonce}`);
     const hostTmpEscapePath = `/tmp/cph-host-temp-${nonce}`;
@@ -84,25 +92,26 @@ describe("real Claude SDK sandbox boundary", () => {
       DATABASE_URL: "postgresql://platform-secret",
       FEISHU_APP_SECRET: "feishu-secret",
       HUB_SESSION_SECRET: "session-secret",
+      HUB_SKILL_STORE_ROOT: skillStore,
     });
 
     const bashCommand = [
       "set -eu",
-      `if printf 'unsafe\\n' > ${shellQuote(unsandboxedEscapePath)} 2>> ${shellQuote(denialLogPath)}; then exit 31; fi`,
+      `printf 'ephemeral\\n' > ${shellQuote(unsandboxedEscapePath)}`,
       `test "$(cat ${shellQuote(join(canonicalWorkspace, "allowed.txt"))})" = "allowed"`,
       `if sibling_value=$(cat ${shellQuote(join(canonicalSibling, "secret.txt"))} 2>> ${shellQuote(denialLogPath)}); then exit 21; fi`,
-      `if printf 'escape\\n' > ${shellQuote(siblingEscapePath)} 2>> ${shellQuote(denialLogPath)}; then exit 32; fi`,
+      `printf 'ephemeral\\n' > ${shellQuote(siblingEscapePath)}`,
       `if service_value=$(cat ${shellQuote(canonicalServiceSecret)} 2>> ${shellQuote(denialLogPath)}); then exit 23; fi`,
       `mkdir ${shellQuote(join(canonicalWorkspace, "subdir"))}`,
       `cd ${shellQuote(join(canonicalWorkspace, "subdir"))}`,
-      `test "\${TMPDIR-unset}" = ${shellQuote(join(canonicalWorkspace, ".cph", "t"))}`,
-      `test "\${TMP-unset}" = ${shellQuote(join(canonicalWorkspace, ".cph", "t"))}`,
-      `test "\${TEMP-unset}" = ${shellQuote(join(canonicalWorkspace, ".cph", "t"))}`,
-      'test "${CLAUDE_CODE_TMPDIR-unset}" = ".cph/t"',
-      `test "$(realpath "$TMPDIR")" = ${shellQuote(join(canonicalWorkspace, ".cph", "t"))}`,
-      `printf 'workspace-temp\\n' > "$TMPDIR/effective-temp.txt"`,
-      `if printf 'host-temp\\n' > ${shellQuote(hostTmpEscapePath)} 2>> ${shellQuote(denialLogPath)}; then exit 33; fi`,
-      `if printf 'host-var-temp\\n' > ${shellQuote(hostVarTmpEscapePath)} 2>> ${shellQuote(denialLogPath)}; then exit 34; fi`,
+      'test "${TMPDIR-unset}" = "${TMP-unset}"',
+      'test "${TMPDIR-unset}" = "${TEMP-unset}"',
+      'test "${TMPDIR-unset}" = "${CLAUDE_CODE_TMPDIR-unset}"',
+      'test "${#TMPDIR}" -le 56',
+      `case "$TMPDIR" in ${shellQuote(canonicalWorkspace)}/*) :;; *) exit 35;; esac`,
+      `printf 'sdk-temp\\n' > "$TMPDIR/effective-temp.txt"`,
+      `printf 'ephemeral\\n' > ${shellQuote(hostTmpEscapePath)}`,
+      `printf 'ephemeral\\n' > ${shellQuote(hostVarTmpEscapePath)}`,
       'test "${DATABASE_URL-unset}" = unset',
       'test "${FEISHU_APP_SECRET-unset}" = unset',
       'test "${HUB_SESSION_SECRET-unset}" = unset',
@@ -131,6 +140,7 @@ describe("real Claude SDK sandbox boundary", () => {
           ANTHROPIC_API_KEY: "",
         },
         tools: ["bash"],
+        skills: [{ name: "outline", version: "1", contentDigest: installedSkill.contentDigest }],
         maxTurns: 3,
         runId: "sandbox-run",
         sessionId: "sandbox-session",
@@ -146,10 +156,18 @@ describe("real Claude SDK sandbox boundary", () => {
         result.status,
         [result.error, sdkStderr.join(""), JSON.stringify(streamEvents)].filter(Boolean).join("\n"),
       ).toBe("completed");
-      expect(stub.requestCount()).toBeGreaterThanOrEqual(2);
+      expect(stub.requestCount()).toBeGreaterThanOrEqual(3);
+      expect(new Set(result.initializedSkillIds)).toEqual(new Set([
+        "cph-runtime:outline",
+      ]));
       const toolResults = streamEvents.filter((event) => event.type === "tool-result");
-      expect(toolResults).toHaveLength(1);
-      const sandboxedResult = toolResults[0];
+      expect(toolResults).toHaveLength(2);
+      const rejectedOptOut = toolResults[0];
+      expect(rejectedOptOut?.type).toBe("tool-result");
+      if (rejectedOptOut?.type !== "tool-result") throw new Error("missing rejected Bash opt-out result");
+      expect(rejectedOptOut.isError).toBe(true);
+      expect(rejectedOptOut.result).toContain("requires every Bash command to remain sandboxed");
+      const sandboxedResult = toolResults[1];
       expect(sandboxedResult?.type).toBe("tool-result");
       if (sandboxedResult?.type !== "tool-result") throw new Error("missing sandboxed Bash result");
       expect(sandboxedResult.isError, `${sandboxedResult.result}\n${sdkStderr.join("")}`).toBe(false);
@@ -159,7 +177,6 @@ describe("real Claude SDK sandbox boundary", () => {
       });
       expect(resultContents).toBe("sandbox-ok\n");
       await expect(readFile(cphVersionPath, "utf8")).resolves.toMatch(/^cph /);
-      await expect(readFile(effectiveTempProbePath, "utf8")).resolves.toBe("workspace-temp\n");
       const denialLog = await readFile(denialLogPath, "utf8");
       expect(denialLog).not.toContain("sibling-secret");
       expect(denialLog).not.toContain("platform-secret");
@@ -198,10 +215,12 @@ async function startAnthropicStub(bashCommand: string): Promise<{
       };
       requests++;
       const events = requests === 1
-        // Deliberately request the SDK's bypass flag. Production sets
-        // allowUnsandboxedCommands=false, so the flag must be ignored and the
-        // host-side escape sentinels must remain absent.
+        // The host hook must reject the SDK's per-call sandbox bypass before
+        // any command starts. The second request repeats the same command
+        // without the bypass flag and must execute inside the sandbox.
         ? bashToolEvents(bashCommand, requests, true)
+        : requests === 2
+          ? bashToolEvents(bashCommand, requests, false)
           : finalTextEvents(requests);
       writeAnthropicStream(response, events);
     } catch (error) {

hub/test/integration/feishu-binding-lifecycle.test.ts

@@ -0,0 +1,181 @@
+import { afterAll, beforeEach, describe, expect, it } from "vitest";
+import { archiveFeishuBindingForLifecycleEvent } from "../../src/feishu/bindingLifecycle.js";
+import { scopedFeishuPrincipalId } from "../../src/feishu/identityNamespace.js";
+import { DEFAULT_ORG_ID, prisma, resetDb, seedProject } from "./helpers.js";
+
+const CONNECTION_ID = "feishu-connection-lifecycle";
+
+describe("Feishu binding lifecycle events", () => {
+  beforeEach(async () => {
+    await resetDb();
+  });
+
+  afterAll(async () => prisma.$disconnect());
+
+  it("archives a bound project and revokes its chat grant when the chat is dissolved", async () => {
+    await seedProject("project-dissolved", "chat-dissolved");
+    await seedFeishuConnection();
+    await prisma.permissionGrant.create({
+      data: {
+        resourceType: "PROJECT",
+        resourceId: "project-dissolved",
+        principalType: "FEISHU_CHAT",
+        principalId: scopedFeishuPrincipalId("CHAT", CONNECTION_ID, "chat-dissolved"),
+        role: "EDIT",
+      },
+    });
+    await prisma.permissionGrant.create({
+      data: {
+        resourceType: "PROJECT",
+        resourceId: "project-dissolved",
+        principalType: "FEISHU_CHAT",
+        principalId: "chat-dissolved",
+        role: "EDIT",
+      },
+    });
+    await prisma.permissionGrant.create({
+      data: {
+        resourceType: "PROJECT",
+        resourceId: "project-dissolved",
+        principalType: "FEISHU_CHAT",
+        principalId: scopedFeishuPrincipalId("CHAT", CONNECTION_ID, "chat-unrelated"),
+        role: "EDIT",
+      },
+    });
+
+    await expect(archiveFeishuBindingForLifecycleEvent(prisma, {
+      chatId: "chat-dissolved",
+      eventId: "event-dissolved",
+      reason: "chat_dissolved",
+    })).resolves.toEqual({ archived: true, projectId: "project-dissolved" });
+
+    await expect(prisma.projectGroupBinding.findFirst({
+      where: { chatId: "chat-dissolved" },
+      select: { archivedAt: true },
+    })).resolves.toMatchObject({ archivedAt: expect.any(Date) });
+    await expect(prisma.permissionGrant.findFirst({
+      where: {
+        resourceId: "project-dissolved",
+        principalId: scopedFeishuPrincipalId("CHAT", CONNECTION_ID, "chat-dissolved"),
+      },
+      select: { revokedAt: true },
+    })).resolves.toMatchObject({ revokedAt: expect.any(Date) });
+    await expect(prisma.permissionGrant.findFirst({
+      where: { resourceId: "project-dissolved", principalId: "chat-dissolved" },
+      select: { revokedAt: true },
+    })).resolves.toMatchObject({ revokedAt: expect.any(Date) });
+    await expect(prisma.permissionGrant.findFirst({
+      where: {
+        resourceId: "project-dissolved",
+        principalId: scopedFeishuPrincipalId("CHAT", CONNECTION_ID, "chat-unrelated"),
+      },
+      select: { revokedAt: true },
+    })).resolves.toEqual({ revokedAt: null });
+    await expect(prisma.auditEntry.findFirst({
+      where: { projectId: "project-dissolved", action: "project.chat_binding_archived" },
+      select: { organizationId: true, metadata: true },
+    })).resolves.toEqual({
+      organizationId: DEFAULT_ORG_ID,
+      metadata: { chatId: "chat-dissolved", eventId: "event-dissolved", reason: "chat_dissolved" },
+    });
+  });
+
+  it("is idempotent when Feishu redelivers a lifecycle event", async () => {
+    await seedProject("project-redelivery", "chat-redelivery");
+    await seedFeishuConnection();
+
+    await archiveFeishuBindingForLifecycleEvent(prisma, {
+      chatId: "chat-redelivery",
+      eventId: "event-redelivery",
+      reason: "bot_removed",
+    });
+    await expect(archiveFeishuBindingForLifecycleEvent(prisma, {
+      chatId: "chat-redelivery",
+      eventId: "event-redelivery",
+      reason: "bot_removed",
+    })).resolves.toEqual({ archived: false });
+
+    await expect(prisma.auditEntry.count({
+      where: { projectId: "project-redelivery", action: "project.chat_binding_archived" },
+    })).resolves.toBe(1);
+  });
+
+  it("does not archive a later binding when an old lifecycle event is redelivered", async () => {
+    await seedProject("project-original", "chat-rebound");
+    await prisma.project.create({
+      data: {
+        id: "project-rebound",
+        organizationId: DEFAULT_ORG_ID,
+        name: "Rebound project",
+        workspaceDir: "/tmp/test-project-rebound",
+      },
+    });
+    await seedFeishuConnection();
+
+    await archiveFeishuBindingForLifecycleEvent(prisma, {
+      chatId: "chat-rebound",
+      eventId: "event-before-rebind",
+      reason: "bot_removed",
+    });
+    await prisma.projectGroupBinding.create({
+      data: {
+        organizationId: DEFAULT_ORG_ID,
+        projectId: "project-rebound",
+        chatId: "chat-rebound",
+        selectedAgentRoleId: `agent_role_draft_${DEFAULT_ORG_ID}`,
+      },
+    });
+
+    await expect(archiveFeishuBindingForLifecycleEvent(prisma, {
+      chatId: "chat-rebound",
+      eventId: "event-before-rebind",
+      reason: "bot_removed",
+    })).resolves.toEqual({ archived: false });
+    await expect(prisma.projectGroupBinding.findFirst({
+      where: { projectId: "project-rebound", archivedAt: null },
+      select: { id: true },
+    })).resolves.not.toBeNull();
+  });
+
+  it("leaves unrelated active bindings untouched", async () => {
+    await seedProject("project-kept", "chat-kept");
+
+    await expect(archiveFeishuBindingForLifecycleEvent(prisma, {
+      chatId: "chat-unknown",
+      eventId: "event-unknown",
+      reason: "chat_dissolved",
+    })).resolves.toEqual({ archived: false });
+
+    await expect(prisma.projectGroupBinding.findFirst({
+      where: { chatId: "chat-kept", archivedAt: null },
+      select: { id: true },
+    })).resolves.not.toBeNull();
+  });
+});
+
+async function seedFeishuConnection(): Promise<void> {
+  await prisma.organizationFeishuApplicationConnection.create({
+    data: {
+      id: CONNECTION_ID,
+      organizationId: DEFAULT_ORG_ID,
+      appIdentityFingerprint: "fingerprint-lifecycle",
+    },
+  });
+  await prisma.feishuApplicationCredentialVersion.create({
+    data: {
+      id: "feishu-secret-version-lifecycle",
+      connectionId: CONNECTION_ID,
+      version: 1,
+      keyId: "test-active",
+      envelope: { fixture: true },
+    },
+  });
+  await prisma.organizationFeishuApplicationConnection.update({
+    where: { id: CONNECTION_ID },
+    data: {
+      status: "ACTIVE",
+      activeSecretVersionId: "feishu-secret-version-lifecycle",
+      activatedAt: new Date(),
+    },
+  });
+}

hub/test/integration/helpers.ts

@@ -34,38 +34,20 @@ export const prisma = new PrismaClient({
 
 /** Truncate all tables before each test for isolation. */
 export async function resetDb(): Promise<void> {
-  const tables = [
-    "FeishuEventReceipt",
-    "FeishuUserIdentity",
-    "FeishuApplicationCredentialVersion",
-    "OrganizationFeishuApplicationConnection",
-    "ProviderCredentialVersion",
-    "OrganizationProviderConnection",
-    "AgentFileChange",
-    "AgentMessage",
-    "AuditEntry",
-    "PermissionSettings",
-    "PermissionGrant",
-    "RoleTriggerGrant",
-    "ExternalPrincipalMembership",
-    "ExternalDirectoryConnection",
-    "TeamExternalBinding",
-    "TeamMembership",
-    "Team",
-    "ProjectAgentLock",
-    "AgentRun",
-    "AgentSession",
-    "ProjectGroupBinding",
-    "Folder",
-    "OrganizationProjectSettings",
-    "OrganizationMembership",
-    "PlatformRoleAssignment",
-    "User",
-    "Project",
-    "Organization",
-  ];
-  // Truncate with CASCADE to wipe dependent rows in one shot.
-  await prisma.$executeRawUnsafe(`TRUNCATE TABLE ${tables.map((t) => `"${t}"`).join(", ")} RESTART IDENTITY CASCADE`);
+  // User and Organization are the aggregate roots for all domain rows; their
+  // declared FK cascades clear projects, search documents, permissions,
+  // sessions and connections without repeatedly truncating pg_trgm indexes.
+  // Event receipts and global audit rows are independent roots.
+  await prisma.$transaction([
+    prisma.feishuEventReceipt.deleteMany(),
+    prisma.auditEntry.deleteMany(),
+    // Permission resource ids are intentionally polymorphic strings, so these
+    // two tables have no FK to Project and must be cleared explicitly.
+    prisma.permissionGrant.deleteMany(),
+    prisma.permissionSettings.deleteMany(),
+    prisma.user.deleteMany(),
+    prisma.organization.deleteMany(),
+  ]);
   await seedTestOrganization();
 }
 
@@ -73,22 +55,36 @@ export async function seedTestOrganization(
   id: string = DEFAULT_ORG_ID,
   slug: string = "test-default",
 ): Promise<void> {
-  await prisma.organization.upsert({
+  await prisma.$transaction(async (tx) => {
+    await tx.organization.upsert({
       where: { id },
       update: {},
-    create: {
-      id,
-      slug,
-      name: "Test Default Organization",
-    },
+      create: { id, slug, name: "Test Default Organization" },
     });
-  await prisma.organizationProjectSettings.upsert({
+    await tx.organizationProjectSettings.upsert({
       where: { organizationId: id },
       update: {},
       create: { organizationId: id, membersCanCreateProjects: true },
     });
+    const defaultRole = await tx.organizationAgentRole.upsert({
+      where: { organizationId_roleId: { organizationId: id, roleId: "draft" } },
+      update: { label: "草稿", isDefault: true, disabledAt: null },
+      create: {
+        id: `agent_role_draft_${id}`,
+        organizationId: id,
+        roleId: "draft",
+        label: "草稿",
+        sortOrder: 10,
+        isDefault: true,
+      },
+    });
+    await tx.organizationAgentRole.updateMany({
+      where: { organizationId: id, id: { not: defaultRole.id }, isDefault: true },
+      data: { isDefault: false },
+    });
+  });
   const inbox = await prisma.folder.findFirst({
-    where: { organizationId: id, parentId: null, name: "Inbox", archivedAt: null },
+    where: { organizationId: id, kind: "SYSTEM_INBOX", archivedAt: null },
     select: { id: true },
   });
   if (inbox === null) {
@@ -97,6 +93,7 @@ export async function seedTestOrganization(
         id: `folder_inbox_${id}`,
         organizationId: id,
         name: "Inbox",
+        kind: "SYSTEM_INBOX",
         sortKey: "000000",
       },
     });
@@ -417,6 +414,12 @@ export async function seedProject(
     },
   });
   await prisma.projectGroupBinding.create({
-    data: { projectId, chatId, createdByUserId: "u_" + projectId },
+    data: {
+      organizationId: DEFAULT_ORG_ID,
+      projectId,
+      chatId,
+      createdByUserId: "u_" + projectId,
+      selectedAgentRoleId: `agent_role_draft_${DEFAULT_ORG_ID}`,
+    },
   });
 }

hub/test/integration/legacy-project-import.test.ts

@@ -0,0 +1,185 @@
+import { mkdir, mkdtemp, readFile, rm, symlink, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeEach, describe, expect, it } from "vitest";
+import { importLegacyProjects } from "../../src/deployment/legacyProjectImport.js";
+import { DEFAULT_ORG_ID, prisma, resetDb } from "./helpers.js";
+
+const temporaryRoots: string[] = [];
+
+describe("legacy teaching-material project import", () => {
+  beforeEach(async () => {
+    await resetDb();
+    await prisma.user.create({
+      data: {
+        id: "legacy-import-owner",
+        feishuOpenId: "ou_legacy_owner",
+        displayName: "Legacy Import Owner",
+        organizationMemberships: { create: { organizationId: DEFAULT_ORG_ID, role: "OWNER" } },
+      },
+    });
+  });
+
+  afterEach(async () => {
+    while (temporaryRoots.length > 0) {
+      const root = temporaryRoots.pop();
+      if (root !== undefined) await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  afterAll(async () => prisma.$disconnect());
+
+  it("imports each legacy project as an unbound resumable project under its old folder path", async () => {
+    const sourceRoot = await temporaryRoot("cph-legacy-source-");
+    const workspaceRoot = await temporaryRoot("cph-legacy-target-");
+    const projectSource = join(sourceRoot, "物理", "M-243-牛顿力学");
+    await mkdir(join(projectSource, "workspace", "chapters"), { recursive: true });
+    await mkdir(join(projectSource, "workspace", ".claude"), { recursive: true });
+    await mkdir(join(projectSource, "workspace", "chapters", ".cph"), { recursive: true });
+    await mkdir(join(projectSource, "_raw"), { recursive: true });
+    await writeFile(join(projectSource, "workspace", "project.toml"), "title = \"牛顿力学\"\n");
+    await writeFile(join(projectSource, "workspace", "chapters", "lesson.typ"), "= 牛顿第二定律\n");
+    await writeFile(join(projectSource, "workspace", ".claude", "session.json"), "{}\n");
+    await writeFile(join(projectSource, "workspace", "chapters", ".cph", "runtime.json"), "{}\n");
+    await writeFile(join(projectSource, "project.json"), "{\"id\":\"M-243\"}\n");
+    await writeFile(join(projectSource, "_raw", "source.txt"), "legacy source\n");
+    const stateFile = join(workspaceRoot, "migration-state", "state.json");
+    const manifest = [{
+      legacyId: "M-243",
+      name: "牛顿力学",
+      folderPath: ["物理"],
+      sourceRelativePath: "物理/M-243-牛顿力学",
+    }];
+
+    const first = await importLegacyProjects({
+      prisma,
+      organizationId: DEFAULT_ORG_ID,
+      actorFeishuOpenId: "ou_legacy_owner",
+      workspaceRoot,
+      sourceRoot,
+      stateFile,
+      projects: manifest,
+    });
+    const imported = first.projects["M-243"];
+    expect(imported).toBeDefined();
+    if (imported === undefined) throw new Error("missing imported project state");
+
+    const project = await prisma.project.findUniqueOrThrow({
+      where: { id: imported.projectId },
+      include: { folder: { include: { parent: true } }, groupBindings: true },
+    });
+    expect(project.name).toBe("牛顿力学");
+    expect(project.folder?.name).toBe("物理");
+    expect(project.folder?.parent?.name).toBe("旧教学资产");
+    expect(project.groupBindings).toEqual([]);
+    await expect(readFile(join(imported.workspaceDir, "chapters", "lesson.typ"), "utf8"))
+      .resolves.toBe("= 牛顿第二定律\n");
+    await expect(readFile(join(imported.workspaceDir, ".claude", "session.json"), "utf8"))
+      .rejects.toMatchObject({ code: "ENOENT" });
+    await expect(readFile(join(imported.workspaceDir, "chapters", ".cph", "runtime.json"), "utf8"))
+      .rejects.toMatchObject({ code: "ENOENT" });
+    await expect(readFile(join(imported.workspaceDir, ".legacy-source", "project.json"), "utf8"))
+      .resolves.toContain("M-243");
+    await expect(readFile(join(imported.workspaceDir, ".legacy-source", "raw", "source.txt"), "utf8"))
+      .resolves.toBe("legacy source\n");
+
+    await unlink(stateFile);
+    const second = await importLegacyProjects({
+      prisma,
+      organizationId: DEFAULT_ORG_ID,
+      actorFeishuOpenId: "ou_legacy_owner",
+      workspaceRoot,
+      sourceRoot,
+      stateFile,
+      projects: manifest,
+    });
+    expect(second.projects["M-243"]?.projectId).toBe(imported.projectId);
+    await expect(prisma.project.count({ where: { organizationId: DEFAULT_ORG_ID } })).resolves.toBe(1);
+    expect(JSON.parse(await readFile(stateFile, "utf8"))).toMatchObject({
+      version: 1,
+      projects: { "M-243": { projectId: imported.projectId } },
+    });
+    await expect(prisma.auditEntry.count({
+      where: { projectId: imported.projectId, action: "legacy_project.imported" },
+    })).resolves.toBe(1);
+
+    await writeFile(join(imported.workspaceDir, ".legacy-source", "migration.json"), "not json\n");
+    await expect(importLegacyProjects({
+      prisma,
+      organizationId: DEFAULT_ORG_ID,
+      actorFeishuOpenId: "ou_legacy_owner",
+      workspaceRoot,
+      sourceRoot,
+      stateFile,
+      projects: manifest,
+    })).rejects.toThrow(/invalid legacy completion marker/);
+    await expect(prisma.project.count({ where: { id: imported.projectId } })).resolves.toBe(1);
+  });
+
+  it("rejects symlinks instead of importing paths outside the staged project", async () => {
+    const sourceRoot = await temporaryRoot("cph-legacy-symlink-");
+    const workspaceRoot = await temporaryRoot("cph-legacy-target-");
+    const projectSource = join(sourceRoot, "legacy");
+    await mkdir(join(projectSource, "workspace"), { recursive: true });
+    await writeFile(join(projectSource, "project.json"), "{}\n");
+    await symlink("/etc/passwd", join(projectSource, "workspace", "outside"));
+
+    await expect(importLegacyProjects({
+      prisma,
+      organizationId: DEFAULT_ORG_ID,
+      actorFeishuOpenId: "ou_legacy_owner",
+      workspaceRoot,
+      sourceRoot,
+      stateFile: join(workspaceRoot, "state.json"),
+      projects: [{ legacyId: "symlink", name: "Symlink", folderPath: [], sourceRelativePath: "legacy" }],
+    })).rejects.toThrow(/rejects symbolic link/);
+    await expect(prisma.project.count()).resolves.toBe(0);
+  });
+
+  it("rejects a manifest path that escapes the staged source root", async () => {
+    const parent = await temporaryRoot("cph-legacy-escape-");
+    const sourceRoot = join(parent, "source");
+    const outside = join(parent, "outside");
+    await mkdir(sourceRoot);
+    await mkdir(outside);
+
+    await expect(importLegacyProjects({
+      prisma,
+      organizationId: DEFAULT_ORG_ID,
+      actorFeishuOpenId: "ou_legacy_owner",
+      workspaceRoot: await temporaryRoot("cph-legacy-target-"),
+      sourceRoot,
+      stateFile: join(parent, "state.json"),
+      projects: [{
+        legacyId: "escape",
+        name: "Escape",
+        folderPath: [],
+        sourceRelativePath: "../outside",
+      }],
+    })).rejects.toThrow(/escapes source root/);
+  });
+
+  it("rejects malformed resume state before creating a project", async () => {
+    const sourceRoot = await temporaryRoot("cph-legacy-state-source-");
+    const workspaceRoot = await temporaryRoot("cph-legacy-state-target-");
+    const stateFile = join(workspaceRoot, "state.json");
+    await writeFile(stateFile, JSON.stringify({ version: 1, projects: { broken: { status: "MAYBE" } } }));
+
+    await expect(importLegacyProjects({
+      prisma,
+      organizationId: DEFAULT_ORG_ID,
+      actorFeishuOpenId: "ou_legacy_owner",
+      workspaceRoot,
+      sourceRoot,
+      stateFile,
+      projects: [],
+    })).rejects.toThrow(/invalid legacy import state fields/);
+    await expect(prisma.project.count()).resolves.toBe(0);
+  });
+});
+
+async function temporaryRoot(prefix: string): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), prefix));
+  temporaryRoots.push(root);
+  return root;
+}

hub/test/integration/project-discovery.test.ts

@@ -0,0 +1,228 @@
+import { afterAll, beforeEach, describe, expect, it } from "vitest";
+import {
+  browseBindableFolder,
+  discoverBindableProjects,
+  normalizeProjectSearchQuery,
+} from "../../src/projectDiscovery.js";
+import { DEFAULT_ORG_ID, prisma, resetDb } from "./helpers.js";
+
+describe("project discovery", () => {
+  beforeEach(async () => {
+    await resetDb();
+    await seedUser("owner", "ou_owner", "OWNER");
+    await seedUser("member", "ou_member", "MEMBER");
+  });
+
+  afterAll(async () => prisma.$disconnect());
+
+  it("normalizes project codes across punctuation, width and case", () => {
+    expect(normalizeProjectSearchQuery(" ＴＨ-141 ")).toBe("th141");
+    expect(normalizeProjectSearchQuery("th_141")).toBe("th141");
+  });
+
+  it("searches normalized codes, Chinese names and complete folder breadcrumbs", async () => {
+    const root = await createFolder("root-legacy", null, "旧教学资产");
+    const subject = await createFolder("folder-physics", root.id, "物理竞赛教研");
+    const thermal = await createFolder("folder-thermal", subject.id, "TH_热学专题");
+    await createProject("project-th141", thermal.id, "TH-141_表面张力的严肃理论");
+    await createProject("project-fullwidth", thermal.id, "ＴＨ－１４２_全角编号");
+    await createProject("project-explicit-code", thermal.id, "表面课程", "PHY-001");
+    await createProject("project-other", thermal.id, "TH-211_理想气体静力学");
+
+    const byCode = await discover("TH141");
+    expect(byCode.items[0]).toMatchObject({
+      projectId: "project-th141",
+      breadcrumb: "旧教学资产 / 物理竞赛教研 / TH_热学专题",
+    });
+    await expect(discover("表面张力")).resolves.toMatchObject({
+      totalItems: 1,
+      items: [{ projectId: "project-th141" }],
+    });
+    await expect(discover("TH142")).resolves.toMatchObject({
+      items: [expect.objectContaining({ projectId: "project-fullwidth" })],
+    });
+    await expect(discover("PHY001")).resolves.toMatchObject({
+      items: [expect.objectContaining({ projectId: "project-explicit-code" })],
+    });
+    const byPath = await discover("物理竞赛教研");
+    expect(byPath.items.map((item) => item.projectId)).toEqual(expect.arrayContaining([
+      "project-th141",
+      "project-other",
+    ]));
+    await expect(discover("物理竞赛 TH141")).resolves.toMatchObject({
+      items: [expect.objectContaining({ projectId: "project-th141" })],
+    });
+    await expect(discover("%")).resolves.toMatchObject({ totalItems: 0 });
+  });
+
+  it("refreshes descendant breadcrumbs after a folder rename", async () => {
+    const root = await createFolder("root-before", null, "旧目录");
+    const child = await createFolder("child", root.id, "子目录");
+    await createProject("project-refresh", child.id, "项目");
+
+    await prisma.folder.update({ where: { id: root.id }, data: { name: "新目录" } });
+
+    await expect(discover("新目录")).resolves.toMatchObject({
+      totalItems: 1,
+      items: [{ projectId: "project-refresh", breadcrumb: "新目录 / 子目录" }],
+    });
+    await expect(discover("旧目录")).resolves.toMatchObject({ totalItems: 0 });
+  });
+
+  it("filters authorization before counting and paginating", async () => {
+    for (let index = 0; index < 12; index += 1) {
+      await createProject(`project-${index}`, null, `TH-${index}`);
+    }
+    await prisma.permissionGrant.create({
+      data: {
+        resourceType: "PROJECT",
+        resourceId: "project-11",
+        principalType: "USER",
+        principalId: "ou_member",
+        role: "MANAGE",
+      },
+    });
+
+    const result = await discoverBindableProjects({
+      prisma,
+      organizationId: DEFAULT_ORG_ID,
+      actorFeishuOpenId: "ou_member",
+      isOrgAdmin: false,
+      query: "TH",
+      page: 2,
+      pageSize: 5,
+    });
+
+    expect(result).toMatchObject({ page: 1, totalItems: 1, totalPages: 1 });
+    expect(result.items.map((item) => item.projectId)).toEqual(["project-11"]);
+  });
+
+  it("browses the preserved folder tree and paginates projects", async () => {
+    const root = await createFolder("root", null, "旧教学资产");
+    const child = await createFolder("child", root.id, "物理竞赛教研");
+    await createProject("project-root", root.id, "根目录项目");
+
+    const result = await browseBindableFolder({
+      prisma,
+      organizationId: DEFAULT_ORG_ID,
+      actorFeishuOpenId: "ou_owner",
+      isOrgAdmin: true,
+      folderId: root.id,
+    });
+
+    expect(result.breadcrumb).toBe("旧教学资产");
+    expect(result.parentFolderId).toBeNull();
+    expect(result.childFolders).toEqual([{ folderId: child.id, name: "物理竞赛教研" }]);
+    expect(result.projects).toEqual([{
+      projectId: "project-root",
+      name: "根目录项目",
+      breadcrumb: "旧教学资产",
+    }]);
+  });
+
+  it("hides the system Inbox at root and presents its projects as unclassified", async () => {
+    const inbox = await prisma.folder.findFirstOrThrow({
+      where: { organizationId: DEFAULT_ORG_ID, kind: "SYSTEM_INBOX" },
+    });
+    const businessRoot = await createFolder("business-root", null, "业务目录");
+    const businessInbox = await createFolder("business-inbox", businessRoot.id, "Inbox");
+    await createProject("project-inbox", inbox.id, "新项目");
+
+    const result = await browseBindableFolder({
+      prisma,
+      organizationId: DEFAULT_ORG_ID,
+      actorFeishuOpenId: "ou_owner",
+      isOrgAdmin: true,
+      folderId: null,
+    });
+
+    expect(result.childFolders.map((folder) => folder.folderId)).not.toContain(inbox.id);
+    expect(result.projects).toContainEqual({
+      projectId: "project-inbox",
+      name: "新项目",
+      breadcrumb: "未分类",
+    });
+
+    const businessResult = await browseBindableFolder({
+      prisma,
+      organizationId: DEFAULT_ORG_ID,
+      actorFeishuOpenId: "ou_owner",
+      isOrgAdmin: true,
+      folderId: businessRoot.id,
+    });
+    expect(businessResult.childFolders).toContainEqual({ folderId: businessInbox.id, name: "Inbox" });
+  });
+
+  it("shares one card page budget across folders and projects", async () => {
+    const root = await createFolder("folder-page-root", null, "目录分页");
+    for (let index = 0; index < 6; index += 1) {
+      await createFolder(`folder-page-${index}`, root.id, `目录-${index}`);
+      await createProject(`project-page-${index}`, root.id, `项目-${index}`);
+    }
+
+    const first = await browseBindableFolder({
+      prisma,
+      organizationId: DEFAULT_ORG_ID,
+      actorFeishuOpenId: "ou_owner",
+      isOrgAdmin: true,
+      folderId: root.id,
+      pageSize: 8,
+    });
+    const second = await browseBindableFolder({
+      prisma,
+      organizationId: DEFAULT_ORG_ID,
+      actorFeishuOpenId: "ou_owner",
+      isOrgAdmin: true,
+      folderId: root.id,
+      page: 2,
+      pageSize: 8,
+    });
+
+    expect(first).toMatchObject({ page: 1, totalPages: 2, totalFolders: 6, totalProjects: 6 });
+    expect(first.childFolders.length + first.projects.length).toBe(8);
+    expect(second.childFolders.length + second.projects.length).toBe(4);
+    expect([...first.projects, ...second.projects].map((project) => project.projectId).sort()).toEqual(
+      Array.from({ length: 6 }, (_, index) => `project-page-${index}`),
+    );
+  });
+});
+
+async function seedUser(id: string, feishuOpenId: string, role: "OWNER" | "MEMBER"): Promise<void> {
+  await prisma.user.create({
+    data: {
+      id,
+      feishuOpenId,
+      displayName: id,
+      organizationMemberships: { create: { organizationId: DEFAULT_ORG_ID, role } },
+    },
+  });
+}
+
+async function createFolder(id: string, parentId: string | null, name: string) {
+  return prisma.folder.create({
+    data: { id, organizationId: DEFAULT_ORG_ID, parentId, name },
+  });
+}
+
+async function createProject(id: string, folderId: string | null, name: string, code?: string) {
+  return prisma.project.create({
+    data: {
+      id,
+      organizationId: DEFAULT_ORG_ID,
+      folderId,
+      ...(code !== undefined ? { code } : {}),
+      name,
+      workspaceDir: `/tmp/${id}`,
+    },
+  });
+}
+
+function discover(query: string) {
+  return discoverBindableProjects({
+    prisma,
+    organizationId: DEFAULT_ORG_ID,
+    actorFeishuOpenId: "ou_owner",
+    isOrgAdmin: true,
+    query,
+  });
+}

hub/test/integration/project-onboarding.test.ts

@@ -55,6 +55,7 @@ describe("ADR-0021 project onboarding", () => {
     expect(result.folderId).toBe(folder.id);
     expect(result.chatId).toBeUndefined();
     expect((await stat(result.workspaceDir)).isDirectory()).toBe(true);
+    expect(result.workspaceDir).toMatch(/\/o_[A-Za-z0-9_-]{16}\/p_[A-Za-z0-9_-]{16}$/);
     const grant = await prisma.permissionGrant.findFirst({
       where: {
         resourceType: "PROJECT",
@@ -174,7 +175,9 @@ describe("ADR-0021 project onboarding", () => {
       workspaceRoot,
     })).rejects.toThrow(/forced permission settings failure/);
 
-    await expect(readdir(join(workspaceRoot, "test-default"))).resolves.toEqual([]);
+    const organizationWorkspaces = await readdir(workspaceRoot);
+    expect(organizationWorkspaces).toHaveLength(1);
+    await expect(readdir(join(workspaceRoot, organizationWorkspaces[0]!))).resolves.toEqual([]);
     await expect(prisma.project.count()).resolves.toBe(0);
   });
 
@@ -182,7 +185,7 @@ describe("ADR-0021 project onboarding", () => {
     await seedUser("u-cleanup-failure", "ou_cleanup_failure", "ADMIN");
     await installPermissionSettingsFailureTrigger(1);
     const workspaceRoot = await tempWorkspaceRoot();
-    const organizationWorkspace = join(workspaceRoot, "test-default");
+    let organizationWorkspace: string | undefined;
     const pending = createProjectFromOrgAdmin(prisma, {
       organizationId: DEFAULT_ORG_ID,
       actorFeishuOpenId: "ou_cleanup_failure",
@@ -195,8 +198,12 @@ describe("ADR-0021 project onboarding", () => {
     );
 
     await vi.waitFor(async () => {
+      const organizationWorkspaces = await readdir(workspaceRoot);
+      expect(organizationWorkspaces).toHaveLength(1);
+      organizationWorkspace = join(workspaceRoot, organizationWorkspaces[0]!);
       expect(await readdir(organizationWorkspace)).toHaveLength(1);
     }, { timeout: 2_000 });
+    if (organizationWorkspace === undefined) throw new Error("organization workspace was not allocated");
     await chmod(organizationWorkspace, 0o500);
     try {
       const error = await outcome;
@@ -255,6 +262,30 @@ describe("ADR-0021 project onboarding", () => {
     });
     expect(oldChatGrant).toBeNull();
   });
+
+  it("rejects selecting an Agent role from another Organization at the database boundary", async () => {
+    await seedUser("u-owner", "ou_owner", "OWNER");
+    const project = await createProjectFromOrgAdmin(prisma, {
+      organizationId: DEFAULT_ORG_ID,
+      actorFeishuOpenId: "ou_owner",
+      name: "Tenant-scoped role project",
+      workspaceRoot: await tempWorkspaceRoot(),
+    });
+    await bindFeishuChatToProject(prisma, {
+      projectId: project.projectId,
+      actorFeishuOpenId: "ou_owner",
+      chatId: "chat-tenant-role",
+    });
+    await seedTestOrganization("org_other", "other");
+    const otherRole = await prisma.organizationAgentRole.findUniqueOrThrow({
+      where: { organizationId_roleId: { organizationId: "org_other", roleId: "draft" } },
+    });
+
+    await expect(prisma.projectGroupBinding.updateMany({
+      where: { projectId: project.projectId, chatId: "chat-tenant-role", archivedAt: null },
+      data: { selectedAgentRoleId: otherRole.id },
+    })).rejects.toThrow();
+  });
 });
 
 async function seedUser(id: string, feishuOpenId: string, role: "OWNER" | "ADMIN" | "MEMBER"): Promise<void> {

hub/test/integration/silo-bootstrap.test.ts

@@ -23,6 +23,7 @@ describe("Alpha Silo bootstrap", () => {
         id: "org_default",
         slug: "legacy-default",
         name: "Legacy Default Organization",
+        agentRoles: { create: { roleId: "draft", label: "草稿", isDefault: true } },
         projectSettings: { create: { membersCanCreateProjects: true } },
         folders: {
           create: {
@@ -53,6 +54,14 @@ describe("Alpha Silo bootstrap", () => {
     expect(await prisma.team.count({ where: { slug: "teachers", archivedAt: null } })).toBe(1);
     expect(await prisma.teamMembership.count({ where: { revokedAt: null } })).toBe(1);
     expect(await prisma.organizationProviderConnection.count({ where: { status: "ACTIVE" } })).toBe(1);
+    await expect(prisma.organizationAgentRole.findMany({
+      where: { organizationId: "org_alpha", disabledAt: null },
+      orderBy: { sortOrder: "asc" },
+      select: { roleId: true, label: true, isDefault: true },
+    })).resolves.toEqual([
+      { roleId: "draft", label: "草稿", isDefault: true },
+      { roleId: "review", label: "审校", isDefault: false },
+    ]);
 
     const persisted = JSON.stringify({
       feishu: await prisma.feishuApplicationCredentialVersion.findMany(),

hub/test/unit/agent-security.test.ts

@@ -14,6 +14,7 @@ describe("agent subprocess security policy", () => {
   it("passes only the run proxy capability and safe runtime variables and protects the capability from tools", async () => {
     const { workspaceRoot, workspace } = await makeWorkspace();
     const policy = await createAgentSecurityPolicy({
+      runId: "run-test",
       workspaceRoot,
       workspaceDir: workspace,
       providerProxyEnv: {
@@ -46,7 +47,13 @@ describe("agent subprocess security policy", () => {
     expect(policy.env).not.toHaveProperty("HUB_SESSION_SECRET");
     expect(policy.env.HOME).toMatch(new RegExp(`^${escapeRegExp(canonicalWorkspace)}/`));
     expect(policy.env.CLAUDE_CONFIG_DIR).toMatch(new RegExp(`^${escapeRegExp(canonicalWorkspace)}/`));
-    expect(policy.env.CLAUDE_CODE_TMPDIR).toBe(join(".cph", "t"));
+    expect(policy.env.CLAUDE_CODE_TMPDIR).toBe(policy.env.TMPDIR);
+    expect(policy.env.TMP).toBe(policy.env.TMPDIR);
+    expect(policy.env.TEMP).toBe(policy.env.TMPDIR);
+    expect(policy.env.TMPDIR).toBe(join(canonicalWorkspace, ".cph", "t"));
+    expect(Buffer.byteLength(policy.env.TMPDIR!)).toBeLessThanOrEqual(56);
+    expect(policy.skillIds).toEqual([]);
+    expect(policy.skillPluginRoot).toBeUndefined();
 
     expect(policy.sandbox).toMatchObject({
       enabled: true,
@@ -71,6 +78,7 @@ describe("agent subprocess security policy", () => {
     const { workspaceRoot, workspace } = await makeWorkspace();
 
     await expect(createAgentSecurityPolicy({
+      runId: "run-test",
       workspaceRoot,
       workspaceDir: workspace,
       providerProxyEnv: {
@@ -81,32 +89,51 @@ describe("agent subprocess security policy", () => {
     })).rejects.toThrow("unsupported provider environment variable: DATABASE_URL");
   });
 
-  it("keeps the short SDK socket directory inside the project workspace", async () => {
+  it("keeps every SDK temp variable on a short path inside the project workspace", async () => {
     const { workspaceRoot, workspace } = await makeWorkspace();
     const policy = await createAgentSecurityPolicy({
+      runId: "run-test",
       workspaceRoot,
       workspaceDir: workspace,
       hostEnv: { PATH: "/usr/bin:/bin" },
     });
 
-    expect(policy.env.CLAUDE_CODE_TMPDIR).toBe(join(".cph", "t"));
-    const absoluteTemp = join(await realpath(workspace), ".cph", "t");
-    expect(policy.env.TMPDIR).toBe(absoluteTemp);
-    expect(policy.env.TMP).toBe(absoluteTemp);
-    expect(policy.env.TEMP).toBe(absoluteTemp);
-    expect(policy.sandbox.filesystem.allowWrite).toEqual([await realpath(workspace)]);
+    const canonicalWorkspace = await realpath(workspace);
+    const temp = policy.env.TMPDIR!;
+    expect(policy.env.CLAUDE_CODE_TMPDIR).toBe(temp);
+    expect(policy.env.TMP).toBe(temp);
+    expect(policy.env.TEMP).toBe(temp);
+    expect(temp).toBe(join(canonicalWorkspace, ".cph", "t"));
+    expect(Buffer.byteLength(temp)).toBeLessThanOrEqual(56);
+    expect(policy.sandbox.filesystem.allowWrite).toEqual([canonicalWorkspace]);
     expect(policy.sandbox.filesystem.denyWrite).toEqual(["/"]);
-    expect(policy.sandbox.filesystem.allowRead).not.toContain(expect.stringMatching(/^\/run\//));
+    expect(policy.sandbox.filesystem.allowRead).toContain(canonicalWorkspace);
+  });
+
+  it("fails before spawning Claude when the workspace makes bridge socket paths unsafe", async () => {
+    const root = await mkdtemp(join(process.platform === "win32" ? tmpdir() : "/tmp", "hub-agent-long-"));
+    roots.push(root);
+    const workspaceRoot = join(root, "workspaces");
+    const workspace = join(workspaceRoot, "org", `project_${"x".repeat(80)}`);
+    await mkdir(workspace, { recursive: true });
+
+    await expect(createAgentSecurityPolicy({
+      runId: "run-test",
+      workspaceRoot,
+      workspaceDir: workspace,
+      hostEnv: { PATH: "/usr/bin:/bin" },
+    })).rejects.toThrow("Agent temp path is too long for sandbox bridge sockets");
   });
 
   it("rejects a project workspace whose real path escapes the configured workspace root", async () => {
     const { root, workspaceRoot } = await makeWorkspace();
     const outside = join(root, "outside");
-    const linked = join(workspaceRoot, "org", "linked-project");
+    const linked = join(workspaceRoot, "o", "linked-project");
     await mkdir(outside);
     await symlink(outside, linked);
 
     await expect(createAgentSecurityPolicy({
+      runId: "run-test",
       workspaceRoot,
       workspaceDir: linked,
       providerProxyEnv: { ANTHROPIC_AUTH_TOKEN: "run-proxy-capability" },
@@ -116,12 +143,13 @@ describe("agent subprocess security policy", () => {
 
   it("rejects a project workspace symlink whose target is a sibling under the same root", async () => {
     const { workspaceRoot } = await makeWorkspace();
-    const sibling = join(workspaceRoot, "org", "sibling-project");
-    const linked = join(workspaceRoot, "org", "linked-project");
+    const sibling = join(workspaceRoot, "o", "sibling-project");
+    const linked = join(workspaceRoot, "o", "linked-project");
     await mkdir(sibling);
     await symlink(sibling, linked);
 
     await expect(createAgentSecurityPolicy({
+      runId: "run-test",
       workspaceRoot,
       workspaceDir: linked,
       providerProxyEnv: { ANTHROPIC_AUTH_TOKEN: "run-proxy-capability" },
@@ -130,10 +158,10 @@ describe("agent subprocess security policy", () => {
   });
 
   async function makeWorkspace(): Promise<{ root: string; workspaceRoot: string; workspace: string }> {
-    const root = await mkdtemp(join(tmpdir(), "hub-agent-security-"));
+    const root = await mkdtemp(join(process.platform === "win32" ? tmpdir() : "/tmp", "h-"));
     roots.push(root);
-    const workspaceRoot = join(root, "workspaces");
-    const workspace = join(workspaceRoot, "org", "project");
+    const workspaceRoot = join(root, "w");
+    const workspace = join(workspaceRoot, "o", "p");
     await mkdir(workspace, { recursive: true });
     return { root, workspaceRoot, workspace };
   }

hub/test/unit/feishu-approval.test.ts

@@ -110,6 +110,8 @@ describe("Feishu approval cards", () => {
       logger: silentLogger(),
       authorizer: allowAllAuthorizer(),
       projectWorkspaceRoot: "/tmp",
+      publicBaseUrl: "https://educraft.example.test",
+      siloOrganizationId: "org_test_default",
       runAgent: async () => ({
         status: "completed",
         text: "",

hub/test/unit/feishu-card-action-ack.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi, beforeEach } from "vitest";
 import type { FastifyBaseLogger } from "fastify";
-import type { CardActionEvent, FeishuRuntime } from "../../src/feishu/client.js";
+import type { CardActionEvent, FeishuBindingLifecycleEvent, FeishuRuntime } from "../../src/feishu/client.js";
 import { startFeishuListenerWithClient } from "../../src/feishu/client.js";
 
 const larkMock = vi.hoisted(() => {
@@ -80,6 +80,57 @@ describe("Feishu card action callbacks", () => {
       expect(logger.error).toHaveBeenCalledWith({ err }, "feishu card action handler threw");
     });
   });
+
+  it("dispatches chat dissolution and bot-removal lifecycle events", async () => {
+    const onLifecycle = vi.fn(async (_event: FeishuBindingLifecycleEvent) => {});
+    await startFeishuListenerWithClient(
+      { appId: "app-id", appSecret: "app-secret", botOpenId: "bot-open-id" },
+      fakeClient(),
+      silentLogger(),
+      async () => {},
+      undefined,
+      undefined,
+      onLifecycle,
+    );
+
+    await lifecycleHandler("im.chat.disbanded_v1")({
+      event_id: "event-dissolved",
+      chat_id: "chat-dissolved",
+    });
+    await lifecycleHandler("im.chat.member.bot.deleted_v1")({
+      header: { event_id: "event-bot-removed" },
+      chat_id: "chat-bot-removed",
+    });
+
+    expect(onLifecycle).toHaveBeenNthCalledWith(1, {
+      eventId: "event-dissolved",
+      chatId: "chat-dissolved",
+      reason: "chat_dissolved",
+    });
+    expect(onLifecycle).toHaveBeenNthCalledWith(2, {
+      eventId: "event-bot-removed",
+      chatId: "chat-bot-removed",
+      reason: "bot_removed",
+    });
+  });
+
+  it("propagates lifecycle archival failures to the WS dispatcher", async () => {
+    const failure = new Error("archive failed");
+    await startFeishuListenerWithClient(
+      { appId: "app-id", appSecret: "app-secret", botOpenId: "bot-open-id" },
+      fakeClient(),
+      silentLogger(),
+      async () => {},
+      undefined,
+      undefined,
+      async () => { throw failure; },
+    );
+
+    await expect(lifecycleHandler("im.chat.disbanded_v1")({
+      event_id: "event-failure",
+      chat_id: "chat-failure",
+    })).rejects.toThrow(failure);
+  });
 });
 
 function cardActionHandler(): (data: unknown) => Promise<void> {
@@ -91,6 +142,15 @@ function cardActionHandler(): (data: unknown) => Promise<void> {
   return handler;
 }
 
+function lifecycleHandler(eventType: string): (data: unknown) => Promise<void> {
+  const start = larkMock.starts[0];
+  if (start === undefined) throw new Error("WSClient.start was not called");
+  const dispatcher = start.eventDispatcher as { readonly handlers?: Record<string, (data: unknown) => Promise<void>> };
+  const handler = dispatcher.handlers?.[eventType];
+  if (handler === undefined) throw new Error(`${eventType} handler was not registered`);
+  return handler;
+}
+
 function makeCardActionEvent(): CardActionEvent {
   return {
     operator: { open_id: "ou_user" },

hub/test/unit/feishu-reactions.test.ts

@@ -103,6 +103,8 @@ async function triggerWithRunAgent(
     logger: rt.logger,
     authorizer: allowAllAuthorizer(),
     projectWorkspaceRoot: "/tmp",
+    publicBaseUrl: "https://educraft.example.test",
+    siloOrganizationId: "org_test_default",
     runAgent,
     messageBatcherOptions: { maxMessages: 1 },
   });
@@ -254,12 +256,25 @@ function mockPrisma(): PrismaClient {
   const session = { id: "session-1", metadata: {} };
 
   const client = {
+    organization: {
+      findFirst: vi.fn(async () => ({ id: "org_test_default", slug: "test-default" })),
+    },
+    feishuUserIdentity: {
+      findFirst: vi.fn(async () => ({
+        user: {
+          organizationMemberships: [{
+            role: "OWNER",
+            organization: { id: "org_test_default", name: "Test Organization" },
+          }],
+        },
+      })),
+    },
     feishuEventReceipt: {
       findUnique: vi.fn(async () => null),
       create: vi.fn(async () => ({ id: "receipt-1" })),
     },
     projectGroupBinding: {
-      findFirst: vi.fn(async () => ({ projectId: "project-1" })),
+      findFirst: vi.fn(async () => ({ projectId: "project-1", selectedRole: { roleId: "draft" } })),
     },
     project: {
       findUnique: vi.fn(async () => ({ workspaceDir: "/tmp/cph-project" })),

hub/test/unit/file-delivery.test.ts

@@ -34,6 +34,65 @@ describe("file delivery path resolution", () => {
     }
   });
 
+  itOnLinux("accepts arbitrary extensions and extensionless workspace files", async () => {
+    const root = await makeRepo();
+    try {
+      const workspace = join(root, "examples", "TH-141");
+      await writeFile(join(workspace, "lesson.json"), "{\"ok\":true}\n");
+      await writeFile(join(workspace, "Makefile"), "all:\n\t@true\n");
+
+      await expect(resolveDeliverableFile("lesson.json", join(root, "examples"), workspace))
+        .resolves.toMatchObject({ name: "lesson.json" });
+      await expect(resolveDeliverableFile("Makefile", join(root, "examples"), workspace))
+        .resolves.toMatchObject({ name: "Makefile" });
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  itOnLinux("allows the Feishu inbox but refuses other platform runtime files", async () => {
+    const root = await makeRepo();
+    try {
+      const workspace = join(root, "examples", "TH-141");
+      await mkdir(join(workspace, ".cph", "agent-runtime"), { recursive: true });
+      await mkdir(join(workspace, ".cph", "inbox"), { recursive: true });
+      await writeFile(join(workspace, ".cph", "agent-runtime", "session.jsonl"), "internal\n");
+      await writeFile(join(workspace, ".cph", "denials.log"), "internal\n");
+      await writeFile(join(workspace, ".cph", "inbox", "source.bin"), "source\n");
+
+      await expect(
+        resolveDeliverableFile(".cph/inbox/source.bin", join(root, "examples"), workspace),
+      ).resolves.toMatchObject({ name: "source.bin" });
+
+      await expect(
+        resolveDeliverableFile(".cph/agent-runtime/session.jsonl", join(root, "examples"), workspace),
+      ).rejects.toMatchObject({ reason: "boundary" });
+      await expect(
+        resolveDeliverableFile(".cph/denials.log", join(root, "examples"), workspace),
+      ).rejects.toMatchObject({ reason: "boundary" });
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  itOnLinux("refuses a file larger than the configured delivery limit", async () => {
+    const root = await makeRepo();
+    try {
+      const workspace = join(root, "examples", "TH-141");
+      await writeFile(join(workspace, "exact.bin"), Buffer.alloc(10));
+      await writeFile(join(workspace, "artifact.bin"), Buffer.alloc(11));
+
+      await expect(
+        resolveDeliverableFile("exact.bin", join(root, "examples"), workspace, 10),
+      ).resolves.toMatchObject({ name: "exact.bin", data: Buffer.alloc(10) });
+      await expect(
+        resolveDeliverableFile("artifact.bin", join(root, "examples"), workspace, 10),
+      ).rejects.toMatchObject({ reason: "limit" });
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
   itOnLinux("rejects a deliverable symlink even when its target exists", async () => {
     const root = await makeRepo();
     try {
@@ -50,7 +109,7 @@ describe("file delivery path resolution", () => {
     }
   });
 
-  it("does not infer files from natural-language prompts", async () => {
+  itOnLinux("does not infer files from natural-language prompts", async () => {
     const root = await makeRepo();
     try {
       const workspace = join(root, "examples", "TH-141");

hub/test/unit/legacy-project-manifest.test.ts

@@ -0,0 +1,63 @@
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { afterEach, describe, expect, it } from "vitest";
+
+const execute = promisify(execFile);
+const temporaryRoots: string[] = [];
+
+describe("legacy project manifest builder", () => {
+  afterEach(async () => {
+    while (temporaryRoots.length > 0) {
+      const root = temporaryRoots.pop();
+      if (root !== undefined) await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("stops at a project root and excludes trash projects", async () => {
+    const root = await mkdtemp(join(tmpdir(), "cph-legacy-manifest-"));
+    temporaryRoots.push(root);
+    const projectRoot = join(root, "物理", "legacy__牛顿力学");
+    await mkdir(join(projectRoot, "workspace", "nested"), { recursive: true });
+    await mkdir(join(projectRoot, "_raw"), { recursive: true });
+    await mkdir(join(root, ".trash", "deleted"), { recursive: true });
+    await writeFile(join(projectRoot, "project.json"), JSON.stringify({
+      id: "legacy",
+      name: "牛顿力学",
+      folderPath: ["物理"],
+    }));
+    await writeFile(join(projectRoot, "workspace", "nested", "project.json"), "not metadata");
+    await writeFile(join(projectRoot, "_raw", "project.json"), "not metadata");
+    await writeFile(join(root, ".trash", "deleted", "project.json"), JSON.stringify({
+      id: "deleted",
+      name: "Deleted",
+    }));
+
+    const { stdout } = await execute(process.execPath, [
+      resolve("deploy/build_legacy_project_manifest.mjs"),
+      root,
+    ]);
+
+    expect(JSON.parse(stdout)).toEqual([{
+      legacyId: "legacy",
+      name: "牛顿力学",
+      folderPath: ["物理"],
+      sourceRelativePath: "物理/legacy__牛顿力学",
+    }]);
+  });
+
+  it("reports untracked symlinked entries instead of silently omitting them", async () => {
+    const root = await mkdtemp(join(tmpdir(), "cph-legacy-manifest-link-"));
+    temporaryRoots.push(root);
+    await symlink("/tmp", join(root, "linked-project"));
+
+    const result = await execute(process.execPath, [
+      resolve("deploy/build_legacy_project_manifest.mjs"),
+      root,
+    ]);
+    expect(result.stderr).toContain("skip untracked symbolic link");
+    expect(JSON.parse(result.stdout)).toEqual([]);
+  });
+});

hub/test/unit/runner.test.ts

@@ -1,8 +1,9 @@
-import { mkdir, mkdtemp, realpath, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { runAgent } from "../../src/agent/runner.js";
+import { importSkillDirectory } from "../../src/agent/skillStore.js";
 
 const queryMock = vi.hoisted(() => vi.fn());
 
@@ -33,6 +34,16 @@ function resultMessage(sessionId: string, costUsd?: number) {
   };
 }
 
+function initMessage(skills: string[]) {
+  return {
+    type: "system",
+    subtype: "init",
+    skills,
+    tools: [],
+    plugins: [],
+  };
+}
+
 function messages(...items: unknown[]) {
   return (async function* () {
     for (const item of items) yield item;
@@ -59,14 +70,14 @@ describe("runAgent", () => {
 
   beforeEach(async () => {
     queryMock.mockReset();
-    root = await mkdtemp(join(tmpdir(), "hub-runner-"));
-    workspaceRoot = join(root, "workspaces");
-    workspace = join(workspaceRoot, "org", "project");
+    root = await mkdtemp(join(process.platform === "win32" ? tmpdir() : "/tmp", "r-"));
+    workspaceRoot = join(root, "w");
+    workspace = join(workspaceRoot, "o", "p");
     await mkdir(workspace, { recursive: true });
     workspaceRoot = await realpath(workspaceRoot);
     workspace = await realpath(workspace);
     previousSecrets = Object.fromEntries(
-      ["DATABASE_URL", "FEISHU_APP_SECRET", "HUB_SESSION_SECRET"].map((name) => [name, process.env[name]]),
+      ["DATABASE_URL", "FEISHU_APP_SECRET", "HUB_SESSION_SECRET", "HUB_SKILL_STORE_ROOT"].map((name) => [name, process.env[name]]),
     );
   });
 
@@ -102,13 +113,15 @@ describe("runAgent", () => {
         permissionMode: "bypassPermissions",
         allowDangerouslySkipPermissions: true,
         settingSources: [],
+        settings: { disableBundledSkills: true },
+        skills: [],
         strictMcpConfig: true,
         sandbox: expect.objectContaining({
           enabled: true,
           failIfUnavailable: true,
           allowUnsandboxedCommands: false,
           filesystem: expect.objectContaining({
-            allowWrite: [workspace],
+            allowWrite: expect.arrayContaining([workspace]),
             denyRead: ["/"],
             allowRead: expect.arrayContaining([workspace]),
           }),
@@ -134,6 +147,26 @@ describe("runAgent", () => {
     expect(call?.options).not.toHaveProperty("resume");
   });
 
+  it("returns the skills actually reported by SDK initialization", async () => {
+    queryMock.mockReturnValue(messages(
+      initMessage(["cph-runtime:outline"]),
+      assistantMessage("fresh"),
+      resultMessage("sdk-session-1"),
+    ));
+
+    const result = await runAgent({
+      prompt: "写一个大纲",
+      model: undefined,
+      project: { projectId: "p", boundChatId: "c", workspaceRoot, workspaceDir: workspace },
+      systemPrompt: undefined,
+      runId: "run-1",
+      sessionId: "hub-session-1",
+      prisma: stubPrisma,
+    });
+
+    expect(result.initializedSkillIds).toEqual(["cph-runtime:outline"]);
+  });
+
   it("maps role tool ids to the Claude SDK tool whitelist", async () => {
     queryMock.mockReturnValue(messages(assistantMessage("ok"), resultMessage("sdk-session-1")));
 
@@ -156,7 +189,7 @@ describe("runAgent", () => {
     });
   });
 
-  it("disables all SDK tools for an empty role tool whitelist", async () => {
+  it("disables SDK tools for an empty role tool and skill selection", async () => {
     queryMock.mockReturnValue(messages(assistantMessage("ok"), resultMessage("sdk-session-1")));
 
     await runAgent({
@@ -178,6 +211,36 @@ describe("runAgent", () => {
     });
   });
 
+  it("loads only the dynamic skills selected by the role", async () => {
+    const source = join(root, "skill-source");
+    const storeRoot = join(root, "skill-store");
+    await mkdir(source);
+    await writeFile(join(source, "SKILL.md"), "---\nname: typst\ndescription: Typst\n---\n");
+    const installed = await importSkillDirectory({ sourceDir: source, storeRoot });
+    process.env["HUB_SKILL_STORE_ROOT"] = storeRoot;
+    queryMock.mockReturnValue(messages(assistantMessage("ok"), resultMessage("sdk-session-1")));
+
+    await runAgent({
+      prompt: "排版",
+      model: undefined,
+      project: { projectId: "p", boundChatId: "c", workspaceRoot, workspaceDir: workspace },
+      systemPrompt: undefined,
+      tools: [],
+      skills: [{ name: "typst", version: "0.15.0", contentDigest: installed.contentDigest }],
+      runId: "run-skill",
+      sessionId: "hub-session-1",
+      prisma: stubPrisma,
+    });
+
+    expect(queryMock.mock.calls[0]?.[0]).toMatchObject({
+      options: {
+        tools: ["Skill"],
+        plugins: [expect.objectContaining({ type: "local", skipMcpDiscovery: true })],
+        skills: ["cph-runtime:typst"],
+      },
+    });
+  });
+
   it("returns SDK-reported cost when present", async () => {
     queryMock.mockReturnValue(messages(assistantMessage("ok"), resultMessage("sdk-session-1", 0.0042)));
 

hub/test/unit/skill-store.test.ts

@@ -0,0 +1,71 @@
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { importSkillDirectory, prepareRunSkillPlugin } from "../../src/agent/skillStore.js";
+
+describe("content-addressed Agent skill store", () => {
+  const roots: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+  });
+
+  it("imports a skill into an immutable digest directory and materializes a selected run plugin", async () => {
+    const root = await makeRoot();
+    const source = await makeSkill(root, "typst", "Typst help");
+    const storeRoot = join(root, "store");
+
+    const installed = await importSkillDirectory({ sourceDir: source, storeRoot });
+    expect(installed).toMatchObject({ name: "typst", description: "Typst help" });
+    expect(installed.contentDigest).toMatch(/^[a-f0-9]{64}$/);
+    await expect(readFile(join(storeRoot, "versions", installed.contentDigest, "SKILL.md"), "utf8"))
+      .resolves.toContain("name: typst");
+
+    const plugin = await prepareRunSkillPlugin({
+      storeRoot,
+      runId: "run-1",
+      skills: [{ name: "typst", version: "0.15.0", contentDigest: installed.contentDigest }],
+    });
+    expect(plugin).not.toBeNull();
+    expect(plugin?.skillIds).toEqual(["cph-runtime:typst"]);
+    await expect(readFile(join(plugin!.root, "skills", "typst", "reference.md"), "utf8"))
+      .resolves.toBe("reference\n");
+
+    await plugin?.cleanup();
+    await expect(readFile(join(plugin!.root, ".claude-plugin", "plugin.json"), "utf8"))
+      .rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("rejects symlinks and detects content tampering before a run", async () => {
+    const root = await makeRoot();
+    const source = await makeSkill(root, "outline", "Outline");
+    await symlink(join(source, "reference.md"), join(source, "link.md"));
+    await expect(importSkillDirectory({ sourceDir: source, storeRoot: join(root, "store") }))
+      .rejects.toThrow(/symlink/);
+    await rm(join(source, "link.md"));
+
+    const storeRoot = join(root, "store");
+    const installed = await importSkillDirectory({ sourceDir: source, storeRoot });
+    await writeFile(join(storeRoot, "versions", installed.contentDigest, "reference.md"), "tampered\n");
+    await expect(prepareRunSkillPlugin({
+      storeRoot,
+      runId: "run-2",
+      skills: [{ name: "outline", version: "1", contentDigest: installed.contentDigest }],
+    })).rejects.toThrow(/content digest mismatch/);
+  });
+
+  async function makeRoot(): Promise<string> {
+    const root = await mkdtemp(join(tmpdir(), "cph-skill-store-"));
+    roots.push(root);
+    return root;
+  }
+});
+
+async function makeSkill(root: string, name: string, description: string): Promise<string> {
+  const source = join(root, "source", name);
+  await mkdir(source, { recursive: true });
+  await writeFile(join(source, "SKILL.md"), `---\nname: ${name}\ndescription: ${description}\n---\n# ${name}\n`);
+  await writeFile(join(source, "reference.md"), "reference\n");
+  return source;
+}

hub/test/unit/slash-commands.test.ts

@@ -1,17 +1,11 @@
 import { describe, expect, it } from "vitest";
-import { parseSlashHelpSubcommand, parseSlashInvocation } from "../../src/feishu/slashCommands.js";
+import { parseSlashInvocation } from "../../src/feishu/slashCommands.js";
 
 describe("slash command parser", () => {
   it("parses a slash invocation without resolving it", () => {
-    expect(parseSlashInvocation("/new")).toEqual({ name: "new", args: [] });
-    expect(parseSlashInvocation("/review 看看这节")).toEqual({ name: "review", args: ["看看这节"] });
+    expect(parseSlashInvocation("/project")).toEqual({ name: "project", args: [] });
+    expect(parseSlashInvocation("/usage project")).toEqual({ name: "usage", args: ["project"] });
     expect(parseSlashInvocation("写教案")).toBeNull();
   });
 
-  it("parses help subcommands only in the exact /<command> help form", () => {
-    expect(parseSlashHelpSubcommand({ name: "new", args: ["help"] })).toBe("new");
-    expect(parseSlashHelpSubcommand({ name: "unknown", args: ["help"] })).toBe("unknown");
-    expect(parseSlashHelpSubcommand({ name: "new", args: ["help", "please"] })).toBeNull();
-    expect(parseSlashHelpSubcommand({ name: "help", args: ["new"] })).toBeNull();
-  });
 });

hub/test/unit/trigger-queue.test.ts

@@ -117,6 +117,8 @@ function makeTrigger(prompt: string): Omit<QueuedTrigger, "projectId" | "enqueue
   return {
     chatId: "chat-1",
     prompt,
+    roleId: "draft",
+    executionKind: "conversation",
     msg: makeMessage(prompt),
     senderOpenId: "ou-user",
     actor: { feishuOpenId: "ou-user", chatId: "chat-1" },

spec/Spec/Prelude.lean

@@ -26,6 +26,9 @@ structure Identifiers where
   session 不跨 provider/model;切 model 即新 session,跨 session 连续性由 ADR-0003 项目
   记忆/锚点重建,不由 session 自带。同 provider/model 内可跨多 run 复用, ADR-0002)。 -/
   SessionId : Type
+  /-- Organization-scoped Agent role 标识(`OPEN` 表示, ADR-0017);role 是动态运行配置,
+  不是 slash command 枚举。 -/
+  AgentRoleId : Type
   /-- 权限主体标识(`OPEN` 表示及其子类型学;ADR-0004 的 user/chat/department/…
       子类型学未定且非本层分歧点,纯 plumbing,故只留 opaque 键)。 -/
   Principal : Type

spec/Spec/System/ProjectGroup.lean

@@ -1,7 +1,7 @@
 import Spec.Prelude
 
 /-!
-# ProjectGroup —— 飞书项目群作为协作空间(ADR-0001)
+# ProjectGroup —— 飞书项目群作为协作空间(ADR-0001/0017)
 
 ADR-0001 的核心:一个 project 对应一个**长生命周期**飞书项目群;群是协作空间,**不是锁
 owner**(锁归 `AgentRun`,见 `Lock` / ADR-0002),不是临时处理 session。群可在无 Claude
@@ -12,6 +12,12 @@ project↔group 的**active**一对一绑定——likec4 画得出"project has g
 **绑定历史(`PINNED`, ADR-0021):** active binding 严格 1:1;实现可以保留 archived
 historical binding rows 供审计/纠错,但 `GroupBinding` 谓词只刻画当前 active 快照。
 群解散/不可达的自动化处理仍为 `OPEN`;pilot 纠错由 org admin 显式归档绑定。
+
+**当前角色(`PINNED`, ADR-0017):** active binding 选择一个 Organization-scoped Agent
+role;普通群消息在接收时冻结该 role,随后即使群切换角色,已接收工作也不漂移。切换角色
+只改变后续工作路由,不把不同 role 的 provider session 合并。每个 Organization 恰有一个
+active 默认 role 用于初始化新 binding,role 名称不硬编码。切换共享 role 的 actor 必须同时
+通过 project `agent.trigger` 与目标 role `role.trigger`;不额外要求 project `MANAGE`。
 -/
 
 namespace Spec.System
@@ -36,4 +42,37 @@ project"。archived historical bindings 不在本快照不变式内。 -/
 def GroupBinding.WellFormed (b : GroupBinding I) : Prop :=
   ∀ p₁ p₂ c, b p₁ = some c → b p₂ = some c → p₁ = p₂
 
+/-- 每个 Organization 的 active 默认 Agent role(`PINNED`, ADR-0017)。函数形状钉死每个
+Organization 恰好一个默认值;role 是否 active 及租户归属由 `WellScoped` 约束。 -/
+def OrganizationDefaultRole := I.OrganizationId → I.AgentRoleId
+
+/-- 默认 role 必须属于作为其 key 的同一个 Organization(`PINNED`, ADR-0017)。 -/
+def OrganizationDefaultRole.WellScoped
+    (defaults : OrganizationDefaultRole I)
+    (roleOrg : I.AgentRoleId → Option I.OrganizationId) : Prop :=
+  ∀ o, roleOrg (defaults o) = some o
+
+/-- Active 项目群选择的 Agent role(`PINNED`, ADR-0017)。role 属于项目 Organization;
+具体外键表示是 plumbing,由 `WellScoped` 钉死租户边界。 -/
+structure GroupSelectedRole where
+  /-- 被选择 role 的项目。 -/
+  project : I.ProjectId
+  /-- 作用于该项目 active 群的动态 Agent role。 -/
+  role : I.AgentRoleId
+
+/-- 群所选 role 必须与 project 同 Organization(`PINNED`, ADR-0017)。 -/
+def GroupSelectedRole.WellScoped
+    (selection : GroupSelectedRole I)
+    (projectOrg : I.ProjectId → Option I.OrganizationId)
+    (roleOrg : I.AgentRoleId → Option I.OrganizationId) : Prop :=
+  ∃ o, projectOrg selection.project = some o ∧ roleOrg selection.role = some o
+
+/-- 已接收群工作冻结其 role(`PINNED`, ADR-0017):调度时使用 admission 中记录的 role,
+而不是重新读取可能已经变化的群当前 role。 -/
+structure GroupRunRoleSnapshot where
+  /-- 被接收的一次 run。 -/
+  run : I.RunId
+  /-- 接收时冻结的 role。 -/
+  role : I.AgentRoleId
+
 end Spec.System