fix: surface the real task error in the stop-review gate instead of stderr noise

[fabiogioachin]

Problem

When the stop-review gate's companion task fails (codex-companion.mjs task --json exits non-zero), the hook reports result.stderr || result.stdout as the failure reason:

const detail = String(result.stderr || result.stdout || "").trim();

On some setups (observed on Windows + recent Node), the child's stderr contains only Node runtime noise:

(node:10964) [DEP0190] DeprecationWarning: Passing args to a child process with shell option true can lead to security vulnerabilities, as the arguments are not escaped, only concatenated.

Since a non-empty stderr wins over stdout, this deprecation warning masks the real error, which is only available as the human-readable message of the failed run. The user sees the gate block with a DeprecationWarning as the "reason" and has no idea what actually failed.

Real-world example: the actual failure was a Codex usage-limit error (You've hit your usage limit... try again at Aug 5th), but the hook surfaced only the DEP0190 line. Diagnosing it required digging into the job log files under the plugin state directory.

Fix

Two small, backward-compatible changes:

1. codex-companion.mjs — runForegroundCommand now includes the human-readable rendered message in the --json payload (additive field; existing consumers that parse rawOutput, status, etc. are unaffected).

2. stop-review-gate-hook.mjs — on non-zero exit, the hook now resolves the failure detail in order of usefulness:

   1. payload.rendered parsed from the JSON stdout (the real error),
   2. stderr with DeprecationWarning noise lines filtered out,
   3. raw stdout as a last resort.

Before / after

Before:

The stop-time Codex review task failed: (node:19580) [DEP0190] DeprecationWarning: Passing args to a child process with shell option true...

After:

The stop-time Codex review task failed: You've hit your usage limit. Upgrade to Plus to continue using Codex (https://chatgpt.com/explore/plus), or try again at Aug 5th, 2026 3:58 AM.

Verified end-to-end on Windows 11 / Node against a live failing Codex run (usage-limit error): the gate now blocks with the actual cause in reason, exit code 0, valid decision JSON. node --test suite passes locally.

🤖 Generated with Claude Code

[Wintersta7e]

This fixes the reported path, but there's a sibling failure it doesn't reach — and the symptom looks almost identical, so it's easy to miss.

failureMessage in codex-companion.mjs reads result.error?.message ?? result.stderr. That covers a turn failing via a separate error notification. But a turn can also fail carrying its cause only in turn/completed's turn.error: lib/codex.mjs exposes it on the result as turn: turnState.finalTurn, and buildResultStatus returns 1 whenever finalTurn.status !== "completed". In that case failureMessage is empty — so the rendered this PR serialises is built from nothing, and the gate surfaces a generic message instead of the real one.

I reproduced it against this PR's approach using a fake app-server that emits a failed terminal turn with only turn.error set, no agent message, and no separate error notification. The gate reports:

The stop-time Codex review task failed: Codex did not return a final message.

rather than the actual cause, which in that fixture is You have hit your usage limit. Try again later.

One line covers it:

const failureMessage =
  result.turn?.error?.message || result.error?.message || result.stderr || "";

Worth folding in here, since the serialisation half is already yours and the two are only useful together.