[Bug] persistent bash mis-expands ! in commands via history expansion; bash 3.2.57 (incl. macOS default) hangs until timeout (shebangs in heredocs) - one-line fix

[guojunyuan2004]

Summary

The persistent bash tool wraps each command into a single physical line and sends it to an interactive bash in a PTY. On bash 3.2.57 (macOS default; reproduced on Linux with a compiled 3.2.57), history expansion runs before parsing, and its quote scanner does not understand ANSI-C $'...'. The \' escapes produced by the tool's own quoting terminate the scanner's single-quote region, so a later ! in the command body (most commonly #!/bin/bash inside a heredoc, or JS negations like if (!m)) is read as an event designator. Bash prints event not found and discards the entire physical line, including both completion markers; the tool then polls until its timeout (default 300 s on macOS) and resets the shell, looking like a hang. Not reproduced on Linux bash 5.3.9 (its history scanner protects $'...', so the tool's wrapping is unaffected). Fix: append set +o histexpand to the shell init.

中文摘要：bash 3.2.57 的历史展开在解析前误读工具包装用的 $'…'，把命令里的 ! 当事件指示符并丢弃整行，工具等到超时后 reset；修复为初始化时追加 set +o histexpand。详见下文验证。

Environment

• Verified against master cd5ef81481 (tag dsh-v0.1.2-alpha.1, merged 2026-08-28; still the tip as of 2026-08-30) and b150a551b8 (dsh-v0.1.1-rc.2); packages/shell/tool-bash-persistent/src/index.ts is identical in both, and line 268 reads text: 'stty -echo',.
• macOS /bin/bash 3.2.57(1)-release (the default); the shell is spawned with --noprofile --norc -i (packages/terminal/terminal-bash/src/config.ts).
• Linux (WSL2/Ubuntu 26.04): reproduced with bash 3.2.57 built from bash-3.2.57.tar.gz — GNU bash, version 3.2.57(2)-release (x86_64-unknown-linux-gnu); build dir and tarball removed afterwards.
• Not reproduced on Linux bash 5.3.9 (distro default). Intermediate bash 4.x not tested; no !( version boundary is claimed.

Trigger surface

On affected bash 3.2.57, a command fires when wrapping leaves a ! outside history expansion's quote tracking. Observed:

• Quoted-heredoc shebangs: cat > script.sh <<'EOF' ... EOF with #!/bin/bash or #!/usr/bin/env node — the common agent-authored shape; simple heredocs work, script-writing heredocs hang.
• JS/TS negations: if (!m) { ... }, if (!res.ok) ..., !line.startsWith(...).
• echo 'hello!world', rg --files -g '!node_modules' (as in 极简模式grep等命令卡死问题复现以及解决方案 #3634).
• Not affected: ! followed by space / tab / newline / = (! cmp -s a b, a != b). !( is not exempt on the tested 3.2.57.
• Silent rewrite: when the event designator matches history (!!, !$, or a !word prefix of an earlier command), the line is rewritten instead of erroring; reproduced !! injecting the previous command.

Reproduction (no DSH install, no PTY needed)

Paste this into affected bash 3.2.57; it feeds the same physical-line shape wrapCommand() emits into an interactive bash:

bash --noprofile --norc -i <<'REPRO'
printf '%s\n' '__DSH_START__'; eval -- $'cat <<\'EOF\'\n#!/bin/bash\nhello\nEOF'; __dsh_persistent_bash_status=$?; printf '%s%s\n' '__DSH_END__:' "$__dsh_persistent_bash_status"
REPRO

Observed on bash 3.2.57 (prompt echo trimmed):

bash: !/bin/bash\nhello\nEOF': event not found

Neither marker appears — the whole line was discarded; same on the Linux-compiled 3.2.57. On bash 5.3.9 the same block prints both markers plus the heredoc body with __DSH_END__:0. With set +o histexpand sent first (the fix):

__DSH_START__
#!/bin/bash
hello
__DSH_END__:0

Smallest scanner illustration (the only difference is the \' before the !; also reproduces on Linux-compiled 3.2.57; on 5.3.9 neither line errors):

eval -- $'echo hi\n#!/bin/bash\n'       # OK - the ! is still inside the scanner's quote region
eval -- $'echo \'hi\'\n#!/bin/bash\n'   # bash: !/bin/bash\n': event not found

Root cause

• wrapCommand() (index.ts:77-82) puts the whole command on one physical line: printf START; eval -- $'<escaped>'; status=$?; printf END status.
• quoteForBash() (index.ts:69-75) escapes \ as \\, ' as \', newlines as \n inside $'...' — safe for the parser.
• On affected bash 3.2.57, history expansion runs before parsing, with a quote scanner that understands \ and ' but not $'...'. The ' inside \' terminates the scanner's single-quote region, so the next ! is read as an event designator. (bash 5.3.9 protects $'...' here — mechanism inferred from behavior; see Linux verification.)
• On failed expansion, bash discards the whole physical line. Both markers live on that line, so commandOutput() never matches and the poll loop (index.ts:309-377) runs to the deadline (index.ts:301).

Why it waits the full timeout

• Here both markers are discarded and the shell stays alive, so the only early return would be stdin_read — the one wait reason that returns a fast partial (index.ts:372-375). Since it never settles (below), the loop polls until the tool's own timeoutMs (index.ts:301), then resets.
• After the discard the shell is back at its prompt, but stdin_read never settles:
  • macOS: the exact-probe path is disabled (MacProcessInspector.isStdinWaiting() returns false unconditionally, packages/subprocess/subprocess-local/src/process-inspector.ts), and the prompt-based path (session.ts:492-496) needs promptSeen/promptTextSeen, which never become true because after the error bash reprints dsh> without first emitting OSC 133;D (verified with a real PTY using the same PS1/PROMPT_COMMAND; after a normal command the marker returns).
  • Linux: the exact-probe path exists (LinuxProcessInspector.isStdinWaiting reads /proc/${pid}/task/${tid}/syscall), but it has a pre-write memory gate this failure cannot pass. setInitialForeground() samples the foreground group before the write (session.ts:138-140,313); acceptsStdinWait() accepts a stdin wait only after a poll has observed the shell leave stdin wait post-write (session.ts:143-149). A histexpand discard returns to readline within the same poll cycle, so that departure is never observed and the exact-probe settle (session.ts:499-501) never fires. This matches the Linux 3.2.57 tool-level test: no quick partial, wait to the tool deadline (5 s/10 s), then reset.
• The timeout is a symptom of marker loss, not evidence that a foreground child is still alive.

Linux verification (WSL2/Ubuntu 26.04)

Measured 2026-08-30 at cd5ef81481 with a WSL2 DSH.

bash 5.3.9 (distro default)

• histexpand is on by default, but 5.3.9 protects $'...' during history expansion: the non-PTY repro prints both markers plus the heredoc body with __DSH_END__:0, and eval -- $'echo \'hi\'\n#!/bin/bash\n' does not error. Double-quoted ! (echo "!/bin/bash") still errors, so history expansion is active — it just does not break the tool's $'...' wrapping.
• Real-PTY regression tests pass without the fix (confirmed against local src, not cache). With the fix, the bash tool ran the heredoc shebang in ~0.0108 s with no timeout/reset.

bash 3.2.57 (compiled from source on Linux)

• Non-PTY repro: with histexpand on, same failure as macOS — bash: !/bin/bash\nhello\nEOF': event not found, neither marker; with set +o histexpand first, it prints __DSH_START__ / #!/bin/bash / hello / __DSH_END__:0. The \'-vs-no-\' pair reproduces identically.
• Real-PTY tool-level (shellPath pointed at the compiled 3.2.57): with the fix, the heredoc shebang returns #!/bin/bash\nhello in ~24 ms. Without the fix, it fails; with timeoutMs set to 5 s/10 s it ran to the tool deadline and reset — a quick stdin_read partial was not observed, the same failure shape as macOS.
• Conclusion: the bug is bash-version-specific, not OS-specific. The fix is necessary on 3.2.57 and harmless/redundant on 5.3.9.

Suggested fix (one line)

--- a/packages/shell/tool-bash-persistent/src/index.ts
+++ b/packages/shell/tool-bash-persistent/src/index.ts
@@ -268 +268 @@
-          text: 'stty -echo',
+          text: 'stty -echo; set +o histexpand',

(set +H is the equivalent short form.)

• Matches non-interactive bash semantics (non-interactive shells keep histexpand off); the init is re-sent after every shell reset.
• Scoped to the persistent-bash tool's own shell (init awaited via await setup.done, index.ts:272); putting +H in DEFAULT_BASH_ARGS would affect every default shell backend session, so not there.
• The existing unit-test stub matches request.text.startsWith('stty -echo') (packages/shell/tool-bash-persistent/tests/tools.spec.ts), so it stays green.
• Suggested regression tests (real PTY with --noprofile --norc -i; on affected 3.2.57 both fail with the current init, on 5.3.9 they pass even without the fix, so the regression must run on affected 3.2.57):

Regression tests (TypeScript, loader-composition.spec.ts)

const shebangHeredoc = text(await execute(
  'heredoc-shebang',
  "cat <<'EOF'\n#!/bin/bash\nhello\nEOF",
))
expect(shebangHeredoc).toBe('#!/bin/bash\nhello')

const bangHeredoc = text(await execute(
  'heredoc-bang',
  "cat <<'EOF'\nif (!m) { console.log('matched') }\nEOF",
))
expect(bangHeredoc).toBe("if (!m) { console.log('matched') }")

The fixtures use a quoted heredoc delimiter (<<'EOF') so quoteForBash emits a \' before the !; a bare ! with no preceding escaped quote stays inside the scanner's single-quote region and passes even with the bug. On 5.3.9 neither shape fails.

Alternatives considered

• Escaping ! in quoteForBash(): not reliable — on the tested 3.2.57 $'\!' yields a literal \! (measured); 5.3.9 was not tested for this escape. Turning histexpand off removes the whole failure class.
• Writing the command to a temp file and sourcing it instead of eval --: larger change; would also address the eval -- bashism noted in Bug: persistent-bash 的 eval -- 是 bashism，非 bash 持久 shell 下每条命令 exit 127 | eval -- breaks every non-bash persistent shell #2271.

Is disabling histexpand by default appropriate for this tool?

• The tool executes programmatically submitted commands; history expansion is an interactive convenience, and for agent-built command strings it is pure risk — silent rewrite at best, full-line discard and timeout at worst.
• Non-interactive bash already ships with histexpand off; the tool uses -i for prompt markers/session lifecycle, not for history expansion, so this aligns with non-interactive semantics.
• The change is scoped to this tool's own shell, not the user's login shell or other terminal sessions. A user who deliberately wants ! can send set -o histexpand as a separate first command; it just should not be the default.

Verdict: appropriate, and the one-line init is the right place.

Relationship to earlier reports

This consolidates and extends two earlier reports of the same root cause:

• BUG: 持久 bash 工具会把单引号参数里的 ! 触发历史展开，整条命令被拒绝执行（macOS 上表现为 300s 超时） #3373 (@stultuss) — same mechanism via single-quoted arguments, plus the macOS isStdinWaiting() aggravator credited above.
• 极简模式grep等命令卡死问题复现以及解决方案 #3634 (@crclz) — same one-line fix (set +H).
• New here: heredoc-shebang and JS/TS trigger surface, copy-paste repro needing neither DSH nor a PTY, silent-rewrite failure mode (!!/!$), regression tests, verification against current master cd5ef81481, and a Linux-compiled bash 3.2.57 run that isolates the bash version.
• Related but distinct: 【BUG】持久化 bash 工具偶发卡死 300 秒——PTY 交互 shell 进入 readline 补全等待状态时无人应答 #4329 (readline "Display all N possibilities?" wait), terminal-bash: persistent shell stalls for the full 300 s timeout on CJK input (C-locale readline reads UTF-8 bytes as Meta bindings) #3522/macOS: PTY persistent shell (official Minimal preset shell) hangs commands to the 300s timeout when command text contains CJK characters #2596/[Bug] macOS 上 bash 工具执行含中文命令会损坏并超时（bash 3.2 PTY 数据损坏） #3391 (CJK input corruption), [Bug] persistent bash each command waits 3.5s: CONTROLLED_PROMPT mismatch SHELL_PROMPT #3657/[Bug & Fix] 极简模式下 persistent bash 每次执行卡顿 3.5s+ 的根本原因与修复方案（附 Fork 分支） #2656 (settle delay), Bug: persistent-bash 的 eval -- 是 bashism，非 bash 持久 shell 下每条命令 exit 127 | eval -- breaks every non-bash persistent shell #2271 (eval -- bashism), Persistent Bash timeout message should not diagnose OOM #1186 (timeout message claims OOM).

Workaround today

Send set +o histexpand as its own first command in the persistent shell; re-send after a timeout-triggered reset. Do not put it on the same line as a command containing ! — history expansion runs when the whole physical line is read, before the setting takes effect. Or avoid ! inside single-quoted strings and heredoc bodies on affected 3.2.57.

[argszero]

Source-verified end to end at cd5ef81481 (0.1.2-alpha.1) — every link in your chain checks out, and I'd add one scoping judgment about the fix location that should survive into the PR.

1. The wrapper chain is exactly as described. quoteForBash (tool-bash-persistent/src/index.ts:69-75) emits $'...' with '→\' and \n→\n; wrapCommand (:77-83) keeps start-marker, eval --, status capture and end-marker on one physical line; the poll loop arms deadline(upstream, config.timeoutMs, TIMEOUT_CODE) (:297-299). Interactive bash's history expansion runs pre-parse with a scanner that only knows \ and ', so \' terminates its quote region and the next ! becomes !word — the whole physical line (markers included) is discarded, and commandOutput never matches until the deadline.

2. Fix location — the init send is the right scope; please keep it there. Appending to the init text at index.ts:268 (after stty -echo) is correct on two counts: the init send is awaited (await setup.done, :270-271) before the shell is handed out, so there is no race with the first wrapped command; and it scopes the change to the tool's own shell. The seemingly-cleaner alternative — +H in DEFAULT_BASH_ARGS (terminal-bash/src/config.ts:56) — would disable history expansion for every interactive bash, including human terminal sessions where ! history is expected UX. Worth a comment in the init text (or PR description) stating that choice explicitly, so a future cleanup doesn't "simplify" it into the shared spawn args.

3. macOS aggravator confirmed as structural, not a probe bug. MacProcessInspector.isStdinWaiting (subprocess-local/src/process-inspector.ts:506) returns false unconditionally — the Linux implementation reads /proc syscall tables (:440), which macOS has no analogue for. That's why Linux recovers fast (probe fires) while macOS burns the full 300 s. The prompt-marker stdin_read path is the only Mac fast path, and it's blind here because bash reprints dsh> after a histexpand error without emitting the OSC 133;D marker — your observation.

4. Design fragility worth a code comment. The deeper issue is that the tool's completion contract is "two markers on one physical line" — any input-level line discard (histexpand today, something else tomorrow) silently converts a 300 ms command into a 300 s timeout with a shell reset. The one-line fix removes the current discard source, but the marker contract itself is what makes the failure mode so expensive. A one-line comment in wrapCommand ("markers must survive any input-line discard; keep the wrapped line discard-proof") would keep future editors aware of the constraint.

5. Regression fixture. For a test that actually pins this: the failure requires the \' interaction — a quoted region before the ! (e.g. printf 'x'\n#!/bin/bash\n, or the echo 'hi' vs echo hi pair in your smallest illustration). A bare ! (e.g. echo !foo) is caught by bash's own !word handling differently and may pass even with the bug; only the escaped-quote-then-! shape reproduces the discard. Your reproduction block is exactly the right fixture shape — worth lifting into the test verbatim.

The consolidation of #3373 + #3634 + this thread into one diagnosis with repro + fix + test is exactly what the maintainers need; this is the strongest candidate in the shell-tool queue for when PRs reopen.

[guojunyuan2004]

Thanks — this is a thorough source-level review, and the scoping point about keeping the fix in the init send rather than DEFAULT_BASH_ARGS is exactly right. I've folded three of your notes into the post: the rationale for the init location (awaited and tool-scoped), the marker-contract fragility (two markers on one physical line), and the regression-fixture shape (the \' before the ! requirement). I also tightened the wrapCommand line range to :77-82.

[liyangbing]

This report adds a particularly important failure class to the persistent-terminal diagnosis: the wrapped physical input line can be discarded before Bash reaches the command, so the missing completion marker does not prove that the intended child process is still running.

That distinction matters for recovery. First capture the exact wrapper shape, Bash version, shell mode, start/end markers, and whether a child PID or process group exists. Then classify separately:

• history expansion rejected or rewrote the input line;
• the command started but the marker was lost;
• the child is still alive after the PTY call timed out; or
• the process is gone and only the UI card remains.

Do not press Enter repeatedly or resubmit a side-effecting command while the marker state is unknown. Confirm the process outcome and durable tool/turn close before retrying. A scoped init change for the persistent tool can be safer than changing shared interactive Bash defaults, but it still needs a real PTY regression test for the escaped-quote-plus-bang shape on the supported platforms.

The handbook terminal runbook has the lane classifier, marker evidence, process ownership and duplicate-side-effect recovery sequence: https://sandbaseai.github.io/deepseek-harness-handbook/long-running-terminal.html

It treats the 300-second display as a symptom, not proof of a live foreground process, and keeps the Bash workaround separate from approval and sandbox policy. The upstream report and the handbook are independent community evidence; neither should be read as proof that every Desktop wrapper uses the same shell path.

[guojunyuan2004]

Thanks — the framing that a missing end marker means "not yet confirmed", not "the child is still running", is an important distinction, and I've reflected the core of it in the post: the 300 s timeout is a symptom of marker loss, not evidence of a live foreground process. Thanks also for the additional pointers — useful context.

[guojunyuan2004]

更新说明 / Update note:

已在正文补充 WSL2/Ubuntu 26.04 的验证：bash 5.3.9 不复现；编译 bash 3.2.57 复现且一行修复有效。据此把结论从“macOS 问题”修正为“bash 3.2.57 低版本适配问题”，并补上了超时路径的代码级解释（Linux 上同样会等到工具 deadline 后 reset）。同时新增一节，讨论默认关闭 histexpand 对该工具本身是否合适。

Added WSL2/Ubuntu 26.04 verification (bash 5.3.9 does not reproduce; compiled 3.2.57 reproduces and the one-line fix works), reworded the conclusion as a bash-3.2.57 compatibility issue rather than a macOS issue, corrected the timeout-path explanation (Linux also waits to the tool deadline), and added a section on whether defaulting histexpand off is appropriate for this tool.

[landchenxuan]

Confirmed on macOS with Harness 47f943859bef60e4160492346772ded9b24f765a and Bash 3.2.57: a successful history match can also cause the 300-second hang.

In a real review run, !* in the valid Git pathspec ':!*.md' expanded to arguments from the previous wrapped command. This broke quoting and left Bash at its > continuation prompt. The tool reported a 300-second timeout; the full call took 306.7 seconds.

Reduced reproduction: submit these as two separate persistent Bash tool calls in the same shell:

printf '%s\n' seed

printf '%s\n' ':!*.md'

Using Harness's actual wrapper with Bash 3.2.57 reproduces the history substitution and continuation prompt. Replaying the original Git command through the real Harness PTY also timed out with history expansion enabled; sending set +H first returned the expected output. Disabling history expansion at shell startup also passed after a shell reset.