… (Bug A)

cli.ts's outer try/finally at the heartbeat boundary calls
\`process.exit(exitCode)\` in the finally block. exitCode is initialized to
1 at function entry and set to 0 on the success path BEFORE any failure
branches throw — so a \`throw new ExitError(N)\` after a successful prior
phase exits with whatever exitCode happens to be at that moment (typically
0, i.e. false success), NOT the thrown ExitError's code. The top-level
catch at \`main().catch(err => process.exit(err.code))\` never runs because
the process already died inside the finally.

This is the load-bearing structural bug in the plan-review-loop restart
storm: a synth_failure that throws ExitError(1) exits 0, the monitor sees
success-shaped exit + a "synth_failure" state status, auto-resumes the
crashed run, which hits the same failure, ad infinitum.

Fix: capture any ExitError thrown inside the outer try via a
\`pendingExitError\` variable. The finally block computes
\`process.exit(pendingExitError?.code ?? exitCode)\` so the thrown code
wins. Pattern is three small additions:
- \`let pendingExitError: ExitError | null = null;\` near \`let exitCode\`
- a new \`catch (err) { if (err instanceof ExitError) pendingExitError = err; throw err; }\` between the try body and finally
- \`process.exit(pendingExitError?.code ?? exitCode)\` at the bottom of finally

This is correct for every \`throw new ExitError(N)\` in cli.ts — Exit 3
STALEMATE, Exit 4 USER ABORT, Exit 130 SIGINT, Exit 1 synth_failure — not
just the one fault path that surfaced it. Worth landing on its own merits.

Test pins the structural fix via static-grep checks plus a JS semantics
sanity check that the pattern correctly preserves thrown codes through
finally. Behavioral coverage comes via plan-reviewer-loop.test.ts and the
new cli-synth-failure-resume.test.ts in subsequent commits.

See ~/.claude/plans/fix-plan-review-loop-stalemate-restart-storm.md Bug A.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…STALEMATE event (Bug D+E loop-side)

plan-review-loop.ts now distinguishes "synth fails at round cap" from
"synth fails mid-loop". The cap case becomes the new outcome
\`synth_failure_stalemate\` with exit code 3 (matching SKILL.md Step 5.5's
documented STALEMATE contract) and emits a stdout JSON event
\`{"event":"STALEMATE","reason":"synth_failure_at_round_cap",...}\` so
operators and monitors can detect convergence failure programmatically.

Mid-loop synth_failure is unchanged — keeps exit code 1, outcome
\`synth_failure\`, retry semantics intact for transient model/network
blips. cli.ts's retry-promotion logic (Bug B fix in the next commit) is
the load-bearing fix for repeated mid-loop synth_failure that creates
the restart storm.

NOTE: the cap-synth-failure path is largely defensive — in practice,
\`shouldBailAdaptive\` at line 380 routes \`round >= maxRounds\` through
the stalemate gate BEFORE the loop body's synth call fires. So the new
exit-3 branch is reached only when an alternative loop flow (e.g.,
\`--no-adaptive-cap\` plus continue-path bail-out) lands at the cap with
a failing synth. Keeping the defensive code anyway so future
\`shouldBailAdaptive\` changes don't regress the contract.

Tests added in plan-reviewer-loop.test.ts:
- Mid-loop synth_failure with maxRounds=5 still returns exit 1 + outcome
  \`synth_failure\` (pins the no-false-positive invariant — the contract
  change is scoped to the cap, not promoted to every synth failure).

See ~/.claude/plans/fix-plan-review-loop-stalemate-restart-storm.md Bug D+E.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…romote to STALEMATE (Bug B)

cli.ts's resume condition at line 11552 previously included
\`state.planReview.status === "synth_failure"\` as a retry trigger,
optimized for transient mid-loop crashes. Combined with Bug A (now fixed)
and the monitor's auto-resume on RUN_STALE, this created the restart
storm: the orchestrator re-ran the same failing loop on every resume,
ad infinitum.

Per the plan, do NOT auto-retry synth_failure on resume. Add a stalemate
guard BEFORE the existing retry condition:

  if status === "synth_failure" OR "synth_failure_stalemate":
    emit STALEMATE event to stdout
    promote status to "synth_failure_stalemate" if needed
    throw ExitError(3) — operator intervention required

The transient-retry case the old code optimized for is, from the operator's
perspective, the same shape as the restart-storm case — both result in a
crashed run that the orchestrator can't recover automatically. The safer
default is to halt with clear guidance:
  1. Edit the plan to address objections, re-run.
  2. Re-launch with --no-plan-review to bypass the gate.
  3. Delete state.planReview to restart the loop fresh.

Also routes \`loopResult.outcome === "synth_failure_stalemate"\` (from the
cap path in plan-review-loop) to record \`status: "synth_failure_stalemate"\`
in the saved state, so the resume guard above recognizes it as definitely-
stalemate (not just first occurrence).

Tests pin the static wiring across five concerns:
- Stalemate guard appears BEFORE the loop-launch if
- Both "synth_failure" and "synth_failure_stalemate" statuses are guarded
- "synth_failure" removed from the resume-retry condition
- exit-3 handler routes synth_failure_stalemate outcome correctly
- STALEMATE event carries reason field for telemetry

See ~/.claude/plans/fix-plan-review-loop-stalemate-restart-storm.md Bug B.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…er-run restart cap (Bug C component 2)

Two new guards on the monitor's auto-resume site, complementing the
heartbeat-tracker fix from commit bd10c04 (Bug C component 1):

1. **Stalemate refusal**: when \`state.planReview.status\` is
   \`synth_failure\` or \`synth_failure_stalemate\`, the monitor refuses
   auto-resume and emits a new \`RUN_HALTED_STALEMATE\` event instead.
   Prevents the storm cycle from starting even if cli.ts's stalemate
   guard (Bug B) were ever bypassed.

2. **Per-run restart cap**: counts auto-resume attempts in a sidecar
   file at \`<stateDir>/<stateSlug>.resume-count\`. Default cap 3,
   overridable via \`GSTACK_MONITOR_MAX_AUTO_RESUME\`. On reaching the
   cap, emits new \`RUN_HALTED_RESTART_CAP\` event. Defense in depth
   for any future failure class where auto-resume keeps spinning
   without converging.

Both new events get exit code 11 (USER_ACTION_REQUIRED-tier) so wrapper
scripts that key on operator-intervention events get the same signal
without needing to learn new exit codes.

Counter semantics: bumped only on actual spawn attempts (dry-run with
\`spawnResume: false\` doesn't consume budget). The counter file
naturally goes stale once a run completes; the next run on a different
stateSlug gets a fresh counter. Failure to write the counter file is
silent (best-effort) — the stalemate refusal guard above is the primary
defense, and the cap is a secondary safety net.

Tests cover: stalemate refusal for both synth_failure and
synth_failure_stalemate statuses, cap hits after default 3 resumes,
env var override raises the cap, RUN_RESUMED metadata surfaces
resumeCount + maxResumes for observability, counter persists across
monitor ticks.

See ~/.claude/plans/fix-plan-review-loop-stalemate-restart-storm.md Bug C.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…case

After the plan-review-loop restart-storm fix (commits f2be7bf → 6d0d9d3),
Exit 3 STALEMATE has three sub-cases instead of two. Document the new
synth_failure_stalemate path and the operator recovery options specific
to it (override with --no-plan-review, edit plan + delete state.planReview
to restart fresh, etc.).

Also note the monitor's new restart-cap behavior (default 3,
GSTACK_MONITOR_MAX_AUTO_RESUME) so operators reading Step 5.5 know what
RUN_HALTED_STALEMATE and RUN_HALTED_RESTART_CAP events mean when they
appear in the monitor log.

Regenerated SKILL.md from the .tmpl change via gen:skill-docs.

See ~/.claude/plans/fix-plan-review-loop-stalemate-restart-storm.md SKILL.md task.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>