Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

fix(core): the Shell line fallback follows the resolved shell, not the platform (#487)

Yaowei Zheng7dc76ea8f50f
diff --git a/changelog/unreleased/2026-08-27-shell-line-fallback-follows-the-shell.md b/changelog/unreleased/2026-08-27-shell-line-fallback-follows-the-shell.md
new file mode 100644
index 00000000..af29b97c
--- /dev/null
+++ b/changelog/unreleased/2026-08-27-shell-line-fallback-follows-the-shell.md
@@ -0,0 +1,17 @@
+# The Shell line fallback follows the resolved shell instead of the platform
+
+- **Date:** 2026-08-27
+- **Type:** fix
+- **Scope:** `core`
+- **PR:** [#487](https://github.com/Prism-Shadow/penguin-harness/pull/487)
+
+[中文版](2026-08-27-shell-line-fallback-follows-the-shell.zh.md)
+
+The `- Shell: <name>` line that render-time assembly injects into system prompts built from pre-`{{SHELL}}` templates was gated on the platform being Windows. That gate was replaced with one on the shell that actually resolved, so a pre-`{{SHELL}}` Agent on macOS or Linux is told about a `zsh`, `dash` or `sh` too.
+
+## Details
+
+- The line was injected on Windows alone, because bash was taken as implied everywhere else. `system_config.yaml` is baked at Agent creation and never auto-upgraded, so a template written before the `{{SHELL}}` placeholder shipped carried no shell line at all and left its model writing bash syntax — `[[ ]]`, arrays, `${var,,}`, process substitution. [The POSIX shell fallback chain](../0.2.7/2026-08-27-posix-shell-fallback.md) retired the premise the gate rested on: a machine with no bash resolved `zsh`, `dash` or `sh`, and exactly those pre-`{{SHELL}}` Agents were left unaware of it.
+- Where bash resolved — the overwhelmingly common case on every platform, a Windows box with Git for Windows included — the assembled prompt was left byte-identical, because bash is what those templates already imply. That byte-identity guarantee was restated in terms of which shell resolved rather than which platform is running.
+- Where bash did not resolve, POSIX took the injection path Windows already took: the line landed directly under the `# Environment` heading, or was appended as a final line when the template had no such section, and a prompt already carrying a `- Shell:` line was left untouched. Nothing was written back to the stored template.
+- The design spec was updated to match ([penguin-harness-design #69](https://github.com/Prism-Shadow/penguin-harness-design/pull/69)).
diff --git a/changelog/unreleased/2026-08-27-shell-line-fallback-follows-the-shell.zh.md b/changelog/unreleased/2026-08-27-shell-line-fallback-follows-the-shell.zh.md
new file mode 100644
index 00000000..0bd34967
--- /dev/null
+++ b/changelog/unreleased/2026-08-27-shell-line-fallback-follows-the-shell.zh.md
@@ -0,0 +1,17 @@
+# Shell 行兜底改按解析出的 shell 判别,不再按平台
+
+- **Date:** 2026-08-27
+- **Type:** fix
+- **Scope:** `core`
+- **PR:** [#487](https://github.com/Prism-Shadow/penguin-harness/pull/487)
+
+[English](2026-08-27-shell-line-fallback-follows-the-shell.md)
+
+组装期向 pre-`{{SHELL}}` 模板注入的 `- Shell: <name>` 行原先以「平台是否为 Windows」为判据。该判据改为「实际解析出的 shell 是什么」,macOS 与 Linux 上的 pre-`{{SHELL}}` Agent 同样会被告知自己跑在 `zsh`、`dash` 还是 `sh` 里。
+
+## 细节
+
+- 该行原先只在 Windows 上注入,因为别处的 shell 被当作必然是 bash。`system_config.yaml` 在 Agent 创建时固化、不自动升级,`{{SHELL}}` 占位符出现之前写就的模板根本没有 shell 行,模型便一直书写 bash 语法——`[[ ]]`、数组、`${var,,}`、进程替换。[POSIX shell 回退链](../0.2.7/2026-08-27-posix-shell-fallback.zh.md)终结了这条判据所依赖的前提:没有 bash 的机器会解析出 `zsh`、`dash` 或 `sh`,而恰恰是这批 pre-`{{SHELL}}` Agent 对此一无所知。
+- 解析出 bash 时——任何平台上的绝大多数情形,包括装有 Git for Windows 的 Windows——组装结果逐字节不变,因为 bash 正是这批模板的隐含预期。这条逐字节不变的保证随之改以「解析出哪个 shell」而非「跑在哪个平台」陈述。
+- 解析结果不是 bash 时,POSIX 走 Windows 早已在走的同一条注入路径:该行落在 `# Environment` 标题正下方,模板没有这一段时作为末行追加,已带 `- Shell:` 行的提示词保持原样。磁盘上的模板不被改写。
+- 设计规格已同步改写([penguin-harness-design #69](https://github.com/Prism-Shadow/penguin-harness-design/pull/69))。
diff --git a/packages/core/src/internal/session-support.ts b/packages/core/src/internal/session-support.ts
index 5ffaac8d..1716e4a5 100644
--- a/packages/core/src/internal/session-support.ts
+++ b/packages/core/src/internal/session-support.ts
@@ -51,8 +51,8 @@ export function sessionEnvironment(
modelId: ids.modelId,
platform: process.platform,
osVersion: getOsVersion(),
- // The shell exec_command actually runs (bash on POSIX; resolved on Windows): the model
- // must know whether to write bash or PowerShell syntax.
+ // The shell exec_command actually runs, resolved once per process on every platform: the
+ // model must know whether to write bash, PowerShell or plain POSIX syntax.
shell: sessionShell().name,
date: formatLocalDate(date),
};
diff --git a/packages/core/src/state/agent-state.ts b/packages/core/src/state/agent-state.ts
index df54a8c8..84610a61 100644
--- a/packages/core/src/state/agent-state.ts
+++ b/packages/core/src/state/agent-state.ts
@@ -631,17 +631,22 @@ export async function listScheduleNames(
}
/**
- * Windows compatibility fallback for pre-`{{SHELL}}` system prompt templates.
+ * Compatibility fallback for pre-`{{SHELL}}` system prompt templates.
*
* `system_config.yaml` is baked at Agent creation and never auto-upgraded, so an Agent created
* before the `{{SHELL}}` placeholder existed never tells its model which shell `exec_command`
- * speaks — and on Windows (where the shell may be PowerShell, not bash) the model then keeps
- * emitting bash syntax into the wrong shell. When the platform is win32 and the template carries
- * no `{{SHELL}}` placeholder, inject a `- Shell: <shell>` line into the assembled prompt at
- * render time: right after the Environment section heading when one exists, else appended as a
- * minimal final line. In-memory only — the stored template is never rewritten. On POSIX the
- * assembled prompt stays byte-identical (bash was always implied there), and a prompt that
- * already carries the exact line is left untouched (idempotent).
+ * speaks. Such a template was written when bash was the only shell commands ever ran in, so the
+ * model keeps emitting bash syntax into whatever the session actually resolved — PowerShell on
+ * Windows, and zsh / dash / sh on a POSIX box that has no bash. When the resolved shell is not
+ * bash and the template carries no `{{SHELL}}` placeholder, inject a `- Shell: <shell>` line
+ * into the assembled prompt at render time: right after the Environment section heading when
+ * one exists, else appended as a minimal final line. In-memory only — the stored template is
+ * never rewritten, and a prompt that already carries a `- Shell:` line is left untouched
+ * (idempotent).
+ *
+ * The gate is the resolved shell, not the platform: wherever bash resolved — the overwhelmingly
+ * common case on every platform — the assembled prompt stays byte-identical, because bash is
+ * precisely what these templates already imply.
*
* Retirement condition: remove this fallback once pre-`{{SHELL}}` Agent configs (created before
* the placeholder shipped in PR #79) are no longer expected in the wild.
@@ -651,8 +656,9 @@ function withShellLineFallback(
template: string,
sessionEnvironment?: SessionEnvironmentValues,
): string {
- if (sessionEnvironment?.platform !== "win32") return assembled;
- if (!sessionEnvironment.shell) return assembled;
+ if (!sessionEnvironment?.shell) return assembled;
+ // Bash is what a pre-`{{SHELL}}` template already implies; only a different shell needs saying.
+ if (sessionEnvironment.shell === "bash") return assembled;
if (template.includes(SHELL_PLACEHOLDER)) return assembled; // The template already renders the line itself.
// Any existing `- Shell:` line means the model is already told a shell — including a custom
// template hardcoding a different value on purpose; never add a second, contradicting line.
@@ -678,8 +684,9 @@ const SECTION_PLACEHOLDER_PATTERN = /\{\{(?:MEMORY|VAULT|SKILLS|SCHEDULES)\}\}/g
* template, and the # Vault / # Skills / # Memory / # Scheduled Tasks statements live in the
* editable `vault.prompt` / `skills.prompt` / `memory.prompt` / `schedules.prompt` config (the
* Prompt is fully transparent and editable via `system_config.yaml`). Other files in Agent
- * State / Workspace are never auto-injected. Sole exception: on win32 a template without
- * `{{SHELL}}` gets a `- Shell:` line injected at render time (see `withShellLineFallback`).
+ * State / Workspace are never auto-injected. Sole exception: a template without `{{SHELL}}`
+ * gets a `- Shell:` line injected at render time when the resolved shell is not bash (see
+ * `withShellLineFallback`).
*
* `{{VAULT}}` expands to the rendered `vault.prompt` (its `{{VAULT_KEYS}}` carrying the
* key-name list — names only, values never enter the context), `{{SKILLS}}` to `skills.prompt`
diff --git a/packages/core/test/state.test.ts b/packages/core/test/state.test.ts
index caf42e53..6c73770a 100644
--- a/packages/core/test/state.test.ts
+++ b/packages/core/test/state.test.ts
@@ -629,7 +629,9 @@ describe("assembleSystemPrompt", () => {
modelId: "deepseek-v4-pro",
platform: "darwin",
osVersion: "Darwin 25.0.0",
- shell: "zsh",
+ // The shell a pre-{{SHELL}} template already implies, so the compatibility fallback
+ // stays out of this assertion; its own cases live in their describe block below.
+ shell: "bash",
date: "2026-06-30",
});
expect(prompt).toBe("base prompt");
@@ -728,9 +730,10 @@ describe("assembleSystemPrompt", () => {
expect(prompt.indexOf("Model ID:")).toBeLessThan(prompt.indexOf("Session ID:"));
});
- // The win32 Shell-line fallback for pre-{{SHELL}} templates (system_config.yaml is baked at
- // Agent creation and never auto-upgraded). Removable together with `withShellLineFallback`
- // once pre-{{SHELL}} Agent configs are no longer expected in the wild.
+ // The Shell-line fallback for pre-{{SHELL}} templates (system_config.yaml is baked at Agent
+ // creation and never auto-upgraded), gated on the resolved shell rather than the platform.
+ // Removable together with `withShellLineFallback` once pre-{{SHELL}} Agent configs are no
+ // longer expected in the wild.
describe("Shell line fallback for templates without {{SHELL}}", () => {
const stateWithPrompt = (system_prompt: string) => ({
root: tmpRoot,
@@ -782,19 +785,21 @@ describe("assembleSystemPrompt", () => {
expect(prompt.split("- Shell: pwsh").length - 1).toBe(1);
});
- it("keeps POSIX output byte-identical (no injected line)", () => {
- for (const platform of ["linux", "darwin"]) {
+ // Bash is what a pre-{{SHELL}} template already implies, so a resolved bash needs no line
+ // — on every platform, Windows included.
+ it("keeps the prompt byte-identical wherever bash resolved (no injected line)", () => {
+ for (const platform of ["linux", "darwin", "win32"]) {
const prompt = assembleSystemPrompt(stateWithPrompt(preShellTemplate), {
...envFor(platform),
shell: "bash",
- osVersion: "Linux 6.1.0",
+ osVersion: "OS 1.0",
});
expect(prompt).toBe(
[
"intro",
"# Environment",
`- Platform: ${platform}`,
- "- OS Version: Linux 6.1.0",
+ "- OS Version: OS 1.0",
"- Date: 2026-07-27",
"",
"# Tail section",
@@ -805,6 +810,35 @@ describe("assembleSystemPrompt", () => {
}
});
+ // Shell resolution falls back to zsh / dash / sh on a POSIX box without bash, and a
+ // pre-{{SHELL}} template would otherwise leave the model writing bash syntax into it.
+ it("injects the line on POSIX when the resolved shell is not bash", () => {
+ for (const { platform, shell } of [
+ { platform: "linux", shell: "dash" },
+ { platform: "darwin", shell: "zsh" },
+ ]) {
+ const prompt = assembleSystemPrompt(stateWithPrompt(preShellTemplate), {
+ ...envFor(platform),
+ shell,
+ osVersion: "OS 1.0",
+ });
+ expect(prompt).toBe(
+ [
+ "intro",
+ "# Environment",
+ `- Shell: ${shell}`,
+ `- Platform: ${platform}`,
+ "- OS Version: OS 1.0",
+ "- Date: 2026-07-27",
+ "",
+ "# Tail section",
+ "tail",
+ ].join("\n"),
+ );
+ expect(prompt.split(`- Shell: ${shell}`).length - 1).toBe(1);
+ }
+ });
+
it("does not duplicate the line when the template has {{SHELL}}", () => {
const template = [
"# Environment",