chore: import upstream snapshot with attribution

python/tests/workspace/expand/__init__.py

@@ -0,0 +1,13 @@
+# ========= 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. =========

python/tests/workspace/expand/classify/test_heuristic.py

@@ -0,0 +1,80 @@
+# ========= 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.resource.ram import RAMResource
+from mirage.types import MountMode, PathSpec
+from mirage.workspace.expand.classify.heuristic import (_unescape_path,
+                                                        classify_word)
+from mirage.workspace.mount import MountRegistry
+
+
+def test_unescape_backslash_apostrophe():
+    assert _unescape_path(r"Zecheng\'s\ Server") == "Zecheng's Server"
+
+
+def test_unescape_no_backslash():
+    assert _unescape_path("normal") == "normal"
+
+
+def test_unescape_only_space():
+    assert _unescape_path(r"hello\ world") == "hello world"
+
+
+def test_classify_backslash_escaped_absolute():
+    registry = MountRegistry()
+    resource = RAMResource()
+    resource._store.dirs.add("/")
+    registry.mount("/ram/", resource, MountMode.WRITE)
+    result = classify_word(r"/ram/Zecheng\'s\ Server/", registry, "/")
+    assert isinstance(result, PathSpec)
+    assert result.virtual == "/ram/Zecheng's Server"
+
+
+def test_classify_quoted_path():
+    registry = MountRegistry()
+    resource = RAMResource()
+    resource._store.dirs.add("/")
+    registry.mount("/ram/", resource, MountMode.WRITE)
+    result = classify_word("/ram/Zecheng's Server/", registry, "/")
+    assert isinstance(result, PathSpec)
+    assert result.virtual == "/ram/Zecheng's Server"
+
+
+def test_bare_filename_stays_text():
+    registry = MountRegistry()
+    registry.mount("/ram/", RAMResource(), MountMode.WRITE)
+    assert classify_word("file.txt", registry, "/ram") == "file.txt"
+
+
+def test_relative_subdir_path_resolves():
+    registry = MountRegistry()
+    registry.mount("/ram/", RAMResource(), MountMode.WRITE)
+    result = classify_word("sub/file.txt", registry, "/ram")
+    assert isinstance(result, PathSpec)
+    assert result.virtual == "/ram/sub/file.txt"
+
+
+def test_relative_glob_resolves_against_cwd():
+    registry = MountRegistry()
+    registry.mount("/ram/", RAMResource(), MountMode.WRITE)
+    result = classify_word("*.txt", registry, "/ram")
+    assert isinstance(result, PathSpec)
+    assert result.pattern == "*.txt"
+    assert result.directory == "/ram/"
+
+
+def test_bare_glob_operator_stays_text():
+    registry = MountRegistry()
+    registry.mount("/ram/", RAMResource(), MountMode.WRITE)
+    assert classify_word("*", registry, "/ram") == "*"

python/tests/workspace/expand/classify/test_parts.py

@@ -0,0 +1,71 @@
+# ========= 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.commands.spec.types import OperandKind
+from mirage.resource.ram import RAMResource
+from mirage.types import MountMode, PathSpec
+from mirage.workspace.expand.classify.parts import classify_parts
+from mirage.workspace.mount import MountRegistry
+
+
+def _registry() -> MountRegistry:
+    registry = MountRegistry()
+    registry.mount("/ram/", RAMResource(), MountMode.WRITE)
+    return registry
+
+
+def test_name_never_classified():
+    result = classify_parts(["/ram/cat", "/ram/x"], _registry(), "/")
+    assert result[0] == "/ram/cat"
+    assert isinstance(result[1], PathSpec)
+
+
+def test_text_kind_keeps_string():
+    result = classify_parts(["cat", "/ram/x"],
+                            _registry(),
+                            "/",
+                            word_kinds=[OperandKind.TEXT])
+    assert result[1] == "/ram/x"
+
+
+def test_path_kind_classifies_bare_filename():
+    result = classify_parts(["cat", "file.txt"],
+                            _registry(),
+                            "/ram",
+                            word_kinds=[OperandKind.PATH])
+    assert isinstance(result[1], PathSpec)
+    assert result[1].virtual == "/ram/file.txt"
+
+
+def test_duplicate_word_kinds_per_slot():
+    result = classify_parts(["grep", "*.txt", "*.txt"],
+                            _registry(),
+                            "/ram",
+                            word_kinds=[OperandKind.TEXT, OperandKind.PATH])
+    assert result[1] == "*.txt"
+    assert isinstance(result[2], PathSpec)
+    assert result[2].pattern == "*.txt"
+
+
+def test_none_kind_falls_back_to_heuristic():
+    result = classify_parts(["cat", "/ram/x", "plain"],
+                            _registry(),
+                            "/",
+                            word_kinds=[None, None])
+    assert isinstance(result[1], PathSpec)
+    assert result[2] == "plain"
+
+
+def test_empty_parts():
+    assert classify_parts([], _registry(), "/") == []

python/tests/workspace/expand/classify/test_path.py

@@ -0,0 +1,45 @@
+# ========= 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.resource.ram import RAMResource
+from mirage.types import MountMode, PathSpec
+from mirage.workspace.expand.classify.path import classify_bare_path
+from mirage.workspace.mount import MountRegistry
+
+
+def _registry() -> MountRegistry:
+    registry = MountRegistry()
+    registry.mount("/ram/", RAMResource(), MountMode.WRITE)
+    return registry
+
+
+def test_bare_filename_resolves_against_cwd():
+    result = classify_bare_path("file.txt", _registry(), "/ram")
+    assert isinstance(result, PathSpec)
+    assert result.virtual == "/ram/file.txt"
+    assert result.resolved
+    assert result.raw_path == "file.txt"
+
+
+def test_bare_glob_becomes_pattern():
+    result = classify_bare_path("f?.txt", _registry(), "/ram")
+    assert isinstance(result, PathSpec)
+    assert result.pattern == "f?.txt"
+    assert result.directory == "/ram/"
+
+
+def test_absolute_path_delegates_to_heuristic():
+    result = classify_bare_path("/ram/file.txt", _registry(), "/")
+    assert isinstance(result, PathSpec)
+    assert result.virtual == "/ram/file.txt"

python/tests/workspace/expand/classify/test_relative.py

@@ -0,0 +1,62 @@
+# ========= 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.resource.ram import RAMResource
+from mirage.types import MountMode, PathSpec
+from mirage.workspace.expand.classify.relative import relative_spec
+from mirage.workspace.mount import MountRegistry
+
+
+def _registry() -> MountRegistry:
+    registry = MountRegistry()
+    registry.mount("/ram/", RAMResource(), MountMode.WRITE)
+    return registry
+
+
+def test_plain_word_resolves_and_keeps_raw():
+    result = relative_spec("sub/a.txt", _registry(), "/ram")
+    assert isinstance(result, PathSpec)
+    assert result.virtual == "/ram/sub/a.txt"
+    assert result.raw_path == "sub/a.txt"
+    assert result.resolved
+    assert result.pattern is None
+
+
+def test_glob_word_becomes_pattern():
+    result = relative_spec("sub/*.txt", _registry(), "/ram")
+    assert isinstance(result, PathSpec)
+    assert result.directory == "/ram/sub/"
+    assert result.pattern == "*.txt"
+    assert not result.resolved
+    assert result.raw_path == "sub/*.txt"
+
+
+def test_dotdot_normalizes():
+    result = relative_spec("../x.txt", _registry(), "/ram/sub")
+    assert isinstance(result, PathSpec)
+    assert result.virtual == "/ram/x.txt"
+    assert result.raw_path == "../x.txt"
+
+
+def test_unmounted_stays_text():
+    registry = MountRegistry()
+    registry.mount("/ram/", RAMResource(), MountMode.WRITE)
+    assert relative_spec("a.txt", registry, "/elsewhere") == "a.txt"
+
+
+def test_raw_path_round_trip():
+    result = relative_spec("./sub/a.txt", _registry(), "/ram")
+    assert isinstance(result, PathSpec)
+    assert result.raw_path == "./sub/a.txt"
+    assert result.virtual == "/ram/sub/a.txt"

python/tests/workspace/expand/test_argv.py

@@ -0,0 +1,58 @@
+# ========= 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 dataclasses
+
+import pytest
+
+from mirage.types import PathSpec
+from mirage.workspace.expand.argv import Argv
+
+
+def _ps(virtual: str) -> PathSpec:
+    return PathSpec(virtual=virtual,
+                    directory=virtual[:virtual.rfind("/") + 1],
+                    resource_path="",
+                    resolved=True)
+
+
+def test_words_includes_name():
+    argv = Argv(name="cat", args=("f.txt", ), operands=(_ps("/ram/f.txt"), ))
+    assert argv.words == ["cat", _ps("/ram/f.txt")]
+
+
+def test_words_empty_command():
+    assert Argv(name="", args=(), operands=()).words == []
+
+
+def test_views_differ_only_in_type():
+    pattern = _ps("/ram/*.txt")
+    argv = Argv(name="ls", args=("/ram/*.txt", ), operands=(pattern, ))
+    assert len(argv.args) == len(argv.operands)
+    assert argv.args[0] == argv.operands[0].virtual
+
+
+def test_with_operands_replaces_only_operands():
+    argv = Argv(name="rm", args=("link", ), operands=(_ps("/ram/link"), ))
+    rewritten = argv.with_operands([_ps("/ram/target")])
+    assert rewritten.operands == (_ps("/ram/target"), )
+    assert rewritten.name == "rm"
+    assert rewritten.args == ("link", )
+    assert argv.operands == (_ps("/ram/link"), )
+
+
+def test_frozen():
+    argv = Argv(name="cat", args=(), operands=())
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        argv.name = "dog"

python/tests/workspace/expand/test_globs.py

@@ -0,0 +1,296 @@
+# ========= 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, patch
+
+from mirage.cache.index import RAMIndexCacheStore
+from mirage.resource.ram import RAMResource
+from mirage.types import PathSpec
+from mirage.utils.key_prefix import mount_key
+from mirage.workspace.expand.globs import resolve_globs
+
+
+def _mock_registry(resolve_result=None):
+    mount = MagicMock()
+    mount.prefix = "/data/"
+
+    async def _resolve_glob(scopes, prefix=""):
+        if resolve_result is not None:
+            return resolve_result
+        return scopes
+
+    mount.resource = MagicMock()
+    mount.resource.resolve_glob = _resolve_glob
+
+    reg = MagicMock()
+    reg.mount_for = MagicMock(return_value=mount)
+    return reg
+
+
+def _run(coro):
+    return asyncio.run(coro)
+
+
+def test_text_passes_through():
+    reg = _mock_registry()
+    classified = ["grep", "pattern"]
+    result = _run(resolve_globs(classified, reg))
+    assert result == ["grep", "pattern"]
+
+
+def test_pathspec_without_pattern_preserved():
+    reg = _mock_registry()
+    ps = PathSpec(resource_path="data/file.txt",
+                  virtual="/data/file.txt",
+                  directory="/data/",
+                  resolved=True)
+    classified = ["cat", ps]
+    result = _run(resolve_globs(classified, reg))
+    assert len(result) == 2
+    assert result[0] == "cat"
+    assert isinstance(result[1], PathSpec)
+    assert result[1] is ps
+
+
+def test_glob_pathspec_resolved_to_pathspec():
+    resolved_ps = PathSpec(
+        resource_path=mount_key("/data/a.txt", "/data"),
+        virtual="/data/a.txt",
+        directory="/data/",
+        resolved=True,
+    )
+    reg = _mock_registry(resolve_result=[resolved_ps])
+    glob_ps = PathSpec(
+        resource_path="data/*.txt",
+        virtual="/data/*.txt",
+        directory="/data/",
+        pattern="*.txt",
+        resolved=False,
+    )
+    classified = ["cat", glob_ps]
+    result = _run(resolve_globs(classified, reg))
+    assert len(result) == 2
+    assert result[0] == "cat"
+    assert isinstance(result[1], PathSpec)
+    assert result[1] is resolved_ps
+
+
+def test_glob_multiple_matches_expand():
+    matches = [
+        PathSpec(resource_path="data/a.txt",
+                 virtual="/data/a.txt",
+                 directory="/data/",
+                 resolved=True),
+        PathSpec(resource_path="data/b.txt",
+                 virtual="/data/b.txt",
+                 directory="/data/",
+                 resolved=True),
+    ]
+    reg = _mock_registry(resolve_result=matches)
+    glob_ps = PathSpec(
+        resource_path="data/*.txt",
+        virtual="/data/*.txt",
+        directory="/data/",
+        pattern="*.txt",
+        resolved=False,
+    )
+    classified = ["ls", glob_ps]
+    result = _run(resolve_globs(classified, reg))
+    assert len(result) == 3
+    assert result[0] == "ls"
+    assert all(isinstance(r, PathSpec) for r in result[1:])
+    assert result[1].virtual == "/data/a.txt"
+    assert result[2].virtual == "/data/b.txt"
+
+
+def test_glob_string_result_wrapped_in_pathspec():
+    reg = _mock_registry(resolve_result=["/a.txt"])
+    glob_ps = PathSpec(
+        resource_path="data/*.txt",
+        virtual="/data/*.txt",
+        directory="/data/",
+        pattern="*.txt",
+        resolved=False,
+    )
+    classified = ["cat", glob_ps]
+    result = _run(resolve_globs(classified, reg))
+    assert len(result) == 2
+    assert isinstance(result[1], PathSpec)
+    assert result[1].virtual == "/data/a.txt"
+
+
+def test_glob_no_match_keeps_literal_word():
+    reg = _mock_registry(resolve_result=[])
+    glob_ps = PathSpec(
+        resource_path="data/*.xyz",
+        virtual="/data/*.xyz",
+        directory="/data/",
+        pattern="*.xyz",
+        resolved=False,
+    )
+    classified = ["cat", glob_ps]
+    result = _run(resolve_globs(classified, reg))
+    assert len(result) == 2
+    assert result[0] == "cat"
+    assert isinstance(result[1], PathSpec)
+    assert result[1].virtual == "/data/*.xyz"
+    assert result[1].pattern
+
+
+def test_mixed_text_and_pathspec():
+    reg = _mock_registry()
+    ps = PathSpec(resource_path="data/file.txt",
+                  virtual="/data/file.txt",
+                  directory="/data/",
+                  resolved=True)
+    classified = ["grep", "-i", "pattern", ps]
+    result = _run(resolve_globs(classified, reg))
+    assert result[0] == "grep"
+    assert result[1] == "-i"
+    assert result[2] == "pattern"
+    assert isinstance(result[3], PathSpec)
+    assert result[3] is ps
+
+
+def test_resolve_error_returns_original_pathspec():
+    reg = _mock_registry()
+    reg.mount_for = MagicMock(side_effect=ValueError("no mount"))
+    glob_ps = PathSpec(
+        resource_path="unknown/*.txt",
+        virtual="/unknown/*.txt",
+        directory="/unknown/",
+        pattern="*.txt",
+        resolved=False,
+    )
+    classified = ["cat", glob_ps]
+    result = _run(resolve_globs(classified, reg))
+    assert len(result) == 2
+    assert isinstance(result[1], PathSpec)
+
+
+def test_pathspec_dir_carries_pattern():
+    ps = PathSpec(
+        resource_path=mount_key("/data/*.txt", "/data"),
+        virtual="/data/*.txt",
+        directory="/data/",
+        pattern="*.txt",
+        resolved=False,
+    )
+    d = ps.dir
+    assert d.virtual == "/data/"
+    assert d.pattern == "*.txt"
+    assert d.resource_path == ""
+
+
+def test_pathspec_dir_no_pattern():
+    ps = PathSpec(
+        resource_path="data/file.txt",
+        virtual="/data/file.txt",
+        directory="/data/",
+        resolved=True,
+    )
+    d = ps.dir
+    assert d.virtual == "/data/"
+    assert d.pattern is None
+
+
+def test_scope_error_truncates_instead_of_crash():
+    from mirage.core.ram.glob import resolve_glob as ram_resolve_glob
+
+    resource = RAMResource()
+    for i in range(20):
+        resource._store.files[f"/f{i:02d}.txt"] = b""
+    resource._store.dirs.add("/")
+    index = RAMIndexCacheStore()
+    glob_ps = PathSpec(
+        resource_path="*.txt",
+        virtual="/*.txt",
+        directory="/",
+        pattern="*.txt",
+        resolved=False,
+    )
+
+    async def _run():
+        with patch("mirage.core.ram.glob.SCOPE_ERROR", 5):
+            result = await ram_resolve_glob(resource.accessor, [glob_ps],
+                                            index)
+        return result
+
+    result = asyncio.run(_run())
+    assert len(result) == 5
+
+
+def test_relative_glob_matches_spelled_as_typed():
+    matches = [
+        PathSpec(resource_path="data/sub/a.txt",
+                 virtual="/data/sub/a.txt",
+                 directory="/data/sub/",
+                 resolved=True),
+    ]
+    reg = _mock_registry(resolve_result=matches)
+    glob_ps = PathSpec(
+        resource_path="data/sub/*.txt",
+        virtual="/data/sub/*.txt",
+        directory="/data/sub/",
+        pattern="*.txt",
+        resolved=False,
+        raw_path="sub/*.txt",
+    )
+    result = _run(resolve_globs(["ls", glob_ps], reg))
+    assert isinstance(result[1], PathSpec)
+    assert result[1].raw_path == "sub/a.txt"
+    assert result[1].virtual == "/data/sub/a.txt"
+
+
+def test_absolute_glob_matches_keep_virtual():
+    matches = [
+        PathSpec(resource_path="data/a.txt",
+                 virtual="/data/a.txt",
+                 directory="/data/",
+                 resolved=True),
+    ]
+    reg = _mock_registry(resolve_result=matches)
+    glob_ps = PathSpec(
+        resource_path="data/*.txt",
+        virtual="/data/*.txt",
+        directory="/data/",
+        pattern="*.txt",
+        resolved=False,
+    )
+    result = _run(resolve_globs(["ls", glob_ps], reg))
+    assert isinstance(result[1], PathSpec)
+    assert result[1].raw_path == result[1].virtual
+    assert result[1].raw_path == "/data/a.txt"
+
+
+def test_bare_relative_glob_raw_has_no_dir_prefix():
+    matches = [
+        PathSpec(resource_path="data/a.txt",
+                 virtual="/data/a.txt",
+                 directory="/data/",
+                 resolved=True),
+    ]
+    reg = _mock_registry(resolve_result=matches)
+    glob_ps = PathSpec(
+        resource_path="data/*.txt",
+        virtual="/data/*.txt",
+        directory="/data/",
+        pattern="*.txt",
+        resolved=False,
+        raw_path="*.txt",
+    )
+    result = _run(resolve_globs(["ls", glob_ps], reg))
+    assert isinstance(result[1], PathSpec)
+    assert result[1].raw_path == "a.txt"

python/tests/workspace/expand/test_redirects.py

@@ -0,0 +1,68 @@
+# ========= 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_at(cwd: str) -> Workspace:
+    ws = Workspace({"/": RAMResource()}, mode=MountMode.WRITE)
+    await ws.execute(f"mkdir -p {cwd}")
+    await ws.execute(f"cd {cwd}")
+    return ws
+
+
+@pytest.mark.asyncio
+async def test_redirect_bare_target_resolves_against_cwd():
+    # A redirect target is a path by definition: `> BARE` must write
+    # cwd/BARE even though the bare word would classify as text.
+    ws = await _workspace_at("/data")
+    await ws.execute("echo hi > BARE")
+    io = await ws.execute("cat /data/BARE")
+    assert (io.stdout or b"") == b"hi\n"
+
+
+@pytest.mark.asyncio
+async def test_redirect_extensionless_relative_target():
+    ws = await _workspace_at("/data")
+    await ws.execute("mkdir -p /data/sub")
+    await ws.execute("echo hi > sub/OUT")
+    io = await ws.execute("cat /data/sub/OUT")
+    assert (io.stdout or b"") == b"hi\n"
+
+
+@pytest.mark.asyncio
+async def test_redirect_append_relative_target():
+    ws = await _workspace_at("/data")
+    await ws.execute("echo one > LOG")
+    await ws.execute("echo two >> LOG")
+    io = await ws.execute("cat /data/LOG")
+    assert (io.stdout or b"") == b"one\ntwo\n"
+
+
+@pytest.mark.asyncio
+async def test_redirect_stdin_relative_source():
+    ws = await _workspace_at("/data")
+    await ws.execute("echo hi > IN")
+    io = await ws.execute("wc -l < IN")
+    assert (io.stdout or b"").strip() == b"1"
+
+
+@pytest.mark.asyncio
+async def test_redirect_absolute_target_unchanged():
+    ws = await _workspace_at("/data")
+    await ws.execute("echo hi > /data/ABS")
+    io = await ws.execute("cat /data/ABS")
+    assert (io.stdout or b"") == b"hi\n"

python/tests/workspace/expand/test_spec_hints.py

@@ -0,0 +1,101 @@
+# ========= 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
+from mirage.commands.spec import SPECS
+from mirage.commands.spec.types import OperandKind
+from mirage.workspace.expand.spec_hints import (spec_for_command,
+                                                spec_word_kinds)
+
+PATH = OperandKind.PATH
+TEXT = OperandKind.TEXT
+
+
+def test_spec_for_command_prefers_cwd_mount():
+    ws = Workspace({"/": RAMResource()}, mode=MountMode.WRITE)
+    mount = ws._registry.mount_for("/")
+    spec = spec_for_command("grep", ws._registry, "/")
+    assert spec is mount.spec_for("grep")
+
+
+def test_spec_for_command_falls_back_to_shared_specs():
+    ws = Workspace({"/": RAMResource()}, mode=MountMode.WRITE)
+    mount = ws._registry.mount_for("/")
+    name = next(n for n in SPECS if mount.spec_for(n) is None)
+    assert spec_for_command(name, ws._registry, "/") is SPECS[name]
+
+
+def test_spec_for_command_unknown_name_is_none():
+    ws = Workspace({"/": RAMResource()}, mode=MountMode.WRITE)
+    assert spec_for_command("no-such-command", ws._registry, "/") is None
+
+
+def test_basic_grep_pattern_and_path():
+    kinds = spec_word_kinds(SPECS["grep"], ["pattern", "file.txt"])
+    assert kinds == [TEXT, PATH]
+
+
+def test_text_flag_values_positional():
+    kinds = spec_word_kinds(SPECS["find"], ["/data", "-name", "*.txt"])
+    assert kinds == [PATH, None, TEXT]
+
+
+def test_long_value_flag_equals_not_classified():
+    kinds = spec_word_kinds(SPECS["du"], ["--max-depth=1", "/data"])
+    assert kinds == [None, PATH]
+
+
+def test_mixed_cluster_value_is_text():
+    kinds = spec_word_kinds(SPECS["grep"], ["-ne", "pat", "/a.txt"])
+    assert kinds == [None, TEXT, PATH]
+
+
+def test_repeated_dash_e_values_are_text():
+    kinds = spec_word_kinds(SPECS["grep"],
+                            ["-e", "foo", "-e", "bar", "/a.txt"])
+    assert kinds == [None, TEXT, None, TEXT, PATH]
+
+
+def test_numeric_shorthand_not_a_path():
+    kinds = spec_word_kinds(SPECS["head"], ["-5", "file.txt"])
+    assert kinds == [None, PATH]
+
+
+def test_find_ignore_tokens_not_classified():
+    kinds = spec_word_kinds(SPECS["find"],
+                            ["/data", "(", "-name", "*.txt", ")"])
+    assert kinds[0] == PATH
+    assert kinds[1] is None
+    assert kinds[4] is None
+
+
+def test_duplicate_word_text_and_path_slots():
+    # F8: the same word is the pattern (TEXT) and a file glob (PATH);
+    # value sets could not tell the two slots apart.
+    kinds = spec_word_kinds(SPECS["grep"], ["*.txt", "*.txt"])
+    assert kinds == [TEXT, PATH]
+
+
+@pytest.mark.asyncio
+async def test_du_max_depth_equals_at_root_mount():
+    ws = Workspace({"/": RAMResource()}, mode=MountMode.WRITE)
+    await ws.execute("mkdir -p /data/sub")
+    await ws.execute("tee /data/sub/n.txt > /dev/null", stdin=b"x\n")
+
+    io = await ws.execute("du --max-depth=1 /data/sub")
+    out = (io.stdout or b"").decode()
+    assert "--max-depth" not in out
+    assert "/data/sub" in out