fix(persistent-bash): distinguish shell exit status

packages/pty/tool-bash-persistent/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/pty/tool-bash-persistent/README.md
-README.md: 04c714d5489dbae8572e9339a4387a148450a0e9
-README.zh.md: adfb38b10409174d9558b963f5a2359cf819f04b
+README.md: 3f5ffbe50bed4a6ab8f7f11ebad47bf933bba1e8
+README.zh.md: 94882534b3a2f8aedf382db0376a19540e2ea0d1

packages/pty/tool-bash-persistent/README.md

@@ -10,7 +10,7 @@ Model-facing `bash(command)` backed by one owner-scoped `ctx.pty` shell. The pac
 |---|---:|---|
 | `backendType` | `shell` | Registered PTY backend used for each Agent shell. |
 | `timeoutMs` | `300000` | Wall-clock limit for one command; timeout closes the shell. |
-| `maxOutputChars` | `16000` | Prefix characters retained before the clipping notice. |
+| `maxOutputChars` | `16000` | Maximum retained command-output characters; fixed diagnostics are added afterward. |
 | `description` | Persistent-shell description | Model-facing environment contract. |
 
 ## Model Experience
@@ -33,11 +33,11 @@ Prefix-stable while the configured description and schema remain unchanged.
 
 #### What the model sees
 
-Commands share one shell per Agent, so cwd, exported variables, activated environments, functions, and background jobs persist across calls. Results exclude private completion markers and the shell prompt. Long output keeps the earliest retained prefix plus a clipping notice. If the PTY has already dropped that prefix, the result says so explicitly instead of presenting a tail as complete output. Timeout returns bounded partial output, closes the uncertain shell, and tells the model that the next call starts fresh.
+Commands share one shell per Agent, so cwd, exported variables, activated environments, functions, and background jobs persist across calls. Results exclude private completion markers and the shell prompt. A nonzero wrapped command appends `[exit code: N]`; a shell that exits before reporting that status instead appends `[shell exited: code N]`, `[shell killed by signal: SIG]`, or `[shell exited]` when the backend supplies neither, then resets and tells the model that the next call starts fresh. Long output keeps the earliest retained prefix plus a clipping notice. If the PTY has already dropped that prefix, the result says so explicitly instead of presenting a tail as complete output. Timeout returns bounded partial output, closes the uncertain shell, and reports the reset.
 
 #### Token effect
 
-Data-dependent and bounded by `maxOutputChars` plus the fixed clipping notice.
+Data-dependent. `maxOutputChars` bounds retained command output; fixed clipping, lost-prefix, status, timeout, and reset diagnostics can extend the result.
 
 #### KV Cache effect
 

packages/pty/tool-bash-persistent/README.zh.md

@@ -10,7 +10,7 @@
 |---|---:|---|
 | `backendType` | `shell` | 每个 Agent shell 使用的已注册 PTY 后端。 |
 | `timeoutMs` | `300000` | 单条命令的墙钟时间上限；超时会关闭 shell。 |
-| `maxOutputChars` | `16000` | 截断提示前保留的前缀字符数。 |
+| `maxOutputChars` | `16000` | 命令输出最多保留的字符数；固定诊断会在此后追加。 |
 | `description` | 持久 shell 描述 | 面向模型的环境契约。 |
 
 ## 模型体验
@@ -33,11 +33,11 @@
 
 #### 模型所见
 
-每个 Agent 的命令共享一个 shell，因此 cwd、导出的环境变量、已激活环境、函数和后台任务会跨调用保留。结果不包含私有完成标记和 shell 提示符。长输出保留仍可读取的最早前缀并追加截断提示；若 PTY 已丢弃真正的开头，结果会明确说明，而不是把尾部伪装成完整输出。超时返回有界的部分输出、关闭状态不确定的 shell，并告知模型下次调用从新 shell 开始。
+每个 Agent 的命令共享一个 shell，因此 cwd、导出的环境变量、已激活环境、函数和后台任务会跨调用保留。结果不包含私有完成标记和 shell 提示符。经封装的命令以非零状态结束时，结果会追加 `[exit code: N]`；若 shell 在报告该状态前退出，则改为追加 `[shell exited: code N]`、`[shell killed by signal: SIG]`，或在后端既未提供退出码也未提供信号时追加 `[shell exited]`；随后重置 shell，并告知模型下次调用从新 shell 开始。长输出保留仍可读取的最早前缀并追加截断提示；若 PTY 已丢弃真正的开头，结果会明确说明，而不是把尾部伪装成完整输出。超时返回有界的部分输出、关闭状态不确定的 shell，并报告该重置。
 
 #### Token 影响
 
-随数据变化，并受 `maxOutputChars` 与固定截断提示约束。
+随数据变化。`maxOutputChars` 限制保留的命令输出；固定的截断、前缀丢失、状态、超时与重置诊断可能使结果更长。
 
 #### KV Cache 影响
 

packages/pty/tool-bash-persistent/src/index.ts

@@ -174,21 +174,28 @@ function renderCaptured(output: CapturedOutput, maxOutputChars: number): string
   const withPrefix = output.incomplete && output.text.length > 0
     ? LOST_PREFIX_MESSAGE + rendered
     : rendered
-  return renderExitStatus(withPrefix, output.exitCode ?? 0, null)
+  const marker = output.exitCode !== undefined && output.exitCode !== 0
+    ? `[exit code: ${output.exitCode}]`
+    : undefined
+  return appendStatusMarker(withPrefix, marker)
 }
 
-function renderExitStatus(
+function appendStatusMarker(content: string, marker: string | undefined): string {
+  if (marker === undefined) return content
+  return content.length === 0 ? marker : `${content}\n${marker}`
+}
+
+function renderShellExitStatus(
   content: string,
   exitCode: number | null,
   signal: NodeJS.Signals | null,
 ): string {
   const marker = signal !== null
-    ? `[killed by signal: ${signal}]`
-    : exitCode !== null && exitCode !== 0
-      ? `[exit code: ${exitCode}]`
-      : undefined
-  if (marker === undefined) return content
-  return content.length === 0 ? marker : `${content}\n${marker}`
+    ? `[shell killed by signal: ${signal}]`
+    : exitCode !== null
+      ? `[shell exited: code ${exitCode}]`
+      : '[shell exited]'
+  return appendStatusMarker(content, marker)
 }
 
 function persistentShells(ctx: Context, config: ResolvedConfig): PersistentShells {
@@ -325,7 +332,7 @@ async function executeCommand(
       const snapshot = retainedScrollback(ctx, owner, id, latest)
       await shells.reset(owner, 'persistent bash shell exited')
       return [
-        renderExitStatus(
+        renderShellExitStatus(
           renderCaptured(partialOutput(snapshot, marker, fallback, fallbackTruncated), config.maxOutputChars),
           result.sessionStatus.exitCode,
           result.sessionStatus.signal,

packages/pty/tool-bash-persistent/tests/tools.spec.ts

@@ -79,6 +79,7 @@ type StubMode =
   | 'stalled-read'
   | 'exit'
   | 'signal-exit'
+  | 'unknown-exit'
   | 'wait-for-abort'
   | 'end-on-abort'
   | 'idle-then-normal'
@@ -184,12 +185,14 @@ class StubPtySession implements PtyBackendSession {
     const exitCode = this.mode === 'nonzero' ? 7 : 0
     const output = `${start ?? ''}\n${commandOutput}\n${end ?? ''}${exitCode}\n${this.motd}`
     this.scrollback += output
-    if (this.mode === 'exit' || this.mode === 'signal-exit') {
+    if (this.mode === 'exit' || this.mode === 'signal-exit' || this.mode === 'unknown-exit') {
       const exitedOutput = `${start ?? ''}\nhello from stub\n`
       this.scrollback = this.scrollback.slice(0, -output.length) + exitedOutput
       this.statusValue = this.mode === 'signal-exit'
         ? { kind: 'exited', exitCode: null, signal: 'SIGTERM' }
-        : { kind: 'exited', exitCode: 9, signal: null }
+        : this.mode === 'exit'
+          ? { kind: 'exited', exitCode: 9, signal: null }
+          : { kind: 'exited', exitCode: null, signal: null }
       return this.operation(Promise.resolve(this.result(exitedOutput, 'session_exit')))
     }
     return this.operation(Promise.resolve(this.result(output, 'stdin_read')))
@@ -339,7 +342,8 @@ describe('tool-bash-persistent', () => {
     session.mode = 'exit'
     const exited = text(await call(ctx, owner, 'exit'))
     expect(exited).toContain('hello from')
-    expect(exited).toContain('[exit code: 9]')
+    expect(exited).toContain('[shell exited: code 9]')
+    expect(exited).not.toContain('[exit code: 9]')
     expect(exited).toContain('next bash call starts from the workspace')
     expect(session.closed).toContain('persistent bash shell exited')
 
@@ -347,7 +351,8 @@ describe('tool-bash-persistent', () => {
     expect(stub.sessions).toHaveLength(2)
     const replacement = stub.sessions[1]!
     replacement.mode = 'signal-exit'
-    expect(text(await call(ctx, owner, 'kill shell'))).toContain('[killed by signal: SIGTERM]')
+    expect(text(await call(ctx, owner, 'kill shell')))
+      .toContain('[shell killed by signal: SIGTERM]')
 
     await call(ctx, owner, 'another shell')
     expect(stub.sessions).toHaveLength(3)
@@ -367,6 +372,14 @@ describe('tool-bash-persistent', () => {
     expect(text(await call(ctx, owner, 'torn status'))).toBe('hello from stub\n[exit code: 7]')
   })
 
+  it('reports a shell exit when the backend has no code or signal', async () => {
+    const { ctx, owner, stub } = await setup({ backendType: 'stub' })
+    await call(ctx, owner, 'warm up')
+    stub.sessions[0]!.mode = 'unknown-exit'
+
+    expect(text(await call(ctx, owner, 'exit without status'))).toContain('[shell exited]')
+  })
+
   it('marks a short missing-prefix result and tolerates exhausted scrollback pages', async () => {
     const { ctx, owner, stub } = await setup({ backendType: 'stub', maxOutputChars: 1_000 })
     await call(ctx, owner, 'warm up')