diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ed54c31..8ef7e08 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -25,3 +25,13 @@ jobs:
       otp_versions: '["26", "27"]'
       elixir_versions: '["1.17", "1.18"]'
       test_command: mix test
+
+  coverage:
+    name: Coverage
+    uses: agentjido/github-actions/.github/workflows/elixir-test.yml@main
+    with:
+      otp_versions: '["27"]'
+      elixir_versions: '["1.18"]'
+      test_command: >-
+        mix coveralls.json &&
+        MIX_ENV=test mix run -e 'data = Jason.decode!(File.read!("cover/excoveralls.json")); coverages = data["source_files"] |> Enum.flat_map(& &1["coverage"]); relevant = Enum.count(coverages, &(!is_nil(&1))); missed = Enum.count(coverages, &(&1 == 0)); percent = (relevant - missed) * 100.0 / relevant; rounded = Float.round(percent, 2); IO.puts("Coverage gate: #{rounded}%"); if percent < 90.0, do: System.halt(1)'
diff --git a/AGENTS.md b/AGENTS.md
index fead125..df9d484 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,150 +2,66 @@
 
 ## Purpose
 
-Jido.Shell is an Elixir-native virtual shell system that provides multi-instance interactive sessions with virtual file system support. It's designed to be embedded in any BEAM application, offering an interactive REPL and full programmatic API for spawning sessions, evaluating commands, and manipulating virtual file systems.
+Jido.Shell is an Elixir-native virtual shell for multi-session, sandboxed command execution over virtual filesystems.
 
-## Commands
+## Key Commands
 
 ```bash
-# Development
-mix setup              # Install deps and git hooks
+mix setup
 mix compile --warnings-as-errors
-mix test               # Run tests (excludes flaky)
-mix test --include flaky  # Run all tests
-mix coveralls.html     # Test coverage report
-
-# Quality
-mix quality            # All checks (format, compile, credo, dialyzer)
-mix q                  # Alias for quality
-mix format             # Auto-format code
-mix credo              # Linting
-mix dialyzer           # Type checking
-
-# Documentation
-mix docs               # Generate docs
-
-# Interactive
-mix kodo               # IEx-style shell
-mix kodo --ui          # Rich terminal UI
+mix test
+mix test --include flaky
+mix coveralls
+mix quality
+mix docs
+mix jido_shell
 ```
 
-## Architecture
-
-### Supervision Tree
+## Core Architecture
 
 ```
 Jido.Shell.Supervisor
+├── Jido.Shell.VFS.MountTable
 ├── Registry (Jido.Shell.SessionRegistry)
 ├── DynamicSupervisor (Jido.Shell.SessionSupervisor)
-│   └── SessionServer processes
 ├── DynamicSupervisor (Jido.Shell.FilesystemSupervisor)
-│   └── Jido.VFS adapter processes
 └── Task.Supervisor (Jido.Shell.CommandTaskSupervisor)
-    └── Command task processes
 ```
 
-### Key Modules
-
-| Module | Purpose |
-|--------|---------|
-| `Jido.Shell.Agent` | Programmatic API for agents (synchronous) |
-| `Jido.Shell.Session` | Session lifecycle management |
-| `Jido.Shell.SessionServer` | Per-session GenServer with state and subscriptions |
-| `Jido.Shell.Command` | Command behaviour definition |
-| `Jido.Shell.Command.Registry` | Command lookup and registration |
-| `Jido.Shell.CommandRunner` | Task-based command execution |
-| `Jido.Shell.VFS` | Virtual filesystem router |
-| `Jido.Shell.VFS.MountTable` | ETS-backed mount table |
-| `Jido.Shell.Transport.IEx` | Interactive IEx transport |
-| `Jido.Shell.Transport.TermUI` | Rich terminal UI transport |
-
-### Command Pattern
+## Main Modules
 
-Commands implement `Jido.Shell.Command` behaviour:
-
-```elixir
-defmodule Jido.Shell.Command.Example do
-  @behaviour Jido.Shell.Command
-
-  @impl true
-  def name, do: "example"
-
-  @impl true
-  def summary, do: "Example command"
-
-  @impl true
-  def schema do
-    Zoi.map(%{
-      args: Zoi.array(Zoi.string()) |> Zoi.default([])
-    })
-  end
-
-  @impl true
-  def run(state, args, emit) do
-    emit.({:output, "Hello\n"})
-    {:ok, nil}  # or {:ok, {:state_update, %{cwd: "/new/path"}}}
-  end
-end
-```
+- `Jido.Shell.Agent` - synchronous API for agents
+- `Jido.Shell.Session` - session lifecycle
+- `Jido.Shell.SessionServer` - per-session GenServer
+- `Jido.Shell.CommandRunner` - command execution and chaining
+- `Jido.Shell.VFS` - mounted filesystem router
+- `Jido.Shell.Transport.IEx` - interactive shell transport
 
-### Session Events
+## Session Events
 
 ```elixir
-{:kodo_session, session_id, event}
-
-# Events:
-{:command_started, line}
-{:output, chunk}
-{:error, %Jido.Shell.Error{}}
-{:cwd_changed, path}
-:command_done
-:command_cancelled
-{:command_crashed, reason}
+{:jido_shell_session, session_id, event}
 ```
 
-## Code Style
+Events:
 
-- Use `mix format` before committing
-- Elixir naming: snake_case functions, PascalCase modules
-- Pattern match with `{:ok, result}` | `{:error, reason}`
-- Add `@spec` type annotations for public functions
-- Test with ExUnit in `describe` blocks
-- Use `Jido.Shell.Error` for structured errors
-- Follow conventional commits for git messages
+- `{:command_started, line}`
+- `{:output, chunk}`
+- `{:error, %Jido.Shell.Error{}}`
+- `{:cwd_changed, path}`
+- `:command_done`
+- `:command_cancelled`
+- `{:command_crashed, reason}`
 
-## Testing
+## Test Layout
 
-```elixir
-# Use Jido.Shell.TestShell for E2E tests
-shell = Jido.Shell.TestShell.start!()
-assert {:ok, "/"} = Jido.Shell.TestShell.run(shell, "pwd")
-```
+- Unit/integration: `test/jido/shell/**/*.exs`
+- End-to-end: `test/jido/shell/e2e_test.exs`
+- Support helpers: `test/support/*.ex`
 
-## File Structure
+## Conventions
 
-```
-lib/
-├── kodo.ex                    # Version and utilities
-├── kodo/
-│   ├── application.ex         # OTP application
-│   ├── agent.ex               # Agent API
-│   ├── session.ex             # Session management
-│   ├── session_server.ex      # Session GenServer
-│   ├── session/state.ex       # Session state struct
-│   ├── command.ex             # Command behaviour
-│   ├── command/               # Built-in commands
-│   ├── command_runner.ex      # Task execution
-│   ├── vfs.ex                 # Virtual filesystem
-│   ├── vfs/                   # VFS internals
-│   ├── transport/             # IEx and TermUI
-│   └── error.ex               # Error handling
-├── mix/tasks/
-│   └── kodo.ex                # mix kodo task
-test/
-├── support/
-│   ├── case.ex                # Test case template
-│   └── test_shell.ex          # E2E test helper
-├── kodo/
-│   ├── e2e_test.exs           # End-to-end tests
-│   └── ...                    # Unit tests
-```
+- Prefer tuple-based APIs: `{:ok, ...}` / `{:error, ...}`
+- Use `Jido.Shell.Error` for structured errors
+- Keep workspace IDs as strings (`String.t()`)
+- Avoid runtime atom generation from user input
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 279ce6e..7b0e8f9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,28 +5,46 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+- Hardened identifier model to use binary workspace IDs across public APIs.
+- Removed runtime-generated atom usage from session/VFS workflows.
+- Updated `SessionServer` and `Agent` APIs to return explicit structured errors for missing sessions and invalid identifiers instead of crashing callers.
+- Added deterministic mount lifecycle behavior:
+  - duplicate mount path rejection,
+  - typed mount startup failures,
+  - owned filesystem process termination on unmount/workspace teardown.
+- Added workspace teardown API wiring for deterministic resource cleanup.
+- Upgraded command parsing to support quote/escape-aware tokenization and top-level chaining (`;`, `&&`).
+- Hardened `sleep` and `seq` argument parsing to return validation errors for invalid numerics.
+- Expanded sandbox network policy endpoint handling and chaining-aware enforcement.
+- Added optional per-command runtime/output limits in execution context.
+- Removed the alternate rich UI mode from the V1 public release surface and CLI flags.
+- Updated docs and examples to current names/event tuples and current package surface.
+
+### Added
+- `MIGRATION.md` documenting V1-facing breaking API changes and upgrade steps.
+- New hardening tests for:
+  - workspace identifier validation and atom leak regression,
+  - session API resilience/error shaping,
+  - mount lifecycle/cleanup behavior,
+  - parser/chaining behavior and syntax errors,
+  - command numeric validation,
+  - network policy edge cases,
+  - transport and helper branch behavior.
+- CI coverage job with enforced coverage gate.
+
 ## [3.0.0] - 2024-12-23
 
 ### Added
-- Complete v3 reimplementation from scratch
-- `Jido.Shell.Session` - Session management with Registry and DynamicSupervisor
-- `Jido.Shell.SessionServer` - GenServer per session with state and subscriptions
-- `Jido.Shell.Command` behaviour - Unified command interface with streaming support
-- `Jido.Shell.CommandRunner` - Task-based command execution
-- `Jido.Shell.VFS` - Virtual filesystem with Hako adapters and mount table
-- `Jido.Shell.Agent` - Agent-friendly programmatic API
-- `Jido.Shell.Transport.IEx` - Interactive IEx shell transport
-- `Jido.Shell.Transport.TermUI` - Rich terminal UI transport
-- Built-in commands: echo, pwd, cd, ls, cat, write, mkdir, rm, cp, env, help, sleep, seq
-- `mix kodo` task for easy shell access
-- Zoi schema validation for command arguments
-- Structured errors with `Jido.Shell.Error`
-- Session events protocol for streaming output
-- Command cancellation support
+- Complete v3 reimplementation from scratch.
+- `Jido.Shell.Session`, `Jido.Shell.SessionServer`, `Jido.Shell.Command`, `Jido.Shell.CommandRunner`, `Jido.Shell.VFS`, `Jido.Shell.Agent`, `Jido.Shell.Transport.IEx`.
+- Built-in commands: `echo`, `pwd`, `cd`, `ls`, `cat`, `write`, `mkdir`, `rm`, `cp`, `env`, `help`, `sleep`, `seq`.
+- Structured shell errors and session event protocol.
 
 ### Changed
-- Complete architecture redesign for streaming and agent integration
-- GenServer-based sessions replace stateless execution
+- Architecture redesign for streaming and agent integration.
 
 ### Removed
-- Legacy v2 implementation
+- Legacy v2 implementation.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ca81bba..179bcf3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,176 +1,69 @@
 # Contributing to Jido.Shell
 
-Thank you for your interest in contributing to Jido.Shell! This document provides guidelines and instructions for contributing.
+Thanks for contributing.
 
 ## Development Setup
 
-1. Clone the repository:
-
-```bash
-git clone https://github.com/agentjido/kodo.git
-cd kodo
-```
-
-2. Install dependencies and set up git hooks:
-
 ```bash
+git clone https://github.com/agentjido/jido_shell.git
+cd jido_shell
 mix setup
+mix test
 ```
 
-3. Run tests to verify your setup:
+## Quality Bar
+
+Run before opening a PR:
 
 ```bash
+mix quality
 mix test
+mix test --include flaky
+mix coveralls
 ```
 
-## Development Workflow
-
-### Running Quality Checks
-
-Before submitting a PR, ensure all quality checks pass:
+## Common Commands
 
 ```bash
-# Run all quality checks
-mix quality
-
-# Or run individually:
 mix format --check-formatted
 mix compile --warnings-as-errors
 mix credo --min-priority higher
 mix dialyzer
+mix docs
 ```
 
-### Running Tests
+## Pull Requests
 
-```bash
-# Run tests
-mix test
-
-# Run tests with coverage
-mix coveralls.html
-
-# Run specific test file
-mix test test/kodo/agent_test.exs
-
-# Run tests matching a pattern
-mix test --only describe:"basic shell operations"
-```
-
-### Code Style
-
-- Follow standard Elixir conventions
-- Use `mix format` before committing
-- Keep functions small and focused
-- Add `@doc` and `@spec` for public functions
-- Use pattern matching over conditionals where appropriate
-
-## Commit Messages
-
-We use [Conventional Commits](https://www.conventionalcommits.org/):
-
-```
-<type>[optional scope]: <description>
+1. Branch from `main`.
+2. Add tests for behavior changes.
+3. Keep docs and examples in sync.
+4. Use conventional commits.
 
-[optional body]
-
-[optional footer(s)]
-```
-
-### Types
-
-| Type | Description |
-|------|-------------|
-| `feat` | New feature |
-| `fix` | Bug fix |
-| `docs` | Documentation only |
-| `style` | Formatting, no code change |
-| `refactor` | Code change, no fix or feature |
-| `perf` | Performance improvement |
-| `test` | Adding/fixing tests |
-| `chore` | Maintenance, deps, tooling |
-| `ci` | CI/CD changes |
-
-### Examples
+Examples:
 
 ```bash
-git commit -m "feat(command): add mv command for moving files"
-git commit -m "fix(vfs): resolve path traversal in relative paths"
-git commit -m "docs: improve API documentation examples"
-git commit -m "feat!: breaking change to session API"
+git commit -m "feat(command): add xyz"
+git commit -m "fix(session): return typed errors for missing sessions"
+git commit -m "docs: update migration guide"
 ```
 
-## Pull Request Process
-
-1. Create a feature branch from `main`:
-   ```bash
-   git checkout -b feat/my-feature
-   ```
-
-2. Make your changes with appropriate tests
-
-3. Ensure all checks pass:
-   ```bash
-   mix quality
-   mix test
-   ```
-
-4. Push and create a Pull Request
-
-5. Respond to review feedback
-
-## Adding New Commands
-
-To add a new command:
+## Adding Commands
 
-1. Create a module implementing `Jido.Shell.Command` behaviour:
-
-```elixir
-defmodule Jido.Shell.Command.MyCommand do
-  @behaviour Jido.Shell.Command
-
-  @impl true
-  def name, do: "mycommand"
-
-  @impl true
-  def summary, do: "Brief description"
-
-  @impl true
-  def schema do
-    Zoi.map(%{
-      args: Zoi.array(Zoi.string()) |> Zoi.default([])
-    })
-  end
-
-  @impl true
-  def run(state, args, emit) do
-    # Implementation
-    emit.({:output, "Result\n"})
-    {:ok, nil}
-  end
-end
-```
-
-2. Register it in `Jido.Shell.Command.Registry`
-
-3. Add tests in `test/kodo/command/my_command_test.exs`
-
-4. Update the README command table
+1. Add a module under `lib/jido/shell/command/` implementing `Jido.Shell.Command`.
+2. Register it in `Jido.Shell.Command.Registry`.
+3. Add tests under `test/jido/shell/command/`.
+4. Update `README.md` command docs.
 
 ## Reporting Issues
 
-When reporting issues, please include:
+Please include:
 
-- Elixir and OTP versions (`elixir --version`)
+- Elixir/OTP versions
 - Jido.Shell version
-- Steps to reproduce
+- Reproduction steps
 - Expected vs actual behavior
-- Any error messages or stack traces
-
-## Questions?
-
-- Open a [GitHub Discussion](https://github.com/agentjido/kodo/discussions)
-- Join our [Discord](https://agentjido.xyz/discord)
+- Logs/stack traces
 
 ## License
 
-By contributing, you agree that your contributions will be licensed under the Apache-2.0 License.
+By contributing, you agree contributions are Apache-2.0 licensed.
diff --git a/MIGRATION.md b/MIGRATION.md
new file mode 100644
index 0000000..7e82ecb
--- /dev/null
+++ b/MIGRATION.md
@@ -0,0 +1,103 @@
+# Migration Guide
+
+This guide covers migration to the V1 hardening surface for `jido_shell`.
+
+## 1. Workspace IDs Are Strings
+
+`workspace_id` is now `String.t()` across public APIs.
+
+### Before
+
+```elixir
+{:ok, session_id} = Jido.Shell.Session.start(:my_workspace)
+```
+
+### After
+
+```elixir
+{:ok, session_id} = Jido.Shell.Session.start("my_workspace")
+```
+
+Invalid workspace identifiers now return structured errors:
+
+```elixir
+{:error, %Jido.Shell.Error{code: {:session, :invalid_workspace_id}}}
+```
+
+## 2. SessionServer APIs Return Explicit Result Tuples
+
+`Jido.Shell.SessionServer` APIs now return explicit success/error tuples and do not crash callers on missing sessions.
+
+### Updated return shapes
+
+- `subscribe/3` -> `{:ok, :subscribed} | {:error, Jido.Shell.Error.t()}`
+- `unsubscribe/2` -> `{:ok, :unsubscribed} | {:error, Jido.Shell.Error.t()}`
+- `get_state/1` -> `{:ok, Jido.Shell.Session.State.t()} | {:error, Jido.Shell.Error.t()}`
+- `run_command/3` -> `{:ok, :accepted} | {:error, Jido.Shell.Error.t()}`
+- `cancel/1` -> `{:ok, :cancelled} | {:error, Jido.Shell.Error.t()}`
+
+## 3. Agent APIs Preserve Tuple Semantics and Return Structured Errors
+
+`Jido.Shell.Agent` now returns typed errors for missing/invalid sessions instead of allowing process exits to leak.
+
+### Example
+
+```elixir
+{:error, %Jido.Shell.Error{code: {:session, :not_found}}} =
+  Jido.Shell.Agent.run("missing-session", "echo hi")
+```
+
+## 4. Interactive CLI Surface Is IEx-Only
+
+The V1 surface supports:
+
+- `mix jido_shell`
+- `Jido.Shell.Transport.IEx`
+
+The alternate rich UI mode is no longer part of the public release surface.
+
+## 5. Command Parsing and Chaining Semantics
+
+Top-level chaining is supported outside `bash`:
+
+- `;` always continues
+- `&&` short-circuits on error
+
+Examples:
+
+```text
+echo one; echo two
+mkdir /tmp && cd /tmp && pwd
+```
+
+Parser behavior is now quote/escape aware and returns structured syntax errors for malformed input.
+
+## 6. Command Validation and Execution Limits
+
+Numeric commands (`sleep`, `seq`) now return validation errors for invalid values instead of crashing.
+
+Optional execution limits can be passed through `execution_context`:
+
+```elixir
+execution_context: %{
+  limits: %{
+    max_runtime_ms: 5_000,
+    max_output_bytes: 50_000
+  }
+}
+```
+
+## 7. Network Policy Defaults
+
+Sandboxed network-style commands are denied by default.
+
+Allow access per command via `execution_context.network` allowlists (domains/ports).
+
+## 8. Session Event Tuple
+
+Session events are emitted as:
+
+```elixir
+{:jido_shell_session, session_id, event}
+```
+
diff --git a/README.md b/README.md
index 3548aa1..8a80580 100644
--- a/README.md
+++ b/README.md
@@ -1,40 +1,36 @@
 # Jido.Shell
 
-[![Hex.pm](https://img.shields.io/hexpm/v/kodo.svg)](https://hex.pm/packages/kodo)
-[![Docs](https://img.shields.io/badge/hex-docs-blue.svg)](https://hexdocs.pm/kodo)
-[![CI](https://github.com/agentjido/kodo/actions/workflows/ci.yml/badge.svg)](https://github.com/agentjido/kodo/actions/workflows/ci.yml)
+[![Hex.pm](https://img.shields.io/hexpm/v/jido_shell.svg)](https://hex.pm/packages/jido_shell)
+[![Docs](https://img.shields.io/badge/hex-docs-blue.svg)](https://hexdocs.pm/jido_shell)
+[![CI](https://github.com/agentjido/jido_shell/actions/workflows/ci.yml/badge.svg)](https://github.com/agentjido/jido_shell/actions/workflows/ci.yml)
 
 Virtual workspace shell for LLM-human collaboration in the AgentJido ecosystem.
 
-Jido.Shell provides an Elixir-native virtual shell with an in-memory filesystem, streaming output, and both interactive and programmatic interfaces. It's designed for AI agents that need to manipulate files and run commands in isolated, sandboxed environments.
+Jido.Shell provides an Elixir-native virtual shell with in-memory filesystems, streaming output, structured errors, and synchronous agent-friendly APIs.
 
 ## Features
 
-- **Virtual Filesystem** - In-memory VFS with [Jido.VFS](https://github.com/agentjido/hako) adapter support
-- **Familiar Shell Interface** - Unix-like commands (ls, cd, cat, echo, etc.)
-- **Streaming Output** - Real-time command output via pub/sub events
-- **Session Management** - Multiple isolated sessions per workspace
-- **Agent-Friendly API** - Simple synchronous interface for AI agents
-- **Interactive Transports** - IEx REPL and rich terminal UI
+- Virtual filesystem with [Jido.VFS](https://github.com/agentjido/hako) adapter support
+- Unix-like built-in commands (`ls`, `cd`, `cat`, `write`, `rm`, `cp`, `env`, `bash`)
+- Session-scoped state (`cwd`, env vars, history)
+- Streaming session events (`{:jido_shell_session, session_id, event}`)
+- Top-level command chaining: `;` (always continue), `&&` (short-circuit on error)
+- Per-command sandbox controls for network and execution limits
 
 ## Installation
 
-### Igniter Installation
-If your project has [Igniter](https://hexdocs.pm/igniter/readme.html) available, 
-you can install Jido Shell using the command 
+### Igniter
 
 ```bash
 mix igniter.install jido_shell
 ```
 
-### Manual Installation
-
-Add `jido_shell` to your dependencies in `mix.exs`:
+### Manual
 
 ```elixir
 def deps do
   [
-    {:jido_shell, "~> 1.0"}
+    {:jido_shell, "~> 3.0"}
   ]
 end
 ```
@@ -44,211 +40,144 @@ end
 ### Interactive Shell
 
 ```bash
-# Start IEx-style shell
 mix jido_shell
-
-# Start with rich terminal UI
-mix jido_shell --ui
+mix jido_shell --workspace my_workspace
 ```
 
-### Programmatic Usage (Agent API)
+### Agent API
 
 ```elixir
-# Create a new session with in-memory VFS
-{:ok, session} = Jido.Shell.Agent.new(:my_workspace)
-
-# Run commands synchronously
-{:ok, output} = Jido.Shell.Agent.run(session, "echo Hello World")
-# => {:ok, "Hello World\n"}
-
-{:ok, output} = Jido.Shell.Agent.run(session, "pwd")
-# => {:ok, "/\n"}
-
-# File operations
-:ok = Jido.Shell.Agent.write_file(session, "/hello.txt", "Hello from Jido.Shell!")
-{:ok, content} = Jido.Shell.Agent.read_file(session, "/hello.txt")
-# => {:ok, "Hello from Jido.Shell!"}
+{:ok, session} = Jido.Shell.Agent.new("my_workspace")
 
-# Directory operations
-{:ok, _} = Jido.Shell.Agent.run(session, "mkdir /projects")
-{:ok, _} = Jido.Shell.Agent.run(session, "cd /projects")
-{:ok, entries} = Jido.Shell.Agent.list_dir(session, "/")
+{:ok, "Hello\n"} = Jido.Shell.Agent.run(session, "echo Hello")
+{:ok, "/\n"} = Jido.Shell.Agent.run(session, "pwd")
 
-# Run multiple commands
-results = Jido.Shell.Agent.run_all(session, ["mkdir /docs", "cd /docs", "pwd"])
+:ok = Jido.Shell.Agent.write_file(session, "/hello.txt", "world")
+{:ok, "world"} = Jido.Shell.Agent.read_file(session, "/hello.txt")
 
-# Clean up
+{:ok, "/"} = Jido.Shell.Agent.cwd(session)
 :ok = Jido.Shell.Agent.stop(session)
 ```
 
 ### Low-Level Session API
 
-For more control over session events:
-
 ```elixir
-# Start a session with VFS
-{:ok, session_id} = Jido.Shell.Session.start_with_vfs(:my_workspace)
-
-# Subscribe to events
-:ok = Jido.Shell.SessionServer.subscribe(session_id, self())
+{:ok, session_id} = Jido.Shell.Session.start_with_vfs("my_workspace")
+{:ok, :subscribed} = Jido.Shell.SessionServer.subscribe(session_id, self())
 
-# Run commands (async, streams events)
-:ok = Jido.Shell.SessionServer.run_command(session_id, "ls -la")
+{:ok, :accepted} = Jido.Shell.SessionServer.run_command(session_id, "echo hi")
 
-# Receive events
 receive do
-  {:kodo_session, ^session_id, {:output, chunk}} -> IO.write(chunk)
-  {:kodo_session, ^session_id, :command_done} -> :done
+  {:jido_shell_session, ^session_id, {:output, chunk}} -> IO.write(chunk)
+  {:jido_shell_session, ^session_id, :command_done} -> :ok
 end
 
-# Cancel running command
-:ok = Jido.Shell.SessionServer.cancel(session_id)
-
-# Stop session
+{:ok, :cancelled} = Jido.Shell.SessionServer.cancel(session_id)
 :ok = Jido.Shell.Session.stop(session_id)
 ```
 
-## Available Commands
+## Command Chaining
 
-| Command                   | Description                           |
-|---------------------------|---------------------------------------|
-| `echo [args...]`          | Print arguments to output             |
-| `pwd`                     | Print working directory               |
-| `cd [path]`               | Change directory                      |
-| `ls [path]`               | List directory contents               |
-| `cat <file>`              | Display file contents                 |
-| `write <file> <content>`  | Write content to file                 |
-| `mkdir <dir>`             | Create directory                      |
-| `rm <file>`               | Remove file                           |
-| `cp <src> <dest>`         | Copy file                             |
-| `bash -c "<script>"`      | Run a bash-like script in sandbox     |
-| `env [VAR] [VAR=value]`   | Display or set environment variables  |
-| `help [command]`          | Show available commands               |
-| `sleep <seconds>`         | Sleep for duration                    |
-| `seq <count> [delay]`     | Print sequence of numbers             |
-
-### Bash Network Permissions
-
-Network-style commands inside `bash` scripts are denied by default.
-
-You can allow specific domains/ports per execution:
+Jido.Shell supports top-level chaining outside `bash`:
+
+- `;` always runs the next command.
+- `&&` runs the next command only if the previous command succeeded.
+
+Examples:
+
+```text
+echo one; echo two
+mkdir /tmp && cd /tmp && pwd
+```
+
+## Bash Sandbox
+
+`bash -c "..."` executes scripts through registered Jido.Shell commands (not the host shell).
+
+Network-style commands are denied by default. Allow per command with `execution_context.network`:
 
 ```elixir
 Jido.Shell.Agent.run(
-  session_id,
+  session,
   "bash -c \"curl https://example.com:8443\"",
   execution_context: %{
     network: %{
       allow_domains: ["example.com"],
-      allow_ports: [8443],
-      block_domains: [],
-      block_ports: []
+      allow_ports: [8443]
     }
   }
 )
 ```
 
-## Architecture
+Optional execution limits are supported through `execution_context.limits`:
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ Transports                                                      │
-│  • Jido.Shell.Transport.IEx (interactive shell in IEx)          │
-│  • Jido.Shell.Transport.TermUI (rich terminal UI)               │
-│  • Jido.Shell.Agent (programmatic API for agents)               │
-└──────────────────────────┬──────────────────────────────────────┘
-                           │ subscribe / run_command
-                           ▼
-┌─────────────────────────────────────────────────────────────────┐
-│ Jido.Shell.SessionServer (GenServer per session)                │
-│  • Holds session state (cwd, env, history)                      │
-│  • Manages transport subscriptions                              │
-│  • Spawns command tasks, broadcasts output                      │
-└──────────────────────────┬──────────────────────────────────────┘
-                           │ spawn Task under CommandTaskSupervisor
-                           ▼
-┌─────────────────────────────────────────────────────────────────┐
-│ Jido.Shell.CommandRunner (Task process)                         │
-│  • Executes command logic                                       │
-│  • Streams output back to session                               │
-└──────────────────────────┬──────────────────────────────────────┘
-                           │ calls
-                           ▼
-┌─────────────────────────────────────────────────────────────────┐
-│ Jido.Shell.Command modules (@behaviour Jido.Shell.Command)      │
-│  • name/0, summary/0, schema/0                                  │
-│  • run/3 (state, args, emit)                                    │
-└──────────────────────────┬──────────────────────────────────────┘
-                           │
-                           ▼
-┌─────────────────────────────────────────────────────────────────┐
-│ Jido.Shell.VFS                                                  │
-│  • Router + ETS mount table                                     │
-│  • File operations over Jido.VFS adapters                           │
-└─────────────────────────────────────────────────────────────────┘
+```elixir
+Jido.Shell.Agent.run(
+  session,
+  "seq 10000 0",
+  execution_context: %{
+    limits: %{
+      max_runtime_ms: 5_000,
+      max_output_bytes: 50_000
+    }
+  }
+)
 ```
 
-## Creating Custom Commands
-
-Implement the `Jido.Shell.Command` behaviour:
+## Available Commands
 
-```elixir
-defmodule MyApp.Command.Greet do
-  @behaviour Jido.Shell.Command
-
-  @impl true
-  def name, do: "greet"
-
-  @impl true
-  def summary, do: "Greet someone"
-
-  @impl true
-  def schema do
-    Zoi.map(%{
-      args: Zoi.array(Zoi.string()) |> Zoi.default([])
-    })
-  end
-
-  @impl true
-  def run(_state, args, emit) do
-    name = Enum.join(args.args, " ") || "World"
-    emit.({:output, "Hello, #{name}!\n"})
-    {:ok, nil}
-  end
-end
-```
+| Command | Description |
+|---|---|
+| `echo [args...]` | Print arguments |
+| `pwd` | Print working directory |
+| `cd [path]` | Change directory |
+| `ls [path]` | List directory contents |
+| `cat <file>` | Display file contents |
+| `write <file> <content>` | Write file |
+| `mkdir <dir>` | Create directory |
+| `rm <file...>` | Remove files |
+| `cp <src> <dest>` | Copy file |
+| `env [VAR] [VAR=value]` | Get/set environment variables |
+| `bash -c "<script>"` / `bash <file>` | Execute sandboxed script |
+| `sleep [seconds]` | Sleep (for cancellation testing) |
+| `seq [count] [delay_ms]` | Emit numeric sequence |
+| `help [command]` | Show help |
 
 ## Session Events
 
-When subscribed to a session, you receive these events:
+Events are published as:
+
+```elixir
+{:jido_shell_session, session_id, event}
+```
 
-| Event                             | Description                    |
-|-----------------------------------|--------------------------------|
-| `{:command_started, line}`        | Command execution began        |
-| `{:output, chunk}`                | Streaming output chunk         |
-| `{:error, Jido.Shell.Error.t()}`  | Error occurred                 |
-| `{:cwd_changed, path}`            | Working directory changed      |
-| `:command_done`                   | Command completed successfully |
-| `:command_cancelled`              | Command was cancelled          |
-| `{:command_crashed, reason}`      | Task terminated abnormally     |
+Event payloads:
 
-## Mounting Local Filesystems
+- `{:command_started, line}`
+- `{:output, chunk}`
+- `{:error, %Jido.Shell.Error{}}`
+- `{:cwd_changed, path}`
+- `:command_done`
+- `:command_cancelled`
+- `{:command_crashed, reason}`
 
-Jido.Shell can mount real directories using Jido.VFS adapters:
+## Local Filesystem Mounts
 
 ```elixir
-# Mount a local directory
-:ok = Jido.Shell.VFS.mount(:workspace, "/code", Jido.VFS.Adapter.Local, prefix: "/path/to/project")
+:ok = Jido.Shell.VFS.mount("workspace", "/code", Jido.VFS.Adapter.Local, prefix: "/path/to/project")
 
-# Start session - now /code maps to the real directory
-{:ok, session} = Jido.Shell.Agent.new(:workspace)
+{:ok, session} = Jido.Shell.Agent.new("workspace")
 {:ok, output} = Jido.Shell.Agent.run(session, "ls /code")
 ```
 
+## Breaking Changes in V1 Hardening
+
+Major V1 hardening changes are documented in [MIGRATION.md](MIGRATION.md).
+
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
-Apache-2.0 - see [LICENSE](LICENSE) for details.
+Apache-2.0. See [LICENSE](LICENSE).
diff --git a/lib/jido/shell.ex b/lib/jido/shell.ex
index 147819f..43a12e8 100644
--- a/lib/jido/shell.ex
+++ b/lib/jido/shell.ex
@@ -18,7 +18,7 @@ defmodule Jido.Shell do
   ## Quick Start
 
       # Start a session
-      {:ok, session_id} = Jido.Shell.Session.start(:my_workspace)
+      {:ok, session_id} = Jido.Shell.Session.start("my_workspace")
 
       # Run commands
       Jido.Shell.SessionServer.run_command(session_id, "pwd")
diff --git a/lib/jido/shell/agent.ex b/lib/jido/shell/agent.ex
index 76d36e9..ce3c95d 100644
--- a/lib/jido/shell/agent.ex
+++ b/lib/jido/shell/agent.ex
@@ -8,7 +8,7 @@ defmodule Jido.Shell.Agent do
   ## Usage
 
       # Start a session
-      {:ok, session} = Jido.Shell.Agent.new(:my_workspace)
+      {:ok, session} = Jido.Shell.Agent.new("my_workspace")
 
       # Run commands synchronously
       {:ok, output} = Jido.Shell.Agent.run(session, "ls")
@@ -27,6 +27,7 @@ defmodule Jido.Shell.Agent do
   alias Jido.Shell.SessionServer
 
   @type session :: String.t()
+  @type workspace_id :: String.t()
   @type result :: {:ok, String.t()} | {:error, Jido.Shell.Error.t()}
 
   @doc """
@@ -34,11 +35,17 @@ defmodule Jido.Shell.Agent do
 
   Returns the session ID which can be used for subsequent operations.
   """
-  @spec new(atom(), keyword()) :: {:ok, session()} | {:error, term()}
-  def new(workspace_id, opts \\ []) when is_atom(workspace_id) do
+  @spec new(workspace_id() | term(), keyword()) :: {:ok, session()} | {:error, term()}
+  def new(workspace_id, opts \\ [])
+
+  def new(workspace_id, opts) when is_binary(workspace_id) do
     Session.start_with_vfs(workspace_id, opts)
   end
 
+  def new(workspace_id, _opts) do
+    {:error, Jido.Shell.Error.session(:invalid_workspace_id, %{workspace_id: workspace_id})}
+  end
+
   @doc """
   Runs a command and waits for completion.
 
@@ -54,13 +61,22 @@ defmodule Jido.Shell.Agent do
     timeout = Keyword.get(opts, :timeout, 30_000)
     command_opts = Keyword.drop(opts, [:timeout])
 
-    :ok = SessionServer.subscribe(session_id, self())
-    :ok = SessionServer.run_command(session_id, command, command_opts)
+    case SessionServer.subscribe(session_id, self()) do
+      {:ok, :subscribed} ->
+        drain_session_events(session_id)
+
+        result =
+          case SessionServer.run_command(session_id, command, command_opts) do
+            {:ok, :accepted} -> collect_output(session_id, [], timeout, false)
+            {:error, _} = error -> error
+          end
 
-    result = collect_output(session_id, [], timeout)
-    :ok = SessionServer.unsubscribe(session_id, self())
+        _ = SessionServer.unsubscribe(session_id, self())
+        result
 
-    result
+      {:error, _} = error ->
+        error
+    end
   end
 
   @doc """
@@ -78,9 +94,10 @@ defmodule Jido.Shell.Agent do
   """
   @spec read_file(session(), String.t()) :: {:ok, binary()} | {:error, Jido.Shell.Error.t()}
   def read_file(session_id, path) do
-    {:ok, state} = SessionServer.get_state(session_id)
-    full_path = resolve_path(state.cwd, path)
-    Jido.Shell.VFS.read_file(state.workspace_id, full_path)
+    with {:ok, state} <- SessionServer.get_state(session_id) do
+      full_path = resolve_path(state.cwd, path)
+      Jido.Shell.VFS.read_file(state.workspace_id, full_path)
+    end
   end
 
   @doc """
@@ -88,9 +105,10 @@ defmodule Jido.Shell.Agent do
   """
   @spec write_file(session(), String.t(), binary()) :: :ok | {:error, Jido.Shell.Error.t()}
   def write_file(session_id, path, content) do
-    {:ok, state} = SessionServer.get_state(session_id)
-    full_path = resolve_path(state.cwd, path)
-    Jido.Shell.VFS.write_file(state.workspace_id, full_path, content)
+    with {:ok, state} <- SessionServer.get_state(session_id) do
+      full_path = resolve_path(state.cwd, path)
+      Jido.Shell.VFS.write_file(state.workspace_id, full_path, content)
+    end
   end
 
   @doc """
@@ -98,9 +116,10 @@ defmodule Jido.Shell.Agent do
   """
   @spec list_dir(session(), String.t()) :: {:ok, [map()]} | {:error, Jido.Shell.Error.t()}
   def list_dir(session_id, path \\ ".") do
-    {:ok, state} = SessionServer.get_state(session_id)
-    full_path = resolve_path(state.cwd, path)
-    Jido.Shell.VFS.list_dir(state.workspace_id, full_path)
+    with {:ok, state} <- SessionServer.get_state(session_id) do
+      full_path = resolve_path(state.cwd, path)
+      Jido.Shell.VFS.list_dir(state.workspace_id, full_path)
+    end
   end
 
   @doc """
@@ -114,10 +133,11 @@ defmodule Jido.Shell.Agent do
   @doc """
   Gets the current working directory.
   """
-  @spec cwd(session()) :: String.t()
+  @spec cwd(session()) :: {:ok, String.t()} | {:error, Jido.Shell.Error.t()}
   def cwd(session_id) do
-    {:ok, state} = state(session_id)
-    state.cwd
+    with {:ok, state} <- state(session_id) do
+      {:ok, state.cwd}
+    end
   end
 
   @doc """
@@ -130,16 +150,19 @@ defmodule Jido.Shell.Agent do
 
   # === Private ===
 
-  defp collect_output(session_id, acc, timeout) do
+  defp collect_output(session_id, acc, timeout, started?) do
     receive do
       {:jido_shell_session, ^session_id, {:command_started, _}} ->
-        collect_output(session_id, acc, timeout)
+        collect_output(session_id, acc, timeout, true)
+
+      {:jido_shell_session, ^session_id, _event} when not started? ->
+        collect_output(session_id, acc, timeout, started?)
 
       {:jido_shell_session, ^session_id, {:output, chunk}} ->
-        collect_output(session_id, [chunk | acc], timeout)
+        collect_output(session_id, [chunk | acc], timeout, started?)
 
       {:jido_shell_session, ^session_id, {:cwd_changed, _}} ->
-        collect_output(session_id, acc, timeout)
+        collect_output(session_id, acc, timeout, started?)
 
       {:jido_shell_session, ^session_id, :command_done} ->
         output = acc |> Enum.reverse() |> Enum.join()
@@ -159,6 +182,16 @@ defmodule Jido.Shell.Agent do
     end
   end
 
+  defp drain_session_events(session_id) do
+    receive do
+      {:jido_shell_session, ^session_id, _event} ->
+        drain_session_events(session_id)
+    after
+      0 ->
+        :ok
+    end
+  end
+
   defp resolve_path(_cwd, "/" <> _ = path), do: path
   defp resolve_path(cwd, path), do: Path.join(cwd, path) |> Path.expand()
 end
diff --git a/lib/jido/shell/application.ex b/lib/jido/shell/application.ex
index 57c51c2..60a0862 100644
--- a/lib/jido/shell/application.ex
+++ b/lib/jido/shell/application.ex
@@ -4,9 +4,8 @@ defmodule Jido.Shell.Application do
 
   @impl true
   def start(_type, _args) do
-    Jido.Shell.VFS.init()
-
     children = [
+      {Jido.Shell.VFS.MountTable, []},
       {Registry, keys: :unique, name: Jido.Shell.SessionRegistry},
       {DynamicSupervisor, strategy: :one_for_one, name: Jido.Shell.SessionSupervisor},
       {DynamicSupervisor, strategy: :one_for_one, name: Jido.Shell.FilesystemSupervisor},
diff --git a/lib/jido/shell/command/parser.ex b/lib/jido/shell/command/parser.ex
index b0f7c33..010c617 100644
--- a/lib/jido/shell/command/parser.ex
+++ b/lib/jido/shell/command/parser.ex
@@ -1,9 +1,6 @@
 defmodule Jido.Shell.Command.Parser do
   @moduledoc """
-  Simple command line parser.
-
-  Tokenizes input into command name and arguments.
-  Supports quoted strings for arguments with spaces.
+  Shell command parser with quoting, escaping, and chaining support.
 
   ## Examples
 
@@ -14,6 +11,12 @@ defmodule Jido.Shell.Command.Parser do
       {:ok, "echo", ["hello world"]}
   """
 
+  @typedoc "Execution gate for a parsed command"
+  @type operator :: :always | :and_if
+
+  @typedoc "Parsed command entry"
+  @type command_entry :: %{operator: operator(), command: String.t(), args: [String.t()]}
+
   @doc """
   Parses a command line into command name and arguments.
 
@@ -21,64 +24,169 @@ defmodule Jido.Shell.Command.Parser do
   """
   @spec parse(String.t()) :: {:ok, String.t(), [String.t()]} | {:error, term()}
   def parse(line) when is_binary(line) do
-    line = String.trim(line)
+    case parse_program(line) do
+      {:ok, [%{command: command, args: args}]} ->
+        {:ok, command, args}
+
+      {:ok, [_ | _]} ->
+        {:error, :chained_command}
+
+      {:error, _} = error ->
+        error
+    end
+  end
+
+  @doc """
+  Parses a command line into one or more chained commands.
 
-    if line == "" do
+  Supported chaining operators:
+  - `;` - Always run next command
+  - `&&` - Run next command only if previous command succeeds
+  """
+  @spec parse_program(String.t()) :: {:ok, [command_entry()]} | {:error, term()}
+  def parse_program(line) when is_binary(line) do
+    trimmed = String.trim(line)
+
+    if trimmed == "" do
       {:error, :empty_command}
     else
-      case tokenize(line) do
-        {:ok, [cmd | args]} -> {:ok, cmd, args}
-        {:ok, []} -> {:error, :empty_command}
-        {:error, _} = error -> error
+      with {:ok, tokens} <- tokenize(trimmed),
+           {:ok, commands} <- build_program(tokens) do
+        {:ok, commands}
       end
     end
   end
 
   defp tokenize(line) do
-    tokenize(line, [], nil)
+    tokenize(line, %{tokens: [], current: [], quote: nil, escaped: false})
   end
 
-  defp tokenize("", tokens, nil) do
-    {:ok, tokens}
+  defp tokenize("", %{quote: quote}) when not is_nil(quote) do
+    {:error, :unclosed_quote}
   end
 
-  defp tokenize("", tokens, current) do
-    {:ok, tokens ++ [current]}
+  defp tokenize("", %{escaped: true}) do
+    {:error, :dangling_escape}
   end
 
-  defp tokenize(<<?">> <> rest, tokens, current) do
-    case consume_quoted(rest, "") do
-      {:ok, quoted, remaining} ->
-        current = (current || "") <> quoted
-        tokenize(remaining, tokens, current)
+  defp tokenize("", state) do
+    state = flush_current(state)
+    {:ok, Enum.reverse(state.tokens)}
+  end
 
-      {:error, _} = error ->
-        error
-    end
+  defp tokenize(<<char::utf8, rest::binary>>, %{escaped: true} = state) do
+    state
+    |> push_char(char)
+    |> Map.put(:escaped, false)
+    |> then(&tokenize(rest, &1))
   end
 
-  defp tokenize(<<?\s>> <> rest, tokens, nil) do
-    tokenize(String.trim_leading(rest), tokens, nil)
+  defp tokenize(<<?\\, rest::binary>>, state) do
+    tokenize(rest, %{state | escaped: true})
   end
 
-  defp tokenize(<<?\s>> <> rest, tokens, current) do
-    tokenize(String.trim_leading(rest), tokens ++ [current], nil)
+  defp tokenize(<<quote::utf8, rest::binary>>, %{quote: nil} = state) when quote in [?', ?"] do
+    tokenize(rest, %{state | quote: quote})
   end
 
-  defp tokenize(<<c::utf8>> <> rest, tokens, current) do
-    current = (current || "") <> <<c::utf8>>
-    tokenize(rest, tokens, current)
+  defp tokenize(<<quote::utf8, rest::binary>>, %{quote: quote} = state) when quote in [?', ?"] do
+    state =
+      if state.current == [] do
+        %{state | quote: nil, current: ["" | state.current]}
+      else
+        %{state | quote: nil}
+      end
+
+    tokenize(rest, state)
   end
 
-  defp consume_quoted("", _acc) do
-    {:error, :unclosed_quote}
+  defp tokenize(<<char::utf8, rest::binary>>, %{quote: nil} = state) when char in [?\s, ?\t] do
+    state
+    |> flush_current()
+    |> then(&tokenize(rest, &1))
   end
 
-  defp consume_quoted(<<?">> <> rest, acc) do
-    {:ok, acc, rest}
+  defp tokenize(<<?;, rest::binary>>, %{quote: nil} = state) do
+    state
+    |> flush_current()
+    |> push_token(:semicolon)
+    |> then(&tokenize(rest, &1))
   end
 
-  defp consume_quoted(<<c::utf8>> <> rest, acc) do
-    consume_quoted(rest, acc <> <<c::utf8>>)
+  defp tokenize(<<?&, ?&, rest::binary>>, %{quote: nil} = state) do
+    state
+    |> flush_current()
+    |> push_token(:and_and)
+    |> then(&tokenize(rest, &1))
+  end
+
+  defp tokenize(<<char::utf8, rest::binary>>, state) do
+    state
+    |> push_char(char)
+    |> then(&tokenize(rest, &1))
+  end
+
+  defp build_program(tokens) do
+    build_program(tokens, [], [], :always)
+  end
+
+  defp build_program([], [], [], _next_operator), do: {:error, :empty_command}
+  defp build_program([], [], _commands, _next_operator), do: {:error, :trailing_operator}
+
+  defp build_program([], current_words, commands, next_operator) do
+    {:ok, Enum.reverse([to_command(current_words, next_operator) | commands])}
+  end
+
+  defp build_program([token | rest], current_words, commands, next_operator) do
+    case token do
+      {:word, word} ->
+        build_program(rest, [word | current_words], commands, next_operator)
+
+      :semicolon ->
+        case current_words do
+          [] ->
+            {:error, :invalid_operator_position}
+
+          _ ->
+            command = to_command(current_words, next_operator)
+            build_program(rest, [], [command | commands], :always)
+        end
+
+      :and_and ->
+        case current_words do
+          [] ->
+            {:error, :invalid_operator_position}
+
+          _ ->
+            command = to_command(current_words, next_operator)
+            build_program(rest, [], [command | commands], :and_if)
+        end
+    end
+  end
+
+  defp to_command(words_reversed, operator) do
+    [command | args] = Enum.reverse(words_reversed)
+    %{operator: operator, command: command, args: args}
+  end
+
+  defp push_char(state, char) do
+    %{state | current: [<<char::utf8>> | state.current]}
+  end
+
+  defp push_token(state, token) do
+    %{state | tokens: [token | state.tokens]}
+  end
+
+  defp flush_current(%{current: []} = state), do: state
+
+  defp flush_current(state) do
+    word =
+      state.current
+      |> Enum.reverse()
+      |> IO.iodata_to_binary()
+
+    state
+    |> Map.put(:current, [])
+    |> push_token({:word, word})
   end
 end
diff --git a/lib/jido/shell/command/seq.ex b/lib/jido/shell/command/seq.ex
index bc67679..afa4249 100644
--- a/lib/jido/shell/command/seq.ex
+++ b/lib/jido/shell/command/seq.ex
@@ -8,6 +8,7 @@ defmodule Jido.Shell.Command.Seq do
   """
 
   @behaviour Jido.Shell.Command
+  alias Jido.Shell.Error
 
   @impl true
   def name, do: "seq"
@@ -18,24 +19,50 @@ defmodule Jido.Shell.Command.Seq do
   @impl true
   def schema do
     Zoi.map(%{
-      args: Zoi.array(Zoi.string()) |> Zoi.default([])
+      args: Zoi.array(Zoi.string()) |> Zoi.max(2) |> Zoi.default([])
     })
   end
 
   @impl true
   def run(_state, args, emit) do
-    {count, delay} =
-      case args.args do
-        [] -> {10, 100}
-        [c] -> {String.to_integer(c), 100}
-        [c, d | _] -> {String.to_integer(c), String.to_integer(d)}
-      end
-
-    Enum.each(1..count, fn i ->
-      emit.({:output, "#{i}\n"})
-      if delay > 0, do: Process.sleep(delay)
-    end)
-
-    {:ok, count}
+    case parse_count_and_delay(args.args) do
+      {:ok, {count, delay}} ->
+        if count > 0 do
+          Enum.each(1..count, fn i ->
+            emit.({:output, "#{i}\n"})
+            if delay > 0, do: Process.sleep(delay)
+          end)
+        end
+
+        {:ok, count}
+
+      {:error, message} ->
+        {:error, Error.validation("seq", [%{message: message}])}
+    end
+  end
+
+  defp parse_count_and_delay([]), do: {:ok, {10, 100}}
+
+  defp parse_count_and_delay([count_arg]) do
+    with {:ok, count} <- parse_non_negative_integer(count_arg, 100_000, "count") do
+      {:ok, {count, 100}}
+    end
+  end
+
+  defp parse_count_and_delay([count_arg, delay_arg]) do
+    with {:ok, count} <- parse_non_negative_integer(count_arg, 100_000, "count"),
+         {:ok, delay} <- parse_non_negative_integer(delay_arg, 60_000, "delay_ms") do
+      {:ok, {count, delay}}
+    end
+  end
+
+  defp parse_non_negative_integer(raw, max_value, name) do
+    case Integer.parse(raw) do
+      {parsed, ""} when parsed >= 0 and parsed <= max_value ->
+        {:ok, parsed}
+
+      _ ->
+        {:error, "seq #{name} must be an integer between 0 and #{max_value}"}
+    end
   end
 end
diff --git a/lib/jido/shell/command/sleep.ex b/lib/jido/shell/command/sleep.ex
index 490b638..c1dc334 100644
--- a/lib/jido/shell/command/sleep.ex
+++ b/lib/jido/shell/command/sleep.ex
@@ -8,6 +8,7 @@ defmodule Jido.Shell.Command.Sleep do
   """
 
   @behaviour Jido.Shell.Command
+  alias Jido.Shell.Error
 
   @impl true
   def name, do: "sleep"
@@ -18,26 +19,40 @@ defmodule Jido.Shell.Command.Sleep do
   @impl true
   def schema do
     Zoi.map(%{
-      args: Zoi.array(Zoi.string()) |> Zoi.default([])
+      args: Zoi.array(Zoi.string()) |> Zoi.max(1) |> Zoi.default([])
     })
   end
 
   @impl true
   def run(_state, args, emit) do
-    seconds =
-      case args.args do
-        [] -> 1
-        [s | _] -> String.to_integer(s)
-      end
+    case parse_seconds(args.args) do
+      {:ok, seconds} ->
+        emit.({:output, "Sleeping for #{seconds} seconds...\n"})
+
+        if seconds > 0 do
+          Enum.each(1..seconds, fn i ->
+            Process.sleep(1000)
+            emit.({:output, "#{i}...\n"})
+          end)
+        end
+
+        emit.({:output, "Done!\n"})
+        {:ok, nil}
+
+      {:error, message} ->
+        {:error, Error.validation("sleep", [%{message: message}])}
+    end
+  end
 
-    emit.({:output, "Sleeping for #{seconds} seconds...\n"})
+  defp parse_seconds([]), do: {:ok, 1}
 
-    Enum.each(1..seconds, fn i ->
-      Process.sleep(1000)
-      emit.({:output, "#{i}...\n"})
-    end)
+  defp parse_seconds([seconds_arg]) do
+    case Integer.parse(seconds_arg) do
+      {seconds, ""} when seconds >= 0 and seconds <= 3_600 ->
+        {:ok, seconds}
 
-    emit.({:output, "Done!\n"})
-    {:ok, nil}
+      _ ->
+        {:error, "sleep seconds must be an integer between 0 and 3600"}
+    end
   end
 end
diff --git a/lib/jido/shell/command_runner.ex b/lib/jido/shell/command_runner.ex
index 5a62a12..a985786 100644
--- a/lib/jido/shell/command_runner.ex
+++ b/lib/jido/shell/command_runner.ex
@@ -3,10 +3,13 @@ defmodule Jido.Shell.CommandRunner do
   Executes commands in Task processes and streams output back.
   """
 
+  alias Jido.Shell.Error
   alias Jido.Shell.Command.Parser
   alias Jido.Shell.Command.Registry
   alias Jido.Shell.Session.State
 
+  @output_bytes_key :jido_shell_command_output_bytes
+
   @doc """
   Runs a command line in the context of a session.
 
@@ -16,9 +19,10 @@ defmodule Jido.Shell.CommandRunner do
   @spec run(pid(), State.t(), String.t(), keyword()) :: term()
   def run(session_pid, state, line, opts \\ []) do
     state = with_execution_context(state, opts)
-    emit = fn event -> send(session_pid, {:command_event, event}) end
+    limits = execution_limits(state)
+    emit = limited_emit(session_pid, limits.max_output_bytes)
 
-    result = execute(state, line, emit)
+    result = execute_with_limits(state, line, emit, limits)
     send(session_pid, {:command_finished, result})
     result
   end
@@ -28,13 +32,72 @@ defmodule Jido.Shell.CommandRunner do
   """
   @spec execute(State.t(), String.t(), Jido.Shell.Command.emit()) :: Jido.Shell.Command.run_result()
   def execute(state, line, emit) do
-    with {:ok, cmd_name, args} <- Parser.parse(line),
-         {:ok, module} <- lookup_command(cmd_name),
+    with {:ok, program} <- parse_program(line) do
+      execute_program(state, program, emit)
+    end
+  end
+
+  defp parse_program(line) do
+    case Parser.parse_program(line) do
+      {:ok, _} = ok ->
+        ok
+
+      {:error, :empty_command} ->
+        {:error, Error.shell(:empty_command, %{line: line})}
+
+      {:error, reason} ->
+        {:error, Error.shell(:syntax_error, %{line: line, reason: reason})}
+    end
+  end
+
+  defp execute_program(initial_state, program, emit) do
+    final =
+      Enum.reduce(program, %{state: initial_state, last_result: {:ok, nil}, state_updates: %{}}, fn entry, acc ->
+        if entry.operator == :and_if and not ok_result?(acc.last_result) do
+          acc
+        else
+          run_program_entry(acc, entry, emit)
+        end
+      end)
+
+    finalize_program_result(final)
+  end
+
+  defp finalize_program_result(%{last_result: {:error, _} = error}), do: error
+
+  defp finalize_program_result(%{last_result: {:ok, result}, state_updates: state_updates}) do
+    if map_size(state_updates) == 0 do
+      {:ok, result}
+    else
+      {:ok, {:state_update, state_updates}}
+    end
+  end
+
+  defp execute_command(state, cmd_name, args, emit) do
+    with {:ok, module} <- lookup_command(cmd_name),
          {:ok, validated_args} <- validate_args(module, cmd_name, args) do
       module.run(state, validated_args, emit)
     end
   end
 
+  defp run_program_entry(acc, %{command: cmd_name, args: args}, emit) do
+    case execute_command(acc.state, cmd_name, args, emit) do
+      {:ok, {:state_update, changes}} ->
+        %{
+          acc
+          | state: apply_state_updates(acc.state, changes),
+            last_result: {:ok, nil},
+            state_updates: Map.merge(acc.state_updates, changes)
+        }
+
+      {:ok, _} = ok ->
+        %{acc | last_result: ok}
+
+      {:error, _} = error ->
+        %{acc | last_result: error}
+    end
+  end
+
   defp lookup_command(name) do
     case Registry.lookup(name) do
       {:ok, _} = result -> result
@@ -56,6 +119,16 @@ defmodule Jido.Shell.CommandRunner do
     %{args: args}
   end
 
+  defp apply_state_updates(state, changes) do
+    Enum.reduce(changes, state, fn {key, value}, acc ->
+      case key do
+        :cwd -> State.set_cwd(acc, value)
+        :env -> %{acc | env: value}
+        _ -> acc
+      end
+    end)
+  end
+
   defp with_execution_context(%State{} = state, opts) do
     base_context =
       state.meta
@@ -96,4 +169,107 @@ defmodule Jido.Shell.CommandRunner do
   end
 
   defp deep_merge(_left, right), do: right
+
+  defp execute_with_limits(state, line, emit, %{max_runtime_ms: nil}) do
+    execute_with_output_guard(state, line, emit)
+  end
+
+  defp execute_with_limits(state, line, emit, %{max_runtime_ms: max_runtime_ms}) do
+    task = Task.async(fn -> execute_with_output_guard(state, line, emit) end)
+
+    case Task.yield(task, max_runtime_ms) || Task.shutdown(task, :brutal_kill) do
+      {:ok, result} ->
+        result
+
+      nil ->
+        {:error, Error.command(:runtime_limit_exceeded, %{line: line, max_runtime_ms: max_runtime_ms})}
+    end
+  end
+
+  defp execute_with_output_guard(state, line, emit) do
+    Process.put(@output_bytes_key, 0)
+
+    try do
+      execute(state, line, emit)
+    catch
+      :throw, {:output_limit_exceeded, %Error{} = error} ->
+        {:error, error}
+    after
+      Process.delete(@output_bytes_key)
+    end
+  end
+
+  defp limited_emit(session_pid, max_output_bytes) do
+    fn event ->
+      case enforce_output_limit(event, max_output_bytes) do
+        :ok ->
+          send(session_pid, {:command_event, event})
+          :ok
+
+        {:error, %Error{} = error} ->
+          throw({:output_limit_exceeded, error})
+      end
+    end
+  end
+
+  defp enforce_output_limit(_event, nil), do: :ok
+
+  defp enforce_output_limit({:output, chunk}, max_output_bytes)
+       when is_integer(max_output_bytes) and max_output_bytes > 0 do
+    emitted_bytes = Process.get(@output_bytes_key, 0)
+    chunk_bytes = chunk |> IO.iodata_to_binary() |> byte_size()
+    updated_total = emitted_bytes + chunk_bytes
+
+    if updated_total > max_output_bytes do
+      {:error,
+       Error.command(:output_limit_exceeded, %{
+         emitted_bytes: updated_total,
+         max_output_bytes: max_output_bytes
+       })}
+    else
+      Process.put(@output_bytes_key, updated_total)
+      :ok
+    end
+  end
+
+  defp enforce_output_limit(_event, _max_output_bytes), do: :ok
+
+  defp execution_limits(%State{} = state) do
+    execution_context = Map.get(state.meta, :execution_context, %{})
+    limits = get_opt(execution_context, :limits, %{})
+
+    %{
+      max_runtime_ms: parse_limit(get_opt(limits, :max_runtime_ms, get_opt(execution_context, :max_runtime_ms, nil))),
+      max_output_bytes:
+        parse_limit(get_opt(limits, :max_output_bytes, get_opt(execution_context, :max_output_bytes, nil)))
+    }
+  end
+
+  defp parse_limit(value) when is_integer(value) and value > 0, do: value
+
+  defp parse_limit(value) when is_binary(value) do
+    case Integer.parse(value) do
+      {parsed, ""} when parsed > 0 -> parsed
+      _ -> nil
+    end
+  end
+
+  defp parse_limit(_), do: nil
+
+  defp ok_result?({:ok, _}), do: true
+  defp ok_result?(_), do: false
+
+  defp get_opt(data, key, default) when is_map(data) do
+    Map.get(data, key, Map.get(data, Atom.to_string(key), default))
+  end
+
+  defp get_opt(data, key, default) when is_list(data) do
+    if Keyword.keyword?(data) do
+      Keyword.get(data, key, default)
+    else
+      default
+    end
+  end
+
+  defp get_opt(_, _, default), do: default
 end
diff --git a/lib/jido/shell/sandbox/bash.ex b/lib/jido/shell/sandbox/bash.ex
index c99e792..68e9cdf 100644
--- a/lib/jido/shell/sandbox/bash.ex
+++ b/lib/jido/shell/sandbox/bash.ex
@@ -16,8 +16,8 @@ defmodule Jido.Shell.Sandbox.Bash do
   @doc """
   Executes a script in the current session context.
 
-  Script lines are split on newlines and `;`, with blank lines and full-line
-  comments (`# ...`) ignored.
+  Script lines are split on newlines, with blank lines and full-line comments
+  (`# ...`) ignored.
   """
   @spec execute(State.t(), String.t(), Jido.Shell.Command.emit()) :: execute_result()
   def execute(%State{} = state, script, emit) when is_binary(script) do
@@ -33,7 +33,6 @@ defmodule Jido.Shell.Sandbox.Bash do
   def statements(script) when is_binary(script) do
     script
     |> String.split(~r/\r?\n/)
-    |> Enum.flat_map(&String.split(&1, ";"))
     |> Enum.map(&String.trim/1)
     |> Enum.reject(&skip_statement?/1)
   end
diff --git a/lib/jido/shell/sandbox/network_policy.ex b/lib/jido/shell/sandbox/network_policy.ex
index e07a0af..795b89a 100644
--- a/lib/jido/shell/sandbox/network_policy.ex
+++ b/lib/jido/shell/sandbox/network_policy.ex
@@ -10,12 +10,17 @@ defmodule Jido.Shell.Sandbox.NetworkPolicy do
   - `:block_ports` (list of ports)
   """
 
+  alias Jido.Shell.Command.Parser
   alias Jido.Shell.Error
 
   @network_commands ~w(curl wget nc ncat telnet ssh scp sftp ftp ping dig nslookup)
   @url_regex ~r/https?:\/\/([A-Za-z0-9\.\-]+)(?::(\d{1,5}))?/
   @host_port_regex ~r/\b([A-Za-z0-9\.\-]+):(\d{1,5})\b/
+  @bracketed_host_port_regex ~r/\[([A-Fa-f0-9:]+)\]:(\d{1,5})/
   @port_flag_regex ~r/^--port=(\d{1,5})$/
+  @port_short_flag_regex ~r/^-p(\d{1,5})$/
+  @domain_like_regex ~r/^(?:[A-Za-z0-9-]+\.)+[A-Za-z]{2,}$/
+  @ipv4_regex ~r/^\d{1,3}(?:\.\d{1,3}){3}$/
 
   @type policy_context :: map() | keyword()
 
@@ -24,19 +29,29 @@ defmodule Jido.Shell.Sandbox.NetworkPolicy do
   """
   @spec enforce(String.t(), policy_context()) :: :ok | {:error, Error.t()}
   def enforce(line, execution_context) when is_binary(line) do
-    case Jido.Shell.Command.Parser.parse(line) do
-      {:ok, command, args} ->
-        if network_command?(command) do
-          check_network_command(line, command, args, normalize_policy(execution_context))
-        else
-          :ok
-        end
+    case Parser.parse_program(line) do
+      {:ok, commands} ->
+        policy = normalize_policy(execution_context)
+        enforce_commands(line, commands, policy)
 
       _ ->
         :ok
     end
   end
 
+  defp enforce_commands(_line, [], _policy), do: :ok
+
+  defp enforce_commands(line, [%{command: command, args: args} | rest], policy) do
+    if network_command?(command) do
+      case check_network_command(line, command, args, policy) do
+        :ok -> enforce_commands(line, rest, policy)
+        {:error, _} = error -> error
+      end
+    else
+      enforce_commands(line, rest, policy)
+    end
+  end
+
   defp check_network_command(line, command, args, policy) do
     endpoints = extract_endpoints(args)
 
@@ -202,11 +217,17 @@ defmodule Jido.Shell.Sandbox.NetworkPolicy do
   defp to_port(_), do: nil
 
   defp extract_endpoints(args) do
-    Enum.reduce(args, %{domains: [], ports: []}, fn arg, acc ->
+    args
+    |> Enum.with_index()
+    |> Enum.reduce(%{domains: [], ports: []}, fn {arg, idx}, acc ->
+      next_arg = Enum.at(args, idx + 1)
+
       acc
       |> extract_from_url(arg)
       |> extract_from_host_port(arg)
-      |> extract_from_port_flags(arg)
+      |> extract_from_bracketed_host_port(arg)
+      |> extract_from_port_flags(arg, next_arg)
+      |> extract_from_bare_host(arg)
     end)
     |> Map.update!(:domains, &Enum.uniq/1)
     |> Map.update!(:ports, &Enum.uniq/1)
@@ -229,11 +250,28 @@ defmodule Jido.Shell.Sandbox.NetworkPolicy do
   end
 
   defp extract_from_host_port(acc, arg) do
-    Regex.scan(@host_port_regex, arg)
+    if String.contains?(arg, "[") do
+      acc
+    else
+      Regex.scan(@host_port_regex, arg)
+      |> Enum.reduce(acc, fn
+        [_, domain, port], current ->
+          current
+          |> add_domain(domain)
+          |> maybe_add_port(port)
+
+        _other, current ->
+          current
+      end)
+    end
+  end
+
+  defp extract_from_bracketed_host_port(acc, arg) do
+    Regex.scan(@bracketed_host_port_regex, arg)
     |> Enum.reduce(acc, fn
-      [_, domain, port], current ->
+      [_, host, port], current ->
         current
-        |> add_domain(domain)
+        |> add_domain(host)
         |> maybe_add_port(port)
 
       _other, current ->
@@ -241,17 +279,64 @@ defmodule Jido.Shell.Sandbox.NetworkPolicy do
     end)
   end
 
-  defp extract_from_port_flags(acc, arg) do
+  defp extract_from_port_flags(acc, arg, next_arg) do
     cond do
       Regex.match?(@port_flag_regex, arg) ->
         [_, port] = Regex.run(@port_flag_regex, arg)
         maybe_add_port(acc, port)
 
+      Regex.match?(@port_short_flag_regex, arg) ->
+        [_, port] = Regex.run(@port_short_flag_regex, arg)
+        maybe_add_port(acc, port)
+
+      arg == "-p" ->
+        maybe_add_port(acc, next_arg)
+
       true ->
         acc
     end
   end
 
+  defp extract_from_bare_host(acc, arg) do
+    normalized =
+      arg
+      |> to_string()
+      |> String.trim()
+      |> String.trim_trailing(",")
+      |> String.trim_trailing(";")
+
+    cond do
+      normalized == "" or String.starts_with?(normalized, "-") ->
+        acc
+
+      String.contains?(normalized, "://") ->
+        acc
+
+      String.starts_with?(normalized, "[") ->
+        acc
+
+      true ->
+        host_part = normalized |> String.split("/", parts: 2) |> hd()
+
+        case String.split(host_part, ":", parts: 2) do
+          [host, port] when host != "" ->
+            acc
+            |> add_domain(host)
+            |> maybe_add_port(port)
+
+          [host] ->
+            if Regex.match?(@domain_like_regex, host) or Regex.match?(@ipv4_regex, host) do
+              add_domain(acc, host)
+            else
+              acc
+            end
+
+          _ ->
+            acc
+        end
+    end
+  end
+
   defp add_domain(acc, domain) do
     normalized = String.trim(String.downcase(domain))
 
diff --git a/lib/jido/shell/session.ex b/lib/jido/shell/session.ex
index bfe8b9f..356451a 100644
--- a/lib/jido/shell/session.ex
+++ b/lib/jido/shell/session.ex
@@ -5,6 +5,11 @@ defmodule Jido.Shell.Session do
   Sessions are GenServer processes that maintain shell state including
   current working directory, environment variables, and command history.
   """
+  alias Jido.Shell.Error
+  alias Jido.Shell.Session.State
+  alias Jido.Shell.SessionServer
+
+  @type workspace_id :: String.t()
 
   @doc """
   Starts a new session for the given workspace.
@@ -20,34 +25,48 @@ defmodule Jido.Shell.Session do
 
   ## Examples
 
-      iex> {:ok, session_id} = Jido.Shell.Session.start(:my_workspace)
+      iex> {:ok, session_id} = Jido.Shell.Session.start("my_workspace")
       iex> String.starts_with?(session_id, "sess-")
       true
   """
-  @spec start(atom(), keyword()) :: {:ok, String.t()} | {:error, term()}
-  def start(workspace_id, opts \\ []) when is_atom(workspace_id) do
-    session_id = Keyword.get_lazy(opts, :session_id, &generate_id/0)
-
-    child_spec = {
-      Jido.Shell.SessionServer,
-      Keyword.merge(opts, session_id: session_id, workspace_id: workspace_id)
-    }
-
-    case DynamicSupervisor.start_child(Jido.Shell.SessionSupervisor, child_spec) do
-      {:ok, _pid} -> {:ok, session_id}
-      {:error, _} = error -> error
+  @spec start(workspace_id(), keyword()) :: {:ok, String.t()} | {:error, Error.t() | term()}
+  def start(workspace_id, opts \\ []) do
+    with :ok <- validate_workspace_id(workspace_id) do
+      session_id = Keyword.get_lazy(opts, :session_id, &generate_id/0)
+
+      child_spec = {
+        Jido.Shell.SessionServer,
+        Keyword.merge(opts, session_id: session_id, workspace_id: workspace_id)
+      }
+
+      case DynamicSupervisor.start_child(Jido.Shell.SessionSupervisor, child_spec) do
+        {:ok, _pid} -> {:ok, session_id}
+        {:error, _} = error -> error
+      end
     end
   end
 
   @doc """
   Stops a session.
   """
-  @spec stop(String.t()) :: :ok | {:error, :not_found}
+  @spec stop(String.t()) :: :ok | {:error, :not_found | term()}
   def stop(session_id) do
     case lookup(session_id) do
       {:ok, pid} ->
-        DynamicSupervisor.terminate_child(Jido.Shell.SessionSupervisor, pid)
-        :ok
+        state =
+          case SessionServer.get_state(session_id) do
+            {:ok, session_state} -> session_state
+            _ -> nil
+          end
+
+        case DynamicSupervisor.terminate_child(Jido.Shell.SessionSupervisor, pid) do
+          :ok ->
+            maybe_cleanup_workspace(state, session_id)
+            :ok
+
+          {:error, :not_found} ->
+            :ok
+        end
 
       {:error, :not_found} = error ->
         error
@@ -111,17 +130,111 @@ defmodule Jido.Shell.Session do
 
   ## Examples
 
-      iex> {:ok, session_id} = Jido.Shell.Session.start_with_vfs(:my_workspace)
+      iex> {:ok, session_id} = Jido.Shell.Session.start_with_vfs("my_workspace")
       iex> String.starts_with?(session_id, "sess-")
       true
   """
-  @spec start_with_vfs(atom(), keyword()) :: {:ok, String.t()} | {:error, term()}
-  def start_with_vfs(workspace_id, opts \\ []) when is_atom(workspace_id) do
+  @spec start_with_vfs(workspace_id(), keyword()) :: {:ok, String.t()} | {:error, Error.t() | term()}
+  def start_with_vfs(workspace_id, opts \\ []) do
+    with :ok <- validate_workspace_id(workspace_id),
+         {:ok, mounted_now?} <- ensure_root_mount(workspace_id) do
+      opts =
+        if mounted_now? do
+          Keyword.update(opts, :meta, %{managed_workspace_mount: true}, fn meta ->
+            Map.put(meta, :managed_workspace_mount, true)
+          end)
+        else
+          opts
+        end
+
+      start(workspace_id, opts)
+    end
+  end
+
+  @doc """
+  Tears down all mounts in a workspace.
+  """
+  @spec teardown_workspace(workspace_id(), keyword()) :: :ok | {:error, Error.t()}
+  def teardown_workspace(workspace_id, opts \\ []) do
+    Jido.Shell.VFS.unmount_workspace(workspace_id, opts)
+  end
+
+  defp ensure_root_mount(workspace_id) do
     if Jido.Shell.VFS.list_mounts(workspace_id) == [] do
-      fs_name = :"kodo_vfs_#{workspace_id}_#{System.unique_integer([:positive])}"
-      :ok = Jido.Shell.VFS.mount(workspace_id, "/", Jido.VFS.Adapter.InMemory, name: fs_name)
+      case Jido.Shell.VFS.mount(
+             workspace_id,
+             "/",
+             Jido.VFS.Adapter.InMemory,
+             name: build_vfs_name(workspace_id),
+             managed: true
+           ) do
+        :ok -> {:ok, true}
+        {:error, _} = error -> error
+      end
+    else
+      {:ok, false}
+    end
+  end
+
+  defp build_vfs_name(workspace_id) do
+    safe_workspace =
+      workspace_id
+      |> String.replace(~r/[^a-zA-Z0-9_-]/, "_")
+      |> String.slice(0, 48)
+
+    "jido_shell_vfs_#{safe_workspace}_#{System.unique_integer([:positive])}"
+  end
+
+  defp maybe_cleanup_workspace(%State{} = state, stopping_session_id) do
+    managed_workspace_mount? = Map.get(state.meta, :managed_workspace_mount, false)
+
+    if managed_workspace_mount? and workspace_inactive?(state.workspace_id, stopping_session_id) do
+      _ = Jido.Shell.VFS.unmount_workspace(state.workspace_id, managed_only: true)
     end
 
-    start(workspace_id, opts)
+    :ok
   end
+
+  defp maybe_cleanup_workspace(_state, _stopping_session_id), do: :ok
+
+  defp workspace_inactive?(workspace_id, stopping_session_id) do
+    DynamicSupervisor.which_children(Jido.Shell.SessionSupervisor)
+    |> Enum.any?(fn
+      {_id, pid, :worker, [Jido.Shell.SessionServer]} when is_pid(pid) ->
+        case safe_get_state(pid) do
+          {:ok, %State{id: session_id, workspace_id: current_workspace}}
+          when session_id != stopping_session_id and current_workspace == workspace_id ->
+            true
+
+          _ ->
+            false
+        end
+
+      _ ->
+        false
+    end)
+    |> Kernel.not()
+  end
+
+  defp safe_get_state(pid) when is_pid(pid) do
+    try do
+      case GenServer.call(pid, :get_state, 1_000) do
+        {:ok, state} -> {:ok, state}
+        _ -> :error
+      end
+    catch
+      :exit, _ -> :error
+    end
+  end
+
+  defp validate_workspace_id(workspace_id) when is_binary(workspace_id) do
+    if String.trim(workspace_id) == "" do
+      {:error, Error.session(:invalid_workspace_id, %{workspace_id: workspace_id})}
+    else
+      :ok
+    end
+  end
+
+  defp validate_workspace_id(workspace_id),
+    do: {:error, Error.session(:invalid_workspace_id, %{workspace_id: workspace_id})}
 end
diff --git a/lib/jido/shell/session/state.ex b/lib/jido/shell/session/state.ex
index 289e9e4..deb1718 100644
--- a/lib/jido/shell/session/state.ex
+++ b/lib/jido/shell/session/state.ex
@@ -9,7 +9,7 @@ defmodule Jido.Shell.Session.State do
   ## Fields
 
   - `id` - Unique session identifier (string)
-  - `workspace_id` - The workspace this session belongs to (atom)
+  - `workspace_id` - The workspace this session belongs to (string)
   - `cwd` - Current working directory (defaults to "/")
   - `env` - Environment variables (map)
   - `history` - Command history (list of strings)
@@ -19,7 +19,7 @@ defmodule Jido.Shell.Session.State do
 
   ## Examples
 
-      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "sess-123", workspace_id: :my_workspace})
+      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "sess-123", workspace_id: "my_workspace"})
       iex> state.cwd
       "/"
       iex> state.history
@@ -31,7 +31,7 @@ defmodule Jido.Shell.Session.State do
             __MODULE__,
             %{
               id: Zoi.string(),
-              workspace_id: Zoi.atom(),
+              workspace_id: Zoi.string() |> Zoi.min(1),
               cwd: Zoi.string() |> Zoi.default("/"),
               env: Zoi.map() |> Zoi.default(%{}),
               history: Zoi.array(Zoi.string()) |> Zoi.default([]),
@@ -43,6 +43,7 @@ defmodule Jido.Shell.Session.State do
           )
 
   @type t :: unquote(Zoi.type_spec(@schema))
+  @default_history_limit 500
 
   @enforce_keys Zoi.Struct.enforce_keys(@schema)
   defstruct Zoi.Struct.struct_fields(@schema)
@@ -67,7 +68,7 @@ defmodule Jido.Shell.Session.State do
 
   ## Examples
 
-      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "sess-1", workspace_id: :test})
+      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "sess-1", workspace_id: "test"})
       iex> state.id
       "sess-1"
 
@@ -84,9 +85,9 @@ defmodule Jido.Shell.Session.State do
 
   ## Examples
 
-      iex> state = Jido.Shell.Session.State.new!(%{id: "sess-1", workspace_id: :test})
+      iex> state = Jido.Shell.Session.State.new!(%{id: "sess-1", workspace_id: "test"})
       iex> state.workspace_id
-      :test
+      "test"
 
   """
   @spec new!(map()) :: t()
@@ -102,7 +103,7 @@ defmodule Jido.Shell.Session.State do
 
   ## Examples
 
-      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "s", workspace_id: :w})
+      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "s", workspace_id: "w"})
       iex> state = Jido.Shell.Session.State.add_transport(state, self())
       iex> MapSet.member?(state.transports, self())
       true
@@ -118,7 +119,7 @@ defmodule Jido.Shell.Session.State do
 
   ## Examples
 
-      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "s", workspace_id: :w})
+      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "s", workspace_id: "w"})
       iex> state = Jido.Shell.Session.State.add_transport(state, self())
       iex> state = Jido.Shell.Session.State.remove_transport(state, self())
       iex> MapSet.member?(state.transports, self())
@@ -135,7 +136,7 @@ defmodule Jido.Shell.Session.State do
 
   ## Examples
 
-      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "s", workspace_id: :w})
+      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "s", workspace_id: "w"})
       iex> state = Jido.Shell.Session.State.add_to_history(state, "ls -la")
       iex> hd(state.history)
       "ls -la"
@@ -143,7 +144,8 @@ defmodule Jido.Shell.Session.State do
   """
   @spec add_to_history(t(), String.t()) :: t()
   def add_to_history(%__MODULE__{} = state, line) when is_binary(line) do
-    %{state | history: [line | state.history]}
+    history_limit = history_limit(state)
+    %{state | history: [line | state.history] |> Enum.take(history_limit)}
   end
 
   @doc """
@@ -151,7 +153,7 @@ defmodule Jido.Shell.Session.State do
 
   ## Examples
 
-      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "s", workspace_id: :w})
+      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "s", workspace_id: "w"})
       iex> state = Jido.Shell.Session.State.set_cwd(state, "/home/user")
       iex> state.cwd
       "/home/user"
@@ -167,7 +169,7 @@ defmodule Jido.Shell.Session.State do
 
   ## Examples
 
-      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "s", workspace_id: :w})
+      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "s", workspace_id: "w"})
       iex> state = Jido.Shell.Session.State.set_current_command(state, %{line: "ls", task: self()})
       iex> state.current_command.line
       "ls"
@@ -183,7 +185,7 @@ defmodule Jido.Shell.Session.State do
 
   ## Examples
 
-      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "s", workspace_id: :w})
+      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "s", workspace_id: "w"})
       iex> state = Jido.Shell.Session.State.set_current_command(state, %{line: "ls"})
       iex> state = Jido.Shell.Session.State.clear_current_command(state)
       iex> state.current_command
@@ -200,7 +202,7 @@ defmodule Jido.Shell.Session.State do
 
   ## Examples
 
-      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "s", workspace_id: :w})
+      iex> {:ok, state} = Jido.Shell.Session.State.new(%{id: "s", workspace_id: "w"})
       iex> Jido.Shell.Session.State.command_running?(state)
       false
 
@@ -208,4 +210,11 @@ defmodule Jido.Shell.Session.State do
   @spec command_running?(t()) :: boolean()
   def command_running?(%__MODULE__{current_command: nil}), do: false
   def command_running?(%__MODULE__{current_command: _}), do: true
+
+  defp history_limit(%__MODULE__{meta: meta}) do
+    case Map.get(meta, :history_limit, Map.get(meta, "history_limit", @default_history_limit)) do
+      limit when is_integer(limit) and limit > 0 -> limit
+      _ -> @default_history_limit
+    end
+  end
 end
diff --git a/lib/jido/shell/session_server.ex b/lib/jido/shell/session_server.ex
index 0e3efcf..bd07d63 100644
--- a/lib/jido/shell/session_server.ex
+++ b/lib/jido/shell/session_server.ex
@@ -8,6 +8,7 @@ defmodule Jido.Shell.SessionServer do
 
   use GenServer
 
+  alias Jido.Shell.Error
   alias Jido.Shell.Session
   alias Jido.Shell.Session.State
 
@@ -29,25 +30,33 @@ defmodule Jido.Shell.SessionServer do
   - `{:jido_shell_session, session_id, {:output, chunk}}`
   - `{:jido_shell_session, session_id, :command_done}`
   """
-  @spec subscribe(String.t(), pid(), keyword()) :: :ok
+  @spec subscribe(String.t(), pid(), keyword()) ::
+          {:ok, :subscribed} | {:error, Error.t()}
   def subscribe(session_id, transport_pid, opts \\ []) do
-    GenServer.call(Session.via_registry(session_id), {:subscribe, transport_pid, opts})
+    with_session(session_id, fn pid ->
+      GenServer.call(pid, {:subscribe, transport_pid, opts})
+    end)
   end
 
   @doc """
   Unsubscribes a transport from session events.
   """
-  @spec unsubscribe(String.t(), pid()) :: :ok
+  @spec unsubscribe(String.t(), pid()) ::
+          {:ok, :unsubscribed} | {:error, Error.t()}
   def unsubscribe(session_id, transport_pid) do
-    GenServer.call(Session.via_registry(session_id), {:unsubscribe, transport_pid})
+    with_session(session_id, fn pid ->
+      GenServer.call(pid, {:unsubscribe, transport_pid})
+    end)
   end
 
   @doc """
   Gets a snapshot of the current session state.
   """
-  @spec get_state(String.t()) :: {:ok, State.t()}
+  @spec get_state(String.t()) :: {:ok, State.t()} | {:error, Error.t()}
   def get_state(session_id) do
-    GenServer.call(Session.via_registry(session_id), :get_state)
+    with_session(session_id, fn pid ->
+      GenServer.call(pid, :get_state)
+    end)
   end
 
   @doc """
@@ -56,17 +65,22 @@ defmodule Jido.Shell.SessionServer do
   `opts` are passed to the command task context (for example
   `execution_context: %{network: %{allow_domains: [...]}}`).
   """
-  @spec run_command(String.t(), String.t(), keyword()) :: :ok
+  @spec run_command(String.t(), String.t(), keyword()) ::
+          {:ok, :accepted} | {:error, Error.t()}
   def run_command(session_id, line, opts \\ []) do
-    GenServer.cast(Session.via_registry(session_id), {:run_command, line, opts})
+    with_session(session_id, fn pid ->
+      GenServer.call(pid, {:run_command, line, opts})
+    end)
   end
 
   @doc """
   Cancels the currently running command.
   """
-  @spec cancel(String.t()) :: :ok
+  @spec cancel(String.t()) :: {:ok, :cancelled} | {:error, Error.t()}
   def cancel(session_id) do
-    GenServer.cast(Session.via_registry(session_id), :cancel)
+    with_session(session_id, fn pid ->
+      GenServer.call(pid, :cancel)
+    end)
   end
 
   # === Server Callbacks ===
@@ -92,13 +106,13 @@ defmodule Jido.Shell.SessionServer do
   def handle_call({:subscribe, transport_pid, _opts}, _from, state) do
     Process.monitor(transport_pid)
     new_state = State.add_transport(state, transport_pid)
-    {:reply, :ok, new_state}
+    {:reply, {:ok, :subscribed}, new_state}
   end
 
   @impl true
   def handle_call({:unsubscribe, transport_pid}, _from, state) do
     new_state = State.remove_transport(state, transport_pid)
-    {:reply, :ok, new_state}
+    {:reply, {:ok, :unsubscribed}, new_state}
   end
 
   @impl true
@@ -107,44 +121,27 @@ defmodule Jido.Shell.SessionServer do
   end
 
   @impl true
-  def handle_cast({:run_command, line, opts}, state) do
-    if State.command_running?(state) do
-      broadcast(state, {:error, Jido.Shell.Error.shell(:busy)})
-      {:noreply, state}
-    else
-      session_pid = self()
-
-      {:ok, task_pid} =
-        Task.Supervisor.start_child(
-          Jido.Shell.CommandTaskSupervisor,
-          fn -> Jido.Shell.CommandRunner.run(session_pid, state, line, opts) end
-        )
-
-      ref = Process.monitor(task_pid)
+  def handle_call({:run_command, line, opts}, _from, state) do
+    {reply, new_state} = do_run_command(state, line, opts)
+    {:reply, reply, new_state}
+  end
 
-      new_state =
-        state
-        |> State.add_to_history(line)
-        |> State.set_current_command(%{task: task_pid, ref: ref, line: line})
+  @impl true
+  def handle_call(:cancel, _from, state) do
+    {reply, new_state} = do_cancel(state)
+    {:reply, reply, new_state}
+  end
 
-      broadcast(new_state, {:command_started, line})
-      {:noreply, new_state}
-    end
+  @impl true
+  def handle_cast({:run_command, line, opts}, state) do
+    {_reply, new_state} = do_run_command(state, line, opts)
+    {:noreply, new_state}
   end
 
   @impl true
   def handle_cast(:cancel, state) do
-    case state.current_command do
-      nil ->
-        {:noreply, state}
-
-      %{task: task_pid, ref: ref} ->
-        Process.demonitor(ref, [:flush])
-        Process.exit(task_pid, :shutdown)
-
-        broadcast(state, :command_cancelled)
-        {:noreply, State.clear_current_command(state)}
-    end
+    {_reply, new_state} = do_cancel(state)
+    {:noreply, new_state}
   end
 
   @impl true
@@ -236,4 +233,66 @@ defmodule Jido.Shell.SessionServer do
       send(pid, {:jido_shell_session, state.id, event})
     end
   end
+
+  defp do_run_command(state, line, opts) do
+    if State.command_running?(state) do
+      error = Error.shell(:busy)
+      broadcast(state, {:error, error})
+      {{:error, error}, state}
+    else
+      session_pid = self()
+
+      case Task.Supervisor.start_child(
+             Jido.Shell.CommandTaskSupervisor,
+             fn -> Jido.Shell.CommandRunner.run(session_pid, state, line, opts) end
+           ) do
+        {:ok, task_pid} ->
+          ref = Process.monitor(task_pid)
+
+          new_state =
+            state
+            |> State.add_to_history(line)
+            |> State.set_current_command(%{task: task_pid, ref: ref, line: line})
+
+          broadcast(new_state, {:command_started, line})
+          {{:ok, :accepted}, new_state}
+
+        {:error, reason} ->
+          {{:error, Error.command(:start_failed, %{reason: reason, line: line})}, state}
+      end
+    end
+  end
+
+  defp do_cancel(state) do
+    case state.current_command do
+      nil ->
+        error = Error.session(:invalid_state_transition, %{state: :idle, action: :cancel})
+        {{:error, error}, state}
+
+      %{task: task_pid, ref: ref} ->
+        Process.demonitor(ref, [:flush])
+        Process.exit(task_pid, :shutdown)
+
+        broadcast(state, :command_cancelled)
+        {{:ok, :cancelled}, State.clear_current_command(state)}
+    end
+  end
+
+  defp with_session(session_id, fun) when is_binary(session_id) and byte_size(session_id) > 0 do
+    case Session.lookup(session_id) do
+      {:ok, pid} ->
+        try do
+          fun.(pid)
+        catch
+          :exit, _ -> {:error, Error.session(:not_found, %{session_id: session_id})}
+        end
+
+      {:error, :not_found} ->
+        {:error, Error.session(:not_found, %{session_id: session_id})}
+    end
+  end
+
+  defp with_session(session_id, _fun) do
+    {:error, Error.session(:invalid_session_id, %{session_id: session_id})}
+  end
 end
diff --git a/lib/jido/shell/transport/iex.ex b/lib/jido/shell/transport/iex.ex
index 0589f0c..3728f50 100644
--- a/lib/jido/shell/transport/iex.ex
+++ b/lib/jido/shell/transport/iex.ex
@@ -7,7 +7,7 @@ defmodule Jido.Shell.Transport.IEx do
 
   ## Usage
 
-      iex> Jido.Shell.Transport.IEx.start(:my_workspace)
+      iex> Jido.Shell.Transport.IEx.start("my_workspace")
       # Enters interactive shell mode
       /home> ls
       file1.txt
@@ -30,38 +30,36 @@ defmodule Jido.Shell.Transport.IEx do
 
   This function blocks and runs the REPL until the user exits.
   """
-  @spec start(atom(), keyword()) :: :ok
-  def start(workspace_id, opts \\ []) when is_atom(workspace_id) do
-    session_id =
-      Keyword.get_lazy(opts, :session_id, fn ->
-        case Session.start_with_vfs(workspace_id, opts) do
-          {:ok, id} -> id
-          {:error, reason} -> raise "Failed to start session: #{inspect(reason)}"
-        end
-      end)
-
-    :ok = SessionServer.subscribe(session_id, self())
-
-    {:ok, initial_state} = SessionServer.get_state(session_id)
-
-    IO.puts("Jido.Shell v#{Jido.Shell.version()}")
-    IO.puts("Type \"exit\" to quit, \"help\" for commands.\n")
-
-    loop(session_id, initial_state.cwd)
+  @spec start(String.t(), keyword()) :: :ok | {:error, Jido.Shell.Error.t() | term()}
+  def start(workspace_id, opts \\ []) when is_binary(workspace_id) do
+    session_result =
+      case Keyword.get(opts, :session_id) do
+        nil -> Session.start_with_vfs(workspace_id, opts)
+        session_id -> {:ok, session_id}
+      end
+
+    with {:ok, session_id} <- session_result,
+         {:ok, :subscribed} <- SessionServer.subscribe(session_id, self()),
+         {:ok, initial_state} <- SessionServer.get_state(session_id) do
+      IO.puts("Jido.Shell v#{Jido.Shell.version()}")
+      IO.puts("Type \"exit\" to quit, \"help\" for commands.\n")
+
+      loop(session_id, initial_state.cwd, opts)
+    end
   end
 
   @doc """
   Attaches to an existing session.
   """
-  @spec attach(String.t()) :: :ok | {:error, :not_found}
-  def attach(session_id) do
+  @spec attach(String.t(), keyword()) :: :ok | {:error, Jido.Shell.Error.t() | :not_found}
+  def attach(session_id, opts \\ []) do
     case Session.lookup(session_id) do
       {:ok, _pid} ->
-        :ok = SessionServer.subscribe(session_id, self())
-        {:ok, state} = SessionServer.get_state(session_id)
-
-        IO.puts("Attached to session #{session_id}")
-        loop(session_id, state.cwd)
+        with {:ok, :subscribed} <- SessionServer.subscribe(session_id, self()),
+             {:ok, state} <- SessionServer.get_state(session_id) do
+          IO.puts("Attached to session #{session_id}")
+          loop(session_id, state.cwd, opts)
+        end
 
       {:error, :not_found} = error ->
         error
@@ -70,10 +68,11 @@ defmodule Jido.Shell.Transport.IEx do
 
   # === Private ===
 
-  defp loop(session_id, cwd) do
+  defp loop(session_id, cwd, opts) do
     prompt = format_prompt(cwd)
+    timeout = wait_timeout(opts)
 
-    case IO.gets(prompt) do
+    case read_line(prompt, opts) do
       :eof ->
         IO.puts("\nGoodbye!")
         :ok
@@ -85,9 +84,9 @@ defmodule Jido.Shell.Transport.IEx do
       line when is_binary(line) ->
         line = String.trim(line)
 
-        case handle_input(session_id, line, cwd) do
+        case handle_input(session_id, line, cwd, timeout) do
           {:continue, new_cwd} ->
-            loop(session_id, new_cwd)
+            loop(session_id, new_cwd, opts)
 
           :exit ->
             IO.puts("Goodbye!")
@@ -96,31 +95,37 @@ defmodule Jido.Shell.Transport.IEx do
     end
   end
 
-  defp handle_input(_session_id, "", cwd), do: {:continue, cwd}
-  defp handle_input(_session_id, "exit", _cwd), do: :exit
-  defp handle_input(_session_id, "quit", _cwd), do: :exit
+  defp handle_input(_session_id, "", cwd, _timeout), do: {:continue, cwd}
+  defp handle_input(_session_id, "exit", _cwd, _timeout), do: :exit
+  defp handle_input(_session_id, "quit", _cwd, _timeout), do: :exit
+
+  defp handle_input(session_id, line, cwd, timeout_ms) do
+    case SessionServer.run_command(session_id, line) do
+      {:ok, :accepted} ->
+        new_cwd = wait_for_completion(session_id, cwd, timeout_ms)
+        {:continue, new_cwd}
 
-  defp handle_input(session_id, line, cwd) do
-    :ok = SessionServer.run_command(session_id, line)
-    new_cwd = wait_for_completion(session_id, cwd)
-    {:continue, new_cwd}
+      {:error, error} ->
+        print_error(error)
+        {:continue, cwd}
+    end
   end
 
-  defp wait_for_completion(session_id, cwd) do
+  defp wait_for_completion(session_id, cwd, timeout_ms) do
     receive do
       {:jido_shell_session, ^session_id, {:command_started, _line}} ->
-        wait_for_completion(session_id, cwd)
+        wait_for_completion(session_id, cwd, timeout_ms)
 
       {:jido_shell_session, ^session_id, {:output, chunk}} ->
         IO.write(chunk)
-        wait_for_completion(session_id, cwd)
+        wait_for_completion(session_id, cwd, timeout_ms)
 
       {:jido_shell_session, ^session_id, {:error, error}} ->
         print_error(error)
         cwd
 
       {:jido_shell_session, ^session_id, {:cwd_changed, new_cwd}} ->
-        wait_for_completion(session_id, new_cwd)
+        wait_for_completion(session_id, new_cwd, timeout_ms)
 
       {:jido_shell_session, ^session_id, :command_done} ->
         cwd
@@ -133,12 +138,26 @@ defmodule Jido.Shell.Transport.IEx do
         IO.puts("#{@error_color}Command crashed: #{inspect(reason)}#{@reset}")
         cwd
     after
-      60_000 ->
+      timeout_ms ->
         IO.puts("#{@error_color}Timeout waiting for command#{@reset}")
         cwd
     end
   end
 
+  defp read_line(prompt, opts) do
+    case Keyword.get(opts, :line_reader) do
+      reader when is_function(reader, 1) -> reader.(prompt)
+      _ -> IO.gets(prompt)
+    end
+  end
+
+  defp wait_timeout(opts) do
+    case Keyword.get(opts, :wait_timeout_ms, 60_000) do
+      timeout when is_integer(timeout) and timeout > 0 -> timeout
+      _ -> 60_000
+    end
+  end
+
   defp format_prompt(cwd) do
     "#{@prompt_color}#{cwd}#{@reset}> "
   end
diff --git a/lib/jido/shell/transport/term_ui.ex b/lib/jido/shell/transport/term_ui.ex
deleted file mode 100644
index cad5dd4..0000000
--- a/lib/jido/shell/transport/term_ui.ex
+++ /dev/null
@@ -1,368 +0,0 @@
-defmodule Jido.Shell.Transport.TermUI do
-  @moduledoc """
-  Rich terminal UI transport for Kodo sessions.
-
-  Provides a full-screen terminal interface with:
-  - Header showing session info and cwd
-  - Scrollable output area
-  - Input line with history navigation
-
-  ## Usage
-
-      iex> Jido.Shell.Transport.TermUI.start(:my_workspace)
-
-  This is a simplified MVU-style implementation that can be
-  enhanced with the term_ui library for more features.
-  """
-
-  alias Jido.Shell.Session
-  alias Jido.Shell.SessionServer
-
-  @type model :: %{
-          session_id: String.t(),
-          workspace_id: atom(),
-          cwd: String.t(),
-          output_buffer: [String.t()],
-          input: String.t(),
-          history: [String.t()],
-          history_index: integer(),
-          command_running: boolean(),
-          scroll_offset: integer()
-        }
-
-  @doc """
-  Starts the TermUI for a workspace.
-  """
-  @spec start(atom(), keyword()) :: :ok
-  def start(workspace_id, opts \\ []) when is_atom(workspace_id) do
-    {:ok, session_id} = Session.start_with_vfs(workspace_id, opts)
-
-    :ok = SessionServer.subscribe(session_id, self())
-
-    {:ok, state} = SessionServer.get_state(session_id)
-
-    model = %{
-      session_id: session_id,
-      workspace_id: workspace_id,
-      cwd: state.cwd,
-      output_buffer: [],
-      input: "",
-      history: [],
-      history_index: 0,
-      command_running: false,
-      scroll_offset: 0
-    }
-
-    run(model)
-  end
-
-  @doc """
-  Attaches to an existing session.
-  """
-  @spec attach(String.t()) :: :ok | {:error, :not_found}
-  def attach(session_id) do
-    case Session.lookup(session_id) do
-      {:ok, _pid} ->
-        :ok = SessionServer.subscribe(session_id, self())
-        {:ok, state} = SessionServer.get_state(session_id)
-
-        model = %{
-          session_id: session_id,
-          workspace_id: state.workspace_id,
-          cwd: state.cwd,
-          output_buffer: [],
-          input: "",
-          history: state.history,
-          history_index: 0,
-          command_running: state.current_command != nil,
-          scroll_offset: 0
-        }
-
-        run(model)
-
-      {:error, :not_found} = error ->
-        error
-    end
-  end
-
-  # === MVU Loop ===
-
-  defp run(model) do
-    clear_screen()
-    render(model)
-
-    case wait_for_input() do
-      {:key, :ctrl_c} when model.command_running ->
-        SessionServer.cancel(model.session_id)
-        run(model)
-
-      {:key, :ctrl_c} ->
-        clear_screen()
-        IO.puts("Goodbye!")
-        :ok
-
-      {:key, :ctrl_d} ->
-        clear_screen()
-        IO.puts("Goodbye!")
-        :ok
-
-      {:key, :enter} ->
-        model = handle_enter(model)
-        run(model)
-
-      {:key, :backspace} ->
-        model = %{model | input: String.slice(model.input, 0..-2//1)}
-        run(model)
-
-      {:key, :up} ->
-        model = history_up(model)
-        run(model)
-
-      {:key, :down} ->
-        model = history_down(model)
-        run(model)
-
-      {:key, {:char, c}} ->
-        model = %{model | input: model.input <> <<c>>}
-        run(model)
-
-      {:session_event, event} ->
-        model = handle_session_event(model, event)
-        run(model)
-
-      :timeout ->
-        run(model)
-
-      _ ->
-        run(model)
-    end
-  catch
-    :exit -> :ok
-  end
-
-  # === Input Handling ===
-
-  defp wait_for_input do
-    receive do
-      {:jido_shell_session, _session_id, event} ->
-        {:session_event, event}
-    after
-      100 ->
-        case IO.getn("", 1) do
-          "\e" ->
-            read_escape_sequence()
-
-          "\r" ->
-            {:key, :enter}
-
-          "\n" ->
-            {:key, :enter}
-
-          <<127>> ->
-            {:key, :backspace}
-
-          <<3>> ->
-            {:key, :ctrl_c}
-
-          <<4>> ->
-            {:key, :ctrl_d}
-
-          c when is_binary(c) and byte_size(c) == 1 ->
-            <<char>> = c
-            {:key, {:char, char}}
-
-          _ ->
-            :timeout
-        end
-    end
-  end
-
-  defp read_escape_sequence do
-    case IO.getn("", 1) do
-      "[" ->
-        case IO.getn("", 1) do
-          "A" -> {:key, :up}
-          "B" -> {:key, :down}
-          "C" -> {:key, :right}
-          "D" -> {:key, :left}
-          _ -> {:key, :escape}
-        end
-
-      _ ->
-        {:key, :escape}
-    end
-  end
-
-  defp handle_enter(%{input: ""} = model), do: model
-
-  defp handle_enter(%{input: "exit"}) do
-    clear_screen()
-    IO.puts("Goodbye!")
-    throw(:exit)
-  end
-
-  defp handle_enter(%{input: "quit"}) do
-    clear_screen()
-    IO.puts("Goodbye!")
-    throw(:exit)
-  end
-
-  defp handle_enter(model) do
-    :ok = SessionServer.run_command(model.session_id, model.input)
-
-    %{
-      model
-      | history: [model.input | model.history],
-        history_index: 0,
-        input: "",
-        command_running: true
-    }
-  end
-
-  defp history_up(%{history: []} = model), do: model
-
-  defp history_up(%{history: history, history_index: idx} = model) do
-    new_idx = min(idx + 1, length(history))
-    input = Enum.at(history, new_idx - 1) || model.input
-    %{model | history_index: new_idx, input: input}
-  end
-
-  defp history_down(%{history_index: 0} = model), do: model
-
-  defp history_down(%{history: history, history_index: idx} = model) do
-    new_idx = max(idx - 1, 0)
-    input = if new_idx == 0, do: "", else: Enum.at(history, new_idx - 1) || ""
-    %{model | history_index: new_idx, input: input}
-  end
-
-  # === Session Events ===
-
-  defp handle_session_event(model, {:command_started, _line}) do
-    model
-  end
-
-  defp handle_session_event(model, {:output, chunk}) do
-    %{model | output_buffer: model.output_buffer ++ [chunk]}
-  end
-
-  defp handle_session_event(model, {:error, error}) do
-    error_line = "\e[31mError: #{error.message}\e[0m\n"
-
-    %{
-      model
-      | output_buffer: model.output_buffer ++ [error_line],
-        command_running: false
-    }
-  end
-
-  defp handle_session_event(model, {:cwd_changed, cwd}) do
-    %{model | cwd: cwd}
-  end
-
-  defp handle_session_event(model, :command_done) do
-    %{model | command_running: false}
-  end
-
-  defp handle_session_event(model, :command_cancelled) do
-    %{
-      model
-      | output_buffer: model.output_buffer ++ ["\e[33mCancelled\e[0m\n"],
-        command_running: false
-    }
-  end
-
-  defp handle_session_event(model, {:command_crashed, reason}) do
-    error_line = "\e[31mCrashed: #{inspect(reason)}\e[0m\n"
-
-    %{
-      model
-      | output_buffer: model.output_buffer ++ [error_line],
-        command_running: false
-    }
-  end
-
-  defp handle_session_event(model, _event), do: model
-
-  # === Rendering ===
-
-  defp clear_screen do
-    IO.write("\e[2J\e[H")
-  end
-
-  defp render(model) do
-    {width, height} = get_terminal_size()
-
-    header = render_header(model, width)
-
-    output_height = height - 4
-
-    output = render_output(model, width, output_height)
-
-    status = render_status(model, width)
-
-    input_line = render_input(model)
-
-    IO.write("\e[H")
-    IO.write(header)
-    IO.write(output)
-    IO.write(status)
-    IO.write(input_line)
-
-    cursor_col = String.length(model.cwd) + String.length(model.input) + 3
-    IO.write("\e[#{height};#{cursor_col}H")
-  end
-
-  defp render_header(model, width) do
-    title = "Kodo Shell - #{model.workspace_id}"
-    cwd_line = "cwd: #{model.cwd}"
-
-    "\e[7m" <>
-      String.pad_trailing(title, width) <>
-      "\e[0m\n" <>
-      "\e[36m#{cwd_line}\e[0m\n"
-  end
-
-  defp render_output(model, _width, height) do
-    all_output = Enum.join(model.output_buffer)
-    lines = String.split(all_output, "\n", trim: false)
-
-    visible_lines = Enum.take(lines, -height)
-
-    padding = height - length(visible_lines)
-    padded = List.duplicate("\n", padding) ++ Enum.map(visible_lines, &(&1 <> "\n"))
-
-    Enum.join(padded)
-  end
-
-  defp render_status(model, width) do
-    status =
-      if model.command_running do
-        "\e[33m[Running...]\e[0m"
-      else
-        "\e[32m[Ready]\e[0m"
-      end
-
-    String.pad_trailing(status, width) <> "\n"
-  end
-
-  defp render_input(model) do
-    prompt = "\e[36m#{model.cwd}\e[0m> "
-    prompt <> model.input
-  end
-
-  defp get_terminal_size do
-    case :io.columns() do
-      {:ok, cols} ->
-        rows =
-          case :io.rows() do
-            {:ok, r} -> r
-            _ -> 24
-          end
-
-        {cols, rows}
-
-      _ ->
-        {80, 24}
-    end
-  end
-end
diff --git a/lib/jido/shell/vfs.ex b/lib/jido/shell/vfs.ex
index bc51bac..a72020b 100644
--- a/lib/jido/shell/vfs.ex
+++ b/lib/jido/shell/vfs.ex
@@ -8,18 +8,19 @@ defmodule Jido.Shell.VFS do
   ## Example
 
       # Mount an in-memory filesystem at root
-      :ok = Jido.Shell.VFS.mount(:my_workspace, "/", Jido.VFS.Adapter.InMemory, [name: :my_fs])
+      :ok = Jido.Shell.VFS.mount("my_workspace", "/", Jido.VFS.Adapter.InMemory, [name: "my_fs"])
 
       # Write a file
-      :ok = Jido.Shell.VFS.write_file(:my_workspace, "/hello.txt", "Hello!")
+      :ok = Jido.Shell.VFS.write_file("my_workspace", "/hello.txt", "Hello!")
 
       # Read it back
-      {:ok, "Hello!"} = Jido.Shell.VFS.read_file(:my_workspace, "/hello.txt")
+      {:ok, "Hello!"} = Jido.Shell.VFS.read_file("my_workspace", "/hello.txt")
   """
 
+  alias Jido.Shell.Error
   alias Jido.Shell.VFS.MountTable
 
-  @type workspace_id :: atom()
+  @type workspace_id :: String.t()
   @type path :: String.t()
 
   @doc """
@@ -34,17 +35,44 @@ defmodule Jido.Shell.VFS do
   @doc """
   Mounts a Jido.VFS adapter at the given path.
   """
-  @spec mount(workspace_id(), path(), module(), keyword()) :: :ok | {:error, term()}
+  @spec mount(workspace_id(), path(), module(), keyword()) :: :ok | {:error, Error.t()}
   def mount(workspace_id, mount_path, adapter, opts \\ []) do
-    MountTable.mount(workspace_id, mount_path, adapter, opts)
+    with :ok <- validate_workspace_id(workspace_id) do
+      case MountTable.mount(workspace_id, mount_path, adapter, opts) do
+        :ok ->
+          :ok
+
+        {:error, :path_already_mounted} ->
+          {:error, Error.vfs(:already_exists, mount_path, %{workspace_id: workspace_id})}
+
+        {:error, reason} ->
+          {:error, Error.vfs(:mount_failed, mount_path, %{workspace_id: workspace_id, reason: reason})}
+      end
+    end
   end
 
   @doc """
   Unmounts a filesystem at the given path.
   """
-  @spec unmount(workspace_id(), path()) :: :ok | {:error, :not_found}
+  @spec unmount(workspace_id(), path()) :: :ok | {:error, Error.t()}
   def unmount(workspace_id, mount_path) do
-    MountTable.unmount(workspace_id, mount_path)
+    with :ok <- validate_workspace_id(workspace_id) do
+      case MountTable.unmount(workspace_id, mount_path) do
+        :ok -> :ok
+        {:error, :not_found} -> {:error, Error.vfs(:not_found, mount_path, %{workspace_id: workspace_id})}
+      end
+    end
+  end
+
+  @doc """
+  Unmounts all mounts for a workspace.
+  """
+  @spec unmount_workspace(workspace_id(), keyword()) :: :ok | {:error, Error.t()}
+  def unmount_workspace(workspace_id, opts \\ []) do
+    with :ok <- validate_workspace_id(workspace_id) do
+      :ok = MountTable.unmount_workspace(workspace_id, opts)
+      :ok
+    end
   end
 
   @doc """
@@ -52,7 +80,11 @@ defmodule Jido.Shell.VFS do
   """
   @spec list_mounts(workspace_id()) :: [Jido.Shell.VFS.Mount.t()]
   def list_mounts(workspace_id) do
-    MountTable.list(workspace_id)
+    if valid_workspace_id?(workspace_id) do
+      MountTable.list(workspace_id)
+    else
+      []
+    end
   end
 
   # === File Operations ===
@@ -62,7 +94,8 @@ defmodule Jido.Shell.VFS do
   """
   @spec read_file(workspace_id(), path()) :: {:ok, binary()} | {:error, Jido.Shell.Error.t()}
   def read_file(workspace_id, path) do
-    with {:ok, mount, relative_path} <- resolve_path(workspace_id, path) do
+    with :ok <- validate_workspace_id(workspace_id),
+         {:ok, mount, relative_path} <- resolve_path(workspace_id, path) do
       case Jido.VFS.read(mount.filesystem, relative_path) do
         {:ok, _} = result -> result
         {:error, reason} -> {:error, Jido.Shell.Error.vfs(error_code(reason), path)}
@@ -75,7 +108,8 @@ defmodule Jido.Shell.VFS do
   """
   @spec write_file(workspace_id(), path(), binary()) :: :ok | {:error, Jido.Shell.Error.t()}
   def write_file(workspace_id, path, content) do
-    with {:ok, mount, relative_path} <- resolve_path(workspace_id, path) do
+    with :ok <- validate_workspace_id(workspace_id),
+         {:ok, mount, relative_path} <- resolve_path(workspace_id, path) do
       case Jido.VFS.write(mount.filesystem, relative_path, content) do
         :ok -> :ok
         {:error, reason} -> {:error, Jido.Shell.Error.vfs(error_code(reason), path)}
@@ -88,7 +122,8 @@ defmodule Jido.Shell.VFS do
   """
   @spec delete(workspace_id(), path()) :: :ok | {:error, Jido.Shell.Error.t()}
   def delete(workspace_id, path) do
-    with {:ok, mount, relative_path} <- resolve_path(workspace_id, path) do
+    with :ok <- validate_workspace_id(workspace_id),
+         {:ok, mount, relative_path} <- resolve_path(workspace_id, path) do
       case Jido.VFS.delete(mount.filesystem, relative_path) do
         :ok -> :ok
         {:error, reason} -> {:error, Jido.Shell.Error.vfs(error_code(reason), path)}
@@ -101,7 +136,8 @@ defmodule Jido.Shell.VFS do
   """
   @spec list_dir(workspace_id(), path()) :: {:ok, [map()]} | {:error, Jido.Shell.Error.t()}
   def list_dir(workspace_id, path) do
-    with {:ok, mount, relative_path} <- resolve_path(workspace_id, path) do
+    with :ok <- validate_workspace_id(workspace_id),
+         {:ok, mount, relative_path} <- resolve_path(workspace_id, path) do
       case Jido.VFS.list_contents(mount.filesystem, relative_path) do
         {:ok, _} = result -> result
         {:error, reason} -> {:error, Jido.Shell.Error.vfs(error_code(reason), path)}
@@ -114,7 +150,8 @@ defmodule Jido.Shell.VFS do
   """
   @spec stat(workspace_id(), path()) :: {:ok, map()} | {:error, Jido.Shell.Error.t()}
   def stat(workspace_id, path) do
-    with {:ok, mount, relative_path} <- resolve_path(workspace_id, path) do
+    with :ok <- validate_workspace_id(workspace_id),
+         {:ok, mount, relative_path} <- resolve_path(workspace_id, path) do
       if relative_path == "." do
         name =
           case Path.basename(path) do
@@ -158,7 +195,8 @@ defmodule Jido.Shell.VFS do
   """
   @spec mkdir(workspace_id(), path()) :: :ok | {:error, Jido.Shell.Error.t()}
   def mkdir(workspace_id, path) do
-    with {:ok, mount, relative_path} <- resolve_path(workspace_id, path) do
+    with :ok <- validate_workspace_id(workspace_id),
+         {:ok, mount, relative_path} <- resolve_path(workspace_id, path) do
       dir_path =
         if String.ends_with?(relative_path, "/"),
           do: relative_path,
@@ -196,4 +234,16 @@ defmodule Jido.Shell.VFS do
   defp error_code(:unsupported), do: :unsupported
   defp error_code(reason) when is_atom(reason), do: reason
   defp error_code(_), do: :unknown
+
+  defp valid_workspace_id?(workspace_id) do
+    is_binary(workspace_id) and String.trim(workspace_id) != ""
+  end
+
+  defp validate_workspace_id(workspace_id) do
+    if valid_workspace_id?(workspace_id) do
+      :ok
+    else
+      {:error, Error.session(:invalid_workspace_id, %{workspace_id: workspace_id})}
+    end
+  end
 end
diff --git a/lib/jido/shell/vfs/mount.ex b/lib/jido/shell/vfs/mount.ex
index 63a447c..2a599ba 100644
--- a/lib/jido/shell/vfs/mount.ex
+++ b/lib/jido/shell/vfs/mount.ex
@@ -3,13 +3,17 @@ defmodule Jido.Shell.VFS.Mount do
   Represents a mounted filesystem at a path.
   """
 
-  defstruct [:path, :adapter, :filesystem, :opts]
+  defstruct [:path, :adapter, :filesystem, :opts, :child_pid, :ownership]
+
+  @type ownership :: :owned | :shared | :none
 
   @type t :: %__MODULE__{
           path: String.t(),
           adapter: module(),
           filesystem: Jido.VFS.filesystem(),
-          opts: keyword()
+          opts: keyword(),
+          child_pid: pid() | nil,
+          ownership: ownership()
         }
 
   @doc """
@@ -17,32 +21,40 @@ defmodule Jido.Shell.VFS.Mount do
   """
   @spec new(String.t(), module(), keyword()) :: {:ok, t()} | {:error, term()}
   def new(path, adapter, opts) do
-    case adapter.configure(opts) do
-      {^adapter, _config} = filesystem ->
-        :ok = maybe_start_filesystem(adapter, filesystem)
-
-        {:ok,
-         %__MODULE__{
-           path: normalize_path(path),
-           adapter: adapter,
-           filesystem: filesystem,
-           opts: opts
-         }}
-
-      {:error, _} = error ->
-        error
+    with {^adapter, _config} = filesystem <- adapter.configure(opts),
+         {:ok, child_pid, ownership} <- maybe_start_filesystem(adapter, filesystem) do
+      {:ok,
+       %__MODULE__{
+         path: normalize_path(path),
+         adapter: adapter,
+         filesystem: filesystem,
+         opts: opts,
+         child_pid: child_pid,
+         ownership: ownership
+       }}
+    else
+      {:error, _} = error -> error
+      other -> {:error, {:invalid_adapter_config, other}}
     end
   end
 
   defp maybe_start_filesystem(adapter, filesystem) do
     if function_exported?(adapter, :starts_processes, 0) and adapter.starts_processes() do
-      case DynamicSupervisor.start_child(Jido.Shell.FilesystemSupervisor, {adapter, filesystem}) do
-        {:ok, _pid} -> :ok
-        {:error, {:already_started, _pid}} -> :ok
-        {:error, reason} -> {:error, reason}
+      try do
+        case DynamicSupervisor.start_child(Jido.Shell.FilesystemSupervisor, {adapter, filesystem}) do
+          {:ok, pid} -> {:ok, pid, :owned}
+          {:error, {:already_started, pid}} -> {:ok, pid, :shared}
+          {:error, reason} -> {:error, reason}
+        end
+      rescue
+        error ->
+          {:error, {:start_child_failed, error}}
+      catch
+        kind, reason ->
+          {:error, {kind, reason}}
       end
     else
-      :ok
+      {:ok, nil, :none}
     end
   end
 
diff --git a/lib/jido/shell/vfs/mount_table.ex b/lib/jido/shell/vfs/mount_table.ex
index 5ca7a16..119dc9a 100644
--- a/lib/jido/shell/vfs/mount_table.ex
+++ b/lib/jido/shell/vfs/mount_table.ex
@@ -3,71 +3,95 @@ defmodule Jido.Shell.VFS.MountTable do
   ETS-backed mount table for VFS.
   """
 
+  use GenServer
+
   alias Jido.Shell.VFS.Mount
 
-  @table :kodo_vfs_mounts
+  @table :jido_shell_vfs_mounts
+  @server __MODULE__
 
   @doc """
   Initializes the ETS table.
   """
   @spec init() :: :ok
   def init do
-    if :ets.whereis(@table) == :undefined do
-      :ets.new(@table, [:named_table, :public, :bag])
+    case Process.whereis(@server) do
+      nil ->
+        case start_link([]) do
+          {:ok, _pid} -> :ok
+          {:error, {:already_started, _pid}} -> :ok
+          {:error, _} -> :ok
+        end
+
+      _pid ->
+        :ok
     end
+  end
 
+  @doc false
+  @spec start_link(keyword()) :: GenServer.on_start()
+  def start_link(_opts) do
+    GenServer.start_link(__MODULE__, :ok, name: @server)
+  end
+
+  @impl true
+  def init(:ok) do
+    ensure_table()
     :ok
+    {:ok, %{}}
   end
 
   @doc """
   Mounts a filesystem.
   """
-  @spec mount(atom(), String.t(), module(), keyword()) :: :ok | {:error, term()}
+  @spec mount(String.t(), String.t(), module(), keyword()) :: :ok | {:error, term()}
   def mount(workspace_id, path, adapter, opts) do
-    case Mount.new(path, adapter, opts) do
-      {:ok, mount} ->
-        :ets.insert(@table, {workspace_id, mount})
-        :ok
-
-      {:error, _} = error ->
-        error
-    end
+    :ok = init()
+    GenServer.call(@server, {:mount, workspace_id, path, adapter, opts})
   end
 
   @doc """
   Unmounts a filesystem.
   """
-  @spec unmount(atom(), String.t()) :: :ok | {:error, :not_found}
+  @spec unmount(String.t(), String.t()) :: :ok | {:error, :not_found}
   def unmount(workspace_id, path) do
-    normalized = normalize_path(path)
-    mounts = list(workspace_id)
-
-    case Enum.find(mounts, fn m -> m.path == normalized end) do
-      nil ->
-        {:error, :not_found}
+    :ok = init()
+    GenServer.call(@server, {:unmount, workspace_id, path})
+  end
 
-      mount ->
-        :ets.delete_object(@table, {workspace_id, mount})
-        :ok
-    end
+  @doc """
+  Unmounts all mounts in a workspace.
+  """
+  @spec unmount_workspace(String.t(), keyword()) :: :ok
+  def unmount_workspace(workspace_id, opts \\ []) do
+    :ok = init()
+    GenServer.call(@server, {:unmount_workspace, workspace_id, opts})
   end
 
   @doc """
   Lists all mounts for a workspace.
   """
-  @spec list(atom()) :: [Mount.t()]
+  @spec list(String.t()) :: [Mount.t()]
   def list(workspace_id) do
-    @table
-    |> :ets.lookup(workspace_id)
-    |> Enum.map(fn {_ws, mount} -> mount end)
-    # Longest first for matching
-    |> Enum.sort_by(fn m -> -String.length(m.path) end)
+    :ok = init()
+
+    case :ets.whereis(@table) do
+      :undefined ->
+        []
+
+      _table ->
+        @table
+        |> :ets.lookup(workspace_id)
+        |> Enum.map(fn {_ws, mount} -> mount end)
+        # Longest first for matching
+        |> Enum.sort_by(fn m -> -String.length(m.path) end)
+    end
   end
 
   @doc """
   Resolves a path to its mount and relative path.
   """
-  @spec resolve(atom(), String.t()) :: {:ok, Mount.t(), String.t()} | {:error, :no_mount}
+  @spec resolve(String.t(), String.t()) :: {:ok, Mount.t(), String.t()} | {:error, :no_mount}
   def resolve(workspace_id, path) do
     path = normalize_path(path)
     mounts = list(workspace_id)
@@ -82,6 +106,69 @@ defmodule Jido.Shell.VFS.MountTable do
     end
   end
 
+  @impl true
+  def handle_call({:mount, workspace_id, path, adapter, opts}, _from, state) do
+    normalized_path = normalize_path(path)
+
+    reply =
+      if path_mounted?(workspace_id, normalized_path) do
+        {:error, :path_already_mounted}
+      else
+        case Mount.new(normalized_path, adapter, opts) do
+          {:ok, mount} ->
+            :ets.insert(@table, {workspace_id, mount})
+            :ok
+
+          {:error, _} = error ->
+            error
+        end
+      end
+
+    {:reply, reply, state}
+  end
+
+  @impl true
+  def handle_call({:unmount, workspace_id, path}, _from, state) do
+    normalized = normalize_path(path)
+    mounts = list(workspace_id)
+
+    reply =
+      case Enum.find(mounts, fn m -> m.path == normalized end) do
+        nil ->
+          {:error, :not_found}
+
+        mount ->
+          :ets.delete_object(@table, {workspace_id, mount})
+          maybe_stop_filesystem(mount)
+          :ok
+      end
+
+    {:reply, reply, state}
+  end
+
+  @impl true
+  def handle_call({:unmount_workspace, workspace_id, opts}, _from, state) do
+    managed_only? = Keyword.get(opts, :managed_only, false)
+
+    workspace_id
+    |> list()
+    |> Enum.filter(fn mount ->
+      not managed_only? or Keyword.get(mount.opts, :managed, false)
+    end)
+    |> Enum.each(fn mount ->
+      :ets.delete_object(@table, {workspace_id, mount})
+      maybe_stop_filesystem(mount)
+    end)
+
+    {:reply, :ok, state}
+  end
+
+  defp ensure_table do
+    if :ets.whereis(@table) == :undefined do
+      :ets.new(@table, [:named_table, :protected, :bag, read_concurrency: true])
+    end
+  end
+
   defp path_under_mount?(_path, "/"), do: true
 
   defp path_under_mount?(path, mount_path) do
@@ -102,6 +189,21 @@ defmodule Jido.Shell.VFS.MountTable do
     String.trim_leading(path, mount_path <> "/")
   end
 
+  defp path_mounted?(workspace_id, normalized_path) do
+    Enum.any?(list(workspace_id), fn mount ->
+      mount.path == normalized_path
+    end)
+  end
+
+  defp maybe_stop_filesystem(%Mount{ownership: :owned, child_pid: pid}) when is_pid(pid) do
+    case DynamicSupervisor.terminate_child(Jido.Shell.FilesystemSupervisor, pid) do
+      :ok -> :ok
+      {:error, :not_found} -> :ok
+    end
+  end
+
+  defp maybe_stop_filesystem(_mount), do: :ok
+
   defp normalize_path("/"), do: "/"
   defp normalize_path(path), do: String.trim_trailing(path, "/")
 end
diff --git a/lib/mix/tasks/jido_shell.ex b/lib/mix/tasks/jido_shell.ex
index 3ce444c..395e8f9 100644
--- a/lib/mix/tasks/jido_shell.ex
+++ b/lib/mix/tasks/jido_shell.ex
@@ -5,7 +5,6 @@ defmodule Mix.Tasks.JidoShell do
   ## Usage
 
       mix jido_shell              # IEx-style shell
-      mix jido_shell --ui         # Rich terminal UI
       mix jido_shell --workspace my_workspace
 
   """
@@ -20,19 +19,20 @@ defmodule Mix.Tasks.JidoShell do
 
     {opts, _, _} =
       OptionParser.parse(args,
-        strict: [workspace: :string, ui: :boolean]
+        strict: [workspace: :string]
       )
 
-    workspace_id =
-      case Keyword.get(opts, :workspace) do
-        nil -> :default
-        name -> String.to_atom(name)
-      end
+    workspace_id = Keyword.get(opts, :workspace, "default")
 
-    if Keyword.get(opts, :ui) do
-      Jido.Shell.Transport.TermUI.start(workspace_id)
-    else
-      Jido.Shell.Transport.IEx.start(workspace_id)
+    case Jido.Shell.Transport.IEx.start(workspace_id) do
+      :ok ->
+        :ok
+
+      {:error, %Jido.Shell.Error{} = error} ->
+        Mix.raise("failed to start shell: #{error.message}")
+
+      {:error, reason} ->
+        Mix.raise("failed to start shell: #{inspect(reason)}")
     end
   end
 end
diff --git a/mix.exs b/mix.exs
index 9955860..3fa4c90 100644
--- a/mix.exs
+++ b/mix.exs
@@ -18,7 +18,8 @@ defmodule Jido.Shell.MixProject do
       # Test Coverage
       test_coverage: [
         tool: ExCoveralls,
-        summary: [threshold: 90]
+        summary: [threshold: 90],
+        coverage_options: [minimum_coverage: 90]
       ],
 
       # Dialyzer
@@ -46,8 +47,10 @@ defmodule Jido.Shell.MixProject do
     [
       preferred_envs: [
         coveralls: :test,
+        "coveralls.detail": :test,
         "coveralls.github": :test,
-        "coveralls.html": :test
+        "coveralls.html": :test,
+        "coveralls.json": :test
       ]
     ]
   end
@@ -101,7 +104,8 @@ defmodule Jido.Shell.MixProject do
 
   defp package do
     [
-      files: ~w(lib mix.exs LICENSE README.md CHANGELOG.md CONTRIBUTING.md AGENTS.md usage-rules.md .formatter.exs),
+      files:
+        ~w(lib mix.exs LICENSE README.md MIGRATION.md CHANGELOG.md CONTRIBUTING.md AGENTS.md usage-rules.md .formatter.exs),
       maintainers: ["Mike Hostetler"],
       licenses: ["Apache-2.0"],
       links: %{
@@ -120,8 +124,10 @@ defmodule Jido.Shell.MixProject do
       source_ref: "v#{@version}",
       extras: [
         {"README.md", title: "Overview"},
+        "MIGRATION.md",
         "CHANGELOG.md",
-        "CONTRIBUTING.md"
+        "CONTRIBUTING.md",
+        "LICENSE"
       ],
       groups_for_modules: [
         Core: [
@@ -138,8 +144,7 @@ defmodule Jido.Shell.MixProject do
           Jido.Shell.VFS.MountTable
         ],
         Transports: [
-          Jido.Shell.Transport.IEx,
-          Jido.Shell.Transport.TermUI
+          Jido.Shell.Transport.IEx
         ],
         Internals: [
           Jido.Shell.CommandRunner,
diff --git a/test/jido/shell/agent_test.exs b/test/jido/shell/agent_test.exs
index 84b8eee..99d882b 100644
--- a/test/jido/shell/agent_test.exs
+++ b/test/jido/shell/agent_test.exs
@@ -1,6 +1,8 @@
 defmodule Jido.Shell.AgentTest do
   use Jido.Shell.Case, async: false
 
+  import Mimic
+
   alias Jido.Shell.Agent
   alias Jido.Shell.VFS
 
@@ -26,8 +28,8 @@ defmodule Jido.Shell.AgentTest do
 
   setup do
     VFS.init()
-    workspace_id = :"agent_test_#{System.unique_integer([:positive])}"
-    fs_name = :"agent_fs_#{System.unique_integer([:positive])}"
+    workspace_id = "agent_test_#{System.unique_integer([:positive])}"
+    fs_name = "agent_fs_#{System.unique_integer([:positive])}"
 
     start_supervised!(
       {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs_name}}}
@@ -99,6 +101,45 @@ defmodule Jido.Shell.AgentTest do
 
       assert error.code == {:shell, :unknown_command}
     end
+
+    test "returns typed errors when session cannot be subscribed" do
+      assert {:error, %Jido.Shell.Error{code: {:session, :not_found}}} =
+               Agent.run("missing-session", "echo hi")
+    end
+
+    test "returns cancellation errors when session command is cancelled", %{session_id: session_id} do
+      {:ok, :subscribed} = Jido.Shell.SessionServer.subscribe(session_id, self())
+
+      task =
+        Task.async(fn ->
+          Agent.run(session_id, "sleep 5", timeout: 10_000)
+        end)
+
+      assert_receive {:jido_shell_session, ^session_id, {:command_started, "sleep 5"}}
+      assert {:ok, :cancelled} = Jido.Shell.SessionServer.cancel(session_id)
+
+      assert {:error, %Jido.Shell.Error{code: {:command, :cancelled}}} = Task.await(task, 2_000)
+    end
+
+    test "returns crash errors when a command crashes", %{session_id: session_id} do
+      {:ok, :subscribed} = Jido.Shell.SessionServer.subscribe(session_id, self())
+
+      task =
+        Task.async(fn ->
+          Agent.run(session_id, "sleep 1", timeout: 10_000)
+        end)
+
+      assert_receive {:jido_shell_session, ^session_id, {:command_started, "sleep 1"}}
+
+      send(task.pid, {:jido_shell_session, session_id, {:command_crashed, :boom}})
+
+      assert {:error, %Jido.Shell.Error{code: {:command, :crashed}}} = Task.await(task, 2_000)
+    end
+
+    test "returns timeout errors when no completion event is received in time", %{session_id: session_id} do
+      assert {:error, %Jido.Shell.Error{code: {:command, :timeout}}} =
+               Agent.run(session_id, "sleep 1", timeout: 10)
+    end
   end
 
   describe "file operations" do
@@ -199,13 +240,13 @@ defmodule Jido.Shell.AgentTest do
     end
 
     test "cwd returns current directory", %{session_id: session_id} do
-      assert Agent.cwd(session_id) == "/"
+      assert {:ok, "/"} = Agent.cwd(session_id)
     end
 
     test "cwd changes after cd command", %{session_id: session_id} do
       {:ok, _} = Agent.run(session_id, "mkdir /testdir")
       {:ok, _} = Agent.run(session_id, "cd /testdir")
-      assert Agent.cwd(session_id) == "/testdir"
+      assert {:ok, "/testdir"} = Agent.cwd(session_id)
     end
   end
 
@@ -266,4 +307,31 @@ defmodule Jido.Shell.AgentTest do
       assert error.code == {:vfs, :not_found}
     end
   end
+
+  describe "run/3 mailbox ordering" do
+    setup :set_mimic_global
+    setup :verify_on_exit!
+
+    test "ignores pre-start session events until command_started arrives" do
+      session_id = "mock_session_#{System.unique_integer([:positive])}"
+      copy(Jido.Shell.SessionServer)
+
+      expect(Jido.Shell.SessionServer, :subscribe, fn ^session_id, pid when pid == self() ->
+        {:ok, :subscribed}
+      end)
+
+      expect(Jido.Shell.SessionServer, :run_command, fn ^session_id, "echo hi", [] ->
+        send(self(), {:jido_shell_session, session_id, {:output, "stale\n"}})
+        send(self(), {:jido_shell_session, session_id, {:command_started, "echo hi"}})
+        send(self(), {:jido_shell_session, session_id, :command_done})
+        {:ok, :accepted}
+      end)
+
+      expect(Jido.Shell.SessionServer, :unsubscribe, fn ^session_id, pid when pid == self() ->
+        {:ok, :unsubscribed}
+      end)
+
+      assert {:ok, ""} = Agent.run(session_id, "echo hi")
+    end
+  end
 end
diff --git a/test/jido/shell/atom_leak_test.exs b/test/jido/shell/atom_leak_test.exs
new file mode 100644
index 0000000..7afa47b
--- /dev/null
+++ b/test/jido/shell/atom_leak_test.exs
@@ -0,0 +1,25 @@
+defmodule Jido.Shell.AtomLeakTest do
+  use Jido.Shell.Case, async: false
+
+  alias Jido.Shell.Session
+
+  test "dynamic workspace/session identifiers do not create unbounded atoms" do
+    warmup_workspace = "atom_warmup_#{System.unique_integer([:positive])}"
+    {:ok, warmup_session} = Session.start_with_vfs(warmup_workspace)
+    :ok = Session.stop(warmup_session)
+    :ok = Session.teardown_workspace(warmup_workspace)
+
+    before_count = :erlang.system_info(:atom_count)
+
+    Enum.each(1..25, fn _ ->
+      workspace_id = "atom_ws_#{System.unique_integer([:positive])}"
+      {:ok, session_id} = Session.start_with_vfs(workspace_id)
+      :ok = Session.stop(session_id)
+      :ok = Session.teardown_workspace(workspace_id)
+    end)
+
+    after_count = :erlang.system_info(:atom_count)
+
+    assert after_count - before_count <= 3
+  end
+end
diff --git a/test/jido/shell/cancellation_test.exs b/test/jido/shell/cancellation_test.exs
index 2847874..a19aad5 100644
--- a/test/jido/shell/cancellation_test.exs
+++ b/test/jido/shell/cancellation_test.exs
@@ -5,21 +5,21 @@ defmodule Jido.Shell.CancellationTest do
   alias Jido.Shell.SessionServer
 
   setup do
-    workspace_id = :"test_ws_#{System.unique_integer([:positive])}"
+    workspace_id = "test_ws_#{System.unique_integer([:positive])}"
     {:ok, session_id} = Session.start(workspace_id)
-    :ok = SessionServer.subscribe(session_id, self())
+    {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
     {:ok, session_id: session_id}
   end
 
   describe "cancel/1" do
     test "cancels running command", %{session_id: session_id} do
-      :ok = SessionServer.run_command(session_id, "sleep 10")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "sleep 10")
 
       assert_receive {:jido_shell_session, _, {:command_started, "sleep 10"}}
       assert_receive {:jido_shell_session, _, {:output, "Sleeping for 10 seconds...\n"}}
 
-      :ok = SessionServer.cancel(session_id)
+      {:ok, :cancelled} = SessionServer.cancel(session_id)
 
       assert_receive {:jido_shell_session, _, :command_cancelled}
 
@@ -28,28 +28,31 @@ defmodule Jido.Shell.CancellationTest do
     end
 
     test "does nothing when no command running", %{session_id: session_id} do
-      :ok = SessionServer.cancel(session_id)
+      assert {:error, %Jido.Shell.Error{code: {:session, :invalid_state_transition}}} =
+               SessionServer.cancel(session_id)
 
       refute_receive {:jido_shell_session, _, _}, 100
     end
 
     test "allows new command after cancellation", %{session_id: session_id} do
-      :ok = SessionServer.run_command(session_id, "sleep 10")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "sleep 10")
       assert_receive {:jido_shell_session, _, {:command_started, _}}
 
-      :ok = SessionServer.cancel(session_id)
+      {:ok, :cancelled} = SessionServer.cancel(session_id)
       assert_receive {:jido_shell_session, _, :command_cancelled}
 
-      :ok = SessionServer.run_command(session_id, "echo done")
+      wait_until_idle(session_id)
+
+      {:ok, :accepted} = SessionServer.run_command(session_id, "echo done")
       assert_receive {:jido_shell_session, _, {:command_started, "echo done"}}
-      assert_receive {:jido_shell_session, _, {:output, "done\n"}}
-      assert_receive {:jido_shell_session, _, :command_done}
+      assert_receive {:jido_shell_session, _, {:output, "done\n"}}, 1_000
+      assert_receive {:jido_shell_session, _, :command_done}, 1_000
     end
   end
 
   describe "streaming" do
     test "streams output chunks", %{session_id: session_id} do
-      :ok = SessionServer.run_command(session_id, "seq 3 10")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "seq 3 10")
 
       assert_receive {:jido_shell_session, _, {:command_started, _}}
       assert_receive {:jido_shell_session, _, {:output, "1\n"}}
@@ -61,12 +64,12 @@ defmodule Jido.Shell.CancellationTest do
 
   describe "robustness" do
     test "handles late messages from cancelled command", %{session_id: session_id} do
-      :ok = SessionServer.run_command(session_id, "seq 5 50")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "seq 5 50")
       assert_receive {:jido_shell_session, _, {:command_started, _}}
 
       assert_receive {:jido_shell_session, _, {:output, "1\n"}}
 
-      :ok = SessionServer.cancel(session_id)
+      {:ok, :cancelled} = SessionServer.cancel(session_id)
       assert_receive {:jido_shell_session, _, :command_cancelled}
 
       Process.sleep(100)
@@ -76,14 +79,29 @@ defmodule Jido.Shell.CancellationTest do
     end
 
     test "rejects command when busy", %{session_id: session_id} do
-      :ok = SessionServer.run_command(session_id, "sleep 5")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "sleep 5")
       assert_receive {:jido_shell_session, _, {:command_started, _}}
 
-      :ok = SessionServer.run_command(session_id, "echo hello")
+      assert {:error, %Jido.Shell.Error{code: {:shell, :busy}}} =
+               SessionServer.run_command(session_id, "echo hello")
 
       assert_receive {:jido_shell_session, _, {:error, %Jido.Shell.Error{code: {:shell, :busy}}}}
 
-      :ok = SessionServer.cancel(session_id)
+      {:ok, :cancelled} = SessionServer.cancel(session_id)
+    end
+  end
+
+  defp wait_until_idle(session_id, attempts \\ 20)
+  defp wait_until_idle(_session_id, 0), do: :ok
+
+  defp wait_until_idle(session_id, attempts) do
+    case SessionServer.get_state(session_id) do
+      {:ok, %{current_command: nil}} ->
+        :ok
+
+      _ ->
+        Process.sleep(10)
+        wait_until_idle(session_id, attempts - 1)
     end
   end
 end
diff --git a/test/jido/shell/command/bash_test.exs b/test/jido/shell/command/bash_test.exs
index 17ba9ef..83a27de 100644
--- a/test/jido/shell/command/bash_test.exs
+++ b/test/jido/shell/command/bash_test.exs
@@ -9,8 +9,8 @@ defmodule Jido.Shell.Command.BashTest do
 
   setup do
     VFS.init()
-    workspace_id = :"bash_ws_#{System.unique_integer([:positive])}"
-    fs_name = :"bash_fs_#{System.unique_integer([:positive])}"
+    workspace_id = "bash_ws_#{System.unique_integer([:positive])}"
+    fs_name = "bash_fs_#{System.unique_integer([:positive])}"
 
     start_supervised!(
       {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs_name}}}
@@ -148,9 +148,9 @@ defmodule Jido.Shell.Command.BashTest do
   describe "integration with session" do
     test "applies script state updates to session", %{workspace_id: workspace_id} do
       {:ok, session_id} = Session.start(workspace_id)
-      :ok = SessionServer.subscribe(session_id, self())
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
-      :ok = SessionServer.run_command(session_id, "bash -c \"mkdir home; cd home\"")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "bash -c \"mkdir home; cd home\"")
 
       assert_receive {:jido_shell_session, ^session_id, {:command_started, _}}
       assert_receive {:jido_shell_session, ^session_id, {:cwd_changed, "/home"}}
@@ -162,13 +162,13 @@ defmodule Jido.Shell.Command.BashTest do
 
     test "supports per-command network execution context overrides", %{workspace_id: workspace_id} do
       {:ok, session_id} = Session.start(workspace_id)
-      :ok = SessionServer.subscribe(session_id, self())
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
-      :ok = SessionServer.run_command(session_id, "bash -c \"curl https://example.com\"")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "bash -c \"curl https://example.com\"")
 
       assert_receive {:jido_shell_session, ^session_id, {:error, %Jido.Shell.Error{code: {:shell, :network_blocked}}}}
 
-      :ok =
+      {:ok, :accepted} =
         SessionServer.run_command(
           session_id,
           "bash -c \"curl https://example.com\"",
diff --git a/test/jido/shell/command/cat_test.exs b/test/jido/shell/command/cat_test.exs
index cdf9c27..23c4bd0 100644
--- a/test/jido/shell/command/cat_test.exs
+++ b/test/jido/shell/command/cat_test.exs
@@ -7,8 +7,8 @@ defmodule Jido.Shell.Command.CatTest do
 
   setup do
     VFS.init()
-    workspace_id = :"test_ws_#{System.unique_integer([:positive])}"
-    fs_name = :"test_fs_#{System.unique_integer([:positive])}"
+    workspace_id = "test_ws_#{System.unique_integer([:positive])}"
+    fs_name = "test_fs_#{System.unique_integer([:positive])}"
 
     start_supervised!(
       {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs_name}}}
diff --git a/test/jido/shell/command/cd_test.exs b/test/jido/shell/command/cd_test.exs
index 6643e60..11dae61 100644
--- a/test/jido/shell/command/cd_test.exs
+++ b/test/jido/shell/command/cd_test.exs
@@ -9,8 +9,8 @@ defmodule Jido.Shell.Command.CdTest do
 
   setup do
     VFS.init()
-    workspace_id = :"test_ws_#{System.unique_integer([:positive])}"
-    fs_name = :"test_fs_#{System.unique_integer([:positive])}"
+    workspace_id = "test_ws_#{System.unique_integer([:positive])}"
+    fs_name = "test_fs_#{System.unique_integer([:positive])}"
 
     start_supervised!(
       {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs_name}}}
@@ -104,9 +104,9 @@ defmodule Jido.Shell.Command.CdTest do
   describe "integration with session" do
     test "cd changes session cwd", %{workspace_id: workspace_id} do
       {:ok, session_id} = Session.start(workspace_id)
-      :ok = SessionServer.subscribe(session_id, self())
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
-      :ok = SessionServer.run_command(session_id, "cd /home")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "cd /home")
 
       assert_receive {:jido_shell_session, ^session_id, {:command_started, _}}
       assert_receive {:jido_shell_session, ^session_id, :command_done}
@@ -118,18 +118,18 @@ defmodule Jido.Shell.Command.CdTest do
 
     test "cwd_changed event is broadcast", %{workspace_id: workspace_id} do
       {:ok, session_id} = Session.start(workspace_id)
-      :ok = SessionServer.subscribe(session_id, self())
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
-      :ok = SessionServer.run_command(session_id, "cd /home/user")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "cd /home/user")
 
       assert_receive {:jido_shell_session, ^session_id, {:cwd_changed, "/home/user"}}
     end
 
     test "relative path resolved from current cwd", %{workspace_id: workspace_id} do
       {:ok, session_id} = Session.start(workspace_id, cwd: "/home")
-      :ok = SessionServer.subscribe(session_id, self())
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
-      :ok = SessionServer.run_command(session_id, "cd user")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "cd user")
 
       assert_receive {:jido_shell_session, ^session_id, :command_done}
       assert_receive {:jido_shell_session, ^session_id, {:cwd_changed, "/home/user"}}
@@ -140,9 +140,9 @@ defmodule Jido.Shell.Command.CdTest do
 
     test "error on cd to non-existent path", %{workspace_id: workspace_id} do
       {:ok, session_id} = Session.start(workspace_id)
-      :ok = SessionServer.subscribe(session_id, self())
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
-      :ok = SessionServer.run_command(session_id, "cd /nonexistent")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "cd /nonexistent")
 
       assert_receive {:jido_shell_session, ^session_id, {:error, %Jido.Shell.Error{code: {:vfs, :not_found}}}}
     end
diff --git a/test/jido/shell/command/cp_test.exs b/test/jido/shell/command/cp_test.exs
index 2e4be97..c526419 100644
--- a/test/jido/shell/command/cp_test.exs
+++ b/test/jido/shell/command/cp_test.exs
@@ -7,8 +7,8 @@ defmodule Jido.Shell.Command.CpTest do
 
   setup do
     VFS.init()
-    workspace_id = :"test_ws_#{System.unique_integer([:positive])}"
-    fs_name = :"test_fs_#{System.unique_integer([:positive])}"
+    workspace_id = "test_ws_#{System.unique_integer([:positive])}"
+    fs_name = "test_fs_#{System.unique_integer([:positive])}"
 
     start_supervised!(
       {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs_name}}}
diff --git a/test/jido/shell/command/echo_test.exs b/test/jido/shell/command/echo_test.exs
index dea6e71..dcad94b 100644
--- a/test/jido/shell/command/echo_test.exs
+++ b/test/jido/shell/command/echo_test.exs
@@ -5,7 +5,7 @@ defmodule Jido.Shell.Command.EchoTest do
   alias Jido.Shell.Session.State
 
   setup do
-    {:ok, state} = State.new(%{id: "test", workspace_id: :test})
+    {:ok, state} = State.new(%{id: "test", workspace_id: "test"})
     {:ok, state: state}
   end
 
diff --git a/test/jido/shell/command/env_test.exs b/test/jido/shell/command/env_test.exs
index 4e4f2a6..c8617cc 100644
--- a/test/jido/shell/command/env_test.exs
+++ b/test/jido/shell/command/env_test.exs
@@ -7,8 +7,8 @@ defmodule Jido.Shell.Command.EnvTest do
 
   setup do
     VFS.init()
-    workspace_id = :"test_ws_#{System.unique_integer([:positive])}"
-    fs_name = :"test_fs_#{System.unique_integer([:positive])}"
+    workspace_id = "test_ws_#{System.unique_integer([:positive])}"
+    fs_name = "test_fs_#{System.unique_integer([:positive])}"
 
     start_supervised!(
       {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs_name}}}
diff --git a/test/jido/shell/command/help_test.exs b/test/jido/shell/command/help_test.exs
index db50189..fb45eed 100644
--- a/test/jido/shell/command/help_test.exs
+++ b/test/jido/shell/command/help_test.exs
@@ -5,7 +5,7 @@ defmodule Jido.Shell.Command.HelpTest do
   alias Jido.Shell.Command.Help
 
   setup do
-    {:ok, state} = State.new(%{id: "test", workspace_id: :test})
+    {:ok, state} = State.new(%{id: "test", workspace_id: "test"})
     {:ok, state: state}
   end
 
diff --git a/test/jido/shell/command/ls_test.exs b/test/jido/shell/command/ls_test.exs
index 14749fb..3e73b92 100644
--- a/test/jido/shell/command/ls_test.exs
+++ b/test/jido/shell/command/ls_test.exs
@@ -7,8 +7,8 @@ defmodule Jido.Shell.Command.LsTest do
 
   setup do
     VFS.init()
-    workspace_id = :"test_ws_#{System.unique_integer([:positive])}"
-    fs_name = :"test_fs_#{System.unique_integer([:positive])}"
+    workspace_id = "test_ws_#{System.unique_integer([:positive])}"
+    fs_name = "test_fs_#{System.unique_integer([:positive])}"
 
     start_supervised!(
       {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs_name}}}
diff --git a/test/jido/shell/command/mkdir_test.exs b/test/jido/shell/command/mkdir_test.exs
index 576c66e..6587e7a 100644
--- a/test/jido/shell/command/mkdir_test.exs
+++ b/test/jido/shell/command/mkdir_test.exs
@@ -9,8 +9,8 @@ defmodule Jido.Shell.Command.MkdirTest do
 
   setup do
     VFS.init()
-    workspace_id = :"test_ws_#{System.unique_integer([:positive])}"
-    fs_name = :"test_fs_#{System.unique_integer([:positive])}"
+    workspace_id = "test_ws_#{System.unique_integer([:positive])}"
+    fs_name = "test_fs_#{System.unique_integer([:positive])}"
 
     start_supervised!(
       {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs_name}}}
@@ -101,9 +101,9 @@ defmodule Jido.Shell.Command.MkdirTest do
   describe "integration with session" do
     test "mkdir creates directories via session", %{workspace_id: workspace_id} do
       {:ok, session_id} = Session.start(workspace_id)
-      :ok = SessionServer.subscribe(session_id, self())
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
-      :ok = SessionServer.run_command(session_id, "mkdir /testdir")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "mkdir /testdir")
 
       assert_receive {:jido_shell_session, ^session_id, {:command_started, _}}
       assert_receive {:jido_shell_session, ^session_id, {:output, "created: /testdir\n"}}
diff --git a/test/jido/shell/command/parser_test.exs b/test/jido/shell/command/parser_test.exs
index 049b274..3fa448f 100644
--- a/test/jido/shell/command/parser_test.exs
+++ b/test/jido/shell/command/parser_test.exs
@@ -49,6 +49,14 @@ defmodule Jido.Shell.Command.ParserTest do
       assert {:ok, "echo", ["helloworld"]} = Parser.parse(~s(echo hello"world"))
     end
 
+    test "handles escaped spaces and separators" do
+      assert {:ok, "echo", ["hello world;still_one"]} = Parser.parse("echo hello\\ world\\;still_one")
+    end
+
+    test "handles escaped quotes inside double quotes" do
+      assert {:ok, "echo", ["he said \"hi\""]} = Parser.parse(~s(echo "he said \\"hi\\""))
+    end
+
     test "handles unicode characters" do
       assert {:ok, "echo", ["héllo", "wörld"]} = Parser.parse("echo héllo wörld")
     end
@@ -56,5 +64,46 @@ defmodule Jido.Shell.Command.ParserTest do
     test "handles quoted unicode" do
       assert {:ok, "echo", ["héllo wörld"]} = Parser.parse(~s(echo "héllo wörld"))
     end
+
+    test "rejects chained commands in parse/1" do
+      assert {:error, :chained_command} = Parser.parse("echo hi; pwd")
+    end
+  end
+
+  describe "parse_program/1" do
+    test "parses semicolon chaining" do
+      assert {:ok,
+              [
+                %{operator: :always, command: "echo", args: ["one"]},
+                %{operator: :always, command: "echo", args: ["two"]}
+              ]} = Parser.parse_program("echo one; echo two")
+    end
+
+    test "parses and-if chaining" do
+      assert {:ok,
+              [
+                %{operator: :always, command: "echo", args: ["one"]},
+                %{operator: :and_if, command: "echo", args: ["two"]}
+              ]} = Parser.parse_program("echo one && echo two")
+    end
+
+    test "preserves quoted separators" do
+      assert {:ok,
+              [
+                %{operator: :always, command: "echo", args: ["a;b&&c"]}
+              ]} = Parser.parse_program(~s(echo "a;b&&c"))
+    end
+
+    test "returns syntax error on trailing operator" do
+      assert {:error, :trailing_operator} = Parser.parse_program("echo hi &&")
+    end
+
+    test "returns syntax error on invalid operator position" do
+      assert {:error, :invalid_operator_position} = Parser.parse_program("&& echo hi")
+    end
+
+    test "returns unclosed quote error" do
+      assert {:error, :unclosed_quote} = Parser.parse_program(~s(echo "hello))
+    end
   end
 end
diff --git a/test/jido/shell/command/pwd_test.exs b/test/jido/shell/command/pwd_test.exs
index f2d0bd5..6029628 100644
--- a/test/jido/shell/command/pwd_test.exs
+++ b/test/jido/shell/command/pwd_test.exs
@@ -5,7 +5,7 @@ defmodule Jido.Shell.Command.PwdTest do
   alias Jido.Shell.Session.State
 
   setup do
-    {:ok, state} = State.new(%{id: "test", workspace_id: :test, cwd: "/home/user"})
+    {:ok, state} = State.new(%{id: "test", workspace_id: "test", cwd: "/home/user"})
     {:ok, state: state}
   end
 
@@ -39,7 +39,7 @@ defmodule Jido.Shell.Command.PwdTest do
     end
 
     test "emits root directory when cwd is root" do
-      {:ok, state} = State.new(%{id: "test", workspace_id: :test, cwd: "/"})
+      {:ok, state} = State.new(%{id: "test", workspace_id: "test", cwd: "/"})
       emit = fn event -> send(self(), {:emit, event}) end
 
       result = Pwd.run(state, %{args: []}, emit)
diff --git a/test/jido/shell/command/rm_test.exs b/test/jido/shell/command/rm_test.exs
index 02622f4..25b548c 100644
--- a/test/jido/shell/command/rm_test.exs
+++ b/test/jido/shell/command/rm_test.exs
@@ -7,8 +7,8 @@ defmodule Jido.Shell.Command.RmTest do
 
   setup do
     VFS.init()
-    workspace_id = :"test_ws_#{System.unique_integer([:positive])}"
-    fs_name = :"test_fs_#{System.unique_integer([:positive])}"
+    workspace_id = "test_ws_#{System.unique_integer([:positive])}"
+    fs_name = "test_fs_#{System.unique_integer([:positive])}"
 
     start_supervised!(
       {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs_name}}}
diff --git a/test/jido/shell/command/seq_test.exs b/test/jido/shell/command/seq_test.exs
index 7f52f02..5840e1c 100644
--- a/test/jido/shell/command/seq_test.exs
+++ b/test/jido/shell/command/seq_test.exs
@@ -5,7 +5,7 @@ defmodule Jido.Shell.Command.SeqTest do
   alias Jido.Shell.Command.Seq
 
   setup do
-    {:ok, state} = State.new(%{id: "test", workspace_id: :test})
+    {:ok, state} = State.new(%{id: "test", workspace_id: "test"})
     {:ok, state: state}
   end
 
@@ -54,6 +54,16 @@ defmodule Jido.Shell.Command.SeqTest do
 
       assert length(events) == 2
     end
+
+    test "returns validation error for invalid count", %{state: state} do
+      assert {:error, %Jido.Shell.Error{code: {:validation, :invalid_args}}} =
+               Seq.run(state, %{args: ["abc", "0"]}, fn _ -> :ok end)
+    end
+
+    test "returns validation error for invalid delay", %{state: state} do
+      assert {:error, %Jido.Shell.Error{code: {:validation, :invalid_args}}} =
+               Seq.run(state, %{args: ["2", "-1"]}, fn _ -> :ok end)
+    end
   end
 
   describe "metadata" do
diff --git a/test/jido/shell/command/sleep_test.exs b/test/jido/shell/command/sleep_test.exs
index 2a519d6..3a39fe3 100644
--- a/test/jido/shell/command/sleep_test.exs
+++ b/test/jido/shell/command/sleep_test.exs
@@ -5,7 +5,7 @@ defmodule Jido.Shell.Command.SleepTest do
   alias Jido.Shell.Command.Sleep
 
   setup do
-    {:ok, state} = State.new(%{id: "test", workspace_id: :test})
+    {:ok, state} = State.new(%{id: "test", workspace_id: "test"})
     {:ok, state: state}
   end
 
@@ -39,6 +39,16 @@ defmodule Jido.Shell.Command.SleepTest do
       result = Sleep.run(state, %{args: ["1"]}, fn _ -> :ok end)
       assert {:ok, nil} = result
     end
+
+    test "returns validation error for invalid numeric input", %{state: state} do
+      assert {:error, %Jido.Shell.Error{code: {:validation, :invalid_args}}} =
+               Sleep.run(state, %{args: ["not-a-number"]}, fn _ -> :ok end)
+    end
+
+    test "returns validation error for out-of-range seconds", %{state: state} do
+      assert {:error, %Jido.Shell.Error{code: {:validation, :invalid_args}}} =
+               Sleep.run(state, %{args: ["999999"]}, fn _ -> :ok end)
+    end
   end
 
   describe "metadata" do
diff --git a/test/jido/shell/command/write_test.exs b/test/jido/shell/command/write_test.exs
index 64c27b1..9fad0fd 100644
--- a/test/jido/shell/command/write_test.exs
+++ b/test/jido/shell/command/write_test.exs
@@ -9,8 +9,8 @@ defmodule Jido.Shell.Command.WriteTest do
 
   setup do
     VFS.init()
-    workspace_id = :"test_ws_#{System.unique_integer([:positive])}"
-    fs_name = :"test_fs_#{System.unique_integer([:positive])}"
+    workspace_id = "test_ws_#{System.unique_integer([:positive])}"
+    fs_name = "test_fs_#{System.unique_integer([:positive])}"
 
     start_supervised!(
       {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs_name}}}
@@ -110,9 +110,9 @@ defmodule Jido.Shell.Command.WriteTest do
   describe "integration with session" do
     test "write creates files via session", %{workspace_id: workspace_id} do
       {:ok, session_id} = Session.start(workspace_id)
-      :ok = SessionServer.subscribe(session_id, self())
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
-      :ok = SessionServer.run_command(session_id, "write /test.txt hello world")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "write /test.txt hello world")
 
       assert_receive {:jido_shell_session, ^session_id, {:command_started, _}}
       assert_receive {:jido_shell_session, ^session_id, {:output, _}}
diff --git a/test/jido/shell/command_runner_test.exs b/test/jido/shell/command_runner_test.exs
index 8a92c7e..bbaa5f1 100644
--- a/test/jido/shell/command_runner_test.exs
+++ b/test/jido/shell/command_runner_test.exs
@@ -5,7 +5,7 @@ defmodule Jido.Shell.CommandRunnerTest do
   alias Jido.Shell.Session.State
 
   setup do
-    {:ok, state} = State.new(%{id: "test-session", workspace_id: :test, cwd: "/home/user"})
+    {:ok, state} = State.new(%{id: "test-session", workspace_id: "test", cwd: "/home/user"})
     {:ok, state: state}
   end
 
@@ -43,7 +43,50 @@ defmodule Jido.Shell.CommandRunnerTest do
 
       result = CommandRunner.execute(state, "", emit)
 
-      assert {:error, :empty_command} = result
+      assert {:error, %Jido.Shell.Error{code: {:shell, :empty_command}}} = result
+    end
+
+    test "returns syntax errors for malformed command lines", %{state: state} do
+      emit = fn _event -> :ok end
+
+      result = CommandRunner.execute(state, ~s(echo "unterminated), emit)
+
+      assert {:error, %Jido.Shell.Error{code: {:shell, :syntax_error}}} = result
+    end
+
+    test "returns validation errors when argument schema parsing fails", %{state: state} do
+      emit = fn _event -> :ok end
+
+      result = CommandRunner.execute(state, "sleep 1 2", emit)
+
+      assert {:error, %Jido.Shell.Error{code: {:validation, :invalid_args}}} = result
+    end
+
+    test "supports semicolon chaining and continues after errors", %{state: state} do
+      emit = fn event -> send(self(), {:emit, event}) end
+
+      result = CommandRunner.execute(state, "unknown_cmd; echo recovered", emit)
+
+      assert {:ok, nil} = result
+      assert_receive {:emit, {:output, "recovered\n"}}
+    end
+
+    test "supports and-if chaining and short-circuits on error", %{state: state} do
+      emit = fn event -> send(self(), {:emit, event}) end
+
+      result = CommandRunner.execute(state, "unknown_cmd && echo skipped", emit)
+
+      assert {:error, %Jido.Shell.Error{code: {:shell, :unknown_command}}} = result
+      refute_receive {:emit, {:output, "skipped\n"}}
+    end
+
+    test "preserves state updates across chained commands", %{state: state} do
+      emit = fn event -> send(self(), {:emit, event}) end
+
+      result = CommandRunner.execute(state, "env FOO=bar && env FOO", emit)
+
+      assert {:ok, {:state_update, %{env: %{"FOO" => "bar"}}}} = result
+      assert_receive {:emit, {:output, "FOO=bar\n"}}
     end
   end
 
@@ -83,5 +126,67 @@ defmodule Jido.Shell.CommandRunnerTest do
 
       assert_receive {:command_finished, {:error, %Jido.Shell.Error{code: {:shell, :unknown_command}}}}, 1_000
     end
+
+    test "enforces runtime limits from execution context", %{state: state} do
+      session_pid = self()
+
+      spawn(fn ->
+        CommandRunner.run(
+          session_pid,
+          state,
+          "sleep 2",
+          execution_context: %{limits: %{max_runtime_ms: 100}}
+        )
+      end)
+
+      assert_receive {:command_finished, {:error, %Jido.Shell.Error{code: {:command, :runtime_limit_exceeded}}}}, 1_000
+    end
+
+    test "accepts runtime and output limits as positive strings", %{state: state} do
+      session_pid = self()
+
+      spawn(fn ->
+        CommandRunner.run(
+          session_pid,
+          state,
+          "echo ok",
+          execution_context: %{limits: %{"max_runtime_ms" => "1000", "max_output_bytes" => "1000"}}
+        )
+      end)
+
+      assert_receive {:command_event, {:output, "ok\n"}}, 1_000
+      assert_receive {:command_finished, {:ok, nil}}, 1_000
+    end
+
+    test "ignores invalid string limits and non-keyword execution contexts", %{state: state} do
+      session_pid = self()
+
+      spawn(fn ->
+        CommandRunner.run(
+          session_pid,
+          state,
+          "echo pass",
+          execution_context: [limits: [{"max_runtime_ms", "bad"}], max_output_bytes: "bad"]
+        )
+      end)
+
+      assert_receive {:command_event, {:output, "pass\n"}}, 1_000
+      assert_receive {:command_finished, {:ok, nil}}, 1_000
+    end
+
+    test "enforces output size limits from execution context", %{state: state} do
+      session_pid = self()
+
+      spawn(fn ->
+        CommandRunner.run(
+          session_pid,
+          state,
+          "seq 10 0",
+          execution_context: %{limits: %{max_output_bytes: 3}}
+        )
+      end)
+
+      assert_receive {:command_finished, {:error, %Jido.Shell.Error{code: {:command, :output_limit_exceeded}}}}, 1_000
+    end
   end
 end
diff --git a/test/jido/shell/identifier_migration_test.exs b/test/jido/shell/identifier_migration_test.exs
new file mode 100644
index 0000000..60803c2
--- /dev/null
+++ b/test/jido/shell/identifier_migration_test.exs
@@ -0,0 +1,32 @@
+defmodule Jido.Shell.IdentifierMigrationTest do
+  use Jido.Shell.Case, async: false
+
+  alias Jido.Shell.Agent
+  alias Jido.Shell.Session
+  alias Jido.Shell.SessionServer
+  alias Jido.Shell.VFS
+
+  test "accepts binary workspace identifiers across public APIs" do
+    workspace_id = "identifier_ws_#{System.unique_integer([:positive])}"
+
+    assert {:ok, session_id} = Session.start(workspace_id)
+    assert {:ok, _state} = SessionServer.get_state(session_id)
+    assert :ok = Session.stop(session_id)
+  end
+
+  test "rejects atom workspace identifiers with typed errors" do
+    assert {:error, %Jido.Shell.Error{code: {:session, :invalid_workspace_id}}} = Session.start(:legacy_workspace)
+    assert {:error, %Jido.Shell.Error{code: {:session, :invalid_workspace_id}}} = Agent.new(:legacy_workspace)
+
+    assert {:error, %Jido.Shell.Error{code: {:session, :invalid_workspace_id}}} =
+             VFS.mount(:legacy_workspace, "/", Jido.VFS.Adapter.InMemory, name: "legacy")
+  end
+
+  test "rejects non-binary session identifiers with typed errors" do
+    assert {:error, %Jido.Shell.Error{code: {:session, :invalid_session_id}}} =
+             SessionServer.get_state(:legacy_session_id)
+
+    assert {:error, %Jido.Shell.Error{code: {:session, :invalid_session_id}}} =
+             SessionServer.run_command(:legacy_session_id, "echo hi")
+  end
+end
diff --git a/test/jido/shell/sandbox/bash_test.exs b/test/jido/shell/sandbox/bash_test.exs
index 77b89ea..180b528 100644
--- a/test/jido/shell/sandbox/bash_test.exs
+++ b/test/jido/shell/sandbox/bash_test.exs
@@ -7,8 +7,8 @@ defmodule Jido.Shell.Sandbox.BashTest do
 
   setup do
     VFS.init()
-    workspace_id = :"sandbox_ws_#{System.unique_integer([:positive])}"
-    fs_name = :"sandbox_fs_#{System.unique_integer([:positive])}"
+    workspace_id = "sandbox_ws_#{System.unique_integer([:positive])}"
+    fs_name = "sandbox_fs_#{System.unique_integer([:positive])}"
 
     start_supervised!(
       {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs_name}}}
@@ -26,7 +26,7 @@ defmodule Jido.Shell.Sandbox.BashTest do
   end
 
   describe "statements/1" do
-    test "splits lines and semicolons and removes comments" do
+    test "splits lines and removes comments" do
       script = """
       # comment
       echo one; echo two
@@ -34,7 +34,12 @@ defmodule Jido.Shell.Sandbox.BashTest do
       pwd
       """
 
-      assert Bash.statements(script) == ["echo one", "echo two", "pwd"]
+      assert Bash.statements(script) == ["echo one; echo two", "pwd"]
+    end
+
+    test "preserves quoted semicolons in a statement" do
+      script = ~s(echo "a;b"; echo c)
+      assert Bash.statements(script) == [~s(echo "a;b"; echo c)]
     end
   end
 
diff --git a/test/jido/shell/sandbox/network_policy_test.exs b/test/jido/shell/sandbox/network_policy_test.exs
index c5bf2bf..9c80561 100644
--- a/test/jido/shell/sandbox/network_policy_test.exs
+++ b/test/jido/shell/sandbox/network_policy_test.exs
@@ -4,6 +4,10 @@ defmodule Jido.Shell.Sandbox.NetworkPolicyTest do
   alias Jido.Shell.Sandbox.NetworkPolicy
 
   describe "enforce/2" do
+    test "returns :ok for unparsable command lines" do
+      assert :ok = NetworkPolicy.enforce(~s(curl "unterminated), %{})
+    end
+
     test "blocks network commands by default" do
       assert {:error, %Jido.Shell.Error{code: {:shell, :network_blocked}, message: message}} =
                NetworkPolicy.enforce("curl https://example.com", %{})
@@ -43,6 +47,20 @@ defmodule Jido.Shell.Sandbox.NetworkPolicyTest do
       assert message =~ "blocklisted"
     end
 
+    test "supports port blocklist checks" do
+      context = %{
+        network: %{
+          allow_domains: ["example.com"],
+          block_ports: [443]
+        }
+      }
+
+      assert {:error, %Jido.Shell.Error{code: {:shell, :network_blocked}, message: message}} =
+               NetworkPolicy.enforce("curl https://example.com:443", context)
+
+      assert message =~ "port 443 is blocklisted"
+    end
+
     test "supports port allowlist checks" do
       context = %{
         network: %{
@@ -54,6 +72,108 @@ defmodule Jido.Shell.Sandbox.NetworkPolicyTest do
       assert :ok = NetworkPolicy.enforce("curl http://example.com:8080", context)
     end
 
+    test "extracts bare host targets for allowlist checks" do
+      assert :ok =
+               NetworkPolicy.enforce(
+                 "curl example.com/path",
+                 %{network: %{allow_domains: ["example.com"]}}
+               )
+    end
+
+    test "supports short port flags" do
+      context = %{
+        network: %{
+          allow_domains: ["example.com"],
+          allow_ports: [8443]
+        }
+      }
+
+      assert :ok = NetworkPolicy.enforce("curl -p 8443 example.com", context)
+    end
+
+    test "supports long port flags" do
+      context = %{
+        network: %{
+          allow_domains: ["example.com"],
+          allow_ports: [9443]
+        }
+      }
+
+      assert :ok = NetworkPolicy.enforce("curl --port=9443 example.com", context)
+    end
+
+    test "rejects commands when allow_domains are set but no target domain is found" do
+      assert {:error, %Jido.Shell.Error{code: {:shell, :network_blocked}, message: message}} =
+               NetworkPolicy.enforce(
+                 "curl --silent",
+                 %{network: %{allow_domains: ["example.com"]}}
+               )
+
+      assert message =~ "unable to determine target domain"
+    end
+
+    test "rejects commands when allow_ports are set but no target port is found" do
+      assert {:error, %Jido.Shell.Error{code: {:shell, :network_blocked}, message: message}} =
+               NetworkPolicy.enforce(
+                 "curl example.com",
+                 %{network: %{allow_ports: [443]}}
+               )
+
+      assert message =~ "unable to determine target port"
+    end
+
+    test "rejects domains with non-allowlisted ports" do
+      assert {:error, %Jido.Shell.Error{code: {:shell, :network_blocked}, message: message}} =
+               NetworkPolicy.enforce(
+                 "curl https://example.com:80",
+                 %{network: %{allow_domains: ["example.com"], allow_ports: [443]}}
+               )
+
+      assert message =~ "port 80 is not allowlisted"
+    end
+
+    test "supports bracketed host:port endpoints" do
+      assert :ok =
+               NetworkPolicy.enforce(
+                 "curl [2001:db8::1]:8080",
+                 %{network: %{allow_domains: ["2001:db8::1"], allow_ports: [8080]}}
+               )
+    end
+
+    test "accepts keyword-style execution contexts and string defaults" do
+      context = [
+        network: [
+          default: "allow"
+        ]
+      ]
+
+      assert :ok = NetworkPolicy.enforce("curl https://example.com", context)
+    end
+
+    test "ignores invalid configured ports" do
+      context = %{
+        network: %{
+          allow_domains: ["example.com"],
+          allow_ports: ["abc", -1, 999_999, 8443]
+        }
+      }
+
+      assert :ok = NetworkPolicy.enforce("curl --port=8443 example.com", context)
+    end
+
+    test "treats non-keyword list contexts as empty config" do
+      assert {:error, %Jido.Shell.Error{code: {:shell, :network_blocked}}} =
+               NetworkPolicy.enforce("curl https://example.com", [:invalid])
+    end
+
+    test "enforces policy across chained commands" do
+      assert {:error, %Jido.Shell.Error{code: {:shell, :network_blocked}}} =
+               NetworkPolicy.enforce(
+                 "echo safe; curl https://example.com",
+                 %{network: %{default: :deny}}
+               )
+    end
+
     test "ignores non-network commands" do
       assert :ok = NetworkPolicy.enforce("echo https://example.com", %{})
     end
diff --git a/test/jido/shell/session/state_test.exs b/test/jido/shell/session/state_test.exs
index f6e05f8..666858e 100644
--- a/test/jido/shell/session/state_test.exs
+++ b/test/jido/shell/session/state_test.exs
@@ -12,13 +12,13 @@ defmodule Jido.Shell.Session.StateTest do
 
   describe "new/1" do
     test "creates state with required fields" do
-      assert {:ok, state} = State.new(%{id: "sess-123", workspace_id: :my_workspace})
+      assert {:ok, state} = State.new(%{id: "sess-123", workspace_id: "my_workspace"})
       assert state.id == "sess-123"
-      assert state.workspace_id == :my_workspace
+      assert state.workspace_id == "my_workspace"
     end
 
     test "applies default values" do
-      {:ok, state} = State.new(%{id: "s", workspace_id: :w})
+      {:ok, state} = State.new(%{id: "s", workspace_id: "w"})
       assert state.cwd == "/"
       assert state.env == %{}
       assert state.history == []
@@ -31,7 +31,7 @@ defmodule Jido.Shell.Session.StateTest do
       {:ok, state} =
         State.new(%{
           id: "s",
-          workspace_id: :w,
+          workspace_id: "w",
           cwd: "/home/user",
           env: %{"PATH" => "/bin"},
           history: ["pwd"],
@@ -47,18 +47,18 @@ defmodule Jido.Shell.Session.StateTest do
     test "returns error for missing required fields" do
       assert {:error, _} = State.new(%{})
       assert {:error, _} = State.new(%{id: "s"})
-      assert {:error, _} = State.new(%{workspace_id: :w})
+      assert {:error, _} = State.new(%{workspace_id: "w"})
     end
 
     test "rejects invalid workspace_id type" do
-      assert {:error, errors} = State.new(%{id: "s", workspace_id: "not_an_atom"})
+      assert {:error, errors} = State.new(%{id: "s", workspace_id: :not_a_string})
       assert length(errors) > 0
     end
   end
 
   describe "new!/1" do
     test "creates state successfully" do
-      state = State.new!(%{id: "s", workspace_id: :w})
+      state = State.new!(%{id: "s", workspace_id: "w"})
       assert %State{} = state
     end
 
@@ -71,7 +71,7 @@ defmodule Jido.Shell.Session.StateTest do
 
   describe "add_transport/2" do
     test "adds a transport PID to the set" do
-      {:ok, state} = State.new(%{id: "s", workspace_id: :w})
+      {:ok, state} = State.new(%{id: "s", workspace_id: "w"})
       pid = self()
 
       state = State.add_transport(state, pid)
@@ -80,7 +80,7 @@ defmodule Jido.Shell.Session.StateTest do
     end
 
     test "can add multiple transports" do
-      {:ok, state} = State.new(%{id: "s", workspace_id: :w})
+      {:ok, state} = State.new(%{id: "s", workspace_id: "w"})
       pid1 = spawn(fn -> :ok end)
       pid2 = spawn(fn -> :ok end)
 
@@ -95,7 +95,7 @@ defmodule Jido.Shell.Session.StateTest do
 
   describe "remove_transport/2" do
     test "removes a transport PID from the set" do
-      {:ok, state} = State.new(%{id: "s", workspace_id: :w})
+      {:ok, state} = State.new(%{id: "s", workspace_id: "w"})
       pid = self()
 
       state =
@@ -107,7 +107,7 @@ defmodule Jido.Shell.Session.StateTest do
     end
 
     test "handles removing non-existent transport" do
-      {:ok, state} = State.new(%{id: "s", workspace_id: :w})
+      {:ok, state} = State.new(%{id: "s", workspace_id: "w"})
       pid = self()
 
       state = State.remove_transport(state, pid)
@@ -118,7 +118,7 @@ defmodule Jido.Shell.Session.StateTest do
 
   describe "add_to_history/2" do
     test "adds command to history" do
-      {:ok, state} = State.new(%{id: "s", workspace_id: :w})
+      {:ok, state} = State.new(%{id: "s", workspace_id: "w"})
 
       state = State.add_to_history(state, "ls -la")
 
@@ -126,7 +126,7 @@ defmodule Jido.Shell.Session.StateTest do
     end
 
     test "prepends to history (most recent first)" do
-      {:ok, state} = State.new(%{id: "s", workspace_id: :w})
+      {:ok, state} = State.new(%{id: "s", workspace_id: "w"})
 
       state =
         state
@@ -139,7 +139,7 @@ defmodule Jido.Shell.Session.StateTest do
 
   describe "set_cwd/2" do
     test "updates the current working directory" do
-      {:ok, state} = State.new(%{id: "s", workspace_id: :w})
+      {:ok, state} = State.new(%{id: "s", workspace_id: "w"})
 
       state = State.set_cwd(state, "/home/user/projects")
 
@@ -149,7 +149,7 @@ defmodule Jido.Shell.Session.StateTest do
 
   describe "set_current_command/2" do
     test "sets the current command" do
-      {:ok, state} = State.new(%{id: "s", workspace_id: :w})
+      {:ok, state} = State.new(%{id: "s", workspace_id: "w"})
       cmd_info = %{line: "ls", task: self(), ref: make_ref()}
 
       state = State.set_current_command(state, cmd_info)
@@ -158,7 +158,7 @@ defmodule Jido.Shell.Session.StateTest do
     end
 
     test "can set to nil" do
-      {:ok, state} = State.new(%{id: "s", workspace_id: :w})
+      {:ok, state} = State.new(%{id: "s", workspace_id: "w"})
 
       state =
         state
@@ -171,7 +171,7 @@ defmodule Jido.Shell.Session.StateTest do
 
   describe "clear_current_command/1" do
     test "clears the current command" do
-      {:ok, state} = State.new(%{id: "s", workspace_id: :w})
+      {:ok, state} = State.new(%{id: "s", workspace_id: "w"})
 
       state =
         state
@@ -184,12 +184,12 @@ defmodule Jido.Shell.Session.StateTest do
 
   describe "command_running?/1" do
     test "returns false when no command is running" do
-      {:ok, state} = State.new(%{id: "s", workspace_id: :w})
+      {:ok, state} = State.new(%{id: "s", workspace_id: "w"})
       refute State.command_running?(state)
     end
 
     test "returns true when a command is running" do
-      {:ok, state} = State.new(%{id: "s", workspace_id: :w})
+      {:ok, state} = State.new(%{id: "s", workspace_id: "w"})
       state = State.set_current_command(state, %{line: "ls"})
       assert State.command_running?(state)
     end
@@ -197,12 +197,12 @@ defmodule Jido.Shell.Session.StateTest do
 
   describe "struct" do
     test "can be pattern matched" do
-      {:ok, state} = State.new(%{id: "s", workspace_id: :w})
-      assert %State{id: "s", workspace_id: :w} = state
+      {:ok, state} = State.new(%{id: "s", workspace_id: "w"})
+      assert %State{id: "s", workspace_id: "w"} = state
     end
 
     test "has the expected struct name" do
-      {:ok, state} = State.new(%{id: "s", workspace_id: :w})
+      {:ok, state} = State.new(%{id: "s", workspace_id: "w"})
       assert state.__struct__ == Jido.Shell.Session.State
     end
   end
diff --git a/test/jido/shell/session_server_test.exs b/test/jido/shell/session_server_test.exs
index 6f4e0fe..1ba2a2b 100644
--- a/test/jido/shell/session_server_test.exs
+++ b/test/jido/shell/session_server_test.exs
@@ -7,13 +7,13 @@ defmodule Jido.Shell.SessionServerTest do
   describe "start_link/1" do
     test "starts a session server" do
       session_id = Session.generate_id()
-      {:ok, pid} = SessionServer.start_link(session_id: session_id, workspace_id: :test)
+      {:ok, pid} = SessionServer.start_link(session_id: session_id, workspace_id: "test")
       assert Process.alive?(pid)
     end
 
     test "registers with SessionRegistry" do
       session_id = Session.generate_id()
-      {:ok, _pid} = SessionServer.start_link(session_id: session_id, workspace_id: :test)
+      {:ok, _pid} = SessionServer.start_link(session_id: session_id, workspace_id: "test")
       assert {:ok, _pid} = Session.lookup(session_id)
     end
   end
@@ -21,12 +21,12 @@ defmodule Jido.Shell.SessionServerTest do
   describe "get_state/1" do
     test "returns the session state" do
       session_id = Session.generate_id()
-      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: :test_ws)
+      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: "test_ws")
 
       {:ok, state} = SessionServer.get_state(session_id)
 
       assert state.id == session_id
-      assert state.workspace_id == :test_ws
+      assert state.workspace_id == "test_ws"
       assert state.cwd == "/"
     end
 
@@ -36,7 +36,7 @@ defmodule Jido.Shell.SessionServerTest do
       {:ok, _} =
         SessionServer.start_link(
           session_id: session_id,
-          workspace_id: :test,
+          workspace_id: "test",
           cwd: "/home/user",
           env: %{"FOO" => "bar"}
         )
@@ -51,9 +51,9 @@ defmodule Jido.Shell.SessionServerTest do
   describe "subscribe/3 and unsubscribe/2" do
     test "subscribes transport to events" do
       session_id = Session.generate_id()
-      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: :test)
+      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: "test")
 
-      :ok = SessionServer.subscribe(session_id, self())
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
       {:ok, state} = SessionServer.get_state(session_id)
       assert MapSet.member?(state.transports, self())
@@ -61,10 +61,10 @@ defmodule Jido.Shell.SessionServerTest do
 
     test "unsubscribes transport" do
       session_id = Session.generate_id()
-      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: :test)
+      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: "test")
 
-      :ok = SessionServer.subscribe(session_id, self())
-      :ok = SessionServer.unsubscribe(session_id, self())
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
+      {:ok, :unsubscribed} = SessionServer.unsubscribe(session_id, self())
 
       {:ok, state} = SessionServer.get_state(session_id)
       refute MapSet.member?(state.transports, self())
@@ -72,7 +72,7 @@ defmodule Jido.Shell.SessionServerTest do
 
     test "removes transport when it crashes" do
       session_id = Session.generate_id()
-      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: :test)
+      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: "test")
 
       transport =
         spawn(fn ->
@@ -81,7 +81,7 @@ defmodule Jido.Shell.SessionServerTest do
           end
         end)
 
-      :ok = SessionServer.subscribe(session_id, transport)
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, transport)
 
       {:ok, state} = SessionServer.get_state(session_id)
       assert MapSet.member?(state.transports, transport)
@@ -97,10 +97,10 @@ defmodule Jido.Shell.SessionServerTest do
   describe "run_command/3" do
     test "adds command to history and broadcasts events" do
       session_id = Session.generate_id()
-      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: :test)
-      :ok = SessionServer.subscribe(session_id, self())
+      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: "test")
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
-      :ok = SessionServer.run_command(session_id, "echo hello")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "echo hello")
 
       assert_receive {:jido_shell_session, ^session_id, {:command_started, "echo hello"}}
       assert_receive {:jido_shell_session, ^session_id, {:output, "hello\n"}}
@@ -112,10 +112,10 @@ defmodule Jido.Shell.SessionServerTest do
 
     test "broadcasts error for unknown command" do
       session_id = Session.generate_id()
-      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: :test)
-      :ok = SessionServer.subscribe(session_id, self())
+      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: "test")
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
-      :ok = SessionServer.run_command(session_id, "unknown_cmd")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "unknown_cmd")
 
       assert_receive {:jido_shell_session, ^session_id, {:command_started, "unknown_cmd"}}
       assert_receive {:jido_shell_session, ^session_id, {:error, %Jido.Shell.Error{code: {:shell, :unknown_command}}}}
@@ -123,26 +123,26 @@ defmodule Jido.Shell.SessionServerTest do
 
     test "broadcasts busy error when command already running" do
       session_id = Session.generate_id()
-      {:ok, server_pid} = SessionServer.start_link(session_id: session_id, workspace_id: :test)
-      :ok = SessionServer.subscribe(session_id, self())
+      {:ok, _server_pid} = SessionServer.start_link(session_id: session_id, workspace_id: "test")
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
-      :sys.suspend(server_pid)
+      {:ok, :accepted} = SessionServer.run_command(session_id, "sleep 5")
+      assert_receive {:jido_shell_session, ^session_id, {:command_started, "sleep 5"}}
 
-      :ok = SessionServer.run_command(session_id, "echo first")
-      :ok = SessionServer.run_command(session_id, "echo second")
+      assert {:error, %Jido.Shell.Error{code: {:shell, :busy}}} =
+               SessionServer.run_command(session_id, "echo second")
 
-      :sys.resume(server_pid)
-
-      assert_receive {:jido_shell_session, ^session_id, {:command_started, "echo first"}}
       assert_receive {:jido_shell_session, ^session_id, {:error, %Jido.Shell.Error{code: {:shell, :busy}}}}
+
+      {:ok, :cancelled} = SessionServer.cancel(session_id)
     end
 
     test "executes pwd command with session cwd" do
       session_id = Session.generate_id()
-      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: :test, cwd: "/home/user")
-      :ok = SessionServer.subscribe(session_id, self())
+      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: "test", cwd: "/home/user")
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
-      :ok = SessionServer.run_command(session_id, "pwd")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "pwd")
 
       assert_receive {:jido_shell_session, ^session_id, {:command_started, "pwd"}}
       assert_receive {:jido_shell_session, ^session_id, {:output, "/home/user\n"}}
@@ -151,15 +151,106 @@ defmodule Jido.Shell.SessionServerTest do
 
     test "clears current_command after completion" do
       session_id = Session.generate_id()
-      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: :test)
-      :ok = SessionServer.subscribe(session_id, self())
+      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: "test")
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
-      :ok = SessionServer.run_command(session_id, "echo test")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "echo test")
 
       assert_receive {:jido_shell_session, ^session_id, :command_done}
 
       {:ok, state} = SessionServer.get_state(session_id)
       assert state.current_command == nil
     end
+
+    test "handles cast-based command execution and cancellation paths" do
+      session_id = Session.generate_id()
+      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: "test")
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
+      {:ok, server_pid} = Session.lookup(session_id)
+
+      GenServer.cast(server_pid, {:run_command, "echo cast", []})
+      assert_receive {:jido_shell_session, ^session_id, {:command_started, "echo cast"}}
+      assert_receive {:jido_shell_session, ^session_id, {:output, "cast\n"}}
+      assert_receive {:jido_shell_session, ^session_id, :command_done}
+
+      # Idle cancel cast should be a no-op with explicit invalid transition handling internally.
+      GenServer.cast(server_pid, :cancel)
+      {:ok, state} = SessionServer.get_state(session_id)
+      assert state.current_command == nil
+    end
+
+    test "broadcasts command_crashed when monitored command exits unexpectedly" do
+      session_id = Session.generate_id()
+      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: "test")
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
+      {:ok, server_pid} = Session.lookup(session_id)
+
+      {:ok, :accepted} = SessionServer.run_command(session_id, "sleep 1")
+      assert_receive {:jido_shell_session, ^session_id, {:command_started, "sleep 1"}}
+      {:ok, state} = SessionServer.get_state(session_id)
+      assert %{ref: ref, task: task_pid} = state.current_command
+
+      send(server_pid, {:DOWN, ref, :process, task_pid, :boom})
+      assert_receive {:jido_shell_session, ^session_id, {:command_crashed, :boom}}
+    end
+
+    test "ignores late command events and late finished messages after cancellation" do
+      session_id = Session.generate_id()
+      {:ok, _} = SessionServer.start_link(session_id: session_id, workspace_id: "test")
+      {:ok, server_pid} = Session.lookup(session_id)
+
+      send(server_pid, {:command_event, {:output, "late"}})
+      send(server_pid, {:command_finished, {:ok, nil}})
+
+      {:ok, state} = SessionServer.get_state(session_id)
+      assert state.current_command == nil
+    end
+  end
+
+  describe "missing session handling" do
+    test "returns typed errors instead of exiting for missing sessions" do
+      missing = "missing-session"
+
+      assert {:error, %Jido.Shell.Error{code: {:session, :not_found}}} =
+               SessionServer.subscribe(missing, self())
+
+      assert {:error, %Jido.Shell.Error{code: {:session, :not_found}}} =
+               SessionServer.unsubscribe(missing, self())
+
+      assert {:error, %Jido.Shell.Error{code: {:session, :not_found}}} =
+               SessionServer.get_state(missing)
+
+      assert {:error, %Jido.Shell.Error{code: {:session, :not_found}}} =
+               SessionServer.run_command(missing, "echo hi")
+
+      assert {:error, %Jido.Shell.Error{code: {:session, :not_found}}} =
+               SessionServer.cancel(missing)
+    end
+
+    test "returns invalid session ID errors for malformed identifiers" do
+      assert {:error, %Jido.Shell.Error{code: {:session, :invalid_session_id}}} =
+               SessionServer.get_state(nil)
+    end
+
+    test "handles registry entries that are not live session servers" do
+      session_id = "fake-#{System.unique_integer([:positive])}"
+      parent = self()
+
+      pid =
+        spawn(fn ->
+          {:ok, _} = Registry.register(Jido.Shell.SessionRegistry, session_id, nil)
+          send(parent, :registered)
+
+          receive do
+            {:"$gen_call", _from, _msg} -> exit(:not_a_server)
+          end
+        end)
+
+      assert_receive :registered
+      assert Process.alive?(pid)
+
+      assert {:error, %Jido.Shell.Error{code: {:session, :not_found}}} =
+               SessionServer.get_state(session_id)
+    end
   end
 end
diff --git a/test/jido/shell/session_test.exs b/test/jido/shell/session_test.exs
index d54a674..603f60e 100644
--- a/test/jido/shell/session_test.exs
+++ b/test/jido/shell/session_test.exs
@@ -69,7 +69,7 @@ defmodule Jido.Shell.SessionTest do
 
   describe "start/2" do
     test "starts a session for a workspace" do
-      {:ok, session_id} = Session.start(:test_workspace)
+      {:ok, session_id} = Session.start("test_workspace")
       assert String.starts_with?(session_id, "sess-")
 
       assert {:ok, pid} = Session.lookup(session_id)
@@ -78,21 +78,41 @@ defmodule Jido.Shell.SessionTest do
 
     test "accepts custom session_id" do
       custom_id = "sess-custom-123"
-      {:ok, ^custom_id} = Session.start(:test, session_id: custom_id)
+      {:ok, ^custom_id} = Session.start("test", session_id: custom_id)
       assert {:ok, _} = Session.lookup(custom_id)
     end
 
     test "passes options to SessionServer" do
-      {:ok, session_id} = Session.start(:test, cwd: "/home", env: %{"X" => "1"})
+      {:ok, session_id} = Session.start("test", cwd: "/home", env: %{"X" => "1"})
       {:ok, state} = Jido.Shell.SessionServer.get_state(session_id)
       assert state.cwd == "/home"
       assert state.env == %{"X" => "1"}
     end
+
+    test "rejects invalid workspace_id types" do
+      assert {:error, %Jido.Shell.Error{code: {:session, :invalid_workspace_id}}} =
+               Session.start(:test_workspace)
+    end
+
+    test "rejects empty workspace identifiers" do
+      assert {:error, %Jido.Shell.Error{code: {:session, :invalid_workspace_id}}} =
+               Session.start("   ")
+    end
+
+    test "returns supervisor child-start errors for duplicate session IDs" do
+      session_id = "sess-duplicate-#{System.unique_integer([:positive])}"
+      assert {:ok, ^session_id} = Session.start("dup_ws", session_id: session_id)
+      assert {:error, _} = Session.start("dup_ws", session_id: session_id)
+
+      on_exit(fn ->
+        _ = Session.stop(session_id)
+      end)
+    end
   end
 
   describe "stop/1" do
     test "stops a running session" do
-      {:ok, session_id} = Session.start(:test)
+      {:ok, session_id} = Session.start("test")
       assert {:ok, pid} = Session.lookup(session_id)
       ref = Process.monitor(pid)
 
@@ -121,7 +141,7 @@ defmodule Jido.Shell.SessionTest do
     end
 
     test "starts a session with VFS auto-mounted" do
-      workspace_id = :"test_ws_vfs_#{System.unique_integer([:positive])}"
+      workspace_id = "test_ws_vfs_#{System.unique_integer([:positive])}"
 
       {:ok, session_id} = Session.start_with_vfs(workspace_id)
 
@@ -138,8 +158,8 @@ defmodule Jido.Shell.SessionTest do
     end
 
     test "does not re-mount if VFS already mounted" do
-      workspace_id = :"test_ws_vfs_exists_#{System.unique_integer([:positive])}"
-      fs_name = :"test_fs_#{System.unique_integer([:positive])}"
+      workspace_id = "test_ws_vfs_exists_#{System.unique_integer([:positive])}"
+      fs_name = "test_fs_#{System.unique_integer([:positive])}"
 
       start_supervised!(
         {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs_name}}}
@@ -157,5 +177,36 @@ defmodule Jido.Shell.SessionTest do
         Jido.Shell.VFS.unmount(workspace_id, "/")
       end)
     end
+
+    test "merges managed mount metadata with existing session metadata" do
+      workspace_id = "test_ws_meta_#{System.unique_integer([:positive])}"
+      {:ok, session_id} = Session.start_with_vfs(workspace_id, meta: %{actor: "test"})
+
+      {:ok, state} = Jido.Shell.SessionServer.get_state(session_id)
+      assert state.meta.actor == "test"
+      assert state.meta.managed_workspace_mount == true
+
+      on_exit(fn ->
+        _ = Session.stop(session_id)
+        _ = Session.teardown_workspace(workspace_id)
+      end)
+    end
+  end
+
+  describe "teardown_workspace/2" do
+    test "unmounts managed workspace resources" do
+      workspace_id = "teardown_ws_#{System.unique_integer([:positive])}"
+      fs_name = "teardown_fs_#{System.unique_integer([:positive])}"
+
+      :ok =
+        Jido.Shell.VFS.mount(workspace_id, "/data", Jido.VFS.Adapter.InMemory,
+          name: fs_name,
+          managed: true
+        )
+
+      assert length(Jido.Shell.VFS.list_mounts(workspace_id)) == 1
+      assert :ok = Session.teardown_workspace(workspace_id, managed_only: true)
+      assert [] = Jido.Shell.VFS.list_mounts(workspace_id)
+    end
   end
 end
diff --git a/test/jido/shell/transport/iex_test.exs b/test/jido/shell/transport/iex_test.exs
index b60bfd3..ca74ac0 100644
--- a/test/jido/shell/transport/iex_test.exs
+++ b/test/jido/shell/transport/iex_test.exs
@@ -1,28 +1,221 @@
 defmodule Jido.Shell.Transport.IExTest do
   use Jido.Shell.Case, async: false
 
-  alias Jido.Shell.Transport.IEx
+  import ExUnit.CaptureIO
+
+  alias Jido.Shell.Error
   alias Jido.Shell.Session
+  alias Jido.Shell.Transport.IEx
   alias Jido.Shell.SessionServer
 
+  defp start_session!() do
+    workspace_id = "test_ws_#{System.unique_integer([:positive])}"
+    {:ok, session_id} = Session.start_with_vfs(workspace_id)
+
+    on_exit(fn ->
+      _ = Session.stop(session_id)
+      _ = Session.teardown_workspace(workspace_id)
+    end)
+
+    {workspace_id, session_id}
+  end
+
   describe "attach/1" do
     test "returns error for non-existent session" do
       assert {:error, :not_found} = IEx.attach("nonexistent-session")
     end
+
+    test "attaches and exits cleanly" do
+      {_workspace_id, session_id} = start_session!()
+
+      output =
+        capture_io("exit\n", fn ->
+          assert :ok = IEx.attach(session_id)
+        end)
+
+      assert output =~ "Attached to session"
+      assert output =~ "Goodbye!"
+    end
   end
 
   describe "event handling" do
     test "receives events from session" do
-      workspace_id = :"test_ws_#{System.unique_integer([:positive])}"
-      {:ok, session_id} = Session.start_with_vfs(workspace_id)
-      :ok = SessionServer.subscribe(session_id, self())
+      {_workspace_id, session_id} = start_session!()
+      {:ok, :subscribed} = SessionServer.subscribe(session_id, self())
 
-      :ok = SessionServer.run_command(session_id, "echo hello")
+      {:ok, :accepted} = SessionServer.run_command(session_id, "echo hello")
 
       assert_receive {:jido_shell_session, ^session_id, {:command_started, "echo hello"}}
       assert_receive {:jido_shell_session, ^session_id, {:output, "hello\n"}}
       assert_receive {:jido_shell_session, ^session_id, :command_done}
     end
+
+    test "starts with an existing session and handles empty input" do
+      {workspace_id, session_id} = start_session!()
+
+      output =
+        capture_io("\nquit\n", fn ->
+          assert :ok = IEx.start(workspace_id, session_id: session_id)
+        end)
+
+      assert output =~ "Jido.Shell v"
+      assert output =~ "Goodbye!"
+    end
+
+    test "returns explicit error when start_with_vfs fails for workspace" do
+      assert {:error, %Error{code: {:session, :invalid_workspace_id}}} = IEx.start("")
+    end
+
+    test "handles EOF input" do
+      {workspace_id, session_id} = start_session!()
+
+      output =
+        capture_io(fn ->
+          assert :ok = IEx.start(workspace_id, session_id: session_id, line_reader: fn _ -> :eof end)
+        end)
+
+      assert output =~ "Goodbye!"
+    end
+
+    test "handles input read errors" do
+      {_workspace_id, session_id} = start_session!()
+
+      output =
+        capture_io(fn ->
+          assert :ok = IEx.attach(session_id, line_reader: fn _ -> {:error, :io_failure} end)
+        end)
+
+      assert output =~ "Input error, exiting."
+    end
+
+    test "prints output and cwd changes while running commands" do
+      {workspace_id, session_id} = start_session!()
+
+      output =
+        capture_io("echo hello\nmkdir /tmp\ncd /tmp\npwd\nexit\n", fn ->
+          assert :ok = IEx.start(workspace_id, session_id: session_id)
+        end)
+
+      assert output =~ "hello"
+      assert output =~ "/tmp"
+    end
+
+    test "prints command errors from session events" do
+      {workspace_id, session_id} = start_session!()
+
+      output =
+        capture_io("unknown_cmd\nexit\n", fn ->
+          assert :ok = IEx.start(workspace_id, session_id: session_id)
+        end)
+
+      assert output =~ "Error:"
+      assert output =~ "unknown_command"
+    end
+
+    test "prints synthetic cancelled event" do
+      {workspace_id, session_id} = start_session!()
+      parent = self()
+
+      spawn(fn ->
+        Process.sleep(25)
+        send(parent, {:jido_shell_session, session_id, :command_cancelled})
+      end)
+
+      output =
+        capture_io("sleep 1\nexit\n", fn ->
+          assert :ok = IEx.start(workspace_id, session_id: session_id)
+        end)
+
+      assert output =~ "Cancelled"
+    end
+
+    test "prints synthetic command crash events" do
+      {workspace_id, session_id} = start_session!()
+      parent = self()
+
+      spawn(fn ->
+        Process.sleep(25)
+        send(parent, {:jido_shell_session, session_id, {:command_crashed, :boom}})
+      end)
+
+      output =
+        capture_io("sleep 1\nexit\n", fn ->
+          assert :ok = IEx.start(workspace_id, session_id: session_id)
+        end)
+
+      assert output =~ "Command crashed: :boom"
+    end
+
+    test "prints generic non-struct errors" do
+      {workspace_id, session_id} = start_session!()
+      parent = self()
+
+      spawn(fn ->
+        Process.sleep(25)
+        send(parent, {:jido_shell_session, session_id, {:error, :oops}})
+      end)
+
+      output =
+        capture_io("sleep 1\nexit\n", fn ->
+          assert :ok = IEx.start(workspace_id, session_id: session_id)
+        end)
+
+      assert output =~ "Error: :oops"
+    end
+
+    test "prints timeout when no completion event arrives in configured window" do
+      {workspace_id, session_id} = start_session!()
+
+      output =
+        capture_io("sleep 1\nexit\n", fn ->
+          assert :ok =
+                   IEx.start(workspace_id,
+                     session_id: session_id,
+                     wait_timeout_ms: 10
+                   )
+        end)
+
+      assert output =~ "Timeout waiting for command"
+    end
+
+    test "falls back to default timeout for invalid timeout options" do
+      {workspace_id, session_id} = start_session!()
+
+      output =
+        capture_io(fn ->
+          assert :ok =
+                   IEx.start(workspace_id,
+                     session_id: session_id,
+                     wait_timeout_ms: :invalid,
+                     line_reader: fn _ -> "exit\n" end
+                   )
+        end)
+
+      assert output =~ "Goodbye!"
+    end
+
+    test "prints errors when command submission fails during loop" do
+      {workspace_id, session_id} = start_session!()
+
+      reader = fn _prompt ->
+        case Process.get(:iex_step, 0) do
+          0 ->
+            Process.put(:iex_step, 1)
+            :ok = Session.stop(session_id)
+            "echo hi\n"
+
+          _ ->
+            "exit\n"
+        end
+      end
+
+      output =
+        capture_io(fn ->
+          assert :ok = IEx.start(workspace_id, session_id: session_id, line_reader: reader)
+        end)
+
+      assert output =~ "Error:"
+    end
   end
 
   describe "help command integration" do
diff --git a/test/jido/shell/transport/term_ui_test.exs b/test/jido/shell/transport/term_ui_test.exs
deleted file mode 100644
index a509987..0000000
--- a/test/jido/shell/transport/term_ui_test.exs
+++ /dev/null
@@ -1,38 +0,0 @@
-defmodule Jido.Shell.Transport.TermUITest do
-  use Jido.Shell.Case, async: false
-
-  alias Jido.Shell.Transport.TermUI
-
-  describe "attach/1" do
-    test "returns error for non-existent session" do
-      assert {:error, :not_found} = TermUI.attach("nonexistent-session")
-    end
-  end
-
-  describe "model structure" do
-    test "has expected fields" do
-      model = %{
-        session_id: "test",
-        workspace_id: :test,
-        cwd: "/",
-        output_buffer: [],
-        input: "",
-        history: [],
-        history_index: 0,
-        command_running: false,
-        scroll_offset: 0
-      }
-
-      assert model.cwd == "/"
-      assert model.output_buffer == []
-      assert model.command_running == false
-    end
-  end
-
-  describe "integration" do
-    @tag :manual
-    test "can be started with mix kodo --ui" do
-      :ok
-    end
-  end
-end
diff --git a/test/jido/shell/vfs/mount_table_test.exs b/test/jido/shell/vfs/mount_table_test.exs
index e8dbfd6..00b6abc 100644
--- a/test/jido/shell/vfs/mount_table_test.exs
+++ b/test/jido/shell/vfs/mount_table_test.exs
@@ -3,10 +3,15 @@ defmodule Jido.Shell.VFS.MountTableTest do
 
   alias Jido.Shell.VFS.MountTable
 
+  defmodule BrokenProcessAdapter do
+    def starts_processes, do: true
+    def configure(opts), do: {__MODULE__, %{name: Keyword.get(opts, :name, "broken")}}
+  end
+
   setup do
     Jido.Shell.VFS.init()
-    workspace_id = :"test_ws_#{System.unique_integer([:positive])}"
-    fs_name = :"test_fs_#{System.unique_integer([:positive])}"
+    workspace_id = "test_ws_#{System.unique_integer([:positive])}"
+    fs_name = "test_fs_#{System.unique_integer([:positive])}"
 
     {:ok, workspace_id: workspace_id, fs_name: fs_name}
   end
@@ -14,7 +19,7 @@ defmodule Jido.Shell.VFS.MountTableTest do
   describe "init/0" do
     test "creates the ETS table" do
       assert :ok = MountTable.init()
-      assert :ets.whereis(:kodo_vfs_mounts) != :undefined
+      assert :ets.whereis(:jido_shell_vfs_mounts) != :undefined
     end
 
     test "is idempotent" do
@@ -36,8 +41,8 @@ defmodule Jido.Shell.VFS.MountTableTest do
     end
 
     test "mounts multiple filesystems at different paths", %{workspace_id: workspace_id} do
-      fs1 = :"fs1_#{System.unique_integer([:positive])}"
-      fs2 = :"fs2_#{System.unique_integer([:positive])}"
+      fs1 = "fs1_#{System.unique_integer([:positive])}"
+      fs2 = "fs2_#{System.unique_integer([:positive])}"
 
       start_supervised!(
         {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs1}}},
@@ -55,6 +60,21 @@ defmodule Jido.Shell.VFS.MountTableTest do
       mounts = MountTable.list(workspace_id)
       assert length(mounts) == 2
     end
+
+    test "rejects duplicate mount paths", %{workspace_id: workspace_id} do
+      fs1 = "dup_fs_#{System.unique_integer([:positive])}"
+      fs2 = "dup_fs_#{System.unique_integer([:positive])}"
+
+      assert :ok = MountTable.mount(workspace_id, "/data", Jido.VFS.Adapter.InMemory, name: fs1)
+
+      assert {:error, :path_already_mounted} =
+               MountTable.mount(workspace_id, "/data", Jido.VFS.Adapter.InMemory, name: fs2)
+    end
+
+    test "returns error when filesystem process startup fails", %{workspace_id: workspace_id} do
+      assert {:error, _reason} =
+               MountTable.mount(workspace_id, "/broken", BrokenProcessAdapter, name: "broken")
+    end
   end
 
   describe "unmount/2" do
@@ -72,6 +92,37 @@ defmodule Jido.Shell.VFS.MountTableTest do
     test "returns error for non-existent mount", %{workspace_id: workspace_id} do
       assert {:error, :not_found} = MountTable.unmount(workspace_id, "/nonexistent")
     end
+
+    test "terminates owned adapter processes on unmount", %{workspace_id: workspace_id} do
+      fs_name = "owned_fs_#{System.unique_integer([:positive])}"
+
+      assert :ok = MountTable.mount(workspace_id, "/owned", Jido.VFS.Adapter.InMemory, name: fs_name)
+      pid = GenServer.whereis(Jido.VFS.Registry.via(Jido.VFS.Adapter.InMemory, fs_name))
+      assert is_pid(pid)
+      ref = Process.monitor(pid)
+
+      assert :ok = MountTable.unmount(workspace_id, "/owned")
+      assert_receive {:DOWN, ^ref, :process, ^pid, _reason}
+    end
+  end
+
+  describe "unmount_workspace/2" do
+    test "can unmount only managed mounts", %{workspace_id: workspace_id} do
+      managed_fs = "managed_fs_#{System.unique_integer([:positive])}"
+      keep_fs = "keep_fs_#{System.unique_integer([:positive])}"
+
+      assert :ok =
+               MountTable.mount(workspace_id, "/managed", Jido.VFS.Adapter.InMemory,
+                 name: managed_fs,
+                 managed: true
+               )
+
+      assert :ok = MountTable.mount(workspace_id, "/keep", Jido.VFS.Adapter.InMemory, name: keep_fs)
+
+      assert :ok = MountTable.unmount_workspace(workspace_id, managed_only: true)
+
+      assert [%{path: "/keep"}] = MountTable.list(workspace_id)
+    end
   end
 
   describe "list/1" do
@@ -80,9 +131,9 @@ defmodule Jido.Shell.VFS.MountTableTest do
     end
 
     test "returns mounts sorted by path length (longest first)", %{workspace_id: workspace_id} do
-      fs1 = :"fs1_#{System.unique_integer([:positive])}"
-      fs2 = :"fs2_#{System.unique_integer([:positive])}"
-      fs3 = :"fs3_#{System.unique_integer([:positive])}"
+      fs1 = "fs1_#{System.unique_integer([:positive])}"
+      fs2 = "fs2_#{System.unique_integer([:positive])}"
+      fs3 = "fs3_#{System.unique_integer([:positive])}"
 
       start_supervised!(
         {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs1}}},
@@ -127,8 +178,8 @@ defmodule Jido.Shell.VFS.MountTableTest do
     end
 
     test "resolves path to nested mount", %{workspace_id: workspace_id} do
-      fs1 = :"fs1_#{System.unique_integer([:positive])}"
-      fs2 = :"fs2_#{System.unique_integer([:positive])}"
+      fs1 = "fs1_#{System.unique_integer([:positive])}"
+      fs2 = "fs2_#{System.unique_integer([:positive])}"
 
       start_supervised!(
         {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs1}}},
@@ -153,7 +204,7 @@ defmodule Jido.Shell.VFS.MountTableTest do
     end
 
     test "resolves mount point itself", %{workspace_id: workspace_id} do
-      fs_name = :"fs_#{System.unique_integer([:positive])}"
+      fs_name = "fs_#{System.unique_integer([:positive])}"
 
       start_supervised!(
         {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs_name}}}
diff --git a/test/jido/shell/vfs/mount_test.exs b/test/jido/shell/vfs/mount_test.exs
index ab1c57a..90d80b0 100644
--- a/test/jido/shell/vfs/mount_test.exs
+++ b/test/jido/shell/vfs/mount_test.exs
@@ -3,9 +3,24 @@ defmodule Jido.Shell.VFS.MountTest do
 
   alias Jido.Shell.VFS.Mount
 
+  defmodule InvalidConfigAdapter do
+    def starts_processes, do: false
+    def configure(_opts), do: :invalid
+  end
+
+  defmodule StatelessAdapter do
+    def starts_processes, do: false
+    def configure(opts), do: {__MODULE__, %{name: Keyword.get(opts, :name, "stateless")}}
+  end
+
+  defmodule BrokenProcessAdapter do
+    def starts_processes, do: true
+    def configure(opts), do: {__MODULE__, %{name: Keyword.get(opts, :name, "broken")}}
+  end
+
   setup do
     Jido.Shell.VFS.init()
-    fs_name = :"test_fs_#{System.unique_integer([:positive])}"
+    fs_name = "test_fs_#{System.unique_integer([:positive])}"
 
     start_supervised!(
       {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs_name}}}
@@ -33,5 +48,20 @@ defmodule Jido.Shell.VFS.MountTest do
       {:ok, mount} = Mount.new("/", Jido.VFS.Adapter.InMemory, name: fs_name)
       assert mount.path == "/"
     end
+
+    test "returns invalid adapter config errors" do
+      assert {:error, {:invalid_adapter_config, :invalid}} =
+               Mount.new("/bad", InvalidConfigAdapter, [])
+    end
+
+    test "returns mounts with no owned child for adapters without process startup" do
+      assert {:ok, mount} = Mount.new("/stateless", StatelessAdapter, name: "stateless")
+      assert mount.ownership == :none
+      assert mount.child_pid == nil
+    end
+
+    test "returns child startup errors for process adapters without child specs" do
+      assert {:error, _reason} = Mount.new("/broken", BrokenProcessAdapter, name: "broken")
+    end
   end
 end
diff --git a/test/jido/shell/vfs_test.exs b/test/jido/shell/vfs_test.exs
index ab1b133..d37d47f 100644
--- a/test/jido/shell/vfs_test.exs
+++ b/test/jido/shell/vfs_test.exs
@@ -3,10 +3,15 @@ defmodule Jido.Shell.VFSTest do
 
   alias Jido.Shell.VFS
 
+  defmodule BrokenAdapter do
+    def starts_processes, do: true
+    def configure(opts), do: {__MODULE__, %{name: Keyword.get(opts, :name, "broken")}}
+  end
+
   setup do
     VFS.init()
-    workspace_id = :"test_ws_#{System.unique_integer([:positive])}"
-    fs_name = :"test_fs_#{System.unique_integer([:positive])}"
+    workspace_id = "test_ws_#{System.unique_integer([:positive])}"
+    fs_name = "test_fs_#{System.unique_integer([:positive])}"
 
     start_supervised!(
       {Jido.VFS.Adapter.InMemory, {Jido.VFS.Adapter.InMemory, %Jido.VFS.Adapter.InMemory.Config{name: fs_name}}}
@@ -38,6 +43,26 @@ defmodule Jido.Shell.VFSTest do
       assert :ok = VFS.unmount(workspace_id, "/")
       assert [] = VFS.list_mounts(workspace_id)
     end
+
+    test "returns explicit errors for invalid workspace identifiers" do
+      assert {:error, %Jido.Shell.Error{code: {:session, :invalid_workspace_id}}} =
+               VFS.mount(:bad_workspace, "/", Jido.VFS.Adapter.InMemory, name: "bad")
+    end
+
+    test "returns already_exists when mount path is already taken", %{workspace_id: workspace_id} do
+      assert {:error, %Jido.Shell.Error{code: {:vfs, :already_exists}}} =
+               VFS.mount(workspace_id, "/", Jido.VFS.Adapter.InMemory, name: "dup")
+    end
+
+    test "returns mount_failed when adapter startup fails", %{workspace_id: workspace_id} do
+      assert {:error, %Jido.Shell.Error{code: {:vfs, :mount_failed}}} =
+               VFS.mount(workspace_id, "/broken", BrokenAdapter, name: "broken")
+    end
+
+    test "returns not_found when unmounting a missing path", %{workspace_id: workspace_id} do
+      assert {:error, %Jido.Shell.Error{code: {:vfs, :not_found}}} =
+               VFS.unmount(workspace_id, "/missing")
+    end
   end
 
   describe "write_file/3 and read_file/2" do
@@ -58,7 +83,7 @@ defmodule Jido.Shell.VFSTest do
     end
 
     test "returns error when no mount exists" do
-      unknown_ws = :"unknown_ws_#{System.unique_integer([:positive])}"
+      unknown_ws = "unknown_ws_#{System.unique_integer([:positive])}"
       assert {:error, error} = VFS.read_file(unknown_ws, "/test.txt")
       assert error.code == {:vfs, :no_mount}
     end
@@ -140,6 +165,11 @@ defmodule Jido.Shell.VFSTest do
       VFS.write_file(workspace_id, "/parent/child/file.txt", "nested")
       assert {:ok, "nested"} = VFS.read_file(workspace_id, "/parent/child/file.txt")
     end
+
+    test "accepts paths that already include trailing slash", %{workspace_id: workspace_id} do
+      assert :ok = VFS.mkdir(workspace_id, "/already/")
+      assert VFS.exists?(workspace_id, "/already")
+    end
   end
 
   describe "path normalization" do
@@ -153,4 +183,37 @@ defmodule Jido.Shell.VFSTest do
       assert {:ok, "content"} = VFS.read_file(workspace_id, "/dir/../dir/file.txt")
     end
   end
+
+  describe "unmount_workspace/2" do
+    test "removes all mounts and terminates owned filesystems" do
+      workspace_id = "teardown_ws_#{System.unique_integer([:positive])}"
+      fs1 = "teardown_fs1_#{System.unique_integer([:positive])}"
+      fs2 = "teardown_fs2_#{System.unique_integer([:positive])}"
+
+      assert :ok = VFS.mount(workspace_id, "/one", Jido.VFS.Adapter.InMemory, name: fs1)
+      assert :ok = VFS.mount(workspace_id, "/two", Jido.VFS.Adapter.InMemory, name: fs2)
+
+      pid1 = GenServer.whereis(Jido.VFS.Registry.via(Jido.VFS.Adapter.InMemory, fs1))
+      pid2 = GenServer.whereis(Jido.VFS.Registry.via(Jido.VFS.Adapter.InMemory, fs2))
+      ref1 = Process.monitor(pid1)
+      ref2 = Process.monitor(pid2)
+
+      assert :ok = VFS.unmount_workspace(workspace_id)
+      assert [] = VFS.list_mounts(workspace_id)
+      assert_receive {:DOWN, ^ref1, :process, ^pid1, _reason}
+      assert_receive {:DOWN, ^ref2, :process, ^pid2, _reason}
+    end
+
+    test "returns invalid workspace error for bad identifiers" do
+      assert {:error, %Jido.Shell.Error{code: {:session, :invalid_workspace_id}}} =
+               VFS.unmount_workspace(:bad_workspace)
+    end
+  end
+
+  describe "list_mounts/1" do
+    test "returns empty list for invalid workspace identifiers" do
+      assert [] = VFS.list_mounts(nil)
+      assert [] = VFS.list_mounts("   ")
+    end
+  end
 end
diff --git a/test/mix/tasks/jido_shell_install_docs_test.exs b/test/mix/tasks/jido_shell_install_docs_test.exs
new file mode 100644
index 0000000..4ff6065
--- /dev/null
+++ b/test/mix/tasks/jido_shell_install_docs_test.exs
@@ -0,0 +1,14 @@
+defmodule Mix.Tasks.JidoShell.InstallDocsTest do
+  use ExUnit.Case, async: true
+
+  alias Mix.Tasks.JidoShell.Install.Docs
+
+  test "short_doc/0 returns install summary" do
+    assert Docs.short_doc() =~ "Install and configure Jido Shell"
+  end
+
+  test "long_doc/0 renders example content with command" do
+    assert Docs.long_doc() =~ Docs.short_doc()
+    assert Docs.long_doc() =~ Docs.example()
+  end
+end
diff --git a/test/mix/tasks/jido_shell_test.exs b/test/mix/tasks/jido_shell_test.exs
new file mode 100644
index 0000000..dc03a9d
--- /dev/null
+++ b/test/mix/tasks/jido_shell_test.exs
@@ -0,0 +1,51 @@
+defmodule Mix.Tasks.JidoShellTest do
+  use ExUnit.Case, async: false
+  import Mimic
+
+  setup :set_mimic_global
+  setup :verify_on_exit!
+
+  test "runs interactive shell with default workspace" do
+    copy(Jido.Shell.Transport.IEx)
+
+    expect(Jido.Shell.Transport.IEx, :start, fn "default" ->
+      :ok
+    end)
+
+    assert :ok = Mix.Tasks.JidoShell.run([])
+  end
+
+  test "runs interactive shell with explicit workspace" do
+    copy(Jido.Shell.Transport.IEx)
+
+    expect(Jido.Shell.Transport.IEx, :start, fn "my_workspace" ->
+      :ok
+    end)
+
+    assert :ok = Mix.Tasks.JidoShell.run(["--workspace", "my_workspace"])
+  end
+
+  test "raises when transport returns an error" do
+    copy(Jido.Shell.Transport.IEx)
+
+    expect(Jido.Shell.Transport.IEx, :start, fn "default" ->
+      {:error, Jido.Shell.Error.session(:not_found, %{})}
+    end)
+
+    assert_raise Mix.Error, ~r/failed to start shell/, fn ->
+      Mix.Tasks.JidoShell.run([])
+    end
+  end
+
+  test "raises when transport returns a non-structured error reason" do
+    copy(Jido.Shell.Transport.IEx)
+
+    expect(Jido.Shell.Transport.IEx, :start, fn "default" ->
+      {:error, :boom}
+    end)
+
+    assert_raise Mix.Error, ~r/failed to start shell: :boom/, fn ->
+      Mix.Tasks.JidoShell.run([])
+    end
+  end
+end
diff --git a/test/support/test_shell.ex b/test/support/test_shell.ex
index 05b578c..ef95a40 100644
--- a/test/support/test_shell.ex
+++ b/test/support/test_shell.ex
@@ -48,7 +48,7 @@ defmodule Jido.Shell.TestShell do
 
   @type t :: %__MODULE__{
           session_id: String.t(),
-          workspace_id: atom(),
+          workspace_id: String.t(),
           owner: pid()
         }
 
@@ -63,12 +63,12 @@ defmodule Jido.Shell.TestShell do
   def start!(opts \\ []) do
     workspace_id =
       Keyword.get_lazy(opts, :workspace_id, fn ->
-        :"test_shell_#{System.unique_integer([:positive])}"
+        "test_shell_#{System.unique_integer([:positive])}"
       end)
 
     # Setup VFS
     VFS.init()
-    fs_name = :"test_fs_#{System.unique_integer([:positive])}"
+    fs_name = "test_fs_#{System.unique_integer([:positive])}"
     :ok = VFS.mount(workspace_id, "/", Jido.VFS.Adapter.InMemory, name: fs_name)
 
     # Create session
@@ -133,7 +133,10 @@ defmodule Jido.Shell.TestShell do
   """
   @spec cwd(t()) :: String.t()
   def cwd(%__MODULE__{session_id: session_id}) do
-    Agent.cwd(session_id)
+    case Agent.cwd(session_id) do
+      {:ok, cwd} -> cwd
+      {:error, reason} -> raise "Failed to get cwd: #{inspect(reason)}"
+    end
   end
 
   @doc """
@@ -216,33 +219,45 @@ defmodule Jido.Shell.TestShell do
 
   Useful for testing event streaming.
   """
-  @spec subscribe(t()) :: :ok
+  @spec subscribe(t()) :: :ok | {:error, term()}
   def subscribe(%__MODULE__{session_id: session_id}) do
-    SessionServer.subscribe(session_id, self())
+    case SessionServer.subscribe(session_id, self()) do
+      {:ok, :subscribed} -> :ok
+      {:error, _} = error -> error
+    end
   end
 
   @doc """
   Unsubscribes from session events.
   """
-  @spec unsubscribe(t()) :: :ok
+  @spec unsubscribe(t()) :: :ok | {:error, term()}
   def unsubscribe(%__MODULE__{session_id: session_id}) do
-    SessionServer.unsubscribe(session_id, self())
+    case SessionServer.unsubscribe(session_id, self()) do
+      {:ok, :unsubscribed} -> :ok
+      {:error, _} = error -> error
+    end
   end
 
   @doc """
   Runs a command asynchronously, useful for testing cancellation.
   """
-  @spec run_async(t(), String.t()) :: :ok
+  @spec run_async(t(), String.t()) :: :ok | {:error, term()}
   def run_async(%__MODULE__{session_id: session_id}, command) do
-    SessionServer.run_command(session_id, command)
+    case SessionServer.run_command(session_id, command) do
+      {:ok, :accepted} -> :ok
+      {:error, _} = error -> error
+    end
   end
 
   @doc """
   Cancels the currently running command.
   """
-  @spec cancel(t()) :: :ok
+  @spec cancel(t()) :: :ok | {:error, term()}
   def cancel(%__MODULE__{session_id: session_id}) do
-    SessionServer.cancel(session_id)
+    case SessionServer.cancel(session_id) do
+      {:ok, :cancelled} -> :ok
+      {:error, _} = error -> error
+    end
   end
 
   @doc """
diff --git a/test/support/test_shell_test.exs b/test/support/test_shell_test.exs
new file mode 100644
index 0000000..2d4b919
--- /dev/null
+++ b/test/support/test_shell_test.exs
@@ -0,0 +1,92 @@
+defmodule Jido.Shell.TestShellTest do
+  use Jido.Shell.Case, async: false
+
+  alias Jido.Shell.TestShell
+
+  defp missing_shell() do
+    %TestShell{
+      session_id: "missing-session",
+      workspace_id: "missing-workspace",
+      owner: self()
+    }
+  end
+
+  describe "error wrappers" do
+    test "run!/3 raises on command errors" do
+      assert_raise RuntimeError, ~r/Command failed/, fn ->
+        TestShell.run!(missing_shell(), "echo hi")
+      end
+    end
+
+    test "cwd/1 raises when state lookup fails" do
+      assert_raise RuntimeError, ~r/Failed to get cwd/, fn ->
+        TestShell.cwd(missing_shell())
+      end
+    end
+
+    test "read_file!/2 raises on missing session" do
+      assert_raise RuntimeError, ~r/Failed to read/, fn ->
+        TestShell.read_file!(missing_shell(), "/missing.txt")
+      end
+    end
+
+    test "ls/2 and ls!/2 propagate errors" do
+      assert {:error, %Jido.Shell.Error{code: {:session, :not_found}}} = TestShell.ls(missing_shell())
+
+      assert_raise RuntimeError, ~r/Failed to list/, fn ->
+        TestShell.ls!(missing_shell())
+      end
+    end
+
+    test "subscribe/unsubscribe/run_async/cancel return explicit errors on missing sessions" do
+      assert {:error, %Jido.Shell.Error{code: {:session, :not_found}}} = TestShell.subscribe(missing_shell())
+      assert {:error, %Jido.Shell.Error{code: {:session, :not_found}}} = TestShell.unsubscribe(missing_shell())
+      assert {:error, %Jido.Shell.Error{code: {:session, :not_found}}} = TestShell.run_async(missing_shell(), "echo hi")
+      assert {:error, %Jido.Shell.Error{code: {:session, :not_found}}} = TestShell.cancel(missing_shell())
+    end
+  end
+
+  describe "helpers" do
+    test "run_all/3 executes command lists" do
+      shell = TestShell.start!()
+
+      assert [
+               {"echo one", {:ok, "one"}},
+               {"echo two", {:ok, "two"}}
+             ] = TestShell.run_all(shell, ["echo one", "echo two"])
+    end
+
+    test "await_event/3 supports timeout and exact matching" do
+      shell = TestShell.start!()
+
+      assert {:error, :timeout} = TestShell.await_event(shell, :command_done, 10)
+
+      send(self(), {:jido_shell_session, shell.session_id, {:output, "exact"}})
+      assert {:ok, {:output, "exact"}} = TestShell.await_event(shell, {:output, "exact"}, 50)
+    end
+
+    test "collect_events/2 handles cancelled and crashed terminal events" do
+      shell = TestShell.start!()
+
+      send(self(), {:jido_shell_session, shell.session_id, :command_cancelled})
+      assert [:command_cancelled] = TestShell.collect_events(shell, 50)
+
+      send(self(), {:jido_shell_session, shell.session_id, {:command_crashed, :boom}})
+      assert [{:command_crashed, :boom}] = TestShell.collect_events(shell, 50)
+    end
+
+    test "exists?/2 resolves relative paths from cwd" do
+      shell = TestShell.start!()
+      :ok = TestShell.write_file(shell, "/exists.txt", "ok")
+
+      assert TestShell.exists?(shell, "exists.txt")
+    end
+
+    test "subscribe/unsubscribe success paths return :ok" do
+      shell = TestShell.start!()
+
+      assert :ok = TestShell.subscribe(shell)
+      assert :ok = TestShell.unsubscribe(shell)
+    end
+  end
+end