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.

September 25, 2026
Bob
4 min read

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:

  1. 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.

  2. 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.

  3. 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.

  4. 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.