Skip to content

fix(cli): print host-runnable onboarding and heartbeat commands - #7160

Merged
huangruiteng merged 3 commits into
loopx-project:mainfrom
JasonBuildAI:codex/agent-p4n8
Oct 23, 2026
Merged

fix(cli): print host-runnable onboarding and heartbeat commands#7160
huangruiteng merged 3 commits into
loopx-project:mainfrom
JasonBuildAI:codex/agent-p4n8

Conversation

@JasonBuildAI

@JasonBuildAI JasonBuildAI commented Oct 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Goal And Delivered Outcome

Every documented LoopX onboarding packet on native Windows starts with Bash/POSIX text that PowerShell rejects, so the first setup or heartbeat step fails before any LoopX command runs; this change makes agent-onboard, codex-cli-bootstrap-message, new-project-prompt, and the full/brief heartbeat command block print host-runnable PowerShell on Windows, including the per-wake Turn bootstrap and quota guard, while keeping the POSIX preflight text byte-identical and rendering both connect commands as one equivalent command line.

Author Declaration

  • Written by: model_agent (DeepSeek V4.1 Flash via DeepSeek Harness), at the human operator's direction and under their review.
  • AI disclosure: this change was drafted with AI assistance at my request, under my direction and review.

Implemented against

Criterion (spec clause) Disposition Symbol / path Test or command
Windows preflight is PowerShell, not Bash implemented install_contract.doctor_preflight_command tests/test_install_hint_platform.py::test_preflight_commands_follow_the_host_platform
Codex CLI install/repair guidance is host-runnable implemented install_contract.codex_cli_install_preflight same test; tests/test_onboarding_command_platform.py
Connect commands are one host-quoted command line implemented project_prompt.render_connect_command, render_codex_cli_bootstrap_connect_command tests/test_onboarding_command_platform.py
agent-onboard commands use host quoting and the call operator implemented loopx/agent_onboarding.py command builders tests/test_onboarding_command_platform.py
Heartbeat Turn bootstrap and quota guard are host-runnable implemented project_prompt.render_turn_bootstrap, render_quota_guard_command, heartbeat/task_body.py test_windows_heartbeat_turn_identity_uses_powershell; native 5.1 guard run
Existing POSIX preflight stays unchanged implemented install_contract.doctor_preflight_command POSIX branch test_posix_preflight_keeps_the_documented_shell; test_posix_connect_commands_are_valid_shell
Generated commands execute on native Windows implemented new native tests test_generated_windows_onboarding_commands_run_in_powershell; manual PowerShell 5.1 runs where pwsh is absent
  • Self-check before submission: ran the focused pytest set, ruff in the required scope, both affected onboarding smokes, git diff --check, and the public-boundary scan; compared the 26 pre-existing Windows test failures in the host-bootstrap/heartbeat suites before and after with no failing-name difference. Deliberately left out: a hosted Windows CI run (this PR may wait for first-time-contributor workflow approval); the POSIX preflight text is byte-identical and the POSIX connect form is one equivalent command line covered by an sh -n test.

Scope And Continuation

  • Completed scope and remaining work: all four documented surfaces are covered, including the full/brief heartbeat Turn bootstrap. The POSIX preflight text is preserved. Markdown fence labels remain bash; the command text itself is host-runnable, and the fence label is presentation only.
  • Slice boundary / successor: complete within this scope; no successor needed. Independent review findings on the first head (heartbeat Turn bootstrap, absolute --cli-bin quoting, PowerShell 5.1-only preflight) were fixed in 08276b942; the re-review returned APPROVE WITH NOTES with those findings resolved and no new blocking regression. The branch was then rebased onto 0f5c3e440 with a byte-identical patch. Hosted CI then exposed one existing test that pinned the POSIX brief-body line count (92) while native Windows now prints a shorter PowerShell preflight (76); b54671c9b keeps the 92-line ceiling and the cross-depth equality, so the required Windows lane no longer fails on the changed surface.

Validation

  • Tested revision: b54671c9bc6ab7daca4ff39724697f1adb7b7f0c (production patch identical to 08276b942, which the independent review approved with notes; the third commit only makes an existing Windows budget assertion host-shell independent after hosted CI exposed the shorter PowerShell preflight)
  • Run state: finished
  • Input classes: synthetic
Check kind Result Public-safe evidence / limitation
static passed python -m ruff check over the changed modules, tests, and smokes: All checks passed!
unit passed python -m pytest -q tests/test_onboarding_command_platform.py tests/test_install_hint_platform.py tests/test_bootstrap_command_pack_platform.py: 26 passed, 12 skipped
unit passed Simulated-Windows tests assert no python3 / `
real_entrypoint passed Native Windows PowerShell 5.1 with no pwsh on PATH: new-project-prompt and codex-cli-bootstrap-message connect commands exit 0 and create .loopx/registry.json and .loopx/goals/<goal>/ACTIVE_GOAL_STATE.md; the generated preflight exits 0; the full/brief heartbeat block runs with $LOOPX_TURN = "<timestamp>", exits 0, and returns heartbeat_receipt.status=committed with that exact turn_instance_id.
regression_parity passed Before: PowerShell rejects the printed connect command (Missing expression after unary operator '--'), preflight (Missing '(' after 'if' in if statement), and heartbeat block (LOOPX_TURN=... The term ... is not recognized). After: all PARSE_OK and execute.
manual passed examples/codex-cli-bootstrap-message-smoke.py and examples/codex-cli-first-run-rehearsal-smoke.py exit 0; the POSIX preflight text is byte-identical and the POSIX single-line connect form passes sh -n.
unit passed tests/control_plane/test_cli_output_budget.py::test_brief_long_path_budget_retains_semantics_across_parent_depths: 1 passed in 12.63s after the host-shell-independent line-count ceiling; the hosted Windows lane failure at step 12 (76 == 92) was this assertion, not a task-body regression.
integration failed loopx canary premerge --from-git-diff --git-diff-base upstream/main: direct diff checks, changed-Python compile, and the public-boundary scan passed; 4 selected smokes failed (install-local, codex-cli-packaged-install, loopx-update; cli-output-budget-regression timed out on this host). The first three reproduce identically on the untouched base d3c79a689 (POSIX bash -n, symlink privileges, installer-environment limits); the timeout is a local-environment limit. Hosted windows-powershell on the final head passes step 12 (the brief budget test) and stops at step 22, the known SQLite exit-test failure tracked by open #7154, not this diff.
regression_parity passed The 26 Windows test failures in tests/control_plane/test_host_bootstrap_lifecycle.py, tests/control_plane/test_heartbeat_agent_input.py, and tests/test_host_loop_activation.py have identical failing test names before and after (0 diff); the premerge smoke failures also reproduce on the base worktree.
real_backend not_applicable No backend or database surface changed.
  • Coverage and gaps: the pwsh-executing test skips on machines without PowerShell 7, but the preflight, connect, and heartbeat commands were executed manually on Windows PowerShell 5.1 (no pwsh). The required hosted Windows lane will exercise the changed code on a real Windows runner; this PR changes Python prompt rendering only. The local premerge gate is red only on environment-bound smokes that also fail on the pristine base, not on the changed paths.

Frontend / Visual Evidence

  • UI impact: none
  • Before: N/A
  • After: N/A
  • States and viewports shown: N/A
  • Source data: none
  • Attention review: N/A - no visual surface changed; the output is CLI text.
  • Craft review: N/A - no visual surface changed.

Type of Change

  • Bug fix

LoopX Area

  • Control plane (goals, todos, quota, scheduler, registry, runtime)

Technical Direction

  • Direction / acceptance reference, when applicable: Core control-plane hardening (host-runnable onboarding and heartbeat guidance).

Shared-authority RFC fixture impact

  • N/A - no authority provider, projection, or migration contract changed.

Boundary Checklist

  • Neither the diff nor this PR body/comments/attachments disclose private state, credentials, raw traces or verifier output, internal links, or local machine paths (including .loopx/, .codex/goals/, and live ACTIVE_GOAL_STATE.md).
  • I did not duplicate maintainer-owned benchmark work unless a maintainer split out a public issue for it.
  • I kept the change scoped to the linked issue/task.
  • I completed the visual evidence section for UI changes, or marked UI impact none.
  • Every commit includes a DCO Signed-off-by trailer (git commit -s).

JasonBuildAI added a commit to JasonBuildAI/loopx that referenced this pull request Oct 23, 2026
@JasonBuildAI
coordination: record agent-p4n8 PR loopx-project#7160 head
43d7334 
Signed-off-by: JasonBuildAI <jasonbuildai@gmail.com>
JasonBuildAI added a commit to JasonBuildAI/loopx that referenced this pull request Oct 23, 2026
@JasonBuildAI
fix(cli): finish host-runnable heartbeat and executable routing
08276b9 
Render the heartbeat Turn bootstrap with PowerShell assignment and pass the Turn id into the quota guard without POSIX parameter expansion. Route quoted executables through the PowerShell call operator, and use the interpreter pip preflight on Windows so Windows PowerShell 5.1 hosts do not require pwsh.

Addresses independent review findings on loopx-project#7160.

Signed-off-by: JasonBuildAI <jasonbuildai@gmail.com>
@JasonBuildAI
fix(cli): print host-runnable onboarding and heartbeat commands
2c4d4eb 
Route the onboarding, Codex CLI bootstrap, new-project, and heartbeat preflight text through loopx/install_contract.py so native Windows prints PowerShell instead of Bash. Render the two connect commands as one host-quoted command line instead of POSIX backslash continuations.

Refs loopx-project#7158

Signed-off-by: JasonBuildAI <jasonbuildai@gmail.com>
@JasonBuildAI
fix(cli): finish host-runnable heartbeat and executable routing
cf503bf 
Render the heartbeat Turn bootstrap with PowerShell assignment and pass the Turn id into the quota guard without POSIX parameter expansion. Route quoted executables through the PowerShell call operator, and use the interpreter pip preflight on Windows so Windows PowerShell 5.1 hosts do not require pwsh.

Addresses independent review findings on loopx-project#7160.

Signed-off-by: JasonBuildAI <jasonbuildai@gmail.com>
@JasonBuildAI
test(cli): keep the brief budget ceiling host-shell independent
b54671c 
Native Windows prints a shorter PowerShell preflight, so the brief Markdown body is 76 lines instead of 92. Assert the frozen 92-line ceiling and retain the cross-depth equality instead of pinning the POSIX line count.

Signed-off-by: JasonBuildAI <jasonbuildai@gmail.com>
loopx-agent
loopx-agent approved these changes Oct 23, 2026
View reviewed changes

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · gpt-6.1-sol · OpenAI · runtime_reported · reasoning_effort=max

动机

Windows 用户按入门提示复制命令时，原先拿到的是 Bash 的条件语句、续行符和变量赋值，PowerShell 在 LoopX 执行前就拒绝这些文本。每次连接项目或启动后续心跳都要人工翻译，会使“复制即可运行”的入口失去作用。本次将四个既有入口的安装检查、连接和心跳命令改为按宿主生成，保留原有权限与结算规则；改进范围是命令生成和消费，不代表已经验证整套 Windows 安装、实际模型工作或长期收益。

改动思路

安装提示继续由既有 install contract 负责，project prompt 负责组装命令，心跳正文负责携带当前轮身份。可执行文件与普通参数分开编码：PowerShell 调用被引号包围的程序路径需要调用运算符，参数则保持单引号字面量。连接命令改为一个完整命令行，心跳使用 PowerShell 赋值并把同一轮身份传给原 guard；调度、权限、状态提供者和后续结算仍由原 owner 判断。

这一分工适合当前修复：复用已有平台 owner，避免四处维护安装脚本，也不引入新的持久状态、权限开关或后台执行器。下面的对照来自实际生成命令的独立执行；PowerShell 7.5.4 在 macOS 上执行的是隔离的源码 CLI，平台选择仅在渲染边界替换，因此不能据此声称完成原生 Windows 5.1 的系统验收。

本 PR 保留为既有命令生成与消费的宿主修复；安装、实际 Host 和长期收益的资格另行保留。

场景 实际基线 当前提交
PowerShell 消费新项目及 Codex 连接命令 解析失败，无法连接 两种命令均执行成功，生成实际项目注册和状态
预检命令 PowerShell 解析拒绝 POSIX 语法 PowerShell 解析通过
两种连接后的 full、brief 心跳 原语法无法形成合法赋值 四次实际 guard 均返回原身份的 committed receipt
POSIX 对照 原有命令及正文 22 组比较保留语义：预检、guard、四种心跳正文逐字节一致；连接只改变续行布局

具体改动

规格依据是 issue #7158 的 Expected behavior，并结合既有 安装 owner 的宿主规则。实际共同祖先为 0f5c3e4408049312f79f89b617471b8512f5e9e8，审查头为 b54671c9bc6ab7daca4ff39724697f1adb7b7f0c。完整审查覆盖全部 11 个文件，包含四个生产文件、平台测试、预算断言和四个既有 smoke 的平台分支；没有把标题或作者声明当作通过证据。

关键代码讲解

  1. doctor_preflight_command 在 Windows 用 Get-Command 检查可达性，仅缺少 CLI 时才进入所属解释器的 pip 分支，最后执行 doctor；普通心跳不因这段提示每轮升级。POSIX 两类预检仍与基线完全一致。
  2. render_cli_command_prefix 让首个程序 token 走 host command owner，后续参数仍走宿主参数编码。带空格或单引号的程序路径不会被当作单独的字符串表达式。
  3. render_connect_command 和 Codex 连接生成器保留原有参数与授权字段，只移除 POSIX 续行依赖；独立执行使用含单引号、空格和中文的项目路径，实际创建注册与状态文件。
  4. render_turn_bootstrap 及 bind_exact_turn_settlement_task_body 联动替换模板赋值，guard 继续消费同一个身份。两类连接分别生成 full、brief 后，四次真实 CLI 回读的 turn_instance_id 都保持原值。

按规格逐项对应：宿主预检、连接参数、agent-onboard 命令和 full/brief 轮身份语法已实现，并由平台测试、实际 PowerShell 解析与隔离 CLI 消费覆盖；POSIX 保持项由 22 组对照覆盖。原生 Windows 5.1 和新的 Windows 安装失败恢复没有在本审查机器上执行，保留为平台资格边界。预算断言从固定 POSIX 行数改为原有 92 行上限，仍保留跨目录深度的完整正文相等检查，没有提高预算。

规格映射 当前 disposition
host-preflight implemented：宿主预检与所属解释器，实际安装未执行
connect-and-onboard implemented：两类实际连接及 onboarding 平台用例
heartbeat-turn implemented：四次实际 guard 精确身份回读
posix-parity implemented：22 组完整比较
native-windows-platform-qualification deferred：仍缺原生 Windows 5.1、缺 CLI 安装恢复与实际 Host 的独立平台资格

对主干的风险

主要风险是只替换看得见的 Bash token，却没有让宿主消费正确的参数、可执行文件或轮身份。我独立使用实际 PowerShell parser 和源码 CLI 验证：两种连接从基线解析失败变为可执行；四次带身份的 full/brief guard 得到 committed 回读。最初探针缺少 agent、随后缺少 runtime profile 的两组拒绝也保留了记录；补齐正式入口要求后才执行成功，没有绕过身份检查。尚未填写的进度分类占位符在两端都不能直接作为脚本执行，它们不是本次新增回归。

本地普通环境的相关测试为当前 27 passed / 12 skipped、基线 16 passed / 10 skipped；提供临时 PowerShell 后为当前 36 passed / 2 skipped、基线 24 passed / 1 skipped，余下跳过项是原生 Windows 条件。标准 premerge 的 6 项直接检查和 19 项选中检查均通过，覆盖安装、升级、输出预算、语义扫描与公开边界；全部改动文件 Ruff 也通过。没有读取或等待 CI。这里的执行证明针对渲染与隔离源码 CLI；没有执行实际 pip 安装、个人 Host 配置或付费模型任务。回退只需还原四个生产文件及对应测试，不涉及状态迁移。

我的整体评价

APPROVE。这是可独立验收、独立回退的命令生成修复切片，机制与反复发生的启动失败相称；新增平台分支仍留在原 owner 中，测试布局的调整有真实宿主差异依据。用户体验在独立 PowerShell 消费路径上得到改善，长程工作的身份、权限和结算约束得到保留，但没有测量长期效果或完整成本收益。新增名称是本地格式化辅助函数，沿用既有协议，不创建共享状态词汇。实际 Windows 5.1、缺失 CLI 的原生安装恢复和真实 Host 采用仍未独立资格，不能用本次通过结果替代；合并权限与原生 readiness 另行判断。

English verdict: APPROVE. The existing onboarding and heartbeat renderers now produce consumable PowerShell commands while preserving POSIX semantics and exact Turn identity. Independent shell/CLI probes and local validation passed; native Windows 5.1 installation and real Host adoption remain explicitly unqualified.

@huangruiteng
huangruiteng merged commit f996120 into loopx-project:main Oct 23, 2026
32 of 42 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@loopx-agent loopx-agent loopx-agent approved these changes
@huangruiteng huangruiteng Awaiting requested review from huangruiteng huangruiteng is a code owner
@songoow songoow Awaiting requested review from songoow songoow is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Bug]: native Windows onboarding and heartbeat prompts still print POSIX-only install and connect commands

3 participants

@JasonBuildAI @loopx-agent @huangruiteng