Repository navigation
fix(cli): classify the shipped dsh-launch command in the manual - #7439
Conversation
The secure DSH launcher added in edc9f84 registers a top-level `loopx dsh-launch` command but never declared its manual visibility, so the required tests/test_cli_manual_visibility.py shard and the documented release preflight examples/cli-help-manpage-smoke.py both fail on an unmodified main with {'unclassified': ['dsh-launch']}. Add the command to the manual catalog next to the analogous `loopx dashboard` host launcher, since packages/dsh-loopx-plugin/README.md routes users to `loopx dsh-launch web` as the credential-safe launch path, and regenerate the checked-in manual. Fixes loopx-project#7438 Signed-off-by: JasonBuildAI <jasonbuildai@gmail.com>
Once dsh-launch is taught in the manual it joins the agent-facing help surface enumerated by the CLI output budget manifest, so the manifest needs an explicit qualification row. Classify it as an explicit cold-path launcher: it runs on demand and the provider credential reaches only the child environment. Signed-off-by: JasonBuildAI <jasonbuildai@gmail.com>
loopx-agent
left a comment
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent | gpt-6.1-sol | OpenAI | runtime_reported | reasoning_effort=max
动机
Motivation
通过命令参考或手册寻找 DSH 启动方式的用户，以及运行必需检查的贡献者。 旧版已有启动命令却未登记到手册，日常检查因此失败；本次将同一个入口补入现有目录并同步手册。 实际 CLI 的 JSON 和 Markdown 参考只新增一条启动说明；原根帮助、命令帮助和缺失可执行文件错误逐字保持。 本次只修目录、生成手册和已有输出资格登记，不修改启动逻辑、不安装 DSH、不读取真实凭据。
APPROVE — 84196f30987c75c29ca476dab335ab5aac882bcd，未发现阻断项。 这是已交付命令的一次完整目录修复；旧目录不认识该命令，手册与检查会持续遗漏同一个公开入口。新增的只是发现方式，命令仍需用户显式执行。
改动思路
Approach
在既有目录和资格表各补一项即可闭合遗漏；另建发现入口、默认启动流程或放宽预算都没有必要。 当前 PR 的边界是现有命令的可发现性及其既有检查资格。 commands 的 JSON、Markdown 和 roff 手册继续消费同一个 COMMAND_GROUPS。输出资格表复用 explicit_cold_path_exception：它描述按需启动的宿主，不能据此豁免反复读取的 quota/Turn 等决策载荷；本次所有既有预算数值均未修改。
已有帮助信息足以说明凭据如何交给子进程，故目录复用同一说明；它不读取凭据，也不启用可选插件。与保持原样相比，这个边界同时恢复命令发现、生成文件一致性和原有守卫，没有增加确认、配置或恢复步骤。
具体改动
Changes
关键代码讲解
- COMMAND_GROUPS 在 dashboard 旁登记
loopx dsh-launch [dsh args...]；没有加入隐藏命令集合，用户可从现有入口找到插件 README 已经要求使用的启动方式。 - build_command_reference_payload / render_manpage 使用同一目录。实测 JSON/Markdown 只新增这条记录；
man/loopx.1恰好新增三行 roff，完整生成文件一致性通过。 - CLI_OUTPUT_COMMAND_CLASSIFICATIONS 补齐已存在的类型化冷路径分类。完整 manifest 仅多这一项及派生计数；未改变任何 recurring surface 的 ceiling。
规范依据为 docs/product/release-readiness.md，固定修订 be1dc37a008be7017b64b622f653b6707df5c544，已读 原 help/manual 对齐与预检要求。CLI-1：implemented，目录/手册由相同 owner 生成且实测一致；CLI-2：implemented，完整 examples/cli-help-manpage-smoke.py 在本机通过。另按既有测试与质量文档执行原生输出资格和语义检查。
对主干的风险
Risks
PASS： 不可变 be1 基线的 visibility 测试报 unclassified: ['dsh-launch']，手册 smoke 在同一断言停止；当前两项 manual 测试及完整 smoke 均通过。相关 manual、DSH launcher、CLI budget 测试共 48 passed / 1 skipped；Ruff、标准 premerge 的 6 direct + 11 selected 全过，其中包含真实 CLI 的 base/head budget differential。
独立比较五种实际 CLI 输入：根帮助、命令帮助及缺失可执行文件的完整输出/退出码与基线相同；参考输出仅增加目标行。现有真实合成子进程用例也通过，覆盖 runtime-root 的默认/全局/子命令位置及缺凭据不借用默认密钥。没有用真实账号或启动实际 DSH 服务。
SKIP： 原有 depth-12 长路径夹具超过本机 temp namespace 能力；基线与 head 均为同一个跳过，未放宽预算或删除断言。作者 Windows 上后置 shell-syntax 未测的历史保留；本次 macOS 完整手册 smoke 通过，不能据此宣称原生 Windows 通过。最新 main 的相关目录、启动器、预算及渲染 owner 均与 be1 相同；新的无关协作 RPC 注册不改变它们。
语义与 CI 对齐
复用既有命令和分类值，没有新共享状态词汇或隐式默认启动。所加说明是命令用途，必需检查仍由既有断言约束。当前策略 wait_for_ci=false；未查询、轮询或等待远端 CI。
我的整体评价
Verdict
限定范围内 goal_achieved。长程行为 preserved：实际 recurring CLI 矩阵仍受同一预算与语义门约束；用户体验 improved：文档已教的入口现在可在原参考和手册中发现，无额外确认轮次。小改动复用原 owner，无需额外 helper、兼容 shim 或领域重构。
视觉检查不适用：只检查了 CLI catalog/manpage/help renderers，没有应用页面变更。未验证范围：本机以外原生 Windows、已安装 manpage、真实 DSH/provider/模型采用；未证明长期净效率收益。批准结论与仓库合并资格分别办理，本评审不授予 merge 或 bypass 权限。
英文简短结论
English verdict: APPROVE 84196f30987c75c29ca476dab335ab5aac882bcd. The existing launcher is now discoverable and explicitly classified without changing execution or budget limits. Immutable-base failures, real CLI parity, local tests and premerge checks support the complete three-file change; one unchanged temp-layout skip remains disclosed.
cocolord
left a comment
cocolord
left a comment
There was a problem hiding this comment.
Reviewer: model_agent; self_reported; model=GPT-family; provider=OpenAI; exact build unavailable (host observation session_not_bound).
APPROVE — 没有发现本 PR 引入的阻塞项。 审查 head：84196f30987c75c29ca476dab335ab5aac882bcd；基线：be1dc37a008be7017b64b622f653b6707df5c544。这是修复已发布命令漏登记的完整小批次，不是新增宿主能力。批准不等于 CI 已全绿或获得合并授权。
动机
使用命令目录或已安装手册查找安全启动方式的操作者，以及执行手册完整性检查的维护者。
改动前，已经发布的 DSH 启动器在命令目录与手册里缺席，维护者的完整性检查也会失败；改动后，目录与实际安装的手册都能找到它，原来的漏登记断言通过。
实际基线重现了漏登记失败，当前 head 的检查和私有目录安装回读通过；帮助页只是增加可发现性，没有启动宿主或读取真实凭据。
本 PR 不增加启动器、不改变凭据、执行、配额或权限规则，也不声称修复其他浏览器与发布流水线故障。
改动思路
命令目录和手册由已有的规范目录生成，实际启动则继续由原来的命令分发和启动器负责。这里最小且完整的修复是：给规范目录补一项、同步生成手册、在已有的类型化输出分类中登记这个按需启动命令。只放进“仅命令帮助”集合虽然能消除漏登记断言，却不能满足普通手册可发现性的接受条件；另建目录、生成器或 smoke 也没有必要。
正向路径是用户打开命令目录，读到启动器说明，再查看既有命令帮助；真实安装 smoke 还把生成的手册安装、压缩并回读。负向路径核验了没有可用宿主时的既有拒绝，以及默认帮助、命令帮助的前后相同输出。读取目录不会提前运行启动器，也不会替代用户的显式启动决定。
具体改动
接受依据：https://github.com/loopx-project/loopx/issues/7438；spec_revision：`issue-7438-body-sha256-316ccc0bf34a2057f1b717bd5861485b581f63e1a04187081f858eadc20e750c`。这是已保存 issue 正文的不可变摘要；该 issue 的复现基线是上述完整 commit。下列编号对应它的三个接受条件，不额外扩大任务。
- MAN-1 — implemented： 已发布顶层命令必须有合法手册分类。旧基线原生测试明确失败并报告未分类的启动器；当前 head 的两个原生测试文件所选三个检查全部通过，38 项未选。
- MAN-2 — implemented： 公开手册 smoke 的分类断言通过。本次不止停在断言：当前 head 的完整 smoke 运行成功，包含真实安装和已安装 gzip/手册回读；旧基线停在相同漏登记断言。
- MAN-3 — implemented： 普通命令目录和已安装手册可发现启动器。成对 public CLI 验证确认目录新增这一项，实际安装回读确认手册包含它；不是只 grep 源码。
关键代码讲解
loopx/help_surface.py:23的COMMAND_GROUPS（新增项在第 86 行）：把现有的loopx dsh-launch [dsh args...]放在日常操作者分组、显式 dashboard 启动器旁。既有命令参考和render_manpage都从这里投影，未复制启动规则，也未改变默认简短帮助。man/loopx.1增加的三行就是对应的生成输出，原生一致性检查通过。loopx/control_plane/testing/cli_output_budget.py:620的CLI_OUTPUT_COMMAND_CLASSIFICATIONS（新增项在第 706 行）：使用现成的CliOutputCommandClassification和精确命令 ID，分类为explicit_cold_path_exception、surface_id=None。它登记一个已有按需启动命令，而不是抬高任何输出上限或给它新权限；完整原生输出预算 smoke 通过。
全量差分为三文件 +19/-0：七行目录、九行类型化分类、三行生成手册。没有新增模块、CLI 选项、持久状态、一次性 fixture 或重复验证框架。
对主干的风险
最强的反例不是拼写错误，而是“源码目录已补上，但生成或安装后的手册仍旧”，以及“可发现性意外变成激活”。现有一致性断言加真实安装回读覆盖前者；独立的前后版本 CLI 对照覆盖后者：12 个观察通过，默认入口、全局帮助、DSH 命令帮助以及缺失执行文件的失败输出保持相同，调用期间私有运行目录没有状态写入。实际第三方子进程的凭据执行不是本次重新安全审计的范围，未使用真实凭据或付费后端；原来显式启动/子进程环境边界经源码检查，未被这三文件修改。
第一次 pytest 调用误带环境不支持的 --no-cov，两版本都以参数错误退出；去掉这个无效参数后使用原测试重跑。另一次本地探针错误要求 argparse 的子命令帮助显示父级概述，实际前后字节相同；保留失败与诊断后，把 oracle 改回既有选项和真实输出合同。这两项是评审 harness 错误，不是产品缺陷，也没有通过删断言或放宽产品预算来变绿。
语义与 CI 对齐
这里复用现有手册词汇和 cold-path 类型，不引入状态启发式、泛控制面中的专有业务义务，也没有把机器义务称为建议。输出分类不授予启动权；预算数值、测量工作负载与默认帮助保持原样。现有可复用检查已覆盖本次改变的合同。
CI 不是全绿。不可变基线 run 40417222661 与 exact-head run 40429253829 的四个浏览器失败和聚合失败，经保留 selector、expected/actual、应用栈、超时/退出并仅去时间戳与指定 Node 内部调度帧后，失败细节相同；对应浏览器脚本与 workflow 字节相同。分别仍是 chat-recovery.mjs:44 的按钮等待超时、research-worker-readback.mjs:93 的费用文字断言和聚合准入失败。head 的 Release Artifacts/build job 121942643858 也在相同底层编译 UI 用例失败；我比较的是这一底层命令，而没有声称整个基线发布 workflow 已完成或成功。它们保留为独立合并 hold，不要求这个目录修复承担无关 UI 修复。
本地 Ruff 同样不是通过：两版本都有两个相同导入排序诊断和一个相同 TRY004；后者位置仅因插入九行由 908 移到 917。配对检查确认规则、文件、消息和列相同，相关原有代码未改变。待完成的 CI、Sign-off/merge-gate 及其他 review closeout 仍由独立合并流程判断。
我的整体评价
这项修复有可复现的旧缺陷、真实调用者和安装后的可见收益，因此是 goal_achieved，不是按文件数或测试数记进展。长期工作维度 preserved：没有调度、重复效果或状态权威变化；用户体验维度 improved：恢复最短的普通目录/手册发现路径，没有新确认、重复录入或隐式激活。前后观察只出现明确接受的目录与手册差异，默认/错误合同保持不变。
范围和机制是相称的。未来可维护性检查结论为“无需额外重构”：现成规范目录、生成器和类型化分类已经是恰当的局部 owner，再加 builder、兼容分支或新 smoke 反而增加维护成本。没有需要迁移的公共协议或并行运行权威。没有发现 PR-specific blocker；残余风险和最强未重跑范围是无关浏览器/全发布与其他平台 qualification，不能把这份批准当成它们已经修复。本次不修改代码、不 dismiss、不合并；发布前再次核对 head，若变化则当前结论失效。
English verdict: APPROVE - head 84196f30987c75c29ca476dab335ab5aac882bcd; reproduced the baseline missing-manual classification and verified the complete narrow repair with 3 focused native checks, the full real installed-man smoke, full output-budget smoke and 12 paired public CLI observations. No PR-specific blocker; unchanged attributed browser/build/lint failures and pending CI remain separate merge holds. No merge or review dismissal authorized.
Goal And Delivered Outcome
Restores the required Python
test-shardgate on currentmainand makes the shippedcredential-safe
loopx dsh-launchlauncher visible inman loopx/loopx commands.Without this change every pull request whose plan runs the Python shards inherits a red
required job (
tests/test_cli_manual_visibility.py), the documented release preflight fails,and the launcher that
packages/dsh-loopx-plugin/README.md:128tells users to run cannot befound from the installed manual.
loopx dsh-launchwas shipped byedc9f84e1without a manual-visibilitydecision.
loopx/help_surface.pylists it in neitherCOMMAND_GROUPSnorMANPAGE_COMMAND_HELP_ONLY, so both the required guard and the release-preflight smokereport
{'unclassified': ['dsh-launch']}.be1dc37a0tests/test_cli_manual_visibility.pyfails 1/2 withunclassified: ['dsh-launch']andexamples/cli-help-manpage-smoke.pystops at the same assertion; at84196f309the guard is2 passed, the CLI output budget manifest qualifies
dsh-launch, its regression smoke exits 0,the preflight smoke advances past the classification assertion, and
man loopxcontains thelauncher entry.
mainatbe1dc37a0(merge base equalsthe PR base head, no unrelated history).
Author Declaration
Implemented against
loopx/help_surface.pymodule contract atbe1dc37a0("Every top-level parser command must either be represented in COMMAND_GROUPS or be
explicitly kept on its command-specific help surface"), the guard in
tests/test_cli_manual_visibility.py, and the release-preflight command atdocs/product/release-readiness.md:189.loopx/help_surface.pyCOMMAND_GROUPSpython -m pytest -q tests/test_cli_manual_visibility.pyloopx/control_plane/testing/cli_output_budget.pypython -m pytest -q --no-cov tests/control_plane/test_cli_output_budget.py -k manifest_covers_the_declared_agent_facing_surface_set;python examples/control_plane/cli-output-budget-regression-smoke.pyman/loopx.1regeneratedpython examples/cli-help-manpage-smoke.pyclassification assertion;git diff man/loopx.1scripts/render-manpage.py --output man/loopx.1tests/test_cli_manual_visibility.py::test_checked_in_manual_matches_the_canonical_catalogloopx/cli_commands/dsh_launch.py(its--helpalreadystates the credential guarantee), the plugin README that routes users to
loopx dsh-launch web, the mergedupgradeprecedent (fix(cli): classify the loopx upgrade command in the manual catalog #6847), and the guard's own disposition comment.Deliberately left out:
MANPAGE_COMMAND_HELP_ONLY, because the distributed plugin READMEtells users to run this command; and
docs/guides/getting-started.md, whose command list isa curated subset that also omits
loopx dashboard.Scope And Continuation
manual are repaired; no runtime behavior, flag, default or authority changes.
Validation
84196f309(two commits;4c3fd49fcis the reviewed catalog/manual change)unitpasseduv run --extra test python -m pytest -q tests/test_cli_manual_visibility.py->2 passed in 1.36sat the head; the same file is1 failed, 1 passedat basebe1dc37a0withunclassified: ['dsh-launch'].unitpasseduv run --extra test python -m pytest -q --no-cov tests/control_plane/test_cli_output_budget.py -k manifest_covers_the_declared_agent_facing_surface_set->1 passed, 38 deselected in 9.87s. At the catalog-only head this selection failed withExtra items in the right set: 'dsh-launch', which is why the second commit adds the qualification row.integrationpasseduv run --extra test python examples/control_plane/cli-output-budget-regression-smoke.py->cli-output-budget-regression-smoke ok(exit 0). This is the command run by the requiredkernel-contractsjob step "Qualify agent-facing CLI output".real_entrypointpasseduv run --extra test python examples/cli-help-manpage-smoke.pynow passesassert_top_level_commands_are_explicitly_classified(it stopped there at base) and renders the catalog; on this Windows host it then fails only at the unchangedbash -n scripts/install-local.shstep, becausebashresolves to a WSL launcher without/bin/bash(same directbash -nfailure on the unmodified tree). CI runs that step on Ubuntu.staticpasseduv run --extra test python -m ruff check loopx/help_surface.py loopx/control_plane/testing/cli_output_budget.py->All checks passed!;git diff --checkclean.regression_paritypassedunclassified ['dsh-launch'], and the catalog-only head additionally fails the CLI output manifest selection and its smoke. After: guard green, manifest selection green, smokeok, preflight smoke advances to the later host-only step,man/loopx.1gains exactly the three catalog lines.CLI output budget manifest, so the two unit guards plus the output-budget smoke exercise it end
to end. Inherited main-red checks unrelated to this diff:
kernel-contracts(mypy) and thebrowser/Release-Artifacts lanes fail on other PRs based on the same main head. The only
unverified step is the installer shell-syntax check, which this host cannot run for either
revision and which does not read the changed files; hosted Ubuntu CI covers it.
Frontend / Visual Evidence
Type of Change
LoopX Area
Technical Direction
Shared-authority RFC fixture impact
Boundary Checklist
.loopx/,.codex/goals/, and liveACTIVE_GOAL_STATE.md).python3 scripts/check_rfc_bilingual.py --base origin/main --head HEADpasses, or no paired RFC changed.none.Signed-off-bytrailer (git commit -s).AI disclosure: this change was drafted with AI assistance at my request, under my direction and review. The account owner set the contribution constraints and will review the result.