fix(B-0421): grok.ts self-documenting failure marker on empty-output cursor-agent exit (acceptance #3)

[AceHack]

Summary

Addresses B-0421 acceptance criterion 3 (surface cursor-agent errors more visibly).

Problem: when cursor-agent exits non-zero with empty stdout, grok.ts silently writes an empty output file. Callers reading only the file (not terminal stderr) cannot tell the call failed.

Fix: capture cursor-agent stderr (was inherit-only, now also pipe-captured + mirrored to process.stderr) AND on the empty-stdout + non-zero-exit case, write a self-documenting failure marker to the output file:

# cursor-agent failure (B-0421 self-documenting marker)
Exit code: <N>
Model: grok-4-20-thinking | grok-4-20
Prompt size (bytes): <N>
## Captured stderr
``` <stderr contents> ```

What changes

Before	After
stderr: inherit only	stderr: pipe + mirror to process.stderr
Output file silently empty on failure	Self-documenting failure marker with exit code + stderr
Caller reading only file: no idea call failed	File explains: exit code, model, prompt size, stderr

Why P2-level fix

Grok is one of four canonical peer-call agents. When it silently fails, BFT-style consensus drops from 4-of-4 to 3-of-4 without the calling agent noticing. The self-documenting failure makes the gap visible.

Acceptance criteria progress

• 3: Surface cursor-agent errors more visibly (this PR)
• 1: Reproduce failure with smaller prompt (next; failure marker will now capture stderr)
• 2: Identify root cause (now investigable via captured stderr when failure recurs)
• 4: 4-wrapper smoke test (next)

Composes with

• B-0421 backlog row (status open → in-progress; full progress note)
• tools/peer-call/grok.ts (the wrapper)
• .claude/rules/peer-call-infrastructure.md (grok.ts entry already cites B-0421 as open per PR fix(.claude/rules): peer-call-infrastructure rule — 8 wrappers not 6 + B-0421 note + website-text-mode-git pointer #2946)
• PR docs(memory): Ani website-text AGENTS.md review META-LOOP #2 + middle-path in math + dharma in code + shadow-Casimir-PR-cascade (Aaron 2026-05-13) #2945 (Ani META-LOOP — Grok website-text-mode-git is working orientation path until B-0421 resolves)

Test plan

• Static analysis: TypeScript types validated (Buffer + spawnSync API used consistently)
• Behavioral diff: success case unchanged (writes stdoutBuf to file as before); empty-failure case writes marker instead of empty
• Stderr mirroring preserves prior visibility (captured + written to process.stderr)
• Live test: requires cursor-agent invocation (not run in CI; will surface in next Grok call)

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 27cc43cb0e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR addresses backlog item B-0421 acceptance criterion #3 by making tools/peer-call/grok.ts self-report cursor-agent failures when the child exits non-zero with empty stdout, so file-only consumers can detect the failure.

Changes:

• Capture cursor-agent stderr (pipe) and mirror it to the parent’s stderr.
• On exitCode != 0 && stdout is empty, write a self-documenting failure marker (exit code, model, prompt bytes, captured stderr) to the output file instead of leaving it empty.
• Update the B-0421 backlog row with progress notes and a status change.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
tools/peer-call/grok.ts	Captures stderr and writes a failure marker to the output file on empty-output failures.
docs/backlog/P2/B-0421-grok-peer-call-failure-cursor-agent-exit-1-2026-05-11.md	Records progress for acceptance criterion #3 and updates frontmatter metadata.