From 1465db80e7ca06688bf09add5edd2a920d5fc80f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 1 Jul 2026 21:42:31 +0000
Subject: [PATCH 1/3] Add platform validation workflow

---
 .github/workflows/platform-validation.yml | 49 +++++++++++++++++++++++
 README.md                                 | 21 ++++++++++
 scripts/diagnose.py                       |  2 +-
 3 files changed, 71 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/platform-validation.yml

diff --git a/.github/workflows/platform-validation.yml b/.github/workflows/platform-validation.yml
new file mode 100644
index 0000000..596244b
--- /dev/null
+++ b/.github/workflows/platform-validation.yml
@@ -0,0 +1,49 @@
+name: Platform Validation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  validate:
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-latest
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install development dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run unit tests
+        run: python -m unittest discover -s tests
+
+      - name: Run capability diagnostics
+        run: python scripts/diagnose.py
+
+      - name: Run process smoke tests
+        run: |
+          python examples/process_smoke.py
+          python examples/async_process_smoke.py
+
+      - name: Build distribution artifacts
+        run: python -m build
diff --git a/README.md b/README.md
index 4b4ce93..bedc990 100644
--- a/README.md
+++ b/README.md
@@ -338,6 +338,27 @@ python examples/async_process_smoke.py
 
 They exercise hosted PowerShell, synchronous process-backed sessions, and async process-backed sessions.
 
+## Platform Validation Matrix
+
+LiveShell's automated platform coverage focuses on the base package behavior that should work on both macOS and Linux without optional extras:
+
+| Platform | Python | Automated checks |
+| --- | --- | --- |
+| Linux | 3.10, 3.11, 3.12, 3.13 | `python -m unittest discover -s tests`, `python scripts/diagnose.py`, `python examples/process_smoke.py`, `python examples/async_process_smoke.py`, `python -m build` |
+| macOS | 3.10, 3.11, 3.12, 3.13 | `python -m unittest discover -s tests`, `python scripts/diagnose.py`, `python examples/process_smoke.py`, `python examples/async_process_smoke.py`, `python -m build` |
+
+This matrix is enforced in GitHub Actions by the `Platform Validation` workflow in `.github/workflows/platform-validation.yml`.
+
+Hosted PowerShell remains an optional path because it requires both a local PowerShell installation and the `powershell` extra:
+
+```powershell
+python -m pip install ".[powershell]"
+python scripts/diagnose.py --preload
+python examples/powershell_smoke.py
+```
+
+Run those hosted PowerShell checks manually on the target macOS/Linux machine when that optional integration matters for a release or deployment.
+
 ## Behavior And Limitations
 
 Process-backed sessions such as `Cmd` and `Bash` keep one child process alive and send commands through it. They preserve shell state, but they are not full terminal or PTY emulators.
diff --git a/scripts/diagnose.py b/scripts/diagnose.py
index fc3d055..0732ce0 100644
--- a/scripts/diagnose.py
+++ b/scripts/diagnose.py
@@ -31,7 +31,7 @@ def main() -> int:
     pythonnet_found = importlib.util.find_spec("pythonnet") is not None
     print(f"pythonnet installed: {pythonnet_found}")
     if not pythonnet_found:
-        print("Install with: python -m pip install -r requirements.txt")
+        print('Install with: python -m pip install ".[powershell]"')
 
     installation = PowerShell.find_installation()
     print(f"PowerShell available: {installation is not None}")

From 85146b03a2420cf64f00180ed078bcd0c4b9c7e8 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 1 Jul 2026 21:44:05 +0000
Subject: [PATCH 2/3] Limit workflow token permissions

---
 .github/workflows/platform-validation.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.github/workflows/platform-validation.yml b/.github/workflows/platform-validation.yml
index 596244b..b4aa39b 100644
--- a/.github/workflows/platform-validation.yml
+++ b/.github/workflows/platform-validation.yml
@@ -6,6 +6,9 @@ on:
       - main
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   validate:
     name: ${{ matrix.os }} / Python ${{ matrix.python-version }}

From 84f7508b5564b4fb6c1963839a8b3bd3f629594f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 8 Jul 2026 22:06:26 +0000
Subject: [PATCH 3/3] Clarify optional PowerShell extra diagnostic

---
 scripts/diagnose.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/diagnose.py b/scripts/diagnose.py
index 0732ce0..34108b3 100644
--- a/scripts/diagnose.py
+++ b/scripts/diagnose.py
@@ -31,7 +31,7 @@ def main() -> int:
     pythonnet_found = importlib.util.find_spec("pythonnet") is not None
     print(f"pythonnet installed: {pythonnet_found}")
     if not pythonnet_found:
-        print('Install with: python -m pip install ".[powershell]"')
+        print('Optional for hosted PowerShell: python -m pip install ".[powershell]"')
 
     installation = PowerShell.find_installation()
     print(f"PowerShell available: {installation is not None}")