chore: import upstream snapshot with attribution

python/tests/workspace/executor/builtins/test_condition.py

@@ -0,0 +1,85 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import pytest
+
+from mirage import MountMode, RAMResource, Workspace
+
+
+async def _workspace() -> Workspace:
+    ws = Workspace({"/": RAMResource()}, mode=MountMode.WRITE)
+    await ws.execute("mkdir -p /data/sub")
+    await ws.execute("tee /data/plain.txt > /dev/null", stdin=b"y\n")
+    await ws.execute("cd /data")
+    return ws
+
+
+async def _rc(ws: Workspace, cmd: str) -> int:
+    io = await ws.execute(cmd)
+    return io.exit_code
+
+
+@pytest.mark.asyncio
+async def test_f_relative_resolves_against_cwd():
+    ws = await _workspace()
+    assert await _rc(ws, "test -f plain.txt") == 0
+
+
+@pytest.mark.asyncio
+async def test_f_relative_missing():
+    ws = await _workspace()
+    assert await _rc(ws, "test -f missing.txt") == 1
+
+
+@pytest.mark.asyncio
+async def test_f_relative_with_dotdot():
+    ws = await _workspace()
+    await ws.execute("cd /data/sub")
+    assert await _rc(ws, "test -f ../plain.txt") == 0
+
+
+@pytest.mark.asyncio
+async def test_d_relative_resolves_against_cwd():
+    ws = await _workspace()
+    assert await _rc(ws, "test -d sub") == 0
+
+
+@pytest.mark.asyncio
+async def test_d_relative_missing():
+    ws = await _workspace()
+    assert await _rc(ws, "test -d nosuch") == 1
+
+
+@pytest.mark.asyncio
+async def test_f_absolute_unchanged():
+    ws = await _workspace()
+    assert await _rc(ws, "test -f /data/plain.txt") == 0
+
+
+@pytest.mark.asyncio
+async def test_f_empty_operand_false():
+    ws = await _workspace()
+    assert await _rc(ws, 'test -f ""') == 1
+
+
+@pytest.mark.asyncio
+async def test_bracket_form_relative():
+    ws = await _workspace()
+    assert await _rc(ws, "[ -f plain.txt ]") == 0
+
+
+@pytest.mark.asyncio
+async def test_negation_relative():
+    ws = await _workspace()
+    assert await _rc(ws, "test ! -f missing.txt") == 0

python/tests/workspace/executor/builtins/test_script.py

@@ -0,0 +1,55 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import time
+
+import pytest
+
+from mirage.workspace.executor.builtins.script import handle_sleep
+
+
+@pytest.mark.asyncio
+async def test_sleep_missing_operand_exits_1():
+    _, io, node = await handle_sleep([])
+    assert io.exit_code == 1
+    assert io.stderr == b"sleep: missing operand\n"
+    assert node.exit_code == 1
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "raw",
+    ["abc", "-1", "inf", "Infinity", "nan", "NaN", "0x10", "1_0", "1e309", ""])
+async def test_sleep_invalid_interval_exits_1(raw):
+    _, io, node = await handle_sleep([raw])
+    assert io.exit_code == 1
+    assert io.stderr == f"sleep: invalid time interval '{raw}'\n".encode()
+    assert node.exit_code == 1
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("raw", ["0", "0.", ".01", "+0.01", "1e-3"])
+async def test_sleep_valid_interval_exits_0(raw):
+    _, io, node = await handle_sleep([raw])
+    assert io.exit_code == 0
+    assert not io.stderr
+    assert node.exit_code == 0
+
+
+@pytest.mark.asyncio
+async def test_sleep_zero_returns_promptly():
+    start = time.monotonic()
+    _, io, _ = await handle_sleep(["0"])
+    assert io.exit_code == 0
+    assert time.monotonic() - start < 0.05

python/tests/workspace/executor/builtins/test_text.py

@@ -0,0 +1,56 @@
+import pytest
+
+from mirage.workspace.executor.builtins.text import handle_echo
+
+
+async def echo_bytes(args: list[str]) -> bytes:
+    out, io, _ = await handle_echo(args)
+    assert io.exit_code == 0
+    assert isinstance(out, bytes)
+    return out
+
+
+@pytest.mark.asyncio
+async def test_plain_words_join_with_newline():
+    assert await echo_bytes(["hi", "there"]) == b"hi there\n"
+
+
+@pytest.mark.asyncio
+async def test_leading_n_suppresses_newline():
+    assert await echo_bytes(["-n", "hi"]) == b"hi"
+
+
+@pytest.mark.asyncio
+async def test_trailing_n_prints_literally():
+    assert await echo_bytes(["hi", "-n"]) == b"hi -n\n"
+
+
+@pytest.mark.asyncio
+async def test_cluster_ne():
+    assert await echo_bytes(["-ne", "a\\tb"]) == b"a\tb"
+
+
+@pytest.mark.asyncio
+async def test_capital_e_disables_escapes():
+    assert await echo_bytes(["-e", "-E", "a\\tb"]) == b"a\\tb\n"
+
+
+@pytest.mark.asyncio
+async def test_last_of_e_and_E_wins_within_cluster():
+    assert await echo_bytes(["-eE", "a\\tb"]) == b"a\\tb\n"
+    assert await echo_bytes(["-Ee", "a\\tb"]) == b"a\tb\n"
+
+
+@pytest.mark.asyncio
+async def test_unknown_char_makes_word_literal():
+    assert await echo_bytes(["-nq", "hi"]) == b"-nq hi\n"
+
+
+@pytest.mark.asyncio
+async def test_option_after_operand_is_literal():
+    assert await echo_bytes(["hi", "-e", "a\\tb"]) == b"hi -e a\\tb\n"
+
+
+@pytest.mark.asyncio
+async def test_lone_dash_is_literal():
+    assert await echo_bytes(["-"]) == b"-\n"

python/tests/workspace/executor/builtins/test_timeout.py

@@ -0,0 +1,99 @@
+import asyncio
+
+import pytest
+
+from mirage.io import IOResult
+from mirage.io.stream import materialize
+from mirage.workspace.executor.builtins.timeout import (handle_timeout,
+                                                        parse_duration)
+from mirage.workspace.session.session import Session
+
+
+class FakeShell:
+
+    def __init__(self, delay: float = 0.0, exit_code: int = 0):
+        self.lines: list[str] = []
+        self.delay = delay
+        self.exit_code = exit_code
+
+    async def __call__(self, line: str, session_id: str) -> IOResult:
+        self.lines.append(line)
+        if self.delay:
+            await asyncio.sleep(self.delay)
+        return IOResult(stdout=b"done\n", exit_code=self.exit_code)
+
+
+def make_session() -> Session:
+    return Session(session_id="s1")
+
+
+def test_parse_duration_units():
+    assert parse_duration("1") == 1.0
+    assert parse_duration("0.5") == 0.5
+    assert parse_duration("2s") == 2.0
+    assert parse_duration("2m") == 120.0
+    assert parse_duration("1h") == 3600.0
+    assert parse_duration("1d") == 86400.0
+    assert parse_duration(".5") == 0.5
+
+
+def test_parse_duration_rejects_garbage():
+    assert parse_duration("xx") is None
+    assert parse_duration("-1") is None
+    assert parse_duration("1x") is None
+    assert parse_duration("") is None
+
+
+@pytest.mark.asyncio
+async def test_command_finishing_in_time_passes_through():
+    shell = FakeShell(exit_code=3)
+    stdout, io, _ = await handle_timeout(shell, ["5", "wc", "-l"],
+                                         make_session())
+    assert shell.lines == ["wc -l"]
+    assert io.exit_code == 3
+    assert stdout == b"done\n"
+
+
+@pytest.mark.asyncio
+async def test_overrun_exits_124():
+    shell = FakeShell(delay=1.0)
+    _, io, node = await handle_timeout(shell, ["0.05", "sleep", "1"],
+                                       make_session())
+    assert io.exit_code == 124
+    assert node.exit_code == 124
+
+
+@pytest.mark.asyncio
+async def test_invalid_duration_exits_125():
+    shell = FakeShell()
+    _, io, _ = await handle_timeout(shell, ["xx", "sleep", "1"],
+                                    make_session())
+    assert io.exit_code == 125
+    assert (await
+            materialize(io.stderr)) == b"timeout: invalid time interval 'xx'\n"
+    assert shell.lines == []
+
+
+@pytest.mark.asyncio
+async def test_missing_operand_exits_125():
+    shell = FakeShell()
+    _, io, _ = await handle_timeout(shell, ["5"], make_session())
+    assert io.exit_code == 125
+    assert await materialize(io.stderr) == b"timeout: missing operand\n"
+
+
+@pytest.mark.asyncio
+async def test_signal_option_rejected():
+    shell = FakeShell()
+    _, io, _ = await handle_timeout(shell, ["-s", "KILL", "1", "sleep", "3"],
+                                    make_session())
+    assert io.exit_code == 125
+    assert (await
+            materialize(io.stderr)) == b"timeout: unsupported option -- '-s'\n"
+
+
+@pytest.mark.asyncio
+async def test_quoting_survives_rejoin():
+    shell = FakeShell()
+    await handle_timeout(shell, ["1", "grep", "a b", "f.txt"], make_session())
+    assert shell.lines == ["grep 'a b' f.txt"]

python/tests/workspace/executor/builtins/test_vars.py

@@ -0,0 +1,76 @@
+import pytest
+
+from mirage.io.stream import materialize
+from mirage.workspace.executor.builtins.vars import (handle_read,
+                                                     handle_return,
+                                                     handle_shift)
+from mirage.workspace.executor.control import ReturnSignal
+from mirage.workspace.session.session import Session
+
+
+def make_session() -> Session:
+    return Session(session_id="s1")
+
+
+@pytest.mark.asyncio
+async def test_shift_non_numeric_errors_like_bash():
+    _, io, _ = await handle_shift(["x"], None, session=make_session())
+    assert io.exit_code == 1
+    assert (await
+            materialize(io.stderr)) == b"shift: x: numeric argument required\n"
+
+
+@pytest.mark.asyncio
+async def test_shift_too_many_arguments():
+    _, io, _ = await handle_shift(["1", "2"], None, session=make_session())
+    assert io.exit_code == 1
+    assert await materialize(io.stderr) == b"shift: too many arguments\n"
+
+
+@pytest.mark.asyncio
+async def test_shift_default_one():
+    session = make_session()
+    session.positional_args = ["a", "b"]
+    _, io, _ = await handle_shift([], None, session=session)
+    assert io.exit_code == 0
+    assert session.positional_args == ["b"]
+
+
+@pytest.mark.asyncio
+async def test_return_non_numeric_raises_2_with_message():
+    with pytest.raises(ReturnSignal) as exc:
+        await handle_return(["x"])
+    assert exc.value.exit_code == 2
+    assert exc.value.stderr == b"return: x: numeric argument required\n"
+
+
+@pytest.mark.asyncio
+async def test_return_numeric():
+    with pytest.raises(ReturnSignal) as exc:
+        await handle_return(["7"])
+    assert exc.value.exit_code == 7
+    assert exc.value.stderr == b""
+
+
+@pytest.mark.asyncio
+async def test_read_invalid_option_exits_2():
+    _, io, _ = await handle_read(["-q", "v"], make_session(), b"line\n")
+    assert io.exit_code == 2
+    assert await materialize(io.stderr) == b"read: -q: invalid option\n"
+
+
+@pytest.mark.asyncio
+async def test_read_dash_r_consumed_not_a_variable():
+    session = make_session()
+    _, io, _ = await handle_read(["-r", "v"], session, b"hello world\n")
+    assert io.exit_code == 0
+    assert session.env["v"] == "hello world"
+    assert "-r" not in session.env
+
+
+@pytest.mark.asyncio
+async def test_read_defaults_to_reply():
+    session = make_session()
+    _, io, _ = await handle_read([], session, b"hi\n")
+    assert io.exit_code == 0
+    assert session.env["REPLY"] == "hi"

python/tests/workspace/executor/builtins/test_xargs.py

@@ -0,0 +1,124 @@
+import pytest
+
+from mirage.io import IOResult
+from mirage.io.stream import materialize
+from mirage.workspace.executor.builtins.xargs import handle_xargs
+from mirage.workspace.session.session import Session
+
+
+class FakeShell:
+
+    def __init__(self, exit_codes: list[int] | None = None):
+        self.lines: list[str] = []
+        self.exit_codes = exit_codes or []
+
+    async def __call__(self, line: str, session_id: str) -> IOResult:
+        self.lines.append(line)
+        code = (self.exit_codes[len(self.lines) - 1]
+                if len(self.lines) <= len(self.exit_codes) else 0)
+        return IOResult(stdout=f"ran:{line}\n".encode(), exit_code=code)
+
+
+def make_session() -> Session:
+    return Session(session_id="s1")
+
+
+@pytest.mark.asyncio
+async def test_batches_one_arg_per_run_with_n1():
+    shell = FakeShell()
+    _, io, _ = await handle_xargs(shell, ["-n1", "echo"], make_session(),
+                                  b"a b c")
+    assert shell.lines == ["echo a", "echo b", "echo c"]
+    assert io.exit_code == 0
+
+
+@pytest.mark.asyncio
+async def test_single_run_without_n():
+    shell = FakeShell()
+    _, io, _ = await handle_xargs(shell, ["echo"], make_session(), b"a b c")
+    assert shell.lines == ["echo a b c"]
+    assert io.exit_code == 0
+
+
+@pytest.mark.asyncio
+async def test_failing_invocation_exits_123_but_continues():
+    shell = FakeShell(exit_codes=[1, 0])
+    _, io, _ = await handle_xargs(shell, ["-n1", "wc"], make_session(), b"a b")
+    assert shell.lines == ["wc a", "wc b"]
+    assert io.exit_code == 123
+
+
+@pytest.mark.asyncio
+async def test_command_not_found_stops_with_127():
+    shell = FakeShell(exit_codes=[127, 0])
+    _, io, _ = await handle_xargs(shell, ["-n1", "nope"], make_session(),
+                                  b"a b")
+    assert shell.lines == ["nope a"]
+    assert io.exit_code == 127
+
+
+@pytest.mark.asyncio
+async def test_no_run_if_empty():
+    shell = FakeShell()
+    _, io, _ = await handle_xargs(shell, ["-r", "echo", "hi"], make_session(),
+                                  b"")
+    assert shell.lines == []
+    assert io.exit_code == 0
+
+
+@pytest.mark.asyncio
+async def test_empty_input_without_r_runs_once():
+    shell = FakeShell()
+    _, io, _ = await handle_xargs(shell, ["echo", "hi"], make_session(), b"")
+    assert shell.lines == ["echo hi"]
+    assert io.exit_code == 0
+
+
+@pytest.mark.asyncio
+async def test_null_delimited_input():
+    shell = FakeShell()
+    await handle_xargs(shell, ["-0", "echo"], make_session(), b"a b\0c\0")
+    assert shell.lines == ["echo 'a b' c"]
+
+
+@pytest.mark.asyncio
+async def test_custom_delimiter():
+    shell = FakeShell()
+    await handle_xargs(shell, ["-d,", "echo"], make_session(), b"a,b,c")
+    assert shell.lines == ["echo a b c"]
+
+
+@pytest.mark.asyncio
+async def test_invalid_option_exits_1():
+    shell = FakeShell()
+    _, io, _ = await handle_xargs(shell, ["-q", "echo"], make_session(), b"x")
+    assert io.exit_code == 1
+    assert await materialize(io.stderr) == b"xargs: invalid option -- 'q'\n"
+    assert shell.lines == []
+
+
+@pytest.mark.asyncio
+async def test_unsupported_option_exits_1():
+    shell = FakeShell()
+    _, io, _ = await handle_xargs(shell, ["-I", "{}", "echo"], make_session(),
+                                  b"x")
+    assert io.exit_code == 1
+    assert await materialize(io.stderr
+                             ) == b"xargs: unsupported option -- 'I'\n"
+
+
+@pytest.mark.asyncio
+async def test_n_zero_rejected():
+    shell = FakeShell()
+    _, io, _ = await handle_xargs(shell, ["-n0", "echo"], make_session(), b"x")
+    assert io.exit_code == 1
+    assert (await
+            materialize(io.stderr
+                        )) == b"xargs: value 0 for -n option should be >= 1\n"
+
+
+@pytest.mark.asyncio
+async def test_input_words_stay_single_tokens():
+    shell = FakeShell()
+    await handle_xargs(shell, ["echo"], make_session(), b"don't $(reboot)")
+    assert shell.lines == ["echo 'don'\"'\"'t' '$(reboot)'"]

python/tests/workspace/executor/test_escapes.py

@@ -0,0 +1,99 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.workspace.executor.builtins import _interpret_escapes
+
+
+def test_newline():
+    assert _interpret_escapes("a\\nb") == "a\nb"
+
+
+def test_tab():
+    assert _interpret_escapes("a\\tb") == "a\tb"
+
+
+def test_carriage_return():
+    assert _interpret_escapes("\\r") == "\r"
+
+
+def test_bell():
+    assert _interpret_escapes("\\a") == "\a"
+
+
+def test_backspace():
+    assert _interpret_escapes("\\b") == "\b"
+
+
+def test_form_feed():
+    assert _interpret_escapes("\\f") == "\f"
+
+
+def test_vertical_tab():
+    assert _interpret_escapes("\\v") == "\v"
+
+
+def test_literal_backslash():
+    assert _interpret_escapes("a\\\\b") == "a\\b"
+
+
+def test_double_backslash_before_n():
+    assert _interpret_escapes("\\\\n") == "\\n"
+
+
+def test_double_backslash_before_b():
+    assert _interpret_escapes("a\\\\b") == "a\\b"
+
+
+def test_hex_escape():
+    assert _interpret_escapes("\\x41") == "A"
+
+
+def test_hex_single_digit():
+    assert _interpret_escapes("\\x9") == "\t"
+
+
+def test_hex_no_digits():
+    assert _interpret_escapes("\\x") == "\\x"
+
+
+def test_octal_escape():
+    assert _interpret_escapes("\\0101") == "A"
+
+
+def test_octal_null():
+    assert _interpret_escapes("\\0") == "\0"
+
+
+def test_stop_output():
+    assert _interpret_escapes("hello\\cworld") == "hello"
+
+
+def test_unknown_escape_passthrough():
+    assert _interpret_escapes("\\z") == "\\z"
+
+
+def test_no_escapes():
+    assert _interpret_escapes("hello world") == "hello world"
+
+
+def test_empty():
+    assert _interpret_escapes("") == ""
+
+
+def test_trailing_backslash():
+    assert _interpret_escapes("end\\") == "end\\"
+
+
+def test_mixed():
+    assert _interpret_escapes("a\\tb\\nc\\\\d") == "a\tb\nc\\d"

python/tests/workspace/executor/test_fanout.py

@@ -0,0 +1,89 @@
+import asyncio
+from types import SimpleNamespace
+
+from mirage.resource.ram import RAMResource
+from mirage.types import MountMode
+from mirage.workspace import Workspace
+from mirage.workspace.executor.fanout import (_adjust_depth_texts,
+                                              _synthesize_find_mount_entries)
+
+
+def _mounts(*prefixes):
+    return [SimpleNamespace(prefix=p) for p in prefixes]
+
+
+def test_synthesize_no_expression_emits_all():
+    desc = _mounts("/ram/", "/disk/")
+    assert _synthesize_find_mount_entries("/", desc, []) == "/ram\n/disk"
+
+
+def test_synthesize_positive_name():
+    desc = _mounts("/ram/", "/disk/")
+    assert _synthesize_find_mount_entries("/", desc,
+                                          ["-name", "ram"]) == "/ram"
+
+
+def test_synthesize_honors_not():
+    desc = _mounts("/ram/", "/disk/", "/notes/")
+    out = _synthesize_find_mount_entries("/", desc, ["-not", "-name", "ram"])
+    assert out == "/disk\n/notes"
+
+
+def test_synthesize_honors_or():
+    desc = _mounts("/ram/", "/disk/", "/notes/")
+    out = _synthesize_find_mount_entries(
+        "/", desc, ["-name", "ram", "-o", "-name", "disk"])
+    assert out == "/ram\n/disk"
+
+
+def test_synthesize_type_file_excludes_mount_dirs():
+    desc = _mounts("/ram/", "/disk/")
+    assert _synthesize_find_mount_entries("/", desc, ["-type", "f"]) == ""
+
+
+def test_synthesize_type_dir_includes_mount_dirs():
+    desc = _mounts("/ram/", "/disk/")
+    assert _synthesize_find_mount_entries("/", desc,
+                                          ["-type", "d"]) == "/ram\n/disk"
+
+
+def test_synthesize_maxdepth_window():
+    desc = _mounts("/ram/", "/a/b/")
+    assert _synthesize_find_mount_entries("/", desc,
+                                          ["-maxdepth", "1"]) == "/ram"
+
+
+def test_adjust_depth_texts_reduces_maxdepth_by_delta():
+    out = _adjust_depth_texts(["-maxdepth", "3", "-name", "x"], "/",
+                              "/data/sub")
+    assert out == ["-maxdepth", "1", "-name", "x"]
+
+
+def test_adjust_depth_texts_clamps_mindepth_at_zero():
+    out = _adjust_depth_texts(["-mindepth", "1"], "/", "/data")
+    assert out == ["-mindepth", "0"]
+
+
+def test_adjust_depth_texts_no_depth_tokens_unchanged():
+    out = _adjust_depth_texts(["-name", "x", "-o", "-name", "y"], "/", "/data")
+    assert out == ["-name", "x", "-o", "-name", "y"]
+
+
+def test_adjust_depth_texts_same_mount_unchanged():
+    assert _adjust_depth_texts(["-maxdepth", "3"], "/data",
+                               "/data") == ["-maxdepth", "3"]
+
+
+def test_maxdepth_applies_to_child_mount_depth_end_to_end():
+    parent = RAMResource()
+    child = RAMResource()
+    child._store.dirs.add("/a")
+    child._store.files["/a/b.txt"] = b"deep\n"
+    ws = Workspace(resources={
+        "/": (parent, MountMode.EXEC),
+        "/data/": (child, MountMode.EXEC),
+    }, )
+    io = asyncio.run(ws.execute("find / -maxdepth 2"))
+    out = (io.stdout if isinstance(io.stdout, bytes) else b"").decode()
+    assert "/data/a" in out
+    assert "/data/a/b.txt" not in out

python/tests/workspace/executor/test_man.py

@@ -0,0 +1,190 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+from unittest.mock import MagicMock
+
+from mirage.commands.config import RegisteredCommand
+from mirage.commands.spec.types import CommandSpec, OperandKind, Option
+from mirage.workspace.executor.builtins import (_collect_man_hits,
+                                                _render_man_entry,
+                                                _render_man_index, handle_man)
+from mirage.workspace.session import Session
+
+
+def _mk_cmd(name, spec, filetype=None, resource="ram"):
+    return RegisteredCommand(
+        name=name,
+        spec=spec,
+        resource=resource,
+        filetype=filetype,
+        fn=lambda *a, **kw: None,
+    )
+
+
+def _mk_mount(prefix, kind, cmds=None, general=None):
+    mount = MagicMock()
+    mount.prefix = prefix
+    mount.resource = MagicMock()
+    mount.resource.name = kind
+    cmds = cmds or {}
+    general = general or {}
+
+    def _resolve(name, extension=None):
+        if name in cmds:
+            return cmds[name]
+        if name in general:
+            return general[name]
+        return None
+
+    def _is_general(name):
+        return name in general and name not in cmds
+
+    def _all():
+        seen = set()
+        out = []
+        for rc in cmds.values():
+            if rc.name in seen:
+                continue
+            seen.add(rc.name)
+            out.append(rc)
+        for rc in general.values():
+            if rc.name in seen:
+                continue
+            seen.add(rc.name)
+            out.append(rc)
+        return out
+
+    mount.resolve_command = MagicMock(side_effect=_resolve)
+    mount.is_general_command = MagicMock(side_effect=_is_general)
+    mount.all_commands = MagicMock(side_effect=_all)
+    return mount
+
+
+def _mk_registry(mounts, cwd_mount=None):
+    reg = MagicMock()
+    reg.mounts = MagicMock(return_value=mounts)
+
+    def _mount_for(path):
+        if cwd_mount is not None:
+            return cwd_mount
+        raise ValueError(f"no mount: {path}")
+
+    reg.mount_for = MagicMock(side_effect=_mount_for)
+    return reg
+
+
+def test_collect_man_hits_skips_dev():
+    spec = CommandSpec(description="x")
+    cat_cmd = _mk_cmd("cat", spec)
+    mount_dev = _mk_mount("/dev/", "dev", cmds={"cat": cat_cmd})
+    mount_ram = _mk_mount("/ram/", "ram", cmds={"cat": cat_cmd})
+    reg = _mk_registry([mount_dev, mount_ram])
+    hits = _collect_man_hits("cat", reg)
+    assert len(hits) == 1
+    assert hits[0].mount is mount_ram
+
+
+def test_render_man_entry_no_options():
+    spec = CommandSpec(description="Concatenate files.")
+    cat_cmd = _mk_cmd("cat", spec)
+    mount = _mk_mount("/ram/", "ram", cmds={"cat": cat_cmd})
+    hits = _collect_man_hits("cat", _mk_registry([mount]))
+    out = _render_man_entry("cat", hits)
+    assert out.startswith("# cat\n")
+    assert "Concatenate files." in out
+    assert "## OPTIONS" not in out
+    assert "## RESOURCES\n\n- ram\n" in out
+
+
+def test_render_man_entry_with_options():
+    spec = CommandSpec(
+        description="Print a sequence.",
+        options=(
+            Option(short="-s",
+                   value_kind=OperandKind.TEXT,
+                   description="separator"),
+            Option(short="-w", description="zero-pad"),
+        ),
+    )
+    cmd = _mk_cmd("seq", spec)
+    mount = _mk_mount("/ram/", "ram", cmds={"seq": cmd})
+    hits = _collect_man_hits("seq", _mk_registry([mount]))
+    out = _render_man_entry("seq", hits)
+    assert "## OPTIONS" in out
+    assert "| short | long | value | description |" in out
+    assert "| -s |  | text | separator |" in out
+    assert "| -w |  | none | zero-pad |" in out
+
+
+def test_render_man_entry_dedupes_by_kind_and_filetype():
+    spec = CommandSpec(description="cat")
+    plain = _mk_cmd("cat", spec)
+    parquet = _mk_cmd("cat", spec, filetype=".parquet")
+    m1 = _mk_mount("/a/", "ram", cmds={"cat": plain})
+    m2 = _mk_mount("/b/", "ram", cmds={"cat": plain})
+    m3 = _mk_mount("/c/", "ram", cmds={"cat": parquet})
+    reg = _mk_registry([m1, m2, m3])
+    hits = _collect_man_hits("cat", reg)
+    out = _render_man_entry("cat", hits)
+    assert out.count("- ram\n") == 1
+    assert "- ram (filetype: .parquet)" in out
+
+
+def test_render_man_entry_general_first():
+    spec = CommandSpec(description="x")
+    cmd = _mk_cmd("bc", spec, resource=None)
+    mount = _mk_mount("/ram/", "ram", general={"bc": cmd})
+    hits = _collect_man_hits("bc", _mk_registry([mount]))
+    out = _render_man_entry("bc", hits)
+    assert out.endswith("- general\n")
+
+
+def test_handle_man_missing_entry():
+    reg = _mk_registry([])
+    out, io, node = asyncio.run(
+        handle_man(["nope"], Session(session_id="t"), reg))
+    assert out is None
+    assert io.exit_code == 1
+    assert io.stderr == b"man: no entry for nope\n"
+    assert node.exit_code == 1
+
+
+def test_handle_man_index_cwd_first():
+    spec_a = CommandSpec(description="ls files")
+    spec_b = CommandSpec(description="cat files")
+    ls = _mk_cmd("ls", spec_a)
+    cat = _mk_cmd("cat", spec_b)
+    mount_z = _mk_mount("/z/", "zfs", cmds={"ls": ls})
+    mount_r = _mk_mount("/ram/", "ram", cmds={"cat": cat})
+    reg = _mk_registry([mount_z, mount_r], cwd_mount=mount_r)
+    out, io, node = asyncio.run(
+        handle_man([], Session(session_id="t", cwd="/ram/x"), reg))
+    assert io.exit_code == 0
+    text = out.decode()
+    ram_pos = text.index("# ram")
+    zfs_pos = text.index("# zfs")
+    assert ram_pos < zfs_pos
+
+
+def test_render_man_index_dedupes_general_across_mounts():
+    spec_g = CommandSpec(description="bc desc")
+    bc = _mk_cmd("bc", spec_g, resource=None)
+    spec_a = CommandSpec(description="ls files")
+    ls = _mk_cmd("ls", spec_a)
+    m1 = _mk_mount("/a/", "ram", cmds={"ls": ls}, general={"bc": bc})
+    m2 = _mk_mount("/b/", "s3", cmds={"ls": ls}, general={"bc": bc})
+    reg = _mk_registry([m1, m2])
+    text = _render_man_index(Session(session_id="t"), reg)
+    assert text.count("- bc \u2014 bc desc") == 1

python/tests/workspace/executor/test_pipes.py

@@ -0,0 +1,77 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import pytest
+
+from mirage.io import IOResult
+from mirage.io.types import materialize
+from mirage.workspace.executor.pipes import handle_pipe
+from mirage.workspace.session import Session
+from mirage.workspace.types import ExecutionNode
+
+
+class FakeNode:
+
+    def __init__(self, text: str):
+        self.text = text
+
+
+@pytest.mark.asyncio
+async def test_handle_pipe_passes_empty_stdin_when_left_returns_none():
+    calls: list[dict] = []
+
+    async def execute_node(nd, _session, stdin, _call_stack=None):
+        stdin_was_none = stdin is None
+        materialized = await materialize(stdin)
+        calls.append({
+            "text": nd.text,
+            "stdin_was_none": stdin_was_none,
+            "stdin_bytes": materialized,
+        })
+        if nd.text == "left":
+            return (None, IOResult(stderr=b"boom", exit_code=1),
+                    ExecutionNode(command=nd.text, exit_code=1))
+        return (b"right-out", IOResult(exit_code=0),
+                ExecutionNode(command=nd.text, exit_code=0))
+
+    await handle_pipe(
+        execute_node,
+        [FakeNode("left"), FakeNode("right")],
+        [False],
+        Session(session_id="t"),
+        None,
+    )
+    right = next(c for c in calls if c["text"] == "right")
+    assert right["stdin_was_none"] is False
+    assert right["stdin_bytes"] == b""
+
+
+@pytest.mark.asyncio
+async def test_handle_pipe_threads_stdout_to_next_stdin():
+    seen: list[bytes] = []
+
+    async def execute_node(nd, _session, stdin, _call_stack=None):
+        seen.append(await materialize(stdin))
+        return (f"{nd.text}-out".encode(), IOResult(exit_code=0),
+                ExecutionNode(command=nd.text, exit_code=0))
+
+    await handle_pipe(
+        execute_node,
+        [FakeNode("a"), FakeNode("b")],
+        [False],
+        Session(session_id="t"),
+        None,
+    )
+    assert seen[0] == b""
+    assert seen[1] == b"a-out"

python/tests/workspace/executor/test_redirect.py

@@ -0,0 +1,103 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import pytest
+
+from mirage import MountMode, RAMResource, Workspace
+
+
+async def _workspace() -> Workspace:
+    ws = Workspace({"/": RAMResource()}, mode=MountMode.WRITE)
+    await ws.execute("mkdir -p /data")
+    return ws
+
+
+async def _out(ws: Workspace, cmd: str) -> str:
+    io = await ws.execute(cmd)
+    return (io.stdout or b"").decode()
+
+
+@pytest.mark.asyncio
+async def test_redirect_target_expands_after_cd_in_list():
+    # tree-sitter hoists the trailing redirect over the && list; the
+    # target must still expand with the cwd the last command sees.
+    ws = await _workspace()
+    await ws.execute("cd /data && echo hi > OUT")
+    assert await _out(ws, "cat /data/OUT") == "hi\n"
+
+
+@pytest.mark.asyncio
+async def test_redirect_captures_only_last_command():
+    ws = await _workspace()
+    out = await _out(ws, "echo one && echo two > /data/f")
+    assert out == "one\n"
+    assert await _out(ws, "cat /data/f") == "two\n"
+
+
+@pytest.mark.asyncio
+async def test_redirect_short_circuit_and():
+    ws = await _workspace()
+    io = await ws.execute("false && echo never > /data/f3")
+    assert io.exit_code == 1
+    io = await ws.execute("test -f /data/f3")
+    assert io.exit_code == 1
+
+
+@pytest.mark.asyncio
+async def test_redirect_short_circuit_or():
+    ws = await _workspace()
+    await ws.execute("false || echo fallback > /data/f4")
+    assert await _out(ws, "cat /data/f4") == "fallback\n"
+
+
+@pytest.mark.asyncio
+async def test_redirect_chain_compounds():
+    # Each redirect re-associates independently, so a multi-redirect
+    # chain executes left to right instead of hoisting.
+    ws = await _workspace()
+    out = await _out(
+        ws, "echo a > /data/c && echo b >> /data/c && cat /data/c"
+        " && wc -l < /data/c")
+    assert out == "a\nb\n2\n"
+
+
+@pytest.mark.asyncio
+async def test_redirect_group_keeps_whole_body():
+    # Compound bodies are real bash group redirects, not hoists.
+    ws = await _workspace()
+    await ws.execute("{ echo g1; echo g2; } > /data/grp")
+    assert await _out(ws, "cat /data/grp") == "g1\ng2\n"
+
+
+@pytest.mark.asyncio
+async def test_redirect_subshell_keeps_whole_body():
+    ws = await _workspace()
+    await ws.execute("(echo s1; echo s2) > /data/subq")
+    assert await _out(ws, "cat /data/subq") == "s1\ns2\n"
+
+
+@pytest.mark.asyncio
+async def test_redirect_pipeline_right_side():
+    ws = await _workspace()
+    out = await _out(
+        ws, "echo x && echo y | tr a-z A-Z > /data/up && cat /data/up")
+    assert out == "x\nY\n"
+
+
+@pytest.mark.asyncio
+async def test_stdin_redirect_binds_last_command():
+    ws = await _workspace()
+    await ws.execute("printf 'l1\\nl2\\n' | tee /data/seed > /dev/null")
+    out = await _out(ws, "echo lead && wc -l < /data/seed")
+    assert out == "lead\n2\n"