RFC: LoopX Desktop Execution Frontends v0

[huangruiteng]

Summary

This RFC defines two explicit LoopX Desktop execution frontend modes:

1. attach to an already-running Codex App/app-server session while the external host keeps process and conversation ownership; and
2. launch a LoopX-managed Pi or DeepSeek Harness runtime, with a provider-neutral adapter contract, Ark Agent Plan as the default profile, and bounded loopx_turn_v0 execution.

Both modes project the same LoopX Goal, Todo, gate, quota, evidence, and terminal truth. The frontend never infers a mode switch or silently starts a second executor.

The proposal also makes external collaboration Agent-scoped:

• Web and Lark can converge on one ordered working Agent session;
• group ingress selects one explicit policy: live steering, bounded session queue, or asynchronous inbox;
• capture, ingress, and reply policies are independent;
• Lark group messages and document comments use a provider-neutral Connector contract with bounded catch-up, cursor/idempotency, durable-effect-before-reply/ACK, and content-free status projection; and
• document bodies remain authority materials, while comments remain collaboration events until explicitly incorporated.

Scope

This PR is RFC-only. It does not change runtime behavior, start a managed executor, or claim that attached-session routing and document-comment connectors are already implemented.

Validation

• python3 examples/docs-governance-smoke.py
• python -m loopx.cli check --scan-path docs/architecture/rfcs/README.md --scan-path docs/architecture/rfcs/desktop-execution-frontends-v0.md
• git diff --check

All changed public files pass the public-boundary scan.

@maxliu, review is requested for the execution ownership split, Agent-scoped Connector boundary, and delivery ordering.

[huangruiteng]

Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

动机

这个 PR 要把 Goal Chat 的长期 Codex 会话和 LoopX 的一次性 governed Turn 对齐：普通问答继续复用 working Agent session，不花执行配额；用户确认后的 Todo 启动、纠偏和 monitor 才进入 exact-Todo admission、独立验证、Kernel writeback 与 quota settlement。同时新增面向协作者的只读状态投影。这个边界值得做，也是 Goal Chat 从“聊天壳”走向真实控制面的关键一步。

改动思路

实现把 app-server Chat transport 与 turn run-once --host codex-cli 串起来：material action 先在 canonical Goal session 建立本地 turn，关闭 app-server adapter，再用同一个 opaque Codex thread id 绑定 fresh Todo lineage 并执行。状态侧从现有 Goal projection 构造 bounded collaboration packet，检查 Todo count、truth contract、freshness、凭据和本机路径，再渲染为只读 Markdown。

具体改动

• [P1] 用户确认的 correction message 在 governed execution 边界被丢失。run.correct 把 parameters["message"] 交给 submit_governed_turn()，但 worker 只把 goal/agent/todo/thread/workdir/turn id 传给 GovernedTurnRunner；runner protocol 和 LoopXChatTurnAdmission.__call__() 都没有 message 字段，最终 turn run-once 的 host request 只看到 fresh Todo envelope。该消息只写进本地 Chat store，从未进入被 resume 的 Codex thread。因此类似“不要再改 X，按 Y 修正”的已确认纠偏会执行旧 Todo 语义。这是相对原先 submit_turn(message=...) 的 silent behavior regression。请把 bounded correction instruction 作为 typed、public/private 边界明确的 Turn input 贯穿 admission/plan/host request，并增加负向测试断言 exact message（或其受控 projection）确实到达 resumed host。
• [P1] 所有 governed Chat Todo 都被无条件绑定为“必须产生 Git workspace delta”，把通用控制面义务错误收窄成 repository-write 义务。LoopXChatTurnAdmission 在 admission 前强制读取 Git HEAD/diff，且始终安装 workspace_progress_validator；validator 明确把 unchanged workspace 判失败。这样 PR review/comment、外部 evidence poll、状态修复、只写 LoopX event ledger、非 Git Goal 等合法 material Todo 都无法得到 validated_progress，即使 capability-owned validation 已经证明了外部结果。请根据 selected Todo 的 typed validation contract / action kind 选择验证器：repository-write Todo 可以要求 workspace delta，external/state-only Todo 应验证对应 receipt/evidence；非 Git workspace 也不能在通用 Goal Chat admission 入口先失败。
• [P2] 新增 focused suite 在 macOS 当前精确 head 上不是全绿：test_chat_admission_invokes_fresh_exact_todo_resume 硬编码 /bin/true，本机不存在该路径，结果为 1 failed / 44 passed。请用 sys.executable、临时可执行 fixture 或平台解析后的命令，保持测试语义且跨平台。changed-surface Ruff 通过；远端 Python Tests、Windows、DCO、dependency review、release build 成功，但 exact head 的 Frontstage Pages build/deploy 是 CANCELLED，修复后也需要重新跑到可接受终态。

对主干的风险

第一处会让用户以为“纠偏已确认并执行”，实际上 Agent 没收到纠偏内容，可能继续做明确被禁止的动作；第二处会把大量非代码但合法的 LoopX material work 错判为 repair required，造成 Goal Chat 在真实 Todo 分布上系统性卡死。它们分别是指令完整性和 domain-neutral validation contract 的核心问题，不能依赖文档说明规避。

我的整体评价

canonical session、exact-Todo guard、opaque session binding、只读 collaboration projection 与 fail-closed truth/freshness 检查的整体方向很好；代码也把大部分 authority boundary 写成了 typed contract。不过当前结论是请求修改。先修复 message propagation 与 validation routing，再补跨平台测试并重跑 cancelled checks；之后值得在新 head 上重新做完整 review。

English verdict: Request changes. The canonical-session and collaboration-projection design is promising, but the governed path currently drops the user-confirmed correction message before resuming Codex, and it silently requires a Git workspace delta for every material Todo, rejecting valid external/state-only work. Route the typed instruction and capability-owned validation contract end to end, fix the portable test, and rerun the cancelled exact-head checks before merge.

[huangruiteng]

@maxliu 麻烦从前端与交互视角 review 这个变更，重点关注 presentation/dashboard 的用户可见合同、状态投影是否适合前端消费，以及 Goal Chat 的交互语义是否清晰。仓库 write 协作者邀请已发出；接受后我会再补 GitHub 的正式 reviewer request。

[huangruiteng]

@maxliu, could you review this RFC-only proposal? The pull request now changes only the RFC and its index; the earlier runtime implementation has been reverted. Please focus on the attached App Session versus managed Turn boundary, session/process ownership, LoopX task-state authority, and future host compatibility.

[huangruiteng]

English verdict: Approve the RFC-only change at exact head d7f512da9213dc72dfce03e523b8301ce5b743ee. The current net diff is documentation-only and cleanly separates an attached App Session from a future LoopX-managed Turn. I found no merge blocker. One P2 wording clarification remains: the validation criteria should distinguish a derived public-safe attachment/session reference from the raw opaque upstream thread or process handle that must stay owner-local. Exact-head validation passed: docs governance smoke, public-boundary scan, and git diff --check; DCO and dependency review are green.

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

动机

这个 PR 当前要解决的不是“立刻实现一个新的执行器”，而是先把前端接入已有 Codex App 会话时的产品所有权边界说清楚。旧的混合方案容易让同一 Goal 同时存在 App Session 与另一个 CLI/Turn 执行器，导致可见对话、纠偏消息、interrupt/resume、sandbox 和实际工作进程分叉。当前精确 head 已把早期运行时代码全部回退，净改动只保留 RFC 与索引，因此评审对象是一个可逆的架构决策：短期模式只 attach 既有会话，LoopX 继续掌握 Goal、Todo、gate、quota、evidence 与终态真相；managed Turn 留到未来独立模式。这个收敛比在一个 PR 里同时决定 transport、executor 与前端投影更容易实现、验证和回滚。

改动思路

RFC 以 attached_app_session 为明确模式，将三类所有权拆开：Codex App/host adapter 拥有 conversation、stream、interrupt 与 resume；LoopX control plane 拥有工作选择、权限、门禁与结算；frontend broker 只保存可撤销的 attachment binding。正向路径是 host-local broker 枚举经裁剪的 descriptor，操作者显式选择，broker 复核 session liveness、Goal/Agent/workspace/trust binding，随后所有消息继续走原 App Session；当 interaction contract 产生实质工作时，仍按选定 Todo、验证、writeback、quota spend 的标准生命周期结算。负向路径也写得清楚：descriptor 失效或绑定不匹配就 fail closed，前端显示 disconnected/stale，不静默拉起第二个 CLI Turn；detach 只移除前端绑定，不结束会话、不完成 Todo、不花配额。这个方案避免靠自由文本分类器决定是否换执行器，也没有提前抽象一个尚无第二实现方的通用 executor registry。

具体改动

• docs/architecture/rfcs/README.md 在 Draft Integration Proposals 中登记新 RFC，并明确它复用现有 automation-prompt/visible-host driver，managed CLI launch 是未来模式。
• docs/architecture/rfcs/attached-app-session-frontend-v0.md 新增 252 行完整提案，覆盖 Summary、Problem、Decision、Product Flow、Execution/Accounting、Identity、Safety/Privacy、Non-Goals、最小实现切片、验收标准与后续兼容性。

关键内容讲解

1. attached_app_session 的定义把“前端可见”与“LoopX 启动进程”解耦：已有 host session 继续拥有 transport，LoopX 不替换 opaque upstream thread，也不因一条消息自动切到第二执行器。
2. Discover -> Attach -> Interact -> Project -> Detach 给出了端到端调用链。descriptor 只允许 public-safe 信息；attach 前重验 live/binding；Interact 仍由现有 LoopX driver 读取 interaction contract；Project 只 join host session read model 与 LoopX authoritative state；Detach 不改变底层会话或 Goal。
3. Execution And Accounting Boundary 将可观察等价性与实现等价性分开：attached mode 仍须呈现 selected work、running/waiting/gated、validated progress、accounting 与 next action，但不要求复用 turn run-once 的进程所有权或 journal。
4. 三身份表把 App session/thread、Goal/Agent/Todo、frontend attachment 分属不同 owner，避免 attachment id 变成隐式 capability grant。
5. 验收标准覆盖单执行器、连续消息同一 session、interrupt/resume、只读零结算、detach 无副作用、stale/mismatch fail-closed，以及公开材料边界；这些条件足以指导后续实现 PR 写出行为测试。

对主干的风险

当前没有运行时或默认行为变更，主要风险是 RFC 被后续实现误读。

• P2 clarity suggestion: Discover 允许 public-safe session reference，并允许 workspace identity 使用 opaque/redacted reference；但最后一条 validation criterion 又笼统要求 public packets “contain no opaque handles”。这里应明确区分：浏览器可以收到派生、不可反查且无权限含义的 attachment/session reference；raw upstream thread id、process handle、credential-bearing locator 必须留在 owner-local broker。否则实现者可能把“opaque”理解成一律禁止，失去稳定关联键，或反过来把 raw host handle 当成 public-safe id 暴露。最小修复只需收紧该验收条目的名词，不影响整体架构结论。
• attachment lifecycle schema、broker 认证细节和最窄 status projection 仍是 open questions；由于 RFC 明确为 Draft、没有生产调用点，也没有声称这些问题已经实现，这些属于后续实现门禁而不是本 PR 的合并阻断。
• 精确 head 的净 diff 只有两个文档文件。python3 examples/docs-governance-smoke.py 通过；loopx check 对两个候选路径返回 ok: true 且 public-boundary scan clean，显示的三个 warning 是现有本地全局 goal/index 状态，与本 PR 文档无关；git diff --check origin/main...HEAD 通过。远端 DCO 与 dependency review 成功；Frontstage Pages 的 build/deploy 为 cancelled，但该工作流不验证本 RFC 的文档语义，且本地 exact-head 文档检查已覆盖本次改动。

我的整体评价

当前 head 已消除旧实现里的 message propagation、通用 Todo 被强制 Git delta 等运行时阻断项，因为那些代码不再位于净 diff 中。保留下来的 RFC 主题统一、domain-neutral、边界清晰，并把正向、失败与隐私路径都写成了后续可测试的合同；256 行新增对于一个完整架构提案是合理规模，没有夹带私有证据、本机路径或未来 runner 脚手架。结论是批准该 RFC-only PR；上述 P2 术语澄清可以在合并前顺手修，也可以作为实现 PR 的文档收紧项。此 COMMENTED 结论仅用于绕过 GitHub 对作者自审的限制，不授予 merge authority；合并仍应走仓库策略。