[kingsword09]

Summary

Harden long-running headless / -p execution around output completion, pending asynchronous work and cancellation.

• Wrap the native prompt lifecycle with a referenced keepalive and flush stdout/stderr before returning, preventing the runtime exit watchdog from dropping queued output.
• Continue forwarding SIGINT/SIGTERM/SIGHUP until the runtime actually exits instead of treating child.killed as process completion.
• Register the headless lifecycle patch as required in runtime synchronization and verification.
• Remove the network tests' test-only keepalive preload and add real Node regressions for retry backoff, slow consumers, cancellation, repeated signals and lifecycle handle cleanup.
• Document headless operation, foreground versus detached execution, completion checks and remaining long-run limitations; include the documentation in published packages.

Reproduced failures

1. A 512 KiB answer sent through a slow output consumer could exit with status 0 without emitting the final result record. The new regression delays reading by 10 seconds and verifies complete text, JSON and stream-JSON output.
2. After an initial termination signal, a second signal was not forwarded to the runtime. The launcher could exit while its runtime remained alive. A deterministic child-process regression verifies both signals reach the runtime.

Validation

• Build: bun run build
• Types: bun run typecheck
• Complete test suite: bun run test:all — 106 passing tests (37 unit, 14 TUI, 38 runtime, 17 Node)
• Runtime verification: bun scripts/check-runtime.ts
• Package verification: bun scripts/check-package.ts
• Whitespace: git diff --check

Validated locally on macOS with Node v26.4.0 and the locked ZCode 3.17.1 / runtime 0.17.1. POSIX signal regressions are explicitly excluded on Windows.

Scope and limits

These bounded regressions are not an hours-long soak test or a constant-memory guarantee. The native runtime still retains turn events and final responses. Consumers must keep draining both output streams; if they stop reading, successful completion waits instead of silently discarding output. Headless mode itself does not detach the process from shell/SSH lifetime.

[kingsword09]

已定位并修复本次 CI 失败：测试、runtime 检查和 release build 均通过，失败在 release:pack 的独立 tarball 白名单漏掉了 docs/HEADLESS.md。现已将该文件加入 requiredFiles 和 allowedRoots，未放宽其他发布路径限制。新增回归测试验证允许已声明的发布文档、拒绝缺失的 HEADLESS.md、拒绝未审核路径。本地 38 项单元测试、typecheck、完整 release:pack（含实际安装冒烟测试）通过。

[github-actions]

pkg-pr-new preview for commit f9dec53659e62933b9d39b1ecc35634b1e67533c.

npx --yes https://pkg.pr.new/zcode-app-cli@f9dec53

Full repository URL

This preview uses the selected commit. PR updates publish automatically after CI succeeds; kingsword09 can also request a preview with /pkg-pr-new.

Workflow logs