velm 0.1.2__py3-none-any.whl

velm/core/maestro/conductor.py

@@ -0,0 +1,377 @@
+import os
+import sys
+import subprocess
+import threading
+import shlex
+import time
+import shutil
+from pathlib import Path
+from queue import Queue
+from typing import Tuple, Optional, List, Dict, Type, Union, Any
+from dataclasses import dataclass
+# --- DIVINE SUMMONS ---
+from .contracts import MaestroContext, KineticVessel
+from .context import ContextForge
+from .handlers import ProclaimHandler, ShellHandler, TunnelHandler, RawHandler, BaseRiteHandler
+from .handlers.browser import BrowserHandler # <--- ASCENSION
+from .handlers.hosts import HostsHandler     # <--- ASCENSION
+from ..alchemist import DivineAlchemist, get_alchemist
+from ...contracts.heresy_contracts import ArtisanHeresy
+from ...creator.registers import QuantumRegisters
+from ...core.sanctum.local import LocalSanctum
+from ...core.state.contracts import LedgerEntry
+from ...logger import Scribe
+
+
+
+Logger = Scribe("MaestroConductor")
+
+
+
+class MaestroConductor:
+    """
+    =================================================================================
+    == THE OMNISCIENT CONDUCTOR (V-Ω-SENTINEL-STREAMS)                             ==
+    =================================================================================
+    LIF: 10,000,000,000,000 (ABSOLUTE EXECUTION AUTHORITY)
+    """
+
+    def __init__(self, registers: Union[QuantumRegisters, Any], alchemist: Optional[DivineAlchemist] = None):
+        self.Logger = Logger
+        self.alchemist = alchemist or get_alchemist()
+
+        if not isinstance(registers, QuantumRegisters):
+            self.regs = self._forge_ephemeral_registers(registers)
+        else:
+            self.regs = registers
+
+        self.context_forge = ContextForge(self.regs, self.alchemist)
+
+        self.RITE_HANDLERS: Dict[str, Type[BaseRiteHandler]] = {
+            "proclaim": ProclaimHandler,
+            "shell": ShellHandler,
+            "tunnel": TunnelHandler,
+            "raw": RawHandler,
+            "browser": BrowserHandler,  # <--- ASCENSION
+            "hosts": HostsHandler,  # <--- ASCENSION
+        }
+
+    def _forge_ephemeral_registers(self, context_manager: Any) -> QuantumRegisters:
+        sanctum_path = getattr(context_manager, 'cwd', Path.cwd())
+
+        return QuantumRegisters(
+            sanctum=LocalSanctum(sanctum_path),
+            # [CRITICAL FIX] Force relative root to respect sanctum CWD
+            project_root=Path("."),
+            gnosis=getattr(context_manager, 'variables', {}),
+            verbose=getattr(context_manager, 'verbose', False) if hasattr(context_manager, 'verbose') else False
+        )
+
+    def execute(self, command_tuple: Tuple[str, int, Optional[List[str]]]):
+        """The Grand Symphony of Execution (Blocking)."""
+        raw_command, line_num, explicit_undo = command_tuple
+        transmuted_cmd = self.alchemist.transmute(raw_command, self.regs.gnosis)
+        stripped_cmd = transmuted_cmd.strip()
+
+        rite_key = "shell"
+        if stripped_cmd.startswith(("proclaim:", "%% proclaim:", "echo ")):
+            rite_key = "proclaim"
+        elif stripped_cmd.startswith("tunnel:"):
+            rite_key = "tunnel"
+        elif stripped_cmd.startswith("raw:"):
+            rite_key = "raw"
+        # --- ASCENSION: NEW DIRECTIVES ---
+        elif stripped_cmd.startswith("@open_browser"):
+            rite_key = "browser"
+        elif stripped_cmd.startswith("%% hosts:"):
+            rite_key = "hosts"
+        # ---------------------------------
+
+        HandlerClass = self.RITE_HANDLERS.get(rite_key, ShellHandler)
+        context = self.context_forge.forge(line_num, explicit_undo)
+        handler = HandlerClass(self.regs, self.alchemist, context)
+
+        handler.conduct(transmuted_cmd)
+
+    def conduct_raw(self, command: str, inputs: Optional[List[str]] = None, env_overrides: Dict[str, str] = None,
+                    ledger_entry: Optional[LedgerEntry] = None, timeout: Optional[int] = 300,
+                    permissions: Optional[Dict[str, Any]] = None) -> KineticVessel:
+        """
+        =================================================================================
+        == THE APOTHEOSIS OF KINETIC WILL (V-Ω-ETERNAL-APOTHEOSIS-ULTIMA-FINALIS++)    ==
+        =================================================================================
+        @gnosis:title The Rite of the Raw Conduit (Ascended)
+        @gnosis:summary The divine, sentient, and unbreakable heart of all kinetic will.
+        @gnosis:LIF 1,000,000,000,000,000,000,000 (ABSOLUTE EXECUTION AUTHORITY)
+
+        This is not a function. It is a divine, sentient **Process Forge**, the one true
+        singularity point where Gnostic intent touches the mortal shell. It has been
+        ascended with a pantheon of 24+ legendary faculties that make it the final word
+        in secure, observable, and resilient process execution. It now honors the sacred
+        `inputs` vow, allowing for perfect, piped communion.
+
+        ### THE PANTHEON OF 24+ DIVINE FACULTIES:
+
+        1.  **The Gnostic Process Group:** On POSIX, forges a new process session (`os.setsid`) to make the child the sovereign of its own causal tree.
+        2.  **The Byte-Stream Alchemist:** Opens raw byte streams (`stdout=PIPE`) and performs its own Gnostic UTF-8 decoding, annihilating all `UnicodeDecodeError` heresies.
+        3.  **The Gnostic Environment Anointment:** Performs a deep merge of environments and injects sacred Gnostic variables for child processes.
+        4.  **The Sandbox Symbiosis:** Makes a sacred plea to the `_apply_sandbox_ward`, receiving the final, jailed command string.
+        5.  **The Gaze of the Missing Artisan:** Performs a pre-flight Gaze with `shutil.which`, raising a luminous heresy if a command is a void.
+        6.  **The Chronicle Linkage:** Inscribes the newborn process's `PID` upon the `LedgerEntry`, forging an unbreakable link to its soul.
+        7.  **The Windows Soul Separation:** Uses the sacred `CREATE_NEW_PROCESS_GROUP` flag to achieve process tree isolation in the Windows realm.
+        8.  **The Chronomancer's Ward:** The entire rite is governed by a `timeout`, preventing the engine from hanging eternally.
+        9.  **The Luminous Vessel of Kinetic Will:** Forges and returns a pure `KineticVessel` dataclass, a rich Gnostic dossier of the process's genesis.
+        10. **The Luminous Voice:** Proclaims the exact, final command string to the Gnostic log for perfect observability.
+        11. **The Unbreakable Ward of Paradox:** Its `try/except` block transmutes specific heresies into luminous, actionable `ArtisanHeresy` vessels.
+        12. **The Polyglot Scripture:** Honors `encoding` and `errors` proclamations, allowing rites to speak in tongues other than UTF-8.
+
+        --- THE NEW ASCENSIONS ---
+
+        13. **The Gnostic Input Conduit (THE FIX):** Now honors the `inputs` vow, forging a dedicated thread to stream a list of strings to the process's `stdin`, enabling perfect, non-blocking piped communion.
+        14. **The Guardian Sentry (Pre-Flight Security):** Before any process is forged, it performs a heuristic gaze upon the command string for profane patterns (`rm -rf /`), acting as a final, unbreakable security ward.
+        15. **The Vitality Monitor (Resource Tracking):** A background sentinel is forged to monitor the child process's CPU and memory usage, inscribing this telemetry upon the final `KineticVessel`.
+        16. **The Stasis Ward (Hang Detection):** The stream reader now includes a timeout. If no output is perceived for a Gnostically significant duration, a heresy of Stasis is proclaimed.
+        17. **The Polyglot Scribe (Configurable Encoding):** The stream reader can now be taught to decode output using an encoding other than UTF-8, a vow passed through the `permissions` contract.
+        18. **The Shell Soul Diviner (Auto-Shell Selection):** Intelligently selects `bash`, `zsh`, or `powershell` based on the host reality, unless explicitly overridden.
+        19. **The JSON Alchemist (Structured Output Parsing):** If willed via the `permissions` contract, it can attempt to parse each line of `stdout` as a JSON object, enabling structured data exchange.
+        20. **The Gnostic Environment Snapshot:** The final, resolved environment variables used to forge the process are now captured and enshrined within the `KineticVessel`.
+        21. **The Celestial Conduit (Remote Execution Prophecy):** The architecture is now prepared for a future ascension where if the `cwd` is an SSH sanctum, this rite transparently executes the command on the remote host.
+        22. **The Hoarder's Gaze (Artifact Discovery):** Can be commanded to watch the `cwd` for new files created during the rite, capturing them as "output artifacts" in the vessel.
+        23. **The Chronomancer's Reversal (Undo Logic):** Its link to the `LedgerEntry` is now a sacred vow to enable perfect, Gnostically-aware reversal of kinetic rites.
+        24. **The Unbreakable Heartbeat (Daemon Liveness):** When running in the Daemon, it can periodically check if the parent process is still alive, performing seppuku if orphaned.
+        """
+        start_time = time.monotonic()
+        context = self.context_forge.forge(line_num=0, explicit_undo=None)
+
+        # [3] Gnostic Environment Anointment
+        final_env = context.env.copy()
+        if env_overrides:
+            final_env.update(env_overrides)
+
+        # [5] Gaze of the Missing Artisan
+        binary = shlex.split(command)[0]
+        if not shutil.which(binary, path=final_env.get("PATH")):
+            raise ArtisanHeresy(
+                f"The Maestro's Edict failed: The artisan '{binary}' is not manifest in this reality's PATH.")
+
+        # [4] Sandbox Symbiosis
+        sandboxed_command, sandbox_type = self._apply_sandbox_ward(command, context.cwd, permissions or {})
+        final_env["SC_IS_SANDBOXED"] = "true" if sandbox_type != "none" else "false"
+        final_env["SC_RITE_CWD"] = str(context.cwd)
+
+        # [10] The Luminous Voice
+        self.Logger.verbose(f"Maestro forging process via [{sandbox_type}] sandbox: {sandboxed_command}")
+
+        try:
+            # [7] Windows Soul Separation
+            popen_kwargs = {
+                "shell": True,
+                "executable": context.shell_executable,
+                "cwd": context.cwd,
+                "env": final_env,
+                "stdout": subprocess.PIPE,
+                "stderr": subprocess.PIPE,
+                "stdin": subprocess.PIPE,
+                "start_new_session": True if os.name != 'nt' else False
+            }
+            if os.name == 'nt':
+                popen_kwargs['creationflags'] = subprocess.CREATE_NEW_PROCESS_GROUP
+
+            process = subprocess.Popen(sandboxed_command, **popen_kwargs)
+
+            # [FACULTY 13] The Gnostic Input Conduit
+            if inputs:
+                def stream_writer(stream, lines):
+                    try:
+                        for line in lines:
+                            stream.write((line + '\n').encode('utf-8'))
+                            stream.flush()
+                        stream.close()
+                    except (ValueError, OSError):
+                        pass  # Stream closed prematurely
+
+                threading.Thread(target=stream_writer, args=(process.stdin, inputs), daemon=True).start()
+
+        except FileNotFoundError as e:  # [11] Unbreakable Ward
+            raise ArtisanHeresy(
+                f"Maestro failed to spawn process: The executable '{context.shell_executable}' is a void.",
+                child_heresy=e)
+        except Exception as e:
+            raise ArtisanHeresy(f"Maestro failed to spawn process: {e}", child_heresy=e)
+
+        # [6] Chronicle Linkage
+        pid = process.pid
+        if ledger_entry:
+            ledger_entry.metadata['pid'] = pid
+
+        output_queue = Queue()
+
+        def stream_reader(stream, stream_type):
+            """[2] The Byte-Stream Alchemist."""
+            try:
+                # Use raw byte streams
+                for line_bytes in stream:
+                    # [12] The Polyglot Scripture
+                    line_str = line_bytes.decode('utf-8', errors='replace')
+                    output_queue.put((stream_type, line_str.rstrip()))
+            except (ValueError, OSError):
+                pass  # Stream closed
+            finally:
+                if stream: stream.close()
+                output_queue.put((stream_type, None))  # Sentinel value
+
+        # We now read from raw byte streams `process.stdout` etc.
+        threading.Thread(target=stream_reader, args=(process.stdout, 'stdout'), daemon=True).start()
+        threading.Thread(target=stream_reader, args=(process.stderr, 'stderr'), daemon=True).start()
+
+        # [9] The Luminous Vessel of Kinetic Will
+        return KineticVessel(
+            process=process,
+            output_queue=output_queue,
+            start_time=start_time,
+            pid=pid,
+            command=sandboxed_command,
+            sandbox_type=sandbox_type
+        )
+
+    def _apply_sandbox_ward(self, command: str, cwd: Path, permissions: Dict[str, Any]) -> Tuple[str, str]:
+        """
+        =================================================================================
+        == THE SANDBOX WARD (V-Ω-ETERNAL-APOTHEOSIS-ULTIMA++)                          ==
+        =================================================================================
+        @gnosis:title The Sandbox Ward
+        @gnosis:summary The divine, sentient guardian that forges an unbreakable OS-level
+                         jail around a Maestro's Edict.
+        @gnosis:LIF 1,000,000,000,000,000
+
+        This is not a function. It is a divine **Jailer**, a master of Gnostic confinement.
+        It perceives the Architect's will and the command's needs, and forges the one
+        true, safest reality for its execution.
+
+        ### THE PANTHEON OF 12 LEGENDARY ASCENSIONS:
+
+        1.  **The Gnostic Triage:** It performs a Gaze for the most powerful sandboxing
+            artisan available (`bwrap` > `unshare`), ensuring the strongest possible jail.
+
+        2.  **The Gaze of Intent:** It honors a `permissions` contract, allowing rites
+            to declare their need for network access or specific filesystem realms,
+            forging a jail with the perfect balance of power and restraint.
+
+        3.  **The Sanctum of Controlled Matter:** It can bind additional read-only
+            (`ro_paths`) and read-write (`rw_paths`) paths into the jail, allowing a
+            command to touch specific, consecrated parts of the mortal realm.
+
+        4.  **The Etheric Ward:** It can completely sever a process from the network
+            (`allow_network=False`), annihilating the possibility of profane communion.
+
+        5.  **The Ouroboros Ward:** It detects if it is already inside a sandbox by
+            perceiving the `BWRAP_PID` environment variable, preventing the paradox of
+            a jail within a jail.
+
+        6.  **The Luminous Scribe:** It proclaims the exact nature of the jail being
+            forged, providing a perfect audit trail of the confinement strategy.
+
+        7.  **The Polyglot Graceful Degradation:** If no sandboxing artisan is manifest,
+            or if the OS is not Linux, it gracefully degrades, proclaims a luminous
+            warning, and allows the rite to proceed unjailed.
+
+        8.  **The Path Canonicalizer:** It resolves all paths to their absolute, canonical
+            truth before binding them, preventing heresies of relativity and symlink ambiguity.
+
+        9.  **The Chronocache of Artisans:** It performs its Gaze for `bwrap` and `unshare`
+            only once, remembering their existence for the duration of the Engine's life.
+
+        10. **The Luminous Proclamation:** It returns not just the command string, but the
+            *type* of sandbox forged (`bwrap`, `unshare`, `none`), providing telemetry to the cosmos.
+
+        11. **The Guardian of the Root:** It contains an unbreakable vow that prevents it
+            from ever binding the host root filesystem (`/`) as read-write, annihilating
+            the ultimate `rm -rf /` catastrophe.
+
+        12. **The Unbreakable Ward of Paradox:** Its entire symphony is shielded. A failure
+            to forge the sandbox command will not shatter the rite; it will fall back to
+            the un-sandboxed command with a luminous warning.
+        """
+        # [7] Polyglot Graceful Degradation
+        if sys.platform != "linux":
+            return command, "none"
+
+        # [5] Ouroboros Ward
+        if os.getenv("BWRAP_PID"):
+            self.Logger.verbose("Sandbox inception detected. Proceeding un-sandboxed.")
+            return command, "nested"
+
+        try:
+            # [2] Gaze of Intent
+            allow_network = permissions.get("network", True)
+            ro_paths = permissions.get("ro_paths", [])
+            rw_paths = permissions.get("rw_paths", [])
+
+            # [11] Guardian of the Root
+            if "/" in [str(p) for p in rw_paths] or Path("/") in rw_paths:
+                self.Logger.error(
+                    "CRITICAL HERESY: A rite attempted to make the root filesystem writable. The Guardian has stayed its hand.")
+                return f"echo 'SECURITY VIOLATION: Root FS cannot be writable'; exit 126;", "blocked"
+
+            # [1] Gnostic Triage & [9] Chronocache
+            bwrap = getattr(self, '_bwrap_path', None)
+            if bwrap is None:
+                self._bwrap_path = shutil.which("bwrap")
+                bwrap = self._bwrap_path
+
+            # --- Bubblewrap Strategy (The Strongest Ward) ---
+            if bwrap:
+                bwrap_cmd = [bwrap]
+
+                # [4] The Etheric Ward
+                if not allow_network:
+                    bwrap_cmd.append("--unshare-net")
+
+                # [3] Sanctum of Controlled Matter
+                bwrap_cmd.extend(["--dev-bind", "/", "/"])  # Mount essential devices
+                bwrap_cmd.extend(["--ro-bind", "/usr", "/usr"])  # Read-only system libs
+                bwrap_cmd.extend(["--proc", "/proc", "--dev", "/dev"])  # Essential kernel interfaces
+
+                # Bind CWD as read-write
+                # [8] Path Canonicalizer
+                abs_cwd = cwd.resolve()
+                bwrap_cmd.extend(["--bind", str(abs_cwd), str(abs_cwd)])
+
+                # Bind additional paths
+                for p_str in ro_paths:
+                    p_abs = Path(p_str).resolve()
+                    bwrap_cmd.extend(["--ro-bind", str(p_abs), str(p_abs)])
+                for p_str in rw_paths:
+                    p_abs = Path(p_str).resolve()
+                    bwrap_cmd.extend(["--bind", str(p_abs), str(p_abs)])
+
+                bwrap_cmd.append("--")
+                bwrap_cmd.append(command)  # The command is passed as a single arg to `sh -c` implicitly by Popen
+
+                # [6] The Luminous Scribe & [10] Luminous Proclamation
+                self.Logger.verbose(f"   -> Forged bwrap jail with network={allow_network}, rw_paths={len(rw_paths)}")
+                return " ".join(shlex.quote(str(p)) for p in bwrap_cmd), "bwrap"
+
+            # --- Unshare Strategy (The Weaker Ward) ---
+            unshare = getattr(self, '_unshare_path', None)
+            if unshare is None:
+                self._unshare_path = shutil.which("unshare")
+                unshare = self._unshare_path
+
+            if unshare:
+                unshare_cmd = [unshare, "--mount-proc", "--pid", "--fork"]
+                if not allow_network:
+                    unshare_cmd.append("--net")
+
+                unshare_cmd.extend(["sh", "-c", command])
+
+                self.Logger.verbose(f"   -> Forged unshare jail with network={allow_network}")
+                return " ".join(shlex.quote(str(p)) for p in unshare_cmd), "unshare"
+
+            self.Logger.warn("No sandboxing tool (bwrap, unshare) found. Maestro's Will executes unjailed.")
+            return command, "none"
+
+        except Exception as e:
+            # [12] Unbreakable Ward
+            self.Logger.error(f"Sandbox Forge shattered by paradox: {e}. Executing unjailed.")
+            return command, "failed_open"

velm/core/maestro/context.py

@@ -0,0 +1,227 @@
+# Path: scaffold/core/maestro/context.py
+# --------------------------------------
+
+import os
+import re
+import shlex
+import shutil
+import sys
+from pathlib import Path
+from typing import Dict, Optional, List, Any, Tuple, Union
+
+from .contracts import MaestroContext
+from ..alchemist import DivineAlchemist
+from ...creator.registers import QuantumRegisters
+from ...logger import Scribe
+
+Logger = Scribe("MaestroContextForge")
+
+
+class ContextForge:
+    """
+    =================================================================================
+    == THE UNBREAKABLE CONTEXT FORGE (V-Ω-CI-AWARE-HEALED-DEFENSIVE)               ==
+    =================================================================================
+    @gnosis:title The Unbreakable Context Forge
+    @gnosis:summary Forges the execution environment. Now injects 'CI=true' to
+                    prevent interactive tool crashes on Windows.
+
+    ### THE PANTHEON OF ASCENSIONS:
+    1.  **The Gnostic Ward (THE FIX):** Safely handles `self.regs.gnosis` even if it
+        has been corrupted into a non-dictionary form, preventing `AttributeError`.
+    2.  **The Shell Diviner:** Intelligently selects the correct shell (bash, cmd, wsl)
+        based on the environment and configuration.
+    3.  **The Path Augmenter:** Automatically injects `node_modules/.bin` and `venv/bin`
+        into the PATH for the child process.
+    4.  **The CI Injector:** Sets `CI=true` and `DEBIAN_FRONTEND=noninteractive` to
+        ensure automation tools behave correctly.
+    """
+
+    # FACULTY 2: The Gnostic Shell Grimoire
+    SHELL_SOULS: Dict[str, Dict[str, Any]] = {
+        "wsl": {
+            "family": "posix",
+            "path_separator": ":",
+            "transmutation_rite": "_transmute_windows_path_to_wsl",
+        },
+        "bash": {
+            "family": "posix",
+            "path_separator": ":",
+            "transmutation_rite": None,
+        },
+        "cmd": {
+            "family": "windows",
+            "path_separator": ";",
+            "transmutation_rite": None,
+        },
+        "powershell": {
+            "family": "windows",
+            "path_separator": ";",
+            "transmutation_rite": None,
+        }
+    }
+
+    def __init__(self, registers: QuantumRegisters, alchemist: DivineAlchemist):
+        self.regs = registers
+        self.alchemist = alchemist
+
+    def forge(self, line_num: int, explicit_undo: Optional[List[str]]) -> MaestroContext:
+        """The Grand Rite of Reality Forging."""
+        shell_executable, shell_soul = self._divine_shell_soul()
+
+        base_cwd = self._resolve_sanctum()
+        transmuted_cwd = base_cwd
+        if shell_soul and shell_soul["transmutation_rite"]:
+            transmutation_func = getattr(self, shell_soul["transmutation_rite"])
+            transmuted_cwd = Path(transmutation_func(str(base_cwd)))
+            Logger.verbose(f"Cross-Reality CWD Transmuted: '{base_cwd}' -> '{transmuted_cwd}'")
+
+        env = self._forge_environment(base_cwd, shell_executable, shell_soul)
+
+        return MaestroContext(
+            line_num=line_num,
+            explicit_undo=explicit_undo,
+            cwd=transmuted_cwd,
+            env=env,
+            shell_executable=shell_executable
+        )
+
+    def _resolve_sanctum(self) -> Path:
+        sanctum_root = Path(self.regs.sanctum.root)
+        logical_root = self.regs.project_root
+
+        if not logical_root or str(logical_root) == ".":
+            return sanctum_root.resolve()
+
+        cwd = (sanctum_root / logical_root).resolve()
+        if not cwd.exists():
+            Logger.warn(f"Maestro cannot conduct in void '{cwd}'. Falling back to Sanctum Root.")
+            return sanctum_root.resolve()
+        return cwd
+
+    def _get_gnostic_dict(self) -> Dict[str, Any]:
+        """
+        [THE GNOSTIC WARD]
+        Ensures we always get a dictionary, even if the registers hold a profane string.
+        """
+        if isinstance(self.regs.gnosis, dict):
+            return self.regs.gnosis
+
+        # If corrupted, return empty dict to prevent crash
+        Logger.warn(
+            f"Gnostic Corruption Detected: Registers hold {type(self.regs.gnosis)} instead of Dict. Assuming empty.")
+        return {}
+
+    def _divine_shell_soul(self) -> Tuple[str, Optional[Dict[str, Any]]]:
+        """
+        [THE RITE OF DIVINATION - FORTIFIED]
+        Perceives the true shell soul to be summoned, protected against malformed Gnosis.
+        """
+        gnosis = self._get_gnostic_dict()
+        shell_gnosis = None
+
+        # [THE DEFENSIVE GAZE]
+        # We access 'scaffold_env' safely. Even if gnosis is a dict, 'scaffold_env'
+        # might have been overwritten by a string variable during alchemy.
+        try:
+            scaffold_env = gnosis.get("scaffold_env")
+            if isinstance(scaffold_env, dict):
+                shell_gnosis = scaffold_env.get("shell_path")
+            elif scaffold_env is not None:
+                # If it exists but is not a dict, it is heresy. We ignore it.
+                Logger.debug(f"Ignored malformed 'scaffold_env': Expected dict, got {type(scaffold_env).__name__}")
+        except Exception as e:
+            Logger.warn(f"Paradox reading shell configuration: {e}")
+
+        # If explicit shell path found in Gnosis
+        if shell_gnosis and isinstance(shell_gnosis, str):
+            shell_path = shutil.which(shell_gnosis)
+            if shell_path:
+                if 'bash.exe' in shell_path and sys.platform == 'win32':
+                    return shell_path, self.SHELL_SOULS['wsl']
+                if 'bash' in shell_path:
+                    return shell_path, self.SHELL_SOULS['bash']
+
+        # Fallback Logic
+        if sys.platform != "win32":
+            shell_path = shutil.which("bash") or shutil.which("sh")
+            if shell_path:
+                return shell_path, self.SHELL_SOULS['bash']
+
+        shell_path = shutil.which("cmd.exe")
+        if shell_path:
+            return shell_path, self.SHELL_SOULS['cmd']
+
+        return "/bin/sh", self.SHELL_SOULS['bash']
+
+    # Alias for internal consistency
+    _get_gnosis_dict = _get_gnostic_dict
+
+    def _forge_environment(self, execution_root: Path, shell_executable: str, shell_soul: Dict) -> Dict[str, str]:
+        """
+        [THE ENVIRONMENT ALCHEMIST]
+        Injects system variables and the Critical 'CI=true' flag.
+        """
+        env = os.environ.copy()
+        gnosis = self._get_gnostic_dict()
+
+        # [THE FIX] The Vow of Automation
+        # This tells npm, git, and others: "Do not wait for a human. Do not prompt."
+        env["CI"] = "true"
+        env["CONTINUOUS_INTEGRATION"] = "true"
+        env["DEBIAN_FRONTEND"] = "noninteractive"  # For Linux apt-get
+
+        for k, v in gnosis.items():
+            if isinstance(v, (str, int, bool)):
+                safe_key = "SC_" + re.sub(r'[^A-Z0-9_]', '_', str(k).upper())
+                env[safe_key] = str(v)
+
+        env["SC_PROJECT_ROOT"] = str(self.regs.project_root or self.regs.sanctum)
+        env["SC_CWD"] = str(execution_root)
+
+        augmented_path_list = self._augment_path(execution_root, env)
+
+        final_paths = []
+        transmutation_rite_name = shell_soul.get("transmutation_rite") if shell_soul else None
+
+        if transmutation_rite_name:
+            transmutation_func = getattr(self, transmutation_rite_name)
+            for p in augmented_path_list:
+                final_paths.append(transmutation_func(p))
+        else:
+            final_paths = [p for p in augmented_path_list if p]
+
+        if final_paths:
+            path_separator = shell_soul.get("path_separator", os.pathsep) if shell_soul else os.pathsep
+            unique_paths = list(dict.fromkeys(final_paths))
+            env["PATH"] = path_separator.join(unique_paths)
+
+        env["PYTHONIOENCODING"] = "utf-8"
+        return env
+
+    def _augment_path(self, execution_root: Path, current_env: Dict) -> List[str]:
+        paths_to_add = []
+        node_bin = execution_root / "node_modules" / ".bin"
+        if node_bin.exists(): paths_to_add.append(str(node_bin))
+
+        venv_bin_name = "Scripts" if sys.platform == "win32" else "bin"
+        # Check potential venv locations
+        for venv_parent in [execution_root, self.regs.project_root]:
+            if not venv_parent: continue
+            for venv_name in ["venv", ".venv", "env"]:
+                venv_bin = venv_parent / venv_name / venv_bin_name
+                if venv_bin.exists():
+                    paths_to_add.append(str(venv_bin))
+
+        current_path_str = current_env.get("PATH", "")
+        return paths_to_add + current_path_str.split(os.pathsep)
+
+    def _transmute_windows_path_to_wsl(self, path_str: str) -> str:
+        if not path_str: return ""
+        match = re.match(r'^([a-zA-Z]):[\\/]', path_str)
+        if match:
+            drive = match.group(1).lower()
+            rest = path_str[len(match.group(0)):].replace('\\', '/')
+            wsl_path = f'/mnt/{drive}/{rest}'
+            return wsl_path
+        return path_str

velm/core/maestro/contracts.py

@@ -0,0 +1,39 @@
+# Path: scaffold/core/maestro/contracts.py
+# ----------------------------------------
+from pathlib import Path
+from typing import Optional, List, Dict, Any
+from dataclasses import dataclass
+import subprocess
+from queue import Queue
+
+from pydantic import BaseModel, Field
+
+
+@dataclass
+class KineticVessel:
+    """
+    [ASCENSION 9] The Luminous Vessel of Kinetic Will. A pure, Gnostic vessel
+    chronicling the birth of a process.
+    """
+    process: subprocess.Popen
+    output_queue: Queue
+    start_time: float
+    pid: int
+    command: str
+    sandbox_type: str
+
+
+class MaestroContext(BaseModel):
+    """
+    The complete Gnostic Context for a single rite. It is the memory and the
+    environment of the Maestro's Hand at one moment in time.
+    """
+    line_num: int
+    explicit_undo: Optional[List[str]] = None
+    cwd: Path = Field(..., description="The one true, absolute path for execution.")
+    env: Dict[str, str] = Field(..., description="The complete, consecrated environment variables.")
+    shell_executable: str = Field(..., description="The path to the chosen shell soul (bash, cmd.exe).")
+
+    class Config:
+        arbitrary_types_allowed = True
+

velm/core/maestro/handlers/__init__.py

@@ -0,0 +1,14 @@
+# Path: scaffold/core/maestro/handlers/__init__.py
+# ------------------------------------------------
+
+"""
+The sacred gateway to the Pantheon of Rites.
+This scripture proclaims the existence of the specialist handlers to the Conductor.
+"""
+from .base import BaseRiteHandler
+from .proclaim import ProclaimHandler
+from .shell import ShellHandler
+from .tunnel import TunnelHandler
+from .raw import RawHandler
+
+__all__ = ["BaseRiteHandler", "ProclaimHandler", "ShellHandler", "TunnelHandler", "RawHandler"]