docs(reference): teach choosing between the steward channel and managed work - #4515
Conversation
The steward could describe a team but had no shipped procedure for the owner's one-sentence request, so the shape of the answer -- and whether anything was created before confirmation -- depended entirely on the Turn. The manager guidance now carries one bounded procedure: answer a team request with a single preview that names the lanes and their Agents, the first bounded Todo per lane, the quota envelope, the acceptance signal, and the stop condition, in that order; build every lane from Agents and Todos Core already knows and from capabilities the current profile grants, naming an unstaffable lane as a gap instead of inventing one; treat the preview as a proposal, never an effect; and apply only after the owner confirms that exact preview, through the canonical owners already named in the preview (Agent registration, Todo creation, quota or goal policy), with one readback afterwards. This is the instruction surface the manager already reads every Turn, so it ships behaviour without adding a contract, a command, or a second owner that nothing calls yet. The preview itself spends no quota and creates no Todo. Verified: tests/test_manager_team_plan_guidance.py asserts the ordered preview fields, the confirmation gate, the canonical-owner routing, the gap-not-guess rule, and the no-quota-for-preview rule; the manager context, handoff and channel-binding suites pass apart from the pre-existing test_every_production_steward_caller_passes_the_machine_defaults failure that also fails on origin/main. Public-boundary scan of both changed paths is clean. Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com>
…ed work The credential reference explained where the operator credential lives and how it resolves, but not which surface it serves or how an operator moves one of them. That gap is what makes the two modes hard to reason about: the steward channel and managed Turns are selected by different inputs, and the credential only authenticates the second. The reference now documents the choice (the steward channel's one machine-level executor versus a managed Turn's credential-resolved host and shipped managed profile), the exact machine-configuration commands for listing, inspecting, previewing, applying, removing and rolling back, the service-environment overrides and their precedence, the readback every entry point publishes (executor_endpoint, executor_endpoint_source, execution_profile, availability, and the bound Session's mode and status), how a connection record can only observe that resolution, and what the selection does not authorize: a credential never selects, the steward still only proposes, and Todos, agent registration, quota and goal policy change solely through their canonical owners after the owner confirms. Verified: public-boundary scan of the changed path is clean. Not verified here: no doc-render or link smoke was run for this path. Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com>
huangruiteng
left a comment
huangruiteng
left a comment
There was a problem hiding this comment.
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
Reviewed exact head: codex/steward-vs-managed-user-guidance (docs-only, 1 file).
动机
凭据文档讲了 key 存在哪、怎么解析，但没说它服务哪个面、运维方怎么移动其中一个面。这正是"管家模式 vs managed 模式"难以推理的原因：两者由不同输入选择，凭据只认证后者。
改动思路
在既有 reference 里补一节（不新增文件），只写"选择什么在哪儿应答"以及它的读回与边界，命令名取自实机的 loopx machine-config --help，未验证的 flag 形状不写死，改用"preview → apply"两步描述。
具体改动
docs/reference/operator-model-credential.md 新增 "Choosing What Answers, And Where"：两个面各自的独立选择器与适用时机；machine-config describe/inspect/preview/apply/remove/rollback；环境变量覆盖与优先级（LOOPX_MANAGER_*、LOOPX_TURN_*）；统一读回字段（executor_endpoint、executor_endpoint_source、execution_profile、available、session_mode/session_status）及"连接记录只是观测"；关闭/回滚与未配置机器的一致性；以及不授权边界（凭据不选择、管家只提议、Todo/注册/quota/goal policy 只经既有 owner 在确认后变更）。
对主干的风险
纯文档，无运行时改动。风险是描述与实现漂移——因此只写已从代码/CLI 帮助确认过的命令与字段，未验证的 flag 形状明确不写。
我的整体评价
无阻断性问题，建议合并（属仓库规则允许自合并的公共文档类）。验证：改动路径公开边界扫描干净（loopx check --scan-path）。诚实说明：本轮未跑文档渲染/链接 smoke，也未跑 pr-review --check-result 机器一致性校验——本 wake 预算用于内容本身，这一点已在 PR 与提交信息里披露。
English verdict: APPROVE - exact head on codex/steward-vs-managed-user-guidance. Adds user-facing guidance for choosing between the steward channel and managed work: independent selectors, exact machine-config commands, environment overrides and precedence, the published readback, disable/rollback, and the authorization boundary. Documentation-only, public-boundary scan clean; the render/link smoke and the machine --check-result were not run and that gap is disclosed.
huangruiteng
left a comment
huangruiteng
left a comment
There was a problem hiding this comment.
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
审查对象：4515@445c21af4db7fc0a566a531b503727562a05c883（已合并，合并后审计）。本 PR 自身改动为 docs/reference/operator-model-credential.md +73 行；分支上另有 SKILL.md +19 与 tests/test_manager_team_plan_guidance.py +30 属于已合并的 #4514，已在 514d8b515b483cb091367700c7da8bfa3f549531 单独出具结论，本次不重复评审。
动机
这份参考文档此前讲清了 operator credential 存在哪、谁能读、解析顺序和失败行为，却没有讲它服务的两个面分别是什么、以及怎么把一个面切到另一个面。缺失的后果很具体：operator 容易以为存了 key 就会把 steward 切到托管主机（其实不会），也容易去改启动脚本来做本该由 machine document 决定的事，并且没有把"凭证耗尽"误判成"管家有缺陷"的依据。
改动思路
在同一份文档里补一节 "Choosing What Answers, And Where"：先分离两个 selector（steward channel 的 machine 级 steward_executor.executor_endpoint 与 managed Turn 的 credential-resolved host / shipped managed profile），再给出确切的 machine-config 命令、服务环境变量与优先级、统一 readback、禁用/回滚路径与未配置机器的一致性，最后明确"选择本身不授权什么"。作者明确只写从 shipped help 读到的命令，不臆测未验证的 flag 形状。
具体改动
单个文件 +73/-0：1 个 H2 + 3 个 H3 + 2 个命令代码块 + 5 段正文，插在 Operating It 与既有的 Authority Boundary 之间。
我做的独立核对（逐条对代码/CLI 验证，而非只读文本）：
- 命令：
loopx machine-config --help确有 describe / preview / apply / inspect / remove / rollback 六个子命令；apply必须带--expected-plan-revision与--execute，remove/rollback同构 → 文档"先 preview 拿 revision 再 apply"的两步描述与实现一致。 - 命名空间与字段：
codex machine-config describe实跑输出确实包含steward_executor；machine-config inspect --format json中该命名空间含executor_endpoint/executor_model/executor_reasoning_effort三个字段，文档引用的steward_executor.executor_endpoint成立。 - 优先级与默认值：
_resolve_manager_endpoint的实际顺序是 machine_configuration → explicit_config → product_default，与"machine document 高于服务环境"一致；steward 默认端点codex、托管常量MANAGER_TURN_HOST = "dsh"、shipped managed profile 为deepseek-v4-flash+high，与文中deepseek-v4-flash@high一致；LOOPX_MANAGER_*与LOOPX_TURN_*六个变量在代码中均存在。 - readback：
manager_channel_binding()返回的键正好是executor_endpoint、executor_endpoint_source（三个取值 machine_configuration/explicit_config/product_default）、execution_profile、available加 session 的session_mode/session_status，并由chat_server.py:1264作为/api/chat/capabilities的manager块发布 → 文档"每个入口发布同一份 readback"成立。 - 边界与格式：
loopx check --scan-path→public boundary scan clean: 1 files；git diff --check干净；提交带 DCO。
对主干的风险
纯文档、无运行时改动，风险只在"读者会怎么做"。三点保留意见（均 P3、非阻塞）：(1) 命令块把 machine-config inspect 注释为"读取存储文档与有效的 steward 解析"，但默认 markdown 输出只有 status/revision/changed_namespaces（文档体要 --format json，而带 source 的有效解析在 /api/chat/capabilities，同一节后面才提到）——照抄这一行的 operator 看不到解析结果；(2) "环境是 bootstrap 与 escape hatch，且优先级低于 machine document"这句里 "escape hatch" 容易被读成"永远能覆盖"，而这恰恰是一个想临时覆盖已写入 machine 值的 operator 会踩的坑（同一文件既有的 Resolution Order 节延续了同样措辞，属继承而非新错）；(3) 该文档未出现在 docs/reference/README.md 的 High-traffic read paths 里，只能靠搜索找到（既有索引缺口，本次可顺手补一行）。另外文档本身未跑渲染/链接 smoke，作者已在 PR 描述里如实标注。
我的整体评价
这是一份"用代码核对过"的文档改动：命令、命名空间、字段、环境变量、默认值和 readback 键我逐项跑/查过，全部与 shipped 实现一致，而且它刻意不写没验证过的 flag 形状、并在最后明确"存 key 不会选择 host、选择托管主机不新增文件/供应商/受众权限"。三点保留意见都是措辞与可达性的小修，其中第一点值得顺手修掉。作为已合并精确 head 的合并后审计，证据支持通过。
English verdict: APPROVE (exact head 445c21a)
1 participant
Motivation
The credential reference explained where the operator credential lives and how it resolves, but not which surface it serves or how an operator moves one of them. That is exactly what makes the two modes hard to reason about: the steward channel and managed Turns are selected by different inputs, and the credential only authenticates the second.
Change
docs/reference/operator-model-credential.mdgains a "Choosing What Answers, And Where" section covering:steward_executor.executor_endpointversus a managed Turn's credential-resolved host and shipped managed profile), with when to choose each;loopx machine-configcommands (describe, inspect, preview → apply, remove, rollback);LOOPX_MANAGER_ENDPOINT/LOOPX_MANAGER_MODEL/LOOPX_MANAGER_REASONING_EFFORT, andLOOPX_TURN_PROVIDER/LOOPX_TURN_MODEL/LOOPX_TURN_REASONING_EFFORT);executor_endpoint,executor_endpoint_source,execution_profile,available, and the bound Session'ssession_mode/session_status), including that a connection record only observes the resolution;Validation
loopx check --scan-path docs/reference/operator-model-credential.md→ public boundary scan clean. Not verified: no doc-render or link smoke was run for this path; the added section is plain Markdown under existing headings.Risk
Documentation only, no runtime change. Command names were read from the shipped
loopx machine-config --helpoutput; the section deliberately describes the preview/apply two-step instead of restating flag shapes it did not verify.