fix(post-edit): join foreground commands before the next turn

[ooiuuii]

Problem

Post-edit currently serializes its own commands but does not coordinate them with the following Agent run. A foreground formatter started by agent_settled can still be writing while the next parent turn reads or edits the same file.

The native lifecycle matters here: Pi marks the run idle before settlement handlers finish, and a custom message with triggerTurn: true enters the parent through a different path from ordinary prompt preflight. Merely awaiting agent_settled or fencing before_agent_start is not sufficient.

Value

Keep the existing opt-in, thin post-edit extension useful for foreground formatters without adding an editing-tool replacement, automatic repair loop, or second orchestration layer. Users can cancel a waiting Agent without losing track of the still-running command.

Approach

• Retain an execution promise until pi.exec actually completes. Requesting abort does not release it early.
• Join outstanding runs at native agent_start, covering ordinary prompts and custom-message parent wakeups with the current Agent cancellation signal installed.
• Keep an abort-aware tool_call backstop for all tools, including read-only and custom tools. A tool-name allowlist cannot identify every workspace reader. A canceled or session-invalidated call is blocked rather than admitted after the wait; only successful native Write/Edit results schedule post-edit.
• Snapshot command and working directory when scheduling. Disabling post-edit drops queued work but lets the active command finish; session reset drops queued work and requests cancellation.
• Treat killed: true as interruption even if Pi reports exit code zero. Keep notices bounded, sanitized, and suppressed for stale sessions.

The command must be finite and foreground-owned. This is not an acceptance gate or a workspace-wide lock: other sessions, concurrent subagents, user shell commands, external editors, and detached descendants remain outside its guarantee. Native Pi cancellation does not promise process-tree termination. A hung command can keep the next turn waiting; cancellation releases the Agent's wait, not the command's ownership. No timeout silently declares completion.

Validation

Environment: Windows, Node 22.22.3 for the review follow-up (22.22.0 for the original proof), Bun 1.3.14, locked Pi 0.85.1. Git's shell directory was on the test process PATH. Original development configuration was isolated from daily Pi settings; pi list resolved one local OpenPI checkout. The follow-up integration tests likewise use an isolated temporary agent directory and a local synthetic provider.

bun run check
node --test --experimental-strip-types tests/extensions/post-edit/index.test.ts tests/extensions/post-edit/lifecycle.test.ts

• Final checks: passed (config/docs contracts, build, formatting, lint, TypeScript).
• Final focused tests: 23 passed — 15 unit cases and 8 native-Pi integration cases.
• Red/green proof: the initial five native integration cases all failed against the original implementation. A scoped review then identified custom-message wakeups and cancelable waits; two additional native cases failed before those fixes and pass afterward. Maintainer review identified the late-scheduled read gap: the new native Read backstop case and expanded reader/cancellation unit assertions failed on 6ea0094 before removing the allowlist and pass afterward. The native Read case checks actual tool-result content, not just the final file on disk.
• Review follow-up: one scoped structured closeout review returned no actionable findings. Commit 51b616a changes five existing files (+67/-26), with no added runtime surface.

The integration tests use real Pi sessions, native tools, real pi.exec, and a real foreground formatter. A localhost TCP release controls completion deterministically; file contents and model/tool entry points establish ordering. The provider is synthetic and local-only, so no credentials or remote model calls are required. Dedicated tool-backstop tests omit only the start-hook registration to isolate that backstop; ordinary prompt, custom-message, and cancellation tests retain it.

Latest GitHub CI: run 35370486717 passed on 51b616a, including Node 22/24/26, Web E2E, and the required Windows process-lifecycle/full-suite-isolation job. All current PR checks are green. The prior Windows git-read cleanup EBUSY was not changed or suppressed in this PR.

Latest local full-suite limitation: bun run test on the review fix had 1,565 passed, 3 failed, and 10 skipped; all 23 post-edit tests passed within that run. The three failures match earlier failures in unchanged git-info command timing, setup's native provider fixture, and narrator's log-flood fixture. Running just those three files once with --test-concurrency=1 passed all 21 tests. This supports load-sensitive timeout behavior, without claiming the complete suite is green locally. The local runner exited before its Windows-serial and Vitest stages; the independent CI results above are reported separately.

Original broader validation history

The original local full-suite run hit five unrelated timing failures; those files passed serially. A bounded-concurrency diagnostic passed the parallel Node group (1,563 passed, 10 skipped) and Vitest (220 passed). The Windows serial group had 87 passed, 7 failed, 4 skipped, in unchanged background-terminal process-tree teardown tests. A representative kill-status failure reproduced independently, with no dependency on post-edit. No fixes to that subsystem are included here.

No live-provider or manual visual TUI test is claimed. The native integration runs use TUI-mode extension contexts programmatically.

Impact

• User-visible: a following TUI Agent run and all of its tool calls wait for outstanding foreground post-edit work; failures/interruption remain notifications, not automatic repair requests.
• Model-visible context/tools: no new tools, schema, system prompt, or injected messages. Interrupted guarded calls return a blocking reason.
• Runtime/lifecycle: joins commands at native lifecycle boundaries; abort-aware waits preserve cancellation and command ownership.
• Persisted config/data: none. Empty/off default, existing /openpi-setup entry point and command limit are unchanged.
• Compatibility/risk: foreground finite commands only; no headless activation, global locking, or detached-process guarantee. The backstop conservatively also delays tools that do not touch files while a command is outstanding. Existing long-running watchers are unsuitable and now explicitly documented as such.

[tt-a1i]

The lifecycle direction and cancellation ownership look good, and all 21 focused post-edit tests pass at this exact head. I found one blocking gap: the late-scheduled-run backstop only fences mutations, so a following Read can still race a formatter. Details inline. The current Windows required check is also red; the observed EBUSY is in unchanged git-read cleanup and looks unrelated, but it still needs a green rerun before merge.

[ooiuuii]

Non-blocking architectural assessment after this review: I would keep post-edit as an opt-in, session-local primitive, with command ownership and cancellation enforced at Pi's existing lifecycle seams. The read gap reinforced that a runtime invariant is more reliable than maintaining lists of tool names.

For a follow-up, my first candidate would be clearer TUI visibility into a running command and an Agent waiting on it, derived from the existing execution state. In particular, "cancellation requested" must stay distinct from "process completed". This would help explain waits without introducing another command scheduler or automatic repair loop.

I would defer file-local tool adapters until a concrete consumer needs the tool's returned content to match the post-processed file. They could own that single-file contract; the thin settlement hook would still own once-per-turn work. Cross-session coordination and process-tree termination need their actual owners and separate proof, not broader promises from this extension.

These are follow-up suggestions for discussion, not additional changes or new requirements in this PR.

[tt-a1i]

审查提交：51b616add4c2038cce506b000118a0f6a6e3dc31。

本轮未发现新的阻断问题。以下结论仅覆盖所列验证范围，不是合并批准。

验证范围

Reviewed production lifecycle diff and test coverage; ran all post-edit tests at frozen head: 23 pass, including 8 real Pi integration tests for prompt, native tools, custom messages, cancellation and failure.

限制与后续

Fence is session-local and covers foreground command settlement; does not claim a cross-session workspace lock or detached descendant tracking. Old tool-filter bypass is fixed at this head.

[tt-a1i]

Re-reviewed 51b616a. The earlier tool-filter gap is fixed. The previous exact-head verification passed 23 post-edit tests, including 8 native Pi integration cases; current required CI is green. The guarantee remains session-local foreground command settlement. No remaining blocking finding.