Give /codex:rescue a wait contract that does not depend on a background-subagent re-invocation

[patriyang]

Closes #99

Problem

plugins/codex/commands/rescue.md stated as a guarantee:

Claude Code re-invokes you when a background subagent finishes; that re-invocation is the rest of this command.

plugins/codex/commands/status.md records the opposite from observation — that re-invocation "has been observed not to arrive for subagent callers, leaving a completed Codex result unread with no signal." These are executable instructions, not prose, so /codex:rescue --background was told to end its turn and wait for a callback the project had already documented as unreliable for exactly this caller shape, with no recovery step. README.md was corrected in #97; rescue.md still promised it.

Fix — option 2 from the issue, not option 1

The issue offered documenting the recovery path (cheap) or giving rescue the same wait contract as the reviews (the real fix, "if the subagent boundary allows it"). It does: handleTask's if (options.background) branch in codex-companion.mjs already enqueues via enqueueBackgroundJob and returns the same { jobId, workspaceRoot, ... } payload the review flows consume. No runtime changes were needed.

• The codex:codex-rescue subagent is now always invoked in the foreground. A foreground Agent call returns inside the current turn — the same property Give the background Codex flows a wait contract that does not depend on harness re-invocation #94 relied on for foreground Bash. Backgrounding the subagent is what created the failure mode, so it is gone.
• --background now backgrounds the Codex run: the subagent enqueues with task --background --json and returns the enqueue JSON; the command reads jobId/workspaceRoot, blocks in bounded foreground steps (status … --wait --timeout-ms 240000 --json, PID-aware re-arm), then presents .storedJob.rendered verbatim in the same turn.
• --wait / no flag: unchanged foreground behavior.
• Recovery is now explicit: a later turn holding a dispatched-but-unread rescue recovers it from disk rather than re-dispatching.
• rescue.md's "There is no job to poll and nothing to fetch afterwards" is corrected — a rescue's task run persists a tracked job record either way.

Changed: commands/rescue.md, agents/codex-rescue.md, skills/codex-cli-runtime/SKILL.md, README.md, plus the version bump to 1.0.43.

Verification

The regression test was written first and observed failing against main (1 fail / 31 pass), then made to pass:

• tests/commands.test.mjs — new test rescue never depends on a background-subagent re-invocation to present its result pins both halves: the stale claims are gone, and the bounded-wait/fetch contract is present in rescue.md.
• commands/rescue.md is now covered by the two existing cross-command contract tests — "the foreground wait mechanism is provisioned on every command that requires it" and "dispatch is never a stopping point across every async surface" — so rescue is held to the same wait contract as the review flows rather than to rescue-only assertions.
• Assertions pinning the old contract were replaced with equally specific ones on the new wording, not loosened.
• Full suite: 347/347 pass.

Notes

• No changes under plugins/codex/scripts/**; status.md was left alone as the accurate side of the contradiction.
• Sibling issues Background review enqueue spawns one git hash-object process per dirty path, so a large dirty tree makes enqueue slow #102 and A review thread is offered every configured MCP server, including ones that cannot serve the workspace #105 were left unclaimed — unrelated module, and an open policy call respectively.

🤖 Generated with Claude Code

[patriyang]

Deep review round 1/3 — needs-attention, one [medium] finding.

Shell-escape the workspace path before constructing wait commands (commands/rescue.md:67-69) — workspaceRoot is interpolated inside double quotes, which do not neutralize an embedded ", backtick, or $().

The finding is real but pre-existing and repo-wide, not introduced here. main already has the identical construction in all three review commands (review.md:57/64/69, adversarial-review.md:63/70/75, deep-review.md:62/69/74); this PR copies that recipe verbatim, which is the point — tests/commands.test.mjs pins the exact string across every command that carries the wait contract, so escaping it in rescue.md alone would either fail that test or leave rescue as the one flow with a divergent recipe.

Filed as #107 to fix uniformly across all four commands. Not addressed in this PR.

No other findings. Full suite green at 347/347.