@functional-systems/srcx 0.1.0-dev.18 → 0.1.0-dev.20

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+- Distinguish Qwen setup, cache, device, input-size and timeout failures with
+  actionable messages while keeping raw worker diagnostics private.
+
+- Record three developer search/read investigations with concrete change maps,
+  bounded live usage and source verification, separate from ranking benchmarks.
+
 - Refresh implemented/remaining scope and verify the published dev.17 package
   through a fresh npm consumer and bounded live first-use workflow.
 

package/README.md

@@ -183,6 +183,27 @@ or fallback. Empty candidate pools skip model execution. Existing search default
 and managed embedding usage rules remain unchanged; wider pools increase source
 verification work. See the [integration validation](VALIDATION.md#local-reranker-integration).
 
+Failures include a fixed remediation message where the cause is known:
+
+| Failure                                     | Action                                                                                               |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Python executable missing or not executable | Check the path and execute permissions in `SRCX_RERANK_PYTHON`.                                      |
+| Missing or incompatible Python imports      | Install `runtime/requirements.txt` using that Python environment.                                    |
+| Missing or incomplete model cache           | Download the pinned revision and all files listed above; check `HF_HUB_CACHE`.                       |
+| Invalid or unavailable device               | Use `SRCX_RERANK_DEVICE=auto` or `cpu`, or an available `mps`/`cuda` device.                         |
+| Request exceeds 4 MiB                       | Reduce `--candidates` or shorten the query.                                                          |
+| A query/chunk pair exceeds 8,192 tokens     | Shorten the query or omit `--rerank`; reducing candidate count does not shorten an individual chunk. |
+| Worker exceeds 120 seconds                  | Reduce `--candidates` or select an available faster device.                                          |
+
+Unknown worker failures remain generic. Raw subprocess output and library
+exceptions are never included in these messages. Failed reranking does not
+silently return the original ranking; rerun without `--rerank` to opt out.
+
+For practical search → read → change-planning examples, see the
+[developer workflow pilot](https://github.com/lambdadb/srcx/blob/develop/eval/DEVELOPER-WORKFLOW-PILOT.md).
+It follows three maintenance investigations through related source and tests,
+including the limitations of previews and optional reranking.
+
 ## Evaluate retrieval quality
 
 The internal [lexical chunking pilot](https://github.com/lambdadb/srcx/blob/develop/eval/README.md) compares syntax-aware and

package/VALIDATION.md

@@ -2,6 +2,55 @@
 
 Date: 2026-09-26 (Asia/Seoul).
 
+## Qwen failure diagnostics
+
+Known worker failures now produce distinct setup, cache, device and input-limit
+messages; host launch and deadline failures have separate remediation. Unknown
+failures remain generic, and raw worker output is not forwarded. Search defaults,
+scores, source verification and the no-fallback policy are unchanged.
+
+Local validation passed 97 Node tests, nine Python checks (six worker and three
+local-reranker protocol checks), three installed-package CLI checks, typecheck,
+formatting and version consistency. Reserved worker exits and unexpected exits
+were exercised with real synthetic subprocesses. Deadline, permission and
+unexpected-signal mapping used a mocked process callback; the test asserted the
+unchanged 120-second/SIGKILL policy rather than waiting for a real timeout.
+
+Six additional offline checks used the existing Python 3.12 environment and
+cached pinned model: missing executable, missing Python imports, empty cache,
+invalid device, unavailable CUDA, and successful MPS inference. All produced the
+expected outcome; the successful two-candidate query returned finite scores and
+ranked the sorting function above an unrelated reader. No LambdaDB calls, document
+embeddings or model downloads were needed. This is an error-handling and inference
+smoke check, not a retrieval-quality comparison.
+
+The retained report is `.srcx/diagnostics/report.json` in the
+`srcx-reranker-diagnostics` worktree, SHA-256
+`7725a96f6c5bf5b4a6a4f01369e2dbea6a8ce16d70692f6e1039774f42564e67`.
+The local runner and Node/package logs are retained alongside it.
+
+## Developer workflow pilot
+
+The [workflow pilot](https://github.com/lambdadb/srcx/blob/develop/eval/DEVELOPER-WORKFLOW-PILOT.md)
+used installed dev.17 against srcx `7521974a331471b264a695e6f9795bba3e4a7dfd`
+for three assistant-selected maintenance investigations. Five searches and 16
+source-verified reads produced change maps for Qwen diagnostics, Go chunking and
+automatic Git sync. No feature implementation or comparative quality claim is
+part of this record.
+
+One import added 127 files / 699 chunks to the existing managed-small Collection,
+with 283,104 estimated document embedding input tokens. Two query embedding
+requests and one cached Qwen invocation stayed within predeclared bounds. All
+live commands completed without replay. Two separate local failure probes
+confirmed indistinguishable public errors for missing Python and an invalid
+device; raw exceptions remained masked.
+
+Evidence is retained in the workflow-pilot worktree under `.srcx/workflow-pilot/`:
+
+- `plan.json`: SHA-256 `86d929c19ff69faaed6a264198e0b9c15bf32d3b721a31c503a08c4d2e12da39`.
+- `run.json`: SHA-256 `f0ca1a5e6ac12d48e4929959b85b08e846fb239011125cb153aaa6d0babb1359`.
+- `error-probes.json`: SHA-256 `a5fb5c44dc089466cee8a6bba1c4d374c46bba01f9eef24ac739cfeac72b8612`.
+
 ## Installed dev package first use
 
 On 2026-09-26, the public `@functional-systems/srcx@0.1.0-dev.17` tarball from

package/dist/rerank.js

@@ -3,6 +3,14 @@ import { fileURLToPath } from "node:url";
 import { invariant } from "./common.js";
 export const QWEN_MODEL = "Qwen/Qwen3-Reranker-0.6B";
 export const QWEN_REVISION = "e61197ed45024b0ed8a2d74b80b4d909f1255473";
+// Reserved worker exit codes; never interpret or forward library stderr.
+const WORKER_FAILURES = {
+    20: "Qwen Python dependencies are missing or incompatible. Install runtime/requirements.txt with the Python selected by SRCX_RERANK_PYTHON.",
+    21: "Qwen model cache is missing or incomplete. Download the pinned model revision from README and check HF_HUB_CACHE.",
+    22: "Qwen device is invalid or unavailable. Set SRCX_RERANK_DEVICE to auto or cpu, or a supported mps/cuda device.",
+    23: "Qwen query/chunk pair exceeds 8,192 tokens. Shorten the query or use search without --rerank; source is not truncated.",
+    24: "Qwen request exceeds 4 MiB. Reduce --candidates or shorten the query.",
+};
 export function candidateLimit(limit, options) {
     invariant(Number.isInteger(limit) && limit >= 1 && limit <= 100, "Limit must be an integer from 1 to 100.");
     invariant(options.rerank === undefined || options.rerank === "qwen", "Unknown reranker.");
@@ -20,7 +28,7 @@ export async function qwenScores(query, candidates) {
         candidates.length <= 100 &&
         new Set(candidates.map((c) => c.id)).size === candidates.length, "Invalid reranker candidates.");
     const input = JSON.stringify({ query, candidates });
-    invariant(Buffer.byteLength(input) <= 4 * 1024 * 1024, "Reranker input exceeds 4 MiB.");
+    invariant(Buffer.byteLength(input) <= 4 * 1024 * 1024, "Reranker input exceeds 4 MiB. Reduce --candidates or shorten the query; no fallback was applied.");
     const python = process.env.SRCX_RERANK_PYTHON;
     invariant(python, "Set SRCX_RERANK_PYTHON to the prepared Python executable.");
     const start = performance.now();
@@ -37,10 +45,21 @@ export async function qwenScores(query, candidates) {
                 TOKENIZERS_PARALLELISM: "false",
             },
         }, (error, output) => {
-            if (error)
-                reject(new Error("Qwen reranking failed or exceeded 120 seconds. Check Python dependencies, cached model and SRCX_RERANK_DEVICE; no fallback was applied."));
-            else
-                resolve(output);
+            if (!error)
+                return resolve(output);
+            let message = "Qwen reranking failed. Check Python dependencies, cached model and SRCX_RERANK_DEVICE.";
+            if (error.code === "ENOENT")
+                message =
+                    "Qwen Python executable was not found. Set SRCX_RERANK_PYTHON to an existing Python executable.";
+            else if (error.code === "EACCES")
+                message =
+                    "Qwen Python executable cannot be started. Check execute permissions for SRCX_RERANK_PYTHON.";
+            else if (error.killed && error.signal === "SIGKILL" && !error.code)
+                message =
+                    "Qwen reranking exceeded 120 seconds. Reduce --candidates or use an available faster device via SRCX_RERANK_DEVICE.";
+            else if (typeof error.code === "number")
+                message = WORKER_FAILURES[error.code] ?? message;
+            reject(new Error(`${message} No fallback was applied.`));
         });
         // An early worker exit can close stdin before Node finishes writing.
         child.stdin?.on("error", () => { });

package/dist/rerank.js.map

@@ -1 +1 @@
-{"version":3,"file":"rerank.js","sourceRoot":"","sources":["../src/rerank.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,CAAC,MAAM,UAAU,GAAG,0BAA0B,CAAC;AACrD,MAAM,CAAC,MAAM,aAAa,GAAG,0CAA0C,CAAC;AAQxE,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,OAAsB;IAClE,SAAS,CACP,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,GAAG,EACrD,yCAAyC,CAC1C,CAAC;IACF,SAAS,CACP,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EACzD,mBAAmB,CACpB,CAAC;IACF,SAAS,CACP,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAClD,sCAAsC,CACvC,CAAC;IACF,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM;QAC1B,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QAC7C,CAAC,CAAC,KAAK,CAAC;IACV,SAAS,CACP,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,KAAK,IAAI,KAAK,IAAI,GAAG,EACzD,wDAAwD,CACzD,CAAC;IACF,IAAI,OAAO,CAAC,MAAM;QAChB,SAAS,CACP,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAC9B,sFAAsF,CACvF,CAAC;IACJ,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAa,EAAE,UAAuB;IACrE,SAAS,CACP,UAAU,CAAC,MAAM,GAAG,CAAC;QACnB,UAAU,CAAC,MAAM,IAAI,GAAG;QACxB,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,MAAM,EACjE,8BAA8B,CAC/B,CAAC;IACF,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;IACpD,SAAS,CACP,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,EAC3C,+BAA+B,CAChC,CAAC;IACF,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAC9C,SAAS,CACP,MAAM,EACN,2DAA2D,CAC5D,CAAC;IACF,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAChC,MAAM,MAAM,GAAG,MAAM,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3D,MAAM,KAAK,GAAG,QAAQ,CACpB,MAAM,EACN,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,oBAAoB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAC/D;YACE,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,OAAO;YAChB,UAAU,EAAE,SAAS;YACrB,SAAS,EAAE,IAAI,GAAG,IAAI;YACtB,GAAG,EAAE;gBACH,GAAG,OAAO,CAAC,GAAG;gBACd,cAAc,EAAE,GAAG;gBACnB,wBAAwB,EAAE,GAAG;gBAC7B,sBAAsB,EAAE,OAAO;aAChC;SACF,EACD,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;YAChB,IAAI,KAAK;gBACP,MAAM,CACJ,IAAI,KAAK,CACP,yIAAyI,CAC1I,CACF,CAAC;;gBACC,OAAO,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC,CACF,CAAC;QACF,qEAAqE;QACrE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACnC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IACH,IAAI,QAAQ,CAAC;IACb,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5C,CAAC;IACD,SAAS,CACP,QAAQ,EAAE,KAAK,KAAK,UAAU;QAC5B,QAAQ,EAAE,QAAQ,KAAK,aAAa;QACpC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;QAC9B,QAAQ,CAAC,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM,EAC9C,kDAAkD,CACnD,CAAC;IACF,MAAM,MAAM,GAAa,QAAQ,CAAC,MAAM,CAAC,GAAG,CAC1C,CAAC,KAAwC,EAAE,KAAa,EAAE,EAAE;QAC1D,SAAS,CACP,KAAK,EAAE,EAAE,KAAK,UAAU,CAAC,KAAK,CAAE,CAAC,EAAE;YACjC,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;YAC/B,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,EAC9B,qDAAqD,CACtD,CAAC;QACF,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC,CACF,CAAC;IACF,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"rerank.js","sourceRoot":"","sources":["../src/rerank.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@functional-systems/srcx",
-  "version": "0.1.0-dev.18",
+  "version": "0.1.0-dev.20",
   "private": false,
   "description": "Version-aware code search on LambdaDB",
   "type": "module",
@@ -64,5 +64,5 @@
     "url": "https://github.com/lambdadb/srcx/issues"
   },
   "license": "Apache-2.0",
-  "gitHead": "7521974a331471b264a695e6f9795bba3e4a7dfd"
+  "gitHead": "d1cdcfd08f3ca8becb5d6a5cd8c42552429509c1"
 }

package/runtime/qwen.py

@@ -4,6 +4,7 @@ import json
 import math
 import os
 import sys
+from pathlib import Path
 
 MODEL = "Qwen/Qwen3-Reranker-0.6B"
 REVISION = "e61197ed45024b0ed8a2d74b80b4d909f1255473"
@@ -14,6 +15,19 @@ PREFIX = (
 )
 SUFFIX = "<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n"
 INSTRUCTION = "Given a code search query, retrieve code passages that answer the query."
+CACHE_FILES = ["config.json", "generation_config.json", "model.safetensors",
+               "tokenizer.json", "tokenizer_config.json", "vocab.json", "merges.txt"]
+
+
+class WorkerFailure(ValueError):
+    """Exit codes: 20 imports, 21 cache, 22 device, 23 pair tokens, 24 request bytes.
+
+    The Node caller maps codes to messages; exception text never crosses the boundary.
+    """
+
+    def __init__(self, code):
+        super().__init__("Qwen worker failure")
+        self.code = code
 
 
 def require(condition, message):
@@ -25,7 +39,8 @@ def encode(tokenizer, query, text):
     body = f"<Instruct>: {INSTRUCTION}\n<Query>: {query}\n<Document>: {text}"
     ids = sum((tokenizer.encode(p, add_special_tokens=False)
                for p in (PREFIX, body, SUFFIX)), [])
-    require(len(ids) <= 8192, "Pair exceeds 8192 tokens; no truncation")
+    if len(ids) > 8192:
+        raise WorkerFailure(23)
     return ids
 
 
@@ -45,22 +60,33 @@ def validate(body):
 
 def score(body):
     os.environ["HF_HUB_OFFLINE"] = "1"
-    from huggingface_hub import snapshot_download
-    from transformers import AutoTokenizer, AutoModelForCausalLM
-    import torch
-
-    path = snapshot_download(MODEL, revision=REVISION, local_files_only=True,
-                             allow_patterns=["config.json", "generation_config.json", "model.safetensors",
-                                             "tokenizer.json", "tokenizer_config.json", "vocab.json", "merges.txt"])
+    device = os.environ.get("SRCX_RERANK_DEVICE", "auto")
+    if device not in ("auto", "cpu", "mps", "cuda"):
+        raise WorkerFailure(22)
+    try:
+        from huggingface_hub import snapshot_download
+        from huggingface_hub.errors import LocalEntryNotFoundError
+        from transformers import AutoTokenizer, AutoModelForCausalLM
+        import torch
+    except ImportError:
+        raise WorkerFailure(20) from None
+    if device == "auto":
+        device = "cuda" if torch.cuda.is_available() else "mps" if torch.backends.mps.is_available() else "cpu"
+    elif ((device == "cuda" and not torch.cuda.is_available()) or
+          (device == "mps" and not torch.backends.mps.is_available())):
+        raise WorkerFailure(22)
+    try:
+        path = snapshot_download(MODEL, revision=REVISION, local_files_only=True,
+                                 allow_patterns=CACHE_FILES)
+    except LocalEntryNotFoundError:
+        raise WorkerFailure(21) from None
+    if not all((Path(path) / name).is_file() for name in CACHE_FILES):
+        raise WorkerFailure(21)
     tokenizer = AutoTokenizer.from_pretrained(path, local_files_only=True, trust_remote_code=False)
     # Reuse exact duplicate code within this query, retaining every candidate ID.
     encoded = {c["text"]: None for c in body["candidates"]}
     for text in encoded:
         encoded[text] = encode(tokenizer, body["query"], text)
-    device = os.environ.get("SRCX_RERANK_DEVICE", "auto")
-    require(device in ("auto", "cpu", "mps", "cuda"), "Invalid device")
-    if device == "auto":
-        device = "cuda" if torch.cuda.is_available() else "mps" if torch.backends.mps.is_available() else "cpu"
     model = AutoModelForCausalLM.from_pretrained(
         path, local_files_only=True, trust_remote_code=False,
         dtype=torch.float32, attn_implementation="sdpa",
@@ -83,15 +109,24 @@ def score(body):
 
 def main():
     raw = sys.stdin.buffer.read(4 * 1024 * 1024 + 1)
-    require(len(raw) <= 4 * 1024 * 1024, "Request exceeds 4 MiB")
+    if len(raw) > 4 * 1024 * 1024:
+        raise WorkerFailure(24)
     body = validate(json.loads(raw))
     print(json.dumps(score(body), allow_nan=False))
 
 
-if __name__ == "__main__":
+def run():
     try:
         main()
+    except WorkerFailure as error:
+        # The Node caller maps these codes to fixed, actionable messages.
+        return error.code
     except Exception:
         # Libraries may include source text or environment values in exceptions.
         print("Qwen worker failed; verify setup, device and input size.", file=sys.stderr)
-        sys.exit(1)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(run())

package/src/rerank.ts

@@ -4,6 +4,14 @@ import { invariant } from "./common.js";
 
 export const QWEN_MODEL = "Qwen/Qwen3-Reranker-0.6B";
 export const QWEN_REVISION = "e61197ed45024b0ed8a2d74b80b4d909f1255473";
+// Reserved worker exit codes; never interpret or forward library stderr.
+const WORKER_FAILURES: Record<number, string> = {
+  20: "Qwen Python dependencies are missing or incompatible. Install runtime/requirements.txt with the Python selected by SRCX_RERANK_PYTHON.",
+  21: "Qwen model cache is missing or incomplete. Download the pinned model revision from README and check HF_HUB_CACHE.",
+  22: "Qwen device is invalid or unavailable. Set SRCX_RERANK_DEVICE to auto or cpu, or a supported mps/cuda device.",
+  23: "Qwen query/chunk pair exceeds 8,192 tokens. Shorten the query or use search without --rerank; source is not truncated.",
+  24: "Qwen request exceeds 4 MiB. Reduce --candidates or shorten the query.",
+};
 export type Candidate = { id: string; text: string };
 export type RerankOptions = {
   rerank?: "qwen";
@@ -49,7 +57,7 @@ export async function qwenScores(query: string, candidates: Candidate[]) {
   const input = JSON.stringify({ query, candidates });
   invariant(
     Buffer.byteLength(input) <= 4 * 1024 * 1024,
-    "Reranker input exceeds 4 MiB.",
+    "Reranker input exceeds 4 MiB. Reduce --candidates or shorten the query; no fallback was applied.",
   );
   const python = process.env.SRCX_RERANK_PYTHON;
   invariant(
@@ -74,13 +82,21 @@ export async function qwenScores(query: string, candidates: Candidate[]) {
         },
       },
       (error, output) => {
-        if (error)
-          reject(
-            new Error(
-              "Qwen reranking failed or exceeded 120 seconds. Check Python dependencies, cached model and SRCX_RERANK_DEVICE; no fallback was applied.",
-            ),
-          );
-        else resolve(output);
+        if (!error) return resolve(output);
+        let message =
+          "Qwen reranking failed. Check Python dependencies, cached model and SRCX_RERANK_DEVICE.";
+        if (error.code === "ENOENT")
+          message =
+            "Qwen Python executable was not found. Set SRCX_RERANK_PYTHON to an existing Python executable.";
+        else if (error.code === "EACCES")
+          message =
+            "Qwen Python executable cannot be started. Check execute permissions for SRCX_RERANK_PYTHON.";
+        else if (error.killed && error.signal === "SIGKILL" && !error.code)
+          message =
+            "Qwen reranking exceeded 120 seconds. Reduce --candidates or use an available faster device via SRCX_RERANK_DEVICE.";
+        else if (typeof error.code === "number")
+          message = WORKER_FAILURES[error.code] ?? message;
+        reject(new Error(`${message} No fallback was applied.`));
       },
     );
     // An early worker exit can close stdin before Node finishes writing.