[Bug] Heredoc shebangs (!) still trigger history expansion → 300s timeout in **0.2.1-alpha.1** — independent repro, cross-verification, and one-line fix verified (follow-up to #3373 / #5046)

[mengjie-du]

Summary

The persistent bash tool still mis-expands ! inside $'...'-wrapped commands on bash 3.2.57 (macOS default shell), causing the entire wrapped command — including the completion markers — to be discarded by history expansion before execution. The tool then waits for an end marker that will never appear, burns the full 300 s deadline, and resets the shell. The model receives only a timeout notice and no error output, so retries the same command and times out again.

This is the same root cause already documented in #3373 (first report, on 0.1.0-rc.7) and #5046 (summary post, source-verified at commit cd5ef81481, the 0.1.2-alpha.1 era). This post is an incremental confirmation: the bug is still present in 0.2.1-alpha.1 (the newest release, published 2026-10-03), across the entire published version line, together with an independent reproduction, a cross-verification matrix, and a working verification of the one-line fix already proposed in #5046.

Environment

• @deepseek-ai/dsh 0.2.1-alpha.1 (dsh web host)
• @deepseek-ai/dsh-tool-bash-persistent 0.2.1-alpha.1, backendType: "shell" (defaults)
• node-pty 1.2.0-beta.15, @xterm/headless 6.0.0
• macOS (Darwin), /bin/bash 3.2.57 (default), persistent shell spawned as bash --noprofile --norc -i, PS1='dsh> ', init send stty -echo, cols=160/rows=40
• All settings stock; no shell rc files involved (--noprofile --norc)

Real-world impact (observed in a live session)

An agent session writing a ~200-line Python script to a file via a heredoc:

cd <workspace> && cat > export_script.py <<'PY'
#!/usr/bin/env python3
"""Export a feature extractor module."""
...
PY
echo 'written export_script.py'

• The write succeeded for a sibling file whose heredoc body contains no ! (a 7,095-byte module, completed in 0.2 s).
• The write failed three times in a row for the script whose body starts with #!/usr/bin/env python3 (7,059 bytes; three attempts — two near-identical retries, the third a shortened body behind a <<'EOF' delimiter): each attempt timed out after 300 s, and the file was never created.
• Each timeout returned to the model: Your command timed out after 300 seconds or experienced an OOM error. Below is partial output: followed by the LOST_PREFIX_MESSAGE note ("The beginning of this command output was dropped by the terminal scrollback limit") and a prompt residue — no trace of the actual bash error, so the model had no way to self-correct and retried identically.

For agent workloads this is a silent, self-reinforcing failure: heredocs that emit scripts (the single most common pattern for writing code files) fail exactly when they carry a shebang, and the timeout framing makes the model believe the command is slow, not dead.

Minimal reproduction

In the persistent bash tool, run:

cat > /tmp/repro.py <<'PY'
#!/usr/bin/env python3
print("hi")
PY
wc -l /tmp/repro.py

Observed: 300 s timeout, /tmp/repro.py never created, shell reset. Control: removing the shebang line makes the same command complete in <1 s.

Root cause (independently confirmed; matches #5046)

No new mechanism is claimed here — this repro validates the chain already described in #5046 at the current version:

1. quoteForBash() encodes the model's multi-line command into a single physical line as eval -- $'...' with ' → \' and \n → \n.
2. In interactive bash (3.2.57), history expansion runs before parsing, and its quote scanner does not understand ANSI-C $'...': the first \' inside the payload terminates the scanner's single-quote region, so everything after it is treated as unquoted.
3. Any ! in that region — most commonly the #!/usr/bin/env python3 / #!/bin/bash first line of a heredoc body — is read as an event designator. With no matching history entry, bash prints bash: !/usr/bin/env: event not found and discards the entire physical line.

The discard explains the symptom signature: the printf for the start marker is part of the same discarded line, so neither __DSH_PERSISTENT_BASH_START_*__ nor the end marker ever reaches the terminal. commandOutput()/partialOutput() then find no start marker at all, which is exactly why the model-visible partial output carries the LOST_PREFIX_MESSAGE.

Secondary behavior worth noting for recovery logic

Reproducing outside dsh (node-pty PTY, faithful re-implementation of the exact spawn/env/init/wrap sequence from 0.2.1-alpha.1) shows:

• bash emits bash: !/usr/bin/env: event not found and returns to the dsh> prompt within milliseconds of the line being written; there is no running child at that point.
• The tool nevertheless waits the full 300 s, because its completion contract is marker-based and the markers were discarded with the line.

This supports the recovery taxonomy sketched in #5046: a missing end marker means "command not confirmed", not "a foreground child is still running". On the history-expansion path specifically, the shell is idle-and-prompted while the tool keeps polling, which also explains why the reset-and-retry loop cannot self-heal.

Cross-verification matrix

Faithful PTY reproduction of the 0.2.1-alpha.1 execution path (same spawn args, PS1/PROMPT_COMMAND env, stty -echo init, same quoteForBash/wrapCommand/marker logic, one-shot write(wrapped + "\r")):

#	Input	Result
1	Real failing command from the session (heredoc with shebang, wrapped to 7,507 chars)	✗ hangs; bash: !/usr/bin/env: event not found; no start marker ever emitted
2	Real succeeding command from the same session (heredoc without !, 7,522 chars)	✓ completes in 2.3 s, markers OK
3	Failing command minus the shebang line	✓ completes in 2.3 s
4	Succeeding command plus a #!/usr/bin/env python3 first line	✗ hangs, same event not found
5	Failing command, after replaying the 25 most recent real session commands as history	✗ same hang, same signature as the live session
6	Failing command, after set +H	✓ completes in 2.2 s, markers OK, exit code 0

Rows 3–4 isolate the shebang's ! as the sole trigger; rows 1/2/6 confirm the fix.

Version audit (npm tarballs)

quoteForBash has been present since the first published release, and no published version disables history expansion in the init send:

@deepseek-ai/dsh-tool-bash-persistent	init send	set +H present
0.0.1-rc.1 (2026-08-10)	(no stty init yet; quoteForBash already present)	no
0.1.0-rc.7 (reported in #3373)	stty -echo	no
0.1.2-rc.1 (0.1.2-alpha era; #5046's source verification was at commit cd5ef81481)	stty -echo	no
0.1.5-rc.1 / 0.1.7-rc.2	stty -echo	no
0.2.0-rc.2	stty -echo	no
0.2.1-alpha.1 (2026-10-03, newest)	stty -echo	no

So the issue is not a regression of the 0.2.x line — it has simply never been fixed since the first release, while the affected user base (macOS default bash) hits it routinely whenever an agent writes a script file with a shebang.

Fix: one line in the init send (as already scoped in #5046), verified

The fix location agreed in #5046 — keep it in the awaited, tool-scoped init send rather than in DEFAULT_BASH_ARGS — is what I patched locally and verified:

--- a/dsh-tool-bash-persistent/lib/index.js
+++ b/dsh-tool-bash-persistent/lib/index.js
@@
-					text: "stty -echo",
+					text: "stty -echo; set +H",

After this change, the exact command that previously hung for 300 s completes in ~2.2 s with normal start/end markers and exit code 0 (matrix row 6). An agent shell has no use for ! history designators, so defaulting history expansion off for this PTY is behavior-preserving for every legitimate tool call (row 2 and all non-! commands unaffected).

For a regression fixture (per the shape noted in #5046): the test command must contain a \' in the payload before the ! — e.g. a quoted string followed by a shebang line inside a heredoc — otherwise the quote scanner stays inside $'...' and the ! is not mis-expanded; e.g. on bash 5.x the same test should simply pass.

One caveat for the fix's blast radius, already discussed in #5046: set +H only affects the persistent interactive shell of this tool. It does not change behavior for non-persistent/sandboxed bash paths (which are non-interactive and don't expand history anyway), and it does not alter HISTSIZE/history recording (arrows/up-history via readline keep working — only ! designator expansion is disabled).

References

• BUG: 持久 bash 工具会把单引号参数里的 ! 触发历史展开，整条命令被拒绝执行（macOS 上表现为 300s 超时） #3373 — original report (single-quoted args containing !, 0.1.0-rc.7, macOS 300 s timeout)
• [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 #5046 — root-cause summary post (source-verified to 0.1.2-alpha.1; bash 3.2.57 vs 5.3.9; one-line fix; recovery taxonomy; regression-fixture shape)
• 用户命令在 ! 前含单引号时，若 persistent shell 默认 histexpand on，! 会被 history expansion 展开，导致 PS2 挂起或 event not found，进而 DSH 300s 超时 #7858 — echo '#!/bin/bash' > f variant; single-quote-before-! pattern
• [Bug] macOS: persistent Bash tool hangs on commands containing ! in sdk-minimal #8591 — sdk-minimal bundle: printf '%s\n' 'Hello, World!' hangs the same way
• 极简模式中 Agent Bash 工具遇命令裸 ! 卡住：dsh 持久 shell 的 history expansion 中止包装命令 #6768 — bare ! inside long single-quoted Swift one-liner hangs the bash tool

[argszero]

Independent confirmation from the newest tree, plus one source-level fact about the 300 s that your report observes but does not attribute — and the one link we could not close.

Still unfixed after 0.2.1-alpha.1. On origin/master at d743267388 (the commit that carries the 0.2.1-alpha.2 release) the awaited init send is byte-for-byte the one your version audit lists:

packages/shell/tool-bash-persistent/src/index.ts:272-277

const setup = ctx.terminals.startSend(owner, spawned.sessionId, {
  text: 'stty -echo',
  submit: true,
  signal: combinedSignal,
})

and a search for histexpand / set +H across packages/, apps/ and docs/ returns nothing. So your table extends by one row — 0.2.1-alpha.2 → init send stty -echo, set +H absent — and the conclusion holds for the newest tree as well: this has never shipped.

Why an idle-and-prompted shell still costs the full deadline. The completion loop is packages/shell/tool-bash-persistent/src/index.ts:321-389, one while (true) whose only non-deadline exits are: the command deadline (:306, config.timeoutMs, default 300_000 at :459), caller abort, an end marker found in the scrollback, session_exit, and result.waitReason === 'stdin_read' (:382). Every other settlement of the send falls through to await pause() (:389) and re-sends. A discarded line therefore costs exactly timeoutMs, never less.

The settle route that would notice "the shell is back at its prompt with nothing running" without a marker is structurally unavailable on darwin:

packages/subprocess/subprocess-local/src/process-inspector.ts:519-521

isStdinWaiting(_pgid: number, _shellPid: number): boolean {
  return false
}

MacProcessInspector has no /proc equivalent of the Linux probe (:443), and foreground.inputWaiting is fed straight from it (packages/subprocess/subprocess-local/src/terminal.ts:161). The consumer then requires that flag twice over — packages/terminal/terminal-bash/src/session.ts:219-224 returns waiting on the group change and waiting && this.initialForegroundLeftWait on the same group, so false in means false out, on every poll. acceptsStdinWait at session.ts:576-580 is consequently never satisfied on macOS, and the exact-probe stdin_read settle below it can never fire. Whatever settles a discarded-line send on macOS, it is not the stdin-wait probe.

The one link we could not close, and it is the interesting one. With the probe out, settlement has to come from the prompt-marker path (promptSeen && promptTextSeen && foreground.processGroupId === shellPgid, session.ts:569-571) or else the send ends as inferred_idle — which the loop treats as "keep polling", hence the 300 s. a8dc6f9776 ("fix(pty): keep the controlled prompt so persistent bash settles fast", 2026-08-15) is the commit that made the marker path load-bearing for exactly this. Whether the marker path actually completes after history expansion aborts the line — bash prints the error and reprompts, so it ought to — is the one step we did not reproduce in a live product PTY, and we would rather hand you the question than assert an answer. If it does complete, the 300 s is inferred_idle looping; if it does not, there is a second defect under the first, and it is worth knowing which before the recovery logic in your last section is written.

Fix location confirmed unchanged, and still the right one. await setup.done follows the init send immediately (:279-281), so appending ; set +H stays tool-scoped and race-free — no synchronization, no change to the completion contract. Please keep it out of DEFAULT_BASH_ARGS (packages/terminal/terminal-bash/src/config.ts:65): that array is shared with human terminals, where ! designators are a feature.

Regression fixture shape. Agreed, and it matches what we checked on the earlier threads in this family: the payload needs a \' — any ' in the command, which quoteForBash turns into \' — before the at-risk !, because the first \' is what ends the scanner's quoted region. A heredoc whose body starts with #!/usr/bin/env … after a quoted string is the canonical case; !(, exempt on bash ≥ 4 but not on the 3.2 default this family is about, is worth keeping in the fixture as a version-sensitive row.

[argszero]

Thanks for the independent repro and the verified one-line fix — the measurements here match what we see on d743267388 (0.2.1-alpha.2): the persistent shell still initializes with stty -echo and no set +o histexpand, so the hazard is unchanged on the current HEAD.

For deployments that cannot patch upstream, this gap now has a plugin-form option, so the failure mode stops being a five-minute silence:

@argszero/dsh-histexpand-guard@0.1.0 — https://www.npmjs.com/package/@argszero/dsh-histexpand-guard (source: https://github.com/argszero/dsh-histexpand-guard)

Mount it like any bundle patch — it ships cordis.patch.yml, and changes nothing else:

- insert:
    - id: histexpand-guard
      name: '@argszero/dsh-histexpand-guard'

What it does, and what it deliberately does not:

• It decides at tools/pre-execute, before the body runs and before any approval prompt, and denies the call with a reason the model can read — so a command that would have been dropped by the expander never reaches the shell and never costs 300 seconds.
• The rule is measured, not reasoned. It refuses a ! that history expansion would act on: one that is not preceded by a backslash, whose follower is not a space or = (a tab does not inhibit), and that is not inside a comment the expander honours. scripts/calibrate-history-expansion.py builds the exact line the wrapper builds, feeds it to a real interactive bash, and compares verdicts — 45/45 agreement on the pinned corpus. Both spellings you list are in it: printf '%s\n' '#!/bin/sh' and cat > x.sh <<'EOF' with a #!/usr/bin/env bash body.
• It never acts on the one-shot bash tool (@deepseek-ai/dsh-tool-bash), whose bash -c shell is non-interactive and where a ! is ordinary text. Both packages register a tool named bash, so it reads the resolved definition and requires the persistent tool's shape (one required command parameter, bare-string result) before acting.
• It fails open: a scan that throws is logged and the call is allowed. mode: 'report' logs the same findings without refusing, and a histexpand_check tool answers the question on demand without running anything.
• arm: true writes your one line into the agent's live shell, for an operator who wants the complete fix without rebuilding anything.

To be clear about the division of labour: this is a guard, not the fix. Refusing the shapes a rule can prove is strictly weaker than removing the hazard — your set +o histexpand at initialization is still the change worth making, and it is the one thing a plugin cannot do (the shell is created inside the tool's own body). The plugin exists for the deployments that cannot patch it, and it is published so that the next person who hits the five-minute silence has an option that day rather than a diagnosis.

No runtime dependencies; verified against the 0.1.7-rc.2 and 0.2.0-rc.2 lines, with 28 tests plus an injected-defect suite (every mutation caught).