From f791315d554a25aab15691af77c1b14d2e9fe5a8 Mon Sep 17 00:00:00 2001
From: cataggar <87583576+cataggar@users.noreply.github.com>
Date: Wed, 19 Aug 2026 19:08:25 +0000
Subject: [PATCH] docs(core): document builtin worker invariant

Assisted-by: GitHub Copilot CLI:gpt-5.6-sol
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 brush-core/src/builtins.rs | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/brush-core/src/builtins.rs b/brush-core/src/builtins.rs
index 66692b9c3..4a9a34427 100644
--- a/brush-core/src/builtins.rs
+++ b/brush-core/src/builtins.rs
@@ -72,6 +72,12 @@ pub trait Command: clap::Parser {
 
     /// Executes the built-in command in the provided context.
     ///
+    /// Builtins can execute inline on the task that invoked them, which is commonly a runtime
+    /// worker. An implementation must not block that worker indefinitely on a file descriptor:
+    /// doing so can prevent a process-substitution producer from being polled and deadlock the
+    /// shell. Wrap synchronous reads that may wait on a pipe in
+    /// [`crate::openfiles::without_parking_worker`].
+    ///
     /// # Arguments
     ///
     /// * `context` - The context in which the command is being executed.