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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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",