feat: Project-Session mapping with stable Project Sessions and routing

[yzxoi]

User report

[需求 4] Project 与 Session 映射。定义 Clarus Project、Runtime Task、Synergy Session 和本地目录之间的关系。每个 Project 应有稳定的 Project Session 和 workspace；Runtime Task 可创建独立执行 Session。还需要明确普通消息、mention 和 task 的路由及唤醒策略，以及 Project 是否可以指定不同的 Primary Agent。

Reporter: Feishu:ou_25b44caac15ab235465df821bd7c8f2a
Source: feishu:oc_46d261becbf063b7e0b667667d210297; message:om_x100b6a7ac5d70c7cc42f17e2290d1c1

Triage

• Type: feature_request
• Target repo: SII-Holos/synergy
• Related area: area/session

Deduplication

No duplicate found in recent open/closed issues. Issue #512 (Super Loop orchestration) and Issue #523 (Agent Organization Runtime) touch on multi-session orchestration but do not define the fundamental Project→Session mapping relationship. No existing issue defines the routing strategy for messages/mentions/tasks in the Clarus Project context.

Static inspection

• packages/synergy/src/session/ — the session runtime system. Currently sessions are created per-conversation (via frontend, channel, or session_control tool) without a stable "Project Session" concept.
• packages/synergy/src/session/inbox.ts — message inbox handling with agent name resolution via Agent.defaultAgent().
• packages/synergy/src/session/input.ts — input routing based on agent name and channel type.
• packages/synergy/src/task/ — task execution, which creates sub-sessions.
• packages/synergy/src/tool/session-control.ts — session_control tool, which creates sessions with optional directory binding.
• packages/synergy/src/runtime/reload.ts — runtime reload, includes default_agent watch.

Expected behavior

1. Each Clarus Project should have a stable "Project Session" — a persistent session tied to the project lifecycle, not to individual user conversations.
2. The Project Session has a dedicated workspace directory (see Issue 3).
3. Runtime Tasks can create independent execution sessions (sub-sessions) distinct from the stable Project Session.
4. Clear routing and wake-up strategy:
   • Normal messages in a project context → routed to Project Session
   • @mention of a specific agent → routed to that agent's session or sub-session
   • Task execution → creates independent sub-session in project workspace
5. Projects should be able to specify a different Primary Agent (via default_agent override at project level).
6. The mapping between entity types (Project, Runtime Task, Session, Directory) should be formally defined.

Actual behavior

• No stable "Project Session" concept exists — sessions are created per interaction.
• Routing is based on channel message metadata and agent mention, not on project membership.
• No formal mapping between projects, tasks, sessions, and directories.

Proposed fix

1. Define a data model for the Project→Session mapping, including:
   • ProjectSession — a persistent session associated with a Clarus Project
   • TaskSession — an execution sub-session created by a Runtime Task
   • Directory — the project workspace path
2. Implement a Project Session lifecycle:
   • Created when the project is first accessed
   • Persists across user conversations
   • Tied to the project workspace directory
   • Stops when project is archived/deleted
3. Define routing rules:
   • Messages in project scope → Project Session with project's assigned Primary Agent
   • @agent → route to that agent (sub-agent or primary)
   • Task tool → create TaskSession in project workspace
4. Allow project-level default_agent override (new config field in project metadata).
5. Document the formal entity relationship.

Suggested labels: enhancement, area/session

[yzxoi]

Note: #581 (Clarus Project root directory / per-project workspaces) has been merged into this issue per the original requirement provider's suggestion. The workspace directory infrastructure is now considered part of the Project-Session mapping scope.

Merged scope additions:

• Configurable clarusRoot directory (e.g. ~/.synergy/clarus/)
• Per-project workspace at <clarusRoot>/<projectId>-<slug>/
• On-demand workspace creation
• Retention policy for rename / exit / delete
• Workspace path exposed to agents

[synergy-oryn]

关于「Project 与 Session 映射」的澄清——先同步当前代码现状,再列出需要确认的决策点。

【现状(main 分支)】

1. Clarus Project 已映射为唯一真实的 Project Scope,workspace 在内部数据目录下按身份哈希确定性生成;Runtime Task 已在该 workspace 内创建独立 unattended Session。这条链路已实现并有测试覆盖。
2. 但架构上目前明确禁止为 Project 创建会话 Session:项目发现不建 Session,项目聊天类事件(如 clarus.project.message.created)在适配层被归为 unknown 直接忽略。即「稳定的 Project Session + 普通消息路由」目前完全不存在,且与现行架构约定相反。
3. Primary Agent 只支持账号级配置(channel.clarus.accounts..agent),没有项目级覆盖。
4. workspace 不是 - 可读布局,也没有可配置根目录——并入本议题的目录需求(feat: Clarus Project root directory with per-project isolated workspaces #581)尚未实现。

【需要确认的问题(回复后我们按答案排期实现)】

1. 项目会话入口:是否确认要为 Clarus Project 增加接收项目内普通消息的稳定 Session?这会推翻「Project 不产生会话 Session」的现有约定,并需要 Holos/Clarus 侧提供稳定的项目消息事件契约(该事件目前无 schema)。平台是否提供/计划提供?
2. @mention 路由:项目消息事件是否携带 mention/目标 agent 元数据?若无,是本地解析 @agent 文本?mention 命中子 agent 时,是路由到子 agent 的独立会话,还是投递给 Project Session 由其委派?
3. workspace 布局:是否要求迁移为 <根目录>/- 且根目录可配置?已存在的哈希布局项目希望保留、迁移还是并存?
4. 项目级 Primary Agent:来源是 Clarus 远端项目元数据(平台是否有该字段)还是本地 Synergy 配置?未设置时是否回落到账号级 agent?
5. 唤醒策略:Project Session 是懒创建(首条消息创建、跨会话持久)还是随项目发现即创建?Task 执行期间到达的项目消息是否照常唤醒 Project Session 并行处理?