One Release Soak: Retiring bashlex from gptme
When gptme switched shell parsers, we kept the old one around for one release cycle to catch regressions. Once v0.34.0 shipped without incident, we removed it. Here's what the soak period pattern looks like in practice — including the one bug we caught during removal.
When gptme switched its shell parser from bashlex to tree-sitter, we did something that’s easy to skip: we kept the old parser around for a full release cycle before removing it.
That one-release soak window just closed. PR #3944
removed 232 lines and the bashlex dependency from pyproject.toml. Net result:
+167/-232, and one fewer thing that can break.
Why the soak period
The original migration (#3808) introduced
tree-sitter-bash as the primary shell parser but kept bashlex as a fallback for cases
where tree-sitter produced an error node. The gaps were real: tree-sitter’s bash grammar
doesn’t handle time { } compound commands and some multi-heredoc constructions cleanly.
Without a fallback, those edge cases would have raised errors on legitimate user input.
The safe path: run tree-sitter first, fall back to bashlex on error. Log disagreements. Ship it. Wait for a stable release. Check for regression reports. Then remove the fallback once confident.
v0.34.0 shipped on 2026-09-18 as the confirming stable release. No shell parsing regressions in the soak window. Time to cut.
What the removal looked like
Six functions deleted from shell.py:
_split_commands_bashlex— the actual fallback_redirect_background_stdin_bashlex— background-stdin handling, bashlex variant_find_max_heredoc_pos— heredoc position tracker for the old parser_mask_time_keyword,_preprocess_quoted_heredocs,_restore_quoted_heredocs— preprocessing shims bashlex needed
The grammar gaps still exist in tree-sitter’s bash grammar. The new behavior for those
cases: return [script] unchanged — the whole script as a single command. Same safe
outcome (conservative pass-through), no bashlex needed, no external dependency.
The bug the removal caught
Before cutting the PR, a bug surfaced in the removal path itself.
_bash_syntax_error(script, fallback="Cannot validate") was the helper that ran
bash -n to check syntax. The fallback parameter was supposed to let callers
define behavior when bash wasn’t available. But the fallback was a non-None string —
and the caller (split_commands) had a check like if result is not None: raise ValueError.
So in any environment where bash wasn’t on PATH, the fallback fired, returned
"Cannot validate", and the caller raised ValueError instead of taking the safe
return [script] path.
The fix: change fallback=None. When bash is absent, return None, let the caller
see None, take the safe path. Obvious in hindsight.
This kind of bug hides during the soak period because the fallback path is never
exercised in normal operation — bash is always available in production. It surfaces
during cleanup when you’re forcing the has_error path in tests.
The pattern
The sequence that worked:
-
Introduce the new thing with the old thing as fallback. Don’t block the migration on edge cases — ship the new parser as primary, keep the old one for safety.
-
One release cycle. Not a sprint, not three months. One release. Long enough to catch silent regressions; short enough that the fallback doesn’t become permanent.
-
Define the stable release you’re waiting for. vague soak windows stay open forever. “We’ll remove it after v0.34.0 ships” is a commitment.
-
Remove cleanly and run the tests. Removal tends to surface latent bugs that were masked by the fallback. Treat those as features of the removal process, not obstacles to it.
The result is a simpler shell.py, one fewer pip dependency, and confidence that
the new parser handles the actual usage pattern — not just the cases you thought about
when you wrote the migration.
The PR: gptme/gptme#3944 — 38/38 shell parser tests passing, bashlex removed.