From 421100d322b46d359edaff4fea9a0b119b829803 Mon Sep 17 00:00:00 2001
From: Hona <10430890+Hona@users.noreply.github.com>
Date: Tue, 21 Jul 2026 00:42:02 +0000
Subject: [PATCH] fix(opencode): clarify incomplete shell output

---
 packages/opencode/src/tool/shell.ts       | 9 ++++++---
 packages/opencode/test/tool/shell.test.ts | 4 +++-
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/packages/opencode/src/tool/shell.ts b/packages/opencode/src/tool/shell.ts
index d25ef16976..17647ae3bb 100644
--- a/packages/opencode/src/tool/shell.ts
+++ b/packages/opencode/src/tool/shell.ts
@@ -25,7 +25,7 @@ import { BashArity } from "@/permission/arity"
 export { Parameters } from "./shell/prompt"
 
 const MAX_METADATA_LENGTH = 30_000
-const POST_EXIT_OUTPUT_GRACE = "500 millis"
+const POST_EXIT_OUTPUT_GRACE_MS = 500
 const CWD = new Set(["cd", "chdir", "popd", "pushd", "push-location", "set-location"])
 const FILES = new Set([
   ...CWD,
@@ -559,7 +559,7 @@ export const ShellTool = Tool.define(
           const outputComplete = yield* Fiber.await(output).pipe(
             Effect.as(true),
             Effect.timeoutOrElse({
-              duration: POST_EXIT_OUTPUT_GRACE,
+              duration: `${POST_EXIT_OUTPUT_GRACE_MS} millis`,
               orElse: () => Effect.succeed(false),
             }),
           )
@@ -576,7 +576,10 @@ export const ShellTool = Tool.define(
         )
       }
       if (aborted) meta.push("User aborted the command")
-      if (incomplete) meta.push("shell tool exited without reaching EOF within 500 ms")
+      if (incomplete)
+        meta.push(
+          `shell tool exited without reaching EOF within ${POST_EXIT_OUTPUT_GRACE_MS} ms; a background descendant may be holding the output pipe open`,
+        )
       const raw = list.map((item) => item.text).join("")
       const end = tail(raw, limits.maxLines, limits.maxBytes)
       if (end.cut) cut = true
diff --git a/packages/opencode/test/tool/shell.test.ts b/packages/opencode/test/tool/shell.test.ts
index 81c2da7678..af0faac514 100644
--- a/packages/opencode/test/tool/shell.test.ts
+++ b/packages/opencode/test/tool/shell.test.ts
@@ -1116,7 +1116,9 @@ describe("tool.shell abort", () => {
 
         expect(Date.now() - started).toBeLessThan(3_000)
         expect(result.output).toContain("parent done")
-        expect(result.output).toContain("shell tool exited without reaching EOF within 500 ms")
+        expect(result.output).toContain(
+          "shell tool exited without reaching EOF within 500 ms; a background descendant may be holding the output pipe open",
+        )
         expect(result.metadata.outputIncomplete).toBe(true)
       }),
     15_000,