Merge pull request #31 from vitry/fix/rescue-live-progress

feat: relay live Rescue progress to Codex

Author: vitry

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+- Added cc-style semantic progress in the selected Rescue child and fixed coarse root liveness relays without exposing raw PTY data, child stderr, tool output, file contents, reasoning, credentials, or capabilities. Progress remains observational: only the original foreground terminal exit and final stdout prove completion. The child also supports an exact bound no-argument status sidecar through `zcode status`, `$zcode:status`, or `/zcode:status` without selecting or replacing the foreground job.
+- Added deterministic installed Codex 0.147 captured-rollout qualification for both the named Role and generic fallback, independently covering yielded foreground and same-child choice continuations; authenticated live qualification still reports only the route Codex actually selected.
 - Added dynamic task-specific Rescue child display names with bounded sibling-collision ordinals. Display identity remains a navigation-only invariant and does not grant, prove, or remove Rescue authorization.
 - Added #24 neutral forwarding hooks, #25 attached-yield continuation on the same running handle, and #26 fixed-shape structural progress probes with detailed status limited to the exact owner.
 - Added an observational, heartbeat-bounded session-snapshot progress fallback when structural conversation probes do not receive accepted online frames. It schema-validates through the ZCode client, scans only the durably accepted current turn, never reads raw logs or emits assistant prose/reasoning/tool output/file contents, and degrades to lifecycle-only updates without changing authoritative completion.

README.md

@@ -52,9 +52,13 @@ The child subscribes to online conversation progress when ZCode supports it and
 
 If accepted online frames remain unavailable, Rescue can fall back to already schema-validated session snapshots at no more than heartbeat frequency. This fallback is bounded to the durably accepted current turn and emits only allowlisted tool state; it does not emit commands or queries. It never reads raw ZCode logs and never emits assistant prose or reasoning, arbitrary tool input or output, errors or metadata, raw paths, file or patch contents, identifiers, environment values, or authorization material. Progress observation is non-authoritative: failure degrades once to lifecycle-only updates and does not change job success. The separate revision-guarded session read after companion completion remains the authoritative terminal result.
 
+The selected Rescue child shows cc-style semantic progress derived from structured ZCode events. Root receives fixed coarse liveness updates, not raw child output. These updates keep the original child wait active but are observational only: progress and status never prove completion; the original foreground terminal exit and final stdout do. Raw PTY data, tool output, file contents, reasoning, credentials, and capabilities are never relayed to root.
+
+Inside that selected Rescue child only, the exact trimmed spellings `zcode status`, `$zcode:status`, and `/zcode:status` inspect only the job bound to that child. This bound status sidecar accepts no job ID or option, cannot select another job, and never starts or replaces the original foreground execution. The public `$zcode:status` command listed above remains the owner-scoped control for ordinary durable jobs.
+
 Background semantics remain unchanged: the child reserves the production background worker and returns the public job ID, while the one-time capability stays on production-owned protected descriptors. Use `$zcode:status`, `$zcode:result`, and `$zcode:cancel` for durable recovery. Ordinary steering, a wait timeout, or parent/child loss does not authorize a replacement execution.
 
-Codex 0.147 is the only installed-host line pinned and targeted by this release's native Rescue qualification suite. A build is qualified only when the strict authenticated suite completes; a default machine-readable `unqualified` result is not compatibility evidence. No other Codex version is claimed compatible until its own installed qualification succeeds. Uninstalling the plugin does not automatically delete its stable private data, managed Role receipt/file, job history, or exact user-config leaves. Finish or cancel owned jobs first, then follow the receipt-gated [manual uninstall and residual-state cleanup guide](docs/manual-uninstall.md); never delete a colliding user or project Role.
+Codex 0.147 is the only installed-host line pinned and targeted by this release's native Rescue qualification suite. Default CI replays sanitized captured 0.147 rollouts independently for both the named Role and generic fallback, including yielded foreground and same-child choice continuations. The authenticated live test still records only the one route Codex actually selects; it does not claim to exercise both routes in one live turn. A build is qualified only when the strict authenticated suite completes; a default machine-readable `unqualified` result is not compatibility evidence. No other Codex version is claimed compatible until its own installed qualification succeeds. Uninstalling the plugin does not automatically delete its stable private data, managed Role receipt/file, job history, or exact user-config leaves. Finish or cancel owned jobs first, then follow the receipt-gated [manual uninstall and residual-state cleanup guide](docs/manual-uninstall.md); never delete a colliding user or project Role.
 
 ## Models
 

README.zh-CN.md

@@ -52,9 +52,13 @@ ZCode 支持时，child 会订阅 online conversation progress，并用结构化
 
 若已接受的 online frame 始终不可用，Rescue 可以按不高于心跳的频率回退读取已经通过 schema 校验的 session snapshot。该回退严格限定在已持久确认的当前 turn，只输出 allowlist 内的工具状态，不输出命令或 query。它绝不读取原始 ZCode 日志，也不输出 assistant 正文或推理、任意工具输入/输出、错误或 metadata、原始路径、文件或 patch 内容、标识符、环境值或授权材料。进度观测不具权威性：失败只会一次性降级为 lifecycle-only 更新，不改变 job 的成功结果。companion 完成后的独立、带 revision guard 的 session read 仍是权威终态结果。
 
+被选中的 Rescue 子 agent 会从结构化 ZCode 事件显示 cc-style 语义进度。root 收到的是固定的粗粒度存活更新，而不是原始子 agent 输出。这些更新只用于保持对原子 agent 的等待，本身只具观察性：进度和 status 永远不能证明完成；只有原始前台进程的终态退出和最终 stdout 才能证明完成。原始 PTY 数据、工具输出、文件内容、reasoning、凭据和 capabilities 永远不会 relay 到 root。
+
+仅在这个被选中的 Rescue 子 agent 内，精确去除首尾空白后的 `zcode status`、`$zcode:status` 和 `/zcode:status` 才会检查只绑定到该子 agent 的 job。这个 bound status sidecar 不接受 job ID 或选项，不能选择其他 job，也绝不会启动或替换原始前台执行。上表中的公开 `$zcode:status` 仍用于普通 durable job 的 owner-scoped 控制。
+
 后台语义保持不变：child 只负责预留生产 background worker 并返回公开 job ID，一次性 capability 仍只经 production-owned protected descriptor 传输。持久恢复继续使用 `$zcode:status`、`$zcode:result` 和 `$zcode:cancel`。普通 steering、等待超时或父/child 丢失都不授权替代执行。
 
-Codex 0.147 是本次发布唯一被固定并纳入原生 Rescue installed-host qualification suite 的版本线。只有严格认证套件完整成功的 build 才算 qualified；默认的机器可读 `unqualified` 结果不是兼容性证据。其他 Codex 版本在各自的 installed qualification 成功前不宣称兼容。uninstall 插件不会自动删除稳定私有数据、受管 Role 收据/文件、job 历史或精确 user-config 配置叶。请先结束或取消 owner job，再按[手动卸载与残留状态清理指南](docs/manual-uninstall.md)审查并移除能证明属于本插件的条目；绝不能删除有冲突的用户或项目 Role。
+Codex 0.147 是本次发布唯一被固定并纳入原生 Rescue installed-host qualification suite 的版本线。默认 CI 会分别重放经过净化的 0.147 captured rollout，独立覆盖具名 Role 和 generic fallback，包括 yielded 前台执行及同一 child 的 choice continuation。带认证的 live 测试仍只记录 Codex 实际选择的一条路由；它不会声称一次 live turn 同时执行了两条路由。只有严格认证套件完整成功的 build 才算 qualified；默认的机器可读 `unqualified` 结果不是兼容性证据。其他 Codex 版本在各自的 installed qualification 成功前不宣称兼容。uninstall 插件不会自动删除稳定私有数据、受管 Role 收据/文件、job 历史或精确 user-config 配置叶。请先结束或取消 owner job，再按[手动卸载与残留状态清理指南](docs/manual-uninstall.md)审查并移除能证明属于本插件的条目；绝不能删除有冲突的用户或项目 Role。
 
 ## 模型
 

agents/zcode-rescue.toml.template

@@ -1,8 +1,17 @@
 developer_instructions = """
-You are the installed ZCode Rescue forwarder. Accept only the exact initial assignment or one of the two exact continuation assignments documented below. Run exactly one mapped constant command in the current workspace, preserve stderr, and return public stdout verbatim and byte-for-byte. Here exactly one command means exactly one `exec_command` companion process; continuation calls only observe its original running handle. Never inspect or modify code independently, interpret results, retry, start a second `exec_command`, cancel, choose a pending branch, or request/print/persist authorization material. Do not accept task text, command arguments, job or session identity, workspace identity, permissions, credentials, or authorization values in the assignment. Reject every other assignment without running a command.
+You are the installed ZCode Rescue forwarder. Accept only the exact initial assignment, one of the two exact continuation assignments, or an exact status intent documented below. Run exactly one mapped foreground Rescue command in the current workspace, preserve stderr, and return public stdout verbatim and byte-for-byte. Exactly one `exec_command` companion process may own the foreground Rescue execution; continuation calls only observe its original running handle. Never inspect or modify code independently, interpret results, retry, start a second `exec_command` for Rescue invocation, cancel, choose a pending branch, or request/print/persist authorization material. The one expressly allowed status sidecar is observational and does not replace that foreground process. Do not accept task text, command arguments, job or session identity, workspace identity, permissions, credentials, or authorization values in the assignment. Reject every other assignment without running a command.
 
 A companion result containing an exit code is terminal. A result containing a running execution or session handle is nonterminal: poll only that same handle with the host continuation tool until it reports an exit code. Partial stdout, stderr, heartbeat text, or an outer code-cell completion is not terminal and must not be returned as final output. A needs-choice response with exit code 3 is terminal for the current child turn.
 
+For every result yielded by the original foreground handle, parse only complete dedicated `[zcode-relay]` lines. Before relay, require JSON with exact keys `version`, `sequence`, `phase`, `code`, and `observedAt`; require version 1, a positive bounded strictly increasing sequence, an allowlisted phase/code pair, and a valid bounded RFC3339 timestamp. Map only through this fixed allowlisted code-to-message map: `started` -> `ZCode Rescue started.`; `model-active` -> `ZCode is generating a response.`; `tool-active` -> `ZCode is working with a tool.`; `editing` -> `ZCode is applying workspace changes.`; `verifying` -> `ZCode is verifying the work.`; `waiting` -> `ZCode Rescue is still running.`; `finalizing` -> `ZCode Rescue is finalizing.`. Coalesce a repeated identical phase. If the native `send_message` tool is available, use `send_message` only to `/root` with the fixed mapped message. If it is unavailable or relay fails, continue polling the original handle. Relay is liveness only and never completion.
+Phase/code pairs are exactly `starting` / `started`, `running` / `model-active`, `investigating` / `tool-active`, `editing` / `editing`, `verifying` / `verifying`, `waiting` / `waiting`, and `finalizing` / `finalizing`.
+
+Never relay detailed `[zcode]` lines, arbitrary stderr, stdout, commands, paths, identifiers, content, results, or errors. Never invent a relay from a partial, malformed, unknown, stale, duplicate, or out-of-order record. After inspecting each yielded result and optionally relaying its valid complete records, continue only with same-handle `write_stdin` polling. A relay or its tool result never replaces a poll and never authorizes another Rescue invocation.
+
+While the original foreground handle is live and only between polls, accept exactly one of these exact trimmed no-argument user status intents: `zcode status`, `$zcode:status`, `/zcode:status`. For any of those spellings run the sidecar with no arguments using only this constant command:
+node "{{PLUGIN_ROOT}}/scripts/zcode-companion.mjs" invoke-status rescue
+Return its bounded status to that requesting child transcript, then resume polling the same original handle. Reject status arguments and every other spelling. Status is liveness only: it does not replace or complete the original handle, does not change terminal authority, and must never be returned as final output.
+
 For the exact initial assignment "Run the installed ZCode Rescue forwarder now. Return its public stdout verbatim.", run only:
 node "{{PLUGIN_ROOT}}/scripts/zcode-companion.mjs" invoke rescue
 
@@ -15,4 +24,6 @@ node "{{PLUGIN_ROOT}}/scripts/zcode-companion.mjs" invoke-choice rescue resume
 Exact fresh continuation: "Continue the pending ZCode Rescue with fresh. Run only the installed fresh forwarder command and return its public stdout verbatim."
 For the exact fresh continuation above, run only:
 node "{{PLUGIN_ROOT}}/scripts/zcode-companion.mjs" invoke-choice rescue fresh
+
+Return only the original foreground execution's terminal public stdout. Never substitute relay output, status output, intermediate output, or child-authored text.
 """