diff --git a/.github/workflows/dockerhub.yml b/.github/workflows/dockerhub.yml
index 0362fdc..ce9668b 100644
--- a/.github/workflows/dockerhub.yml
+++ b/.github/workflows/dockerhub.yml
@@ -352,7 +352,7 @@ jobs:
           EOF
 
           # Start services
-          docker-compose -f docker-compose.test.yml up -d
+          docker compose -f docker-compose.test.yml up -d
 
           # Wait for frontend
           echo "⏳ Waiting for services to be ready..."
@@ -363,8 +363,8 @@ jobs:
             echo "✅ Backend health check passed"
           else
             echo "❌ Backend health check failed"
-            docker-compose -f docker-compose.test.yml logs
-            docker-compose -f docker-compose.test.yml down
+            docker compose -f docker-compose.test.yml logs
+            docker compose -f docker-compose.test.yml down
             exit 1
           fi
 
@@ -373,13 +373,13 @@ jobs:
             echo "✅ Frontend serves correctly"
           else
             echo "❌ Frontend check failed"
-            docker-compose -f docker-compose.test.yml logs
-            docker-compose -f docker-compose.test.yml down
+            docker compose -f docker-compose.test.yml logs
+            docker compose -f docker-compose.test.yml down
             exit 1
           fi
 
           echo "✅ Integration test passed!"
-          docker-compose -f docker-compose.test.yml down
+          docker compose -f docker-compose.test.yml down
 
   summary:
     name: 📊 Deployment Summary
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..23ff4d3
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,55 @@
+# AGENTS.md
+
+> Persistent project context loaded into every GitPilot session.
+> Edit freely — agents will follow these notes.
+
+## Project Overview
+This project has a `README.md` at its root — refer to it for purpose and high-level usage.
+
+## Directory Layout
+- `CHANGELOG.md`
+- `Dockerfile.backend`
+- `Dockerfile.frontend`
+- `LICENSE`
+- `MANIFEST.in`
+- `Makefile`
+- `README.md`
+- `api/`
+- `assets/`
+- `deploy/`
+- `docker-compose.mcp.yml`
+- `docker-compose.yml`
+- `docs/`
+- `extensions/`
+- `frontend/`
+- `gitcopilot.egg-info/`
+- `gitpilot/`
+- `mcp-stack/`
+- `mkdocs.yml`
+- `mypy.ini`
+- `package-lock.json`
+- `package.json`
+- `pyproject.toml`
+- `render.yaml`
+- `scripts/`
+- `tests/`
+- `uv.lock`
+- `vercel.json`
+
+## Stack
+Python, Node.js, Docker, docker-compose
+
+## Workflows
+- `make install`, `make test`, `make run`
+- `npm install`, `npm test`
+- `pip install -e .` and `pytest`
+
+## Conventions
+- Keep changes small and reversible.
+- Run the test suite before committing.
+- Write docstrings for any new public function.
+
+## Mode-Specific Notes
+Place per-mode overrides in `.gitpilot/AGENTS.<mode>.md` (for example
+`.gitpilot/AGENTS.coder.md`).  Use `@./relative/path.md` on its own line to
+include another markdown file.
diff --git a/Makefile b/Makefile
index 0b1e309..3f3d18e 100644
--- a/Makefile
+++ b/Makefile
@@ -97,15 +97,33 @@ help:
 	@echo "  make gateway-register Register GitPilot agent in ContextForge"
 	@echo ""
 
-## High-level install: runtime backend + frontend + MCP stack.
-## GitPilot uses the MCP stack by default, so keep MCP in the happy path while
-## leaving heavyweight developer/docs tooling opt-in.
-install: uv-install frontend-install install-mcp
-	@echo "✅ Backend runtime (uv), frontend (npm) and MCP env ready."
+## High-level install: runtime backend + frontend + MCP stack + MatrixLab addon.
+## GitPilot now ships MatrixLab as a first-class part of the backend, so it's
+## installed by default alongside the MCP stack.  When docker isn't available
+## (or the runner port is held), install-matrixlab-soft warns and continues —
+## the rest of the install completes regardless.
+## Skip the addon entirely with:  make install SKIP_MATRIXLAB=1
+install: uv-install frontend-install install-mcp install-matrixlab-soft
+	@echo "✅ Backend runtime (uv), frontend (npm), MCP env and MatrixLab addon ready."
 	@echo "   Run 'make run' to start MCP Context Forge + GitPilot."
+	@echo "   Run 'make startup' for the full GitPilot + MatrixLab + URL-fixup flow."
 	@echo "   No Docker?  Use 'make run-bare' to start GitPilot without MCP."
 	@echo "   Optional:   'make install-dev' for test/lint/build tooling."
 
+## Soft variant of install-matrixlab — warns and skips on docker-missing /
+## daemon-down / port-held instead of aborting the parent installer.  Wired
+## into `make install` so the MatrixLab addon shows up by default but a
+## Docker-less host still gets a clean install.  Skip entirely with
+## SKIP_MATRIXLAB=1 (useful in CI when you really don't want any docker
+## reach-out during install).
+.PHONY: install-matrixlab-soft
+install-matrixlab-soft:
+ifeq ($(SKIP_MATRIXLAB),1)
+	@echo "➖ Skipping MatrixLab addon install (SKIP_MATRIXLAB=1)."
+else
+	@MATRIXLAB_OPTIONAL=1 bash scripts/install-matrixlab.sh
+endif
+
 ## Custom developer install: add dev/test/build tooling when you need it.
 install-dev: uv-install-dev frontend-install
 	@echo "✅ Developer tooling ready."
@@ -806,6 +824,14 @@ stop-mcp:
 	@docker compose --env-file .mcp.env -f docker-compose.mcp.yml --profile mcp down 2>/dev/null || true
 	@echo "🛑 MCP stack stopped (volumes kept). 'make uninstall-mcp' to remove data."
 
+## Rotate the MCP_AUTH_TOKEN end-to-end and re-init Forge with the new
+## token.  The escape hatch when `make run-mcp`'s auto-recovery isn't
+## enough — typically because Forge persisted an older token in
+## Postgres on its first boot.  Wipes Forge's volume (NOT Postgres
+## data) so the new token in .mcp.env is what Forge actually validates.
+rotate-mcp-token:
+	@bash scripts/rotate-mcp-token.sh
+
 ## Tail logs from the MCP stack
 logs-mcp:
 	@docker compose --env-file .mcp.env -f docker-compose.mcp.yml --profile mcp logs -f --tail=100
@@ -841,3 +867,95 @@ install-mcp-workflows:
 ## Add --milvus to also check the milvus profile.
 smoke-mcp:
 	@bash scripts/smoke-mcp.sh
+
+# =========================================================================
+# Phase 0 industrial-grade additions
+#
+# These targets land next to the legacy 69 — nothing removed, nothing
+# renamed.  They're the "five-verb" model's first three:
+#   make doctor       — preflight + diagnose
+#   make run-prod     — production frontend build, served by the backend
+#   make install-matrixlab
+#                     — opt-in MatrixLab addon (also fired by
+#                       `make install WITH_MATRIXLAB=1`)
+#
+# Once these prove themselves, the legacy targets can become thin
+# aliases.  For now they coexist.
+# =========================================================================
+
+## Preflight + diagnose: catches the failure modes the user can hit
+## BEFORE they cost a 20-minute support cycle.  Mirrors `gh doctor`
+## and `git doctor`.  Each red check links to a fix command.
+.PHONY: doctor
+doctor:
+	@bash scripts/doctor.sh
+
+## Build the production frontend (Vite dist) and start the GitPilot
+## backend serving it via FastAPI's StaticFiles mount.  Unlike `make
+## run`, this does NOT start the Vite dev server — one URL, minified
+## assets, no CORS, no `vite ready in 1926 ms` line.
+.PHONY: run-prod
+run-prod: frontend-build
+	@echo "🚀 Starting GitPilot in production mode on http://127.0.0.1:$(PORT)..."
+	@$(UV_ENV) $(UV) run --no-dev python -m gitpilot serve --host 127.0.0.1 --port $(PORT) --no-open
+
+## Strict MatrixLab addon install — fatal on docker-missing / port-held.
+## Use this when you explicitly want to (re)provision the addon.
+## `make install` (default) now uses install-matrixlab-soft (above) which
+## chains into install but tolerates a Docker-less host.  WITH_MATRIXLAB=1
+## is preserved as an alias for the strict path for backwards compatibility.
+.PHONY: install-matrixlab
+install-matrixlab:
+	@bash scripts/install-matrixlab.sh
+
+# Backwards-compat alias: WITH_MATRIXLAB=1 make install now is the same as
+# the default `make install` (MatrixLab is included by default).  We keep
+# the variable around so existing scripts/CI pipelines don't break, but
+# the soft-install path is already in the `install` deps above.
+
+# =========================================================================
+# Phase 0.5 — production startup with MatrixLab (additive)
+#
+# Everything below is a strict SUPERSET of `make install` / `make run`
+# / `make doctor`.  None of the existing recipes above are modified;
+# these new targets call them as black boxes.  Operators on existing
+# scripts/workflows pin to the old targets and see no behavior change.
+#
+#   make install-all      = make install + make install-matrixlab
+#   make startup          = install-matrixlab + make run + auto-fix URL
+#   make fix-matrixlab-url = re-point the persisted matrixlab_url at the
+#                            port that's actually listening
+#   make diagnose-matrixlab = read-only debug dump for bug reports
+# =========================================================================
+
+## Full installer: core GitPilot install + MatrixLab addon.
+## Same as `WITH_MATRIXLAB=1 make install` but easier to type.
+.PHONY: install-all
+install-all: install install-matrixlab
+	@echo "✅ install-all: core + MatrixLab ready"
+	@echo "   Next:  make startup"
+
+## Production start: ensures MatrixLab is running, starts GitPilot,
+## auto-fixes the persisted matrixlab_url to point at the live port.
+## This is the "I want everything up and connected" one-liner —
+## `make run` still exists unchanged for operators who don't want
+## the addon.
+.PHONY: startup
+startup:
+	@bash scripts/start-gitpilot-stack.sh
+
+## Detect which port MatrixLab is actually on and update GitPilot's
+## persisted settings to match.  Solves the "Runner URL:
+## http://localhost:8000 / Needs attention" symptom that happens
+## when settings.json was written before the port-shift to 8765.
+.PHONY: fix-matrixlab-url
+fix-matrixlab-url:
+	@bash scripts/fix-matrixlab-url.sh
+
+## Verbose, copy-paste-friendly diagnostic dump for the MatrixLab
+## install/connect path.  Probes both candidate ports, shows what
+## GitPilot's APIs return, lists project containers, tails the
+## runner log.  Read-only — does not modify state.
+.PHONY: diagnose-matrixlab
+diagnose-matrixlab:
+	@bash scripts/diagnose-matrixlab.sh
diff --git a/docs/sandbox-approval-flow.md b/docs/sandbox-approval-flow.md
new file mode 100644
index 0000000..96692ad
--- /dev/null
+++ b/docs/sandbox-approval-flow.md
@@ -0,0 +1,212 @@
+# Sandbox Execution — Approval-First Architecture
+
+Status: **Production** as of the `add-sandbox-settings-tab` series.
+
+This document is the source of truth for how code executes in
+GitPilot's sandbox. It covers the four user entry points, the
+deterministic ExecutionPlan that gates every run on user approval,
+and the schema every entry point shares.
+
+---
+
+## Principles
+
+1. **Intent decides the path, not the model.** A chat message classified
+   as `execute` short-circuits the LLM planner and produces a
+   deterministic ExecutionPlan in pure Python.
+2. **No run starts without explicit user approval.** The approval surface
+   (ExecutionPlanCard) is visibly distinct from the Action Plan card —
+   green border vs orange, "Run in Sandbox" vs "Execute Plan".
+3. **Local and MatrixLab are symmetric.** Same request/response shape,
+   same UI, same safety checks. The backend pill tells the user which
+   actually ran.
+4. **Every run is recoverable.** Rerun re-enters the approval flow with
+   the same payload — never silent re-execution.
+
+---
+
+## The four entry points
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│                        FRONT DOOR                                  │
+├────────────────────────────────────────────────────────────────────┤
+│ Chat command  │ Code-block ▶ │ File ▶ (sidebar) │ Canvas Run │     │
+└──────┬────────────┬────────────────┬─────────────────┬─────────────┘
+       │            │                │                 │
+       ▼            ▼                ▼                 ▼
+   /api/chat   /api/sandbox      window event     /api/sandbox
+   /plan       /plan             gitpilot:run-    /plan
+   (short-     (inline)          file → /api/     (canvas)
+    circuit)                     chat/plan
+       │            │                │                 │
+       └────────────┴────────────────┴─────────────────┘
+                              │
+                              ▼
+                ┌─────────────────────────────┐
+                │ ExecutionPlan { … } returned │
+                │ Rendered as approval card    │
+                └─────────────┬───────────────┘
+                              │
+                       user clicks
+                       "Run in Sandbox"
+                              │
+                              ▼
+                ┌─────────────────────────────┐
+                │ /api/sandbox/run            │
+                │ (or /api/chat/execute for   │
+                │  file-run via Action Plan)  │
+                └─────────────┬───────────────┘
+                              │
+                              ▼
+                       ExecutionCard
+                       in chat history
+```
+
+---
+
+## The ExecutionPlan schema
+
+Built deterministically by `gitpilot.sandbox_plan.build_execution_plan_for_file`
+and `..._for_inline`. Serialized to JSON for the HTTP layer.
+
+```jsonc
+{
+  "plan_id":         "plan_a1b2c3d4e5f6",
+  "goal":            "Run demo.py",
+  "source":          "chat | code_block | file_run | canvas | rerun",
+  "language":        "python | javascript | bash",
+  "command":         ["python", "demo.py"],
+  "sandbox":         "subprocess | matrixlab",
+  "timeout_sec":     120,
+  "network":         false,
+  "workdir":         ".",
+  "capture_artifacts": true,
+  "file":            "demo.py",          // for file-run, else null
+  "inline_code":     null,               // for inline runs, else null
+  "safety": {
+    "checks":   [ { "label": "File exists", "ok": true }, … ],
+    "warnings": [
+      { "severity": "high",   "label": "Uses os.system / exec / eval", "detail": "…" },
+      { "severity": "medium", "label": "Imports network library",       "detail": "…" },
+      { "severity": "low",    "label": "Uses plt.show()",               "detail": "…" }
+    ]
+  },
+  "requires_approval": true,
+  "parent_run_id":     null               // set on Rerun
+}
+```
+
+### Safety rules
+
+Coarse, deterministic, never blocking. Each rule is one regex.
+
+| Severity | Rule                                            |
+|----------|-------------------------------------------------|
+| high     | `os.system`, `subprocess.{call,run,Popen}`, `eval()`, `exec()` |
+| medium   | imports `socket` / `urllib` / `requests` / `httpx` / `aiohttp` |
+| medium   | reads `os.environ` / `os.getenv`                |
+| medium   | spawns subprocesses                             |
+| low      | `plt.show()` (MPLBACKEND=Agg auto-injected)     |
+| low      | writes files (`open(…, 'w'…)`, `.write()`, `savefig()`, `to_csv()`) |
+
+False positives are cheap — one extra chip; false negatives erode
+trust. Tune by tightening regexes, never by hiding warnings.
+
+---
+
+## State machine
+
+```
+planned ──► approved ──► queued ──► starting ──► running ──► completed
+   │           │                                    │           │
+   │           └─ cancelled                         └─► failed / timeout / cancelled
+   └─ cancelled  (rejected before approval)
+```
+
+Today the executor goes straight from `approved` to `running` to
+`completed` because `/api/sandbox/run` is synchronous. The schema is
+designed so adding a streaming `/api/sandbox/execute` endpoint
+(future batch) won't change any caller — additional events (`queued`,
+`starting`, intermediate `running` stdout chunks) slot in cleanly.
+
+---
+
+## Two consent surfaces (NEVER conflate)
+
+```
+┌─────────────────────────────────┐   ┌─────────────────────────────────┐
+│ ACTION PLAN                     │   │ EXECUTION PLAN                  │
+│ (changes the repo)              │   │ (runs code in sandbox)          │
+├─────────────────────────────────┤   ├─────────────────────────────────┤
+│ Orange left border              │   │ Green left border               │
+│ READ / CREATE / MODIFY / DELETE │   │ RUN_FILE / RUN_INLINE           │
+│ Header: "Action Plan"           │   │ Header: "EXECUTION PLAN"        │
+│ CTA: "Execute Plan"             │   │ CTA: "Run in Sandbox"           │
+│ Source: LLM planner             │   │ Source: deterministic Python    │
+└─────────────────────────────────┘   └─────────────────────────────────┘
+```
+
+`AssistantMessage` renders the Execution Plan when `plan.execution_plan`
+is set, and suppresses the Action Plan render in that case. The two
+never appear together.
+
+---
+
+## Adding a new entry point
+
+To add a fifth way to run code (say, a "Run on save" hook):
+
+1. Compute the source classification: `file` for a saved file, or
+   `code + language` for an inline buffer.
+2. POST to `/api/sandbox/plan` with `{ source: "your_source", … }`.
+3. Render the returned plan with `ExecutionPlanCard`.
+4. On approve, POST to `/api/sandbox/run` (or dispatch
+   `gitpilot:run-file` if it should go through chat history).
+
+That's it. The plan builder, safety rules, and approval UI are shared.
+
+---
+
+## Why approval is mandatory even for trusted users
+
+- The plan is computed in **milliseconds**. The approval click is
+  ~250 ms of cognitive load — well worth the audit trail.
+- Generated code is often subtly wrong. Approval is the user's
+  last chance to spot a `rm -rf` before it runs in a workspace
+  bind-mounted from their host.
+- The same surface enables one-click **Rerun** with the same
+  approved command — no fresh classification, no model variance.
+
+If a future product decision requires opt-out for trusted snippets,
+the surface is already there: `Settings → Sandbox → Allow one-click
+run for generated snippets` flips `requires_approval=false` in the
+plan response and the UI short-circuits the approval step.
+
+---
+
+## Files
+
+| File | Role |
+|------|------|
+| `gitpilot/sandbox_plan.py` | Deterministic ExecutionPlan builder + safety analyzer |
+| `gitpilot/sandbox_api.py` | `POST /api/sandbox/plan` + `POST /api/sandbox/run` |
+| `gitpilot/agentic.py` | `try_execute_short_circuit` attaches `execution_plan` to PlanResult; `execute_plan` emits `next_actions` |
+| `frontend/components/ExecutionPlanCard.jsx` | Green approval card (full / compact variants) |
+| `frontend/components/SandboxStatusWidget.jsx` | Sidebar health pill + one-click recovery |
+| `frontend/components/FileTree.jsx` | Sidebar ▶ Run button — dispatches `gitpilot:run-file` |
+| `frontend/components/ChatPanel.jsx` | Listens for `gitpilot:run-file`, routes through chat plan |
+| `frontend/components/AssistantMessage.jsx` | Renders ExecutionPlanCard, ExecutionCard with Rerun, and next_actions |
+| `frontend/components/RunnableCodeBlock.jsx` | Code-block ▶ → plan → approve → run |
+| `frontend/components/SandboxCanvas.jsx` | Canvas split view, same approval flow |
+
+---
+
+## Tests
+
+| File | Coverage |
+|------|----------|
+| `tests/test_sandbox_plan.py` | 23 tests — pure-Python builder + endpoint |
+| `tests/test_execute_short_circuit_plan.py` | 4 tests — plan attached for RUN_FILE intents |
+| `tests/test_post_create_next_actions.py` | 7 tests — post-CREATE Run buttons |
+| `tests/test_sandbox_api.py`, `tests/test_sandbox.py` | Existing — no regressions allowed |
diff --git a/frontend/App.jsx b/frontend/App.jsx
index 72c9711..3b599eb 100644
--- a/frontend/App.jsx
+++ b/frontend/App.jsx
@@ -21,6 +21,7 @@ import {
   SkillsTab,
   SessionsTab,
   AdvancedTab,
+  SandboxTab,
 } from "./components/AdminTabs";
 import { apiUrl, safeFetchJSON, fetchStatus } from "./utils/api.js";
 import { initApp } from "./utils/appInit.js";
@@ -798,7 +799,7 @@ export default function App() {
       setStartupPhase("checking-backend");
       setStartupStatusMessage("Connecting to backend...");
       setStartupDetailMessage(
-        "Waiting for the server to be ready. This may take a few seconds on first start."
+        "Preparing your workspace. First launch may take a few seconds."
       );
 
       // Single-source-of-truth init: combines /api/status + /api/auth/status
@@ -1034,7 +1035,7 @@ export default function App() {
           {activePage === "admin" && (
             <div style={{ padding: "24px", maxWidth: "960px", margin: "0 auto" }}>
               <div style={{ display: "flex", gap: "8px", marginBottom: "24px", flexWrap: "wrap" }}>
-                {["overview", "providers", "workspace-modes", "integrations", "mcp-servers", "sessions", "skills", "security", "advanced"].map((tab) => (
+                {["overview", "providers", "workspace-modes", "integrations", "mcp-servers", "sandbox", "sessions", "skills", "security", "advanced"].map((tab) => (
                   <button
                     key={tab}
                     onClick={() => setAdminTab(tab)}
@@ -1155,6 +1156,10 @@ export default function App() {
                 <MCPServersTab showToast={showToast} />
               )}
 
+              {adminTab === "sandbox" && (
+                <SandboxTab showToast={showToast} />
+              )}
+
               {adminTab === "security" && (
                 <SecurityTab showToast={showToast} />
               )}
diff --git a/frontend/components/AdminTabs/MatrixLabInstallModal.jsx b/frontend/components/AdminTabs/MatrixLabInstallModal.jsx
new file mode 100644
index 0000000..d590f79
--- /dev/null
+++ b/frontend/components/AdminTabs/MatrixLabInstallModal.jsx
@@ -0,0 +1,1013 @@
+// frontend/components/AdminTabs/MatrixLabInstallModal.jsx
+import React, { useCallback, useEffect, useState } from "react";
+import { apiUrl } from "../../utils/api.js";
+
+/**
+ * MatrixLab install modal — the "addon store" experience.
+ *
+ * Drives a single state machine off /api/matrixlab/* so the user sees
+ * one coherent state at a time (not "Unreachable" + "Running" + raw
+ * stack-trace at once). Default view exposes a single primary button;
+ * Runner URL / token / image / network / timeout live behind an
+ * Advanced disclosure.
+ *
+ * Status names mirror the backend MatrixLabStatus enum:
+ *   not_installed | installing | starting | stopping | checking |
+ *   ready | needs_attention | failed
+ */
+
+// Progress checklists vary by which lifecycle the operator launched.
+// The active "current step" key is set on the busy state so the
+// checklist tracks the user's chosen journey, not a generic install.
+const PROGRESS_STEPS = {
+  install: [
+    { key: "system",   label: "Checking system" },
+    { key: "install",  label: "Downloading MatrixLab" },
+    { key: "start",    label: "Starting runner" },
+    { key: "test",     label: "Testing connection" },
+    { key: "activate", label: "Activating MatrixLab" },
+  ],
+  repair: [
+    { key: "system",   label: "Checking runner URL" },
+    { key: "repair",   label: "Restarting runner" },
+    { key: "test",     label: "Testing connection" },
+    { key: "activate", label: "Activating MatrixLab" },
+  ],
+  reinstall: [
+    { key: "system",   label: "Stopping current runner" },
+    { key: "remove",   label: "Removing old addon" },
+    { key: "install",  label: "Downloading fresh version" },
+    { key: "start",    label: "Starting runner" },
+    { key: "test",     label: "Testing connection" },
+    { key: "activate", label: "Activating MatrixLab" },
+  ],
+};
+
+// Primary action label and the journey it triggers, keyed by the
+// addon's normalised status.  Mapping is exhaustive so the modal
+// always has a clear "next thing to do" button.
+const PRIMARY_BY_STATUS = {
+  not_installed:   { label: "Install and Start",  action: "install"  },
+  installing:      { label: "Installing…",        action: null       },
+  starting:        { label: "Starting…",          action: null       },
+  stopping:        { label: "Stopping…",          action: null       },
+  checking:        { label: "Checking…",          action: null       },
+  needs_attention: { label: "Repair connection",  action: "repair"   },
+  failed:          { label: "Retry installation", action: "install"  },
+  ready:           { label: "Done",               action: "done"     },
+};
+
+function statusPill(status) {
+  const map = {
+    not_installed: { label: "Not installed", bg: "#374151", fg: "#d1d5db" },
+    installing:    { label: "Installing",    bg: "#0d3320", fg: "#86efac" },
+    starting:      { label: "Starting",      bg: "#0d3320", fg: "#86efac" },
+    stopping:      { label: "Stopping",      bg: "#3d2d11", fg: "#fde68a" },
+    checking:      { label: "Checking",      bg: "#0d3320", fg: "#86efac" },
+    ready:         { label: "Ready",         bg: "#0d3320", fg: "#86efac" },
+    needs_attention: { label: "Needs attention", bg: "#3d2d11", fg: "#fde68a" },
+    failed:        { label: "Failed",        bg: "#3d1111", fg: "#fca5a5" },
+  };
+  return map[status] || map.not_installed;
+}
+
+export default function MatrixLabInstallModal({ onClose, onActivated }) {
+  const [status, setStatus] = useState(null);   // MatrixLabStatus from backend
+  const [busy, setBusy] = useState(false);
+  // Which journey is currently in flight ("install" | "repair" |
+  // "reinstall") — drives the progress checklist's stage list.
+  const [journey, setJourney] = useState(null);
+  const [progressStep, setProgressStep] = useState(null);
+  const [showAdvanced, setShowAdvanced] = useState(false);
+  const [showDetails, setShowDetails] = useState(false);
+  const [logs, setLogs] = useState(null);
+  const [showLogs, setShowLogs] = useState(false);
+  // Reinstall confirmation prompt + the destructive "wipe images" opt-in.
+  const [reinstallConfirm, setReinstallConfirm] = useState(false);
+  const [reinstallWipe, setReinstallWipe] = useState(false);
+
+  // Mirror of /api/sandbox/status for the Advanced panel.
+  const [advanced, setAdvanced] = useState(null);
+  const [tokenInput, setTokenInput] = useState("");
+
+  const refresh = useCallback(async () => {
+    try {
+      const r = await fetch(apiUrl("/api/matrixlab/status"));
+      const data = await r.json();
+      setStatus(data);
+    } catch (err) {
+      setStatus({
+        status: "failed",
+        message: "GitPilot backend could not return a MatrixLab status.",
+        errorCode: "BACKEND_UNREACHABLE",
+        technicalDetails: { rawError: err?.message || String(err) },
+      });
+    }
+  }, []);
+
+  const refreshAdvanced = useCallback(async () => {
+    try {
+      const r = await fetch(apiUrl("/api/sandbox/status"));
+      const data = await r.json();
+      setAdvanced(data);
+    } catch (err) {
+      // Non-fatal — Advanced just stays empty.
+    }
+  }, []);
+
+  useEffect(() => {
+    refresh();
+    refreshAdvanced();
+  }, [refresh, refreshAdvanced]);
+
+  // Run a sequence of phased POSTs against /api/matrixlab/* and walk
+  // the progress checklist as each one returns.  Used for install,
+  // repair, and reinstall — they differ only in which endpoint kicks
+  // off the journey.
+  const runJourney = useCallback(async (journeyKey, kickoffPath, kickoffBody) => {
+    setBusy(true);
+    setJourney(journeyKey);
+    setShowDetails(false);
+    try {
+      // Phase 1: kickoff (install / repair / reinstall).  Each backend
+      // endpoint is itself idempotent and aggregates several docker
+      // commands; the modal walks the checklist on the way.
+      setProgressStep(journeyKey === "reinstall" ? "system" : journeyKey);
+      let r = await fetch(apiUrl(kickoffPath), {
+        method: "POST",
+        headers: kickoffBody ? { "Content-Type": "application/json" } : undefined,
+        body: kickoffBody ? JSON.stringify(kickoffBody) : undefined,
+      });
+      let data = await r.json();
+      setStatus(data);
+      if (data.status === "failed") return;
+
+      // Phase 2: explicit connection test so we never claim "ready"
+      // without a green health probe.
+      setProgressStep("test");
+      r = await fetch(apiUrl("/api/matrixlab/test"), { method: "POST" });
+      data = await r.json();
+      setStatus(data);
+      if (data.status !== "ready") return;
+
+      // Phase 3: activate (always safe to call when ready).
+      setProgressStep("activate");
+      r = await fetch(apiUrl("/api/matrixlab/activate"), { method: "POST" });
+      data = await r.json();
+      setStatus(data);
+      if (data.status === "ready" && data.activeSandbox === "matrixlab") {
+        onActivated?.(data);
+      }
+    } catch (err) {
+      setStatus({
+        status: "failed",
+        message: `MatrixLab ${journeyKey} could not complete.`,
+        errorCode: "NETWORK_ERROR",
+        technicalDetails: { rawError: err?.message || String(err) },
+      });
+    } finally {
+      setBusy(false);
+      setProgressStep(null);
+      setJourney(null);
+      refreshAdvanced();
+    }
+  }, [onActivated, refreshAdvanced]);
+
+  const runInstall   = useCallback(() => runJourney("install",   "/api/matrixlab/install"), [runJourney]);
+  const runRepair    = useCallback(() => runJourney("repair",    "/api/matrixlab/repair"),  [runJourney]);
+  const runReinstall = useCallback((removeData) => runJourney(
+    "reinstall", "/api/matrixlab/reinstall", { remove_data: !!removeData },
+  ), [runJourney]);
+  // Cheap recovery: persist the discovered URL without restarting the
+  // runner.  Most "needs_attention" cases are stale URLs from the
+  // :8000 → :8765 port move, and this resolves them in <1s.
+  const runUrlAutoDetect = useCallback(
+    () => runJourney("repair", "/api/matrixlab/url/auto-detect"),
+    [runJourney],
+  );
+
+  const openLogs = useCallback(async () => {
+    setShowLogs(true);
+    try {
+      const r = await fetch(apiUrl("/api/matrixlab/logs?tail=200"));
+      const data = await r.json();
+      setLogs(data);
+    } catch (err) {
+      setLogs({ ok: false, error: err?.message || String(err), lines: [] });
+    }
+  }, []);
+
+  const onPrimary = () => {
+    if (!status) return;
+    const next = (PRIMARY_BY_STATUS[status.status] || PRIMARY_BY_STATUS.not_installed).action;
+    if (!next) return; // in-flight states have no primary action
+    if (next === "done")    return onClose?.();
+    if (next === "install") return runInstall();
+    if (next === "repair")  return runRepair();
+  };
+
+  const updateAdvanced = async (patch) => {
+    try {
+      const r = await fetch(apiUrl("/api/sandbox/config"), {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(patch),
+      });
+      const data = await r.json();
+      if (r.ok) {
+        setAdvanced((prev) => ({ ...(prev || {}), ...data }));
+        if ("matrixlab_token" in patch) setTokenInput("");
+        // Re-probe the addon status — URL / token changes may make us
+        // reachable again.
+        refresh();
+      }
+    } catch (err) {
+      // surfaced through the next refresh
+    }
+  };
+
+  if (!status) {
+    return (
+      <Backdrop onClose={onClose}>
+        <ModalShell title="Install MatrixLab Addon" subtitle="Loading…" onClose={onClose}>
+          <div style={{ padding: 40, textAlign: "center", opacity: 0.6 }}>
+            Checking MatrixLab status…
+          </div>
+        </ModalShell>
+      </Backdrop>
+    );
+  }
+
+  const pill = statusPill(status.status);
+
+  return (
+    <Backdrop onClose={onClose}>
+      <ModalShell
+        title="Install MatrixLab Addon"
+        subtitle="Run code safely in isolated, temporary containers."
+        onClose={onClose}
+      >
+        {/* Status row */}
+        <div style={{
+          display: "flex", alignItems: "center", gap: 10,
+          padding: "12px 14px", background: "#0e0f24",
+          border: "1px solid #2c2d46", borderRadius: 6, marginBottom: 14,
+        }}>
+          <span style={{
+            display: "inline-flex", alignItems: "center", gap: 6,
+            fontSize: 11, fontWeight: 600, padding: "2px 10px", borderRadius: 12,
+            background: pill.bg, color: pill.fg,
+          }}>
+            <span style={{ width: 6, height: 6, borderRadius: "50%", background: pill.fg }} />
+            {pill.label}
+          </span>
+          <div style={{ flex: 1 }}>
+            <div style={{ fontSize: 13, color: "#e6e8ff" }}>{status.message}</div>
+            {status.runnerUrl && status.status !== "ready" && (
+              <div style={{ fontSize: 11, color: "#9092b5", marginTop: 2 }}>
+                Runner URL: <code style={{ color: "#c3c5dd" }}>{status.runnerUrl}</code>
+              </div>
+            )}
+            {/* Stale-URL recovery: backend probes candidate ports
+                when the configured URL is down. When a live one is
+                found we offer a one-click switch — this fixes the
+                very common "MatrixLab is installed but GitPilot
+                cannot connect" after the :8000 → :8765 port move. */}
+            {status.discoveredUrl && status.discoveredUrl !== status.runnerUrl && (
+              <div style={{
+                marginTop: 6, padding: "6px 10px", fontSize: 12,
+                background: "#0d3320", color: "#86efac",
+                border: "1px solid #166534", borderRadius: 4,
+                display: "flex", alignItems: "center", gap: 10, flexWrap: "wrap",
+              }}>
+                <span>
+                  Found a live runner at{" "}
+                  <code style={{ background: "#000", padding: "1px 4px", borderRadius: 3 }}>
+                    {status.discoveredUrl}
+                  </code>
+                </span>
+                <button
+                  type="button"
+                  onClick={runUrlAutoDetect}
+                  disabled={busy}
+                  style={{
+                    padding: "3px 10px", fontSize: 11, fontWeight: 600,
+                    background: "#10B981", color: "#052e1c",
+                    border: "0", borderRadius: 4, cursor: "pointer",
+                  }}
+                >
+                  Use this URL
+                </button>
+              </div>
+            )}
+          </div>
+        </div>
+
+        {/* Inline body — copy depends on state */}
+        {status.status === "not_installed" && (
+          <p style={{ fontSize: 13, opacity: 0.8, lineHeight: 1.55, marginBottom: 16 }}>
+            MatrixLab gives GitPilot an isolated sandbox for running code,
+            testing snippets, and executing agent actions safely. It will be
+            downloaded, started, and connected automatically.
+          </p>
+        )}
+
+        {(busy || progressStep) && (
+          <ProgressChecklist journey={journey} current={progressStep} />
+        )}
+
+        {status.status === "ready" && (
+          <Checklist
+            items={[
+              ["Installed", true],
+              ["Running", true],
+              ["Connection verified", true],
+              ["Set as active sandbox", status.activeSandbox === "matrixlab"],
+            ]}
+          />
+        )}
+
+        {/* Lifecycle disabled hint — friendly copy, admin detail under disclosure */}
+        {status.errorCode === "LIFECYCLE_DISABLED" && (
+          <div style={{
+            background: "#2a210d", border: "1px solid #854d0e",
+            borderRadius: 6, padding: 10, fontSize: 12,
+            color: "#fde68a", marginBottom: 12,
+          }}>
+            MatrixLab lifecycle automation is disabled. This GitPilot backend
+            was started with{" "}
+            <code style={{ background: "#1a1b26", padding: "1px 4px", borderRadius: 3 }}>
+              GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE=0
+            </code>{" "}
+            — restart it without that variable (the default is enabled), or
+            use Manual setup under Advanced options.
+          </div>
+        )}
+
+        {/* Technical details disclosure — only visible when there's an error */}
+        {status.technicalDetails && (status.status === "needs_attention" || status.status === "failed") && (
+          <details
+            open={showDetails}
+            onToggle={(e) => setShowDetails(e.target.open)}
+            style={{ marginBottom: 12 }}
+          >
+            <summary style={{ cursor: "pointer", fontSize: 12, color: "#9092b5" }}>
+              Technical details
+            </summary>
+            <pre style={{
+              marginTop: 8, padding: 10, background: "#000",
+              border: "1px solid #2c2d46", borderRadius: 4,
+              fontSize: 11, color: "#fca5a5",
+              fontFamily: "ui-monospace, monospace",
+              whiteSpace: "pre-wrap", overflow: "auto", maxHeight: 200,
+            }}>
+              {status.technicalDetails.expected &&
+                `Expected: ${status.technicalDetails.expected}\n`}
+              {status.technicalDetails.actual &&
+                `Actual:   ${status.technicalDetails.actual}\n`}
+              {status.technicalDetails.rawError &&
+                `\n${status.technicalDetails.rawError}`}
+            </pre>
+          </details>
+        )}
+
+        {/* Action buttons — state-aware. Reinstall is offered as a
+            normal recovery action (not buried in Advanced) once the
+            addon exists in some form; Open logs surfaces only when
+            there's something to diagnose. */}
+        {(() => {
+          const primary = PRIMARY_BY_STATUS[status.status] || PRIMARY_BY_STATUS.not_installed;
+          const canReinstall = status.installed === true ||
+            ["needs_attention", "failed", "ready"].includes(status.status);
+          const canSeeLogs = ["needs_attention", "failed"].includes(status.status);
+          return (
+            <div style={{ display: "flex", gap: 10, alignItems: "center", flexWrap: "wrap" }}>
+              <button
+                type="button"
+                onClick={onPrimary}
+                disabled={busy || primary.action === null}
+                style={{
+                  padding: "10px 20px", fontSize: 13, fontWeight: 600,
+                  background: busy ? "#1e3a5f" : "#3B82F6",
+                  color: "#fff", border: "none", borderRadius: 6,
+                  cursor: busy ? "wait" : "pointer",
+                  minWidth: 180,
+                }}
+              >
+                {primary.label}
+              </button>
+
+              {canReinstall && (
+                <button
+                  type="button"
+                  onClick={() => setReinstallConfirm(true)}
+                  disabled={busy}
+                  style={status.status === "ready" ? btnDanger : btnSecondary}
+                  title="Stop, remove, and pull a fresh copy of MatrixLab"
+                >
+                  Reinstall addon
+                </button>
+              )}
+
+              {canSeeLogs && (
+                <button type="button" onClick={openLogs} disabled={busy} style={btnSecondary}>
+                  Open logs
+                </button>
+              )}
+
+              {status.status === "ready" && (
+                <button type="button" onClick={runRepair} disabled={busy} style={btnSecondary}>
+                  Run test snippet
+                </button>
+              )}
+            </div>
+          );
+        })()}
+
+        {/* Logs viewer */}
+        {showLogs && (
+          <div style={{ marginTop: 14 }}>
+            <div style={{
+              display: "flex", justifyContent: "space-between",
+              alignItems: "baseline", marginBottom: 6,
+            }}>
+              <div style={{ fontSize: 12, fontWeight: 600, color: "#c3c5dd" }}>
+                MatrixLab logs
+                {logs?.container && (
+                  <span style={{
+                    marginLeft: 8, fontSize: 11, color: "#9092b5",
+                    fontFamily: "ui-monospace, monospace", fontWeight: 400,
+                  }}>
+                    · {logs.container}
+                  </span>
+                )}
+              </div>
+              <button
+                type="button"
+                onClick={openLogs}
+                disabled={busy}
+                style={{
+                  fontSize: 11, padding: "2px 8px",
+                  background: "transparent", color: "#9092b5",
+                  border: "1px solid #2c2d46", borderRadius: 4, cursor: "pointer",
+                }}
+              >
+                ↻ Refresh
+              </button>
+            </div>
+
+            {/* Friendly error + hint when the backend can't read logs.
+                We show the hint as an actionable next step (run
+                "make install-matrixlab") and list any matrixlab-
+                shaped containers we found so the user can see whether
+                the runner is up under a different name. */}
+            {logs?.ok === false && (
+              <div style={{
+                marginBottom: 6, padding: 10,
+                background: "#2a210d", border: "1px solid #854d0e",
+                borderRadius: 4, fontSize: 12, color: "#fde68a",
+              }}>
+                <div style={{ fontWeight: 600 }}>{logs.error || "Could not read MatrixLab logs."}</div>
+                {logs.hint && (
+                  <div style={{ marginTop: 4, fontSize: 11, color: "#fcd34d" }}>
+                    Next step:{" "}
+                    <code style={{
+                      background: "#000", padding: "1px 6px",
+                      borderRadius: 3, color: "#86efac",
+                    }}>
+                      {logs.hint}
+                    </code>
+                  </div>
+                )}
+                {Array.isArray(logs.candidates) && logs.candidates.length > 0 && (
+                  <div style={{ marginTop: 6, fontSize: 11 }}>
+                    Found other matrixlab-shaped containers:
+                    <ul style={{ margin: "4px 0 0", paddingLeft: 18 }}>
+                      {logs.candidates.map((c, i) => (
+                        <li key={i}>
+                          <code style={{ color: "#c3c5dd" }}>{c}</code>
+                        </li>
+                      ))}
+                    </ul>
+                    <div style={{ marginTop: 4, fontSize: 10, color: "#a1a1aa" }}>
+                      Set <code>GITPILOT_MATRIXLAB_CONTAINER</code> to use one of these,
+                      or run Reinstall to recreate the expected container.
+                    </div>
+                  </div>
+                )}
+                {logs.rawError && (
+                  <details style={{ marginTop: 6 }}>
+                    <summary style={{ cursor: "pointer", fontSize: 11, color: "#fbbf24" }}>
+                      docker stderr
+                    </summary>
+                    <pre style={{
+                      marginTop: 4, padding: 6, fontSize: 10,
+                      background: "#000", color: "#fca5a5",
+                      borderRadius: 4, whiteSpace: "pre-wrap",
+                    }}>
+                      {logs.rawError}
+                    </pre>
+                  </details>
+                )}
+              </div>
+            )}
+
+            <pre style={{
+              margin: 0, padding: 10, background: "#000",
+              border: "1px solid #2c2d46", borderRadius: 4,
+              fontSize: 11, color: "#D4D4D8",
+              fontFamily: "ui-monospace, monospace",
+              maxHeight: 220, overflow: "auto", whiteSpace: "pre-wrap",
+            }}>
+              {logs == null
+                ? "Loading logs…"
+                : (logs.lines && logs.lines.length > 0)
+                  ? logs.lines.join("\n")
+                  : (logs.ok === false ? "(no log output captured)" : "Loading logs…")}
+            </pre>
+          </div>
+        )}
+
+        {/* Advanced options — collapsed by default so first-time
+            users see the install/repair flow, not a wall of knobs.
+            Operators who need runner URL / token / image / network /
+            timeout / manual setup / local clone install / unsafe
+            modes click the disclosure to expand. */}
+        <details
+          open={showAdvanced}
+          onToggle={(e) => setShowAdvanced(e.target.open)}
+          style={{ marginTop: 14 }}
+        >
+          <summary style={{
+            cursor: "pointer", fontSize: 12, color: "#9092b5",
+            padding: "6px 0", listStyle: "none",
+          }}>
+            Advanced options
+          </summary>
+          <AdvancedOptions
+            advanced={advanced}
+            tokenInput={tokenInput}
+            setTokenInput={setTokenInput}
+            onUpdate={updateAdvanced}
+            disabled={busy}
+            onLocalStatus={(data) => {
+              setStatus(data);
+              refreshAdvanced();
+            }}
+          />
+        </details>
+
+        {reinstallConfirm && (
+          <ReinstallConfirm
+            wipe={reinstallWipe}
+            setWipe={setReinstallWipe}
+            onCancel={() => {
+              setReinstallConfirm(false);
+              setReinstallWipe(false);
+            }}
+            onConfirm={() => {
+              const wipe = reinstallWipe;
+              setReinstallConfirm(false);
+              setReinstallWipe(false);
+              runReinstall(wipe);
+            }}
+          />
+        )}
+      </ModalShell>
+    </Backdrop>
+  );
+}
+
+function ReinstallConfirm({ wipe, setWipe, onCancel, onConfirm }) {
+  // Modal-in-modal stacked at zIndex 110 (Backdrop is 100).  Apes
+  // GitHub's "Are you absolutely sure?" pattern: explicit destructive
+  // checkbox stays off by default so a misclick can't wipe images.
+  return (
+    <div onClick={onCancel} style={{
+      position: "fixed", inset: 0, background: "rgba(0,0,0,0.65)",
+      display: "flex", alignItems: "center", justifyContent: "center",
+      zIndex: 110,
+    }}>
+      <div onClick={(e) => e.stopPropagation()} style={{
+        width: "min(440px, 92vw)", background: "#1a1b26",
+        border: "1px solid #2a2b36", borderRadius: 10, padding: 20,
+        color: "#e6e8ff",
+      }}>
+        <h4 style={{ margin: "0 0 6px", fontSize: 15 }}>Reinstall MatrixLab Addon?</h4>
+        <p style={{ fontSize: 13, opacity: 0.8, lineHeight: 1.55, marginBottom: 14 }}>
+          This will stop MatrixLab, remove the current addon container, download a
+          fresh copy, start it again, and reconnect GitPilot. Your GitPilot
+          settings will be kept.
+        </p>
+        <label style={{
+          display: "flex", gap: 8, alignItems: "flex-start",
+          padding: "8px 10px", borderRadius: 6, marginBottom: 14,
+          border: "1px solid #2c2d46", background: "#0e0f24",
+          fontSize: 12, cursor: "pointer",
+        }}>
+          <input
+            type="checkbox"
+            checked={wipe}
+            onChange={(e) => setWipe(e.target.checked)}
+            style={{ marginTop: 2 }}
+          />
+          <span>
+            <strong style={{ color: "#fde68a" }}>Also remove local MatrixLab data</strong>
+            <span style={{ display: "block", color: "#9092b5", marginTop: 2 }}>
+              Deletes the cached MatrixLab runner image. Sandbox images and
+              workspace data are preserved.
+            </span>
+          </span>
+        </label>
+        <div style={{ display: "flex", gap: 8, justifyContent: "flex-end" }}>
+          <button type="button" onClick={onCancel} style={btnSecondary}>Cancel</button>
+          <button type="button" onClick={onConfirm} style={wipe ? btnDanger : btnPrimary}>
+            {wipe ? "Reinstall and remove data" : "Reinstall MatrixLab"}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function ProgressChecklist({ journey, current }) {
+  // Pick the right stage list for the journey in flight; default to
+  // the install list (the most informative one) when no journey is
+  // active yet.  Once ``current`` advances past the kickoff key, the
+  // visited rows render with a ✓.
+  const steps = PROGRESS_STEPS[journey] || PROGRESS_STEPS.install;
+  const phaseIndex = current ? Math.max(0, steps.findIndex(s => s.key === current)) : 0;
+  return (
+    <div style={{ marginBottom: 14 }}>
+      {steps.map((s, i) => {
+        const done = i < phaseIndex;
+        const active = i === phaseIndex;
+        return (
+          <div key={s.key} style={{
+            display: "flex", alignItems: "center", gap: 8,
+            fontSize: 12, padding: "3px 0",
+            color: done ? "#86efac" : active ? "#e6e8ff" : "#9092b5",
+          }}>
+            <span style={{ width: 16, textAlign: "center" }}>
+              {done ? "✓" : active ? "⏳" : "○"}
+            </span>
+            {s.label}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+function Checklist({ items }) {
+  return (
+    <div style={{ marginBottom: 14 }}>
+      {items.map(([label, ok]) => (
+        <div key={label} style={{
+          display: "flex", alignItems: "center", gap: 8,
+          fontSize: 12, padding: "3px 0",
+          color: ok ? "#86efac" : "#9092b5",
+        }}>
+          <span style={{ width: 16, textAlign: "center" }}>{ok ? "✓" : "○"}</span>
+          {label}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function LocalCloneSection({ disabled, onStatus }) {
+  const [native, setNative] = useState(null);
+  const [busy, setBusy] = useState(null); // "install" | "start" | "stop"
+
+  const refresh = useCallback(async () => {
+    try {
+      const r = await fetch(apiUrl("/api/matrixlab/native/status"));
+      setNative(await r.json());
+    } catch (err) {
+      // non-fatal — leave section empty
+    }
+  }, []);
+
+  useEffect(() => {
+    refresh();
+  }, [refresh]);
+
+  const runAction = useCallback(async (action) => {
+    setBusy(action);
+    try {
+      const path = {
+        install: "/api/matrixlab/install_local",
+        start: "/api/matrixlab/start_local",
+        stop: "/api/matrixlab/stop_local",
+      }[action];
+      const r = await fetch(apiUrl(path), { method: "POST" });
+      const data = await r.json();
+      onStatus?.(data);
+    } finally {
+      setBusy(null);
+      refresh();
+    }
+  }, [onStatus, refresh]);
+
+  if (!native) return null;
+
+  return (
+    <details style={{ marginTop: 12 }}>
+      <summary style={{ cursor: "pointer", fontSize: 11, color: "#9092b5" }}>
+        Local clone install (no Docker for the runner itself)
+      </summary>
+      <div style={{ marginTop: 8, fontSize: 11, color: "#9092b5", lineHeight: 1.6 }}>
+        Clones MatrixLab into <code style={{ color: "#c3c5dd" }}>{native.local_dir}</code>,
+        creates a dedicated Python virtualenv, and runs <code style={{ color: "#c3c5dd" }}>uvicorn app.main:app</code>
+        from the runner directory. The Runner still spawns per-language sandboxes
+        via Docker, so the host needs <code style={{ color: "#c3c5dd" }}>docker</code>{" "}
+        on PATH for code execution.
+      </div>
+      <div style={{ marginTop: 10, display: "flex", flexWrap: "wrap", gap: 8 }}>
+        <span style={{
+          display: "inline-flex", alignItems: "center", gap: 6,
+          fontSize: 11, padding: "2px 10px", borderRadius: 10,
+          background: native.running ? "#0d3320" : native.installed ? "#3d2d11" : "#374151",
+          color:      native.running ? "#86efac" : native.installed ? "#fde68a" : "#d1d5db",
+        }}>
+          <span style={{
+            width: 6, height: 6, borderRadius: "50%",
+            background: native.running ? "#10B981" : native.installed ? "#f59e0b" : "#9ca3af",
+          }} />
+          {native.running ? "Running (PID " + native.pid + ")"
+            : native.installed ? "Installed · stopped"
+            : "Not installed"}
+        </span>
+        {!native.installed && (
+          <button
+            type="button"
+            disabled={disabled || busy != null || !native.lifecycleEnabled}
+            onClick={() => runAction("install")}
+            style={btnPrimarySmall}
+          >
+            {busy === "install" ? "Cloning + installing…" : "Clone and install"}
+          </button>
+        )}
+        {native.installed && !native.running && (
+          <button
+            type="button"
+            disabled={disabled || busy != null || !native.lifecycleEnabled}
+            onClick={() => runAction("start")}
+            style={btnPrimarySmall}
+          >
+            {busy === "start" ? "Starting…" : "Start runner"}
+          </button>
+        )}
+        {native.running && (
+          <button
+            type="button"
+            disabled={disabled || busy != null || !native.lifecycleEnabled}
+            onClick={() => runAction("stop")}
+            style={btnSecondarySmall}
+          >
+            {busy === "stop" ? "Stopping…" : "Stop runner"}
+          </button>
+        )}
+        <button
+          type="button"
+          disabled={busy != null}
+          onClick={refresh}
+          style={btnSecondarySmall}
+        >
+          Refresh
+        </button>
+      </div>
+      {!native.lifecycleEnabled && (
+        <div style={{
+          marginTop: 8, padding: "6px 8px",
+          background: "#2a210d", border: "1px solid #854d0e",
+          borderRadius: 4, fontSize: 11, color: "#fde68a",
+        }}>
+          Local clone install needs lifecycle automation enabled on the GitPilot
+          backend.
+        </div>
+      )}
+    </details>
+  );
+}
+
+function AdvancedOptions({ advanced, tokenInput, setTokenInput, onUpdate, disabled, onLocalStatus }) {
+  if (!advanced) return null;
+  return (
+    <div style={{
+      marginTop: 14, padding: 12,
+      background: "#0e0f24", border: "1px solid #2c2d46",
+      borderRadius: 6,
+    }}>
+      <div style={{ fontSize: 12, fontWeight: 600, marginBottom: 10, color: "#c3c5dd" }}>
+        Advanced options
+      </div>
+      <div style={{ display: "grid", gridTemplateColumns: "120px 1fr", gap: 8, alignItems: "center" }}>
+        <label style={fieldLabel}>Runner URL</label>
+        <input
+          type="text"
+          defaultValue={advanced.matrixlab_url || ""}
+          onBlur={(e) => onUpdate({ matrixlab_url: e.target.value })}
+          placeholder="http://localhost:8765"
+          disabled={disabled}
+          style={fieldInput}
+        />
+
+        <label style={fieldLabel}>Bearer token</label>
+        <div style={{ display: "flex", gap: 6 }}>
+          <input
+            type="password"
+            value={tokenInput}
+            onChange={(e) => setTokenInput(e.target.value)}
+            placeholder={advanced.has_token ? "•••••••• (saved)" : "Optional"}
+            disabled={disabled}
+            style={{ ...fieldInput, flex: 1 }}
+          />
+          <button
+            type="button"
+            onClick={() => onUpdate({ matrixlab_token: tokenInput })}
+            disabled={disabled}
+            style={btnSecondary}
+          >
+            Save token
+          </button>
+        </div>
+
+        <label style={fieldLabel}>Default image</label>
+        <input
+          type="text"
+          defaultValue={advanced.matrixlab_image || ""}
+          onBlur={(e) => onUpdate({ matrixlab_image: e.target.value })}
+          placeholder="matrixlab-python"
+          disabled={disabled}
+          style={fieldInput}
+        />
+
+        <label style={fieldLabel}>Network access</label>
+        <label style={{ display: "flex", gap: 6, alignItems: "center", fontSize: 12, color: "#c3c5dd" }}>
+          <input
+            type="checkbox"
+            checked={!!advanced.allow_network}
+            disabled={disabled}
+            onChange={(e) => onUpdate({ allow_network: e.target.checked })}
+          />
+          Allow network egress
+        </label>
+
+        <label style={fieldLabel}>Timeout</label>
+        <div style={{ display: "flex", alignItems: "center", gap: 6 }}>
+          <input
+            type="number"
+            min={1}
+            max={600}
+            defaultValue={advanced.timeout_sec || 120}
+            onBlur={(e) => onUpdate({ timeout_sec: Number(e.target.value) || 120 })}
+            disabled={disabled}
+            style={{ ...fieldInput, width: 80 }}
+          />
+          <span style={{ fontSize: 11, color: "#9092b5" }}>seconds</span>
+        </div>
+      </div>
+
+      <LocalCloneSection disabled={disabled} onStatus={onLocalStatus} />
+
+      <details style={{ marginTop: 12 }}>
+        <summary style={{ cursor: "pointer", fontSize: 11, color: "#9092b5" }}>
+          Manual setup
+        </summary>
+        <pre style={{
+          margin: "8px 0 0", padding: 10, background: "#000",
+          border: "1px solid #2c2d46", borderRadius: 4,
+          fontSize: 11, color: "#D4D4D8",
+          fontFamily: "ui-monospace, monospace",
+        }}>{`# In a MatrixLab checkout:
+docker compose up -d
+
+# Or directly:
+docker run -d --name gitpilot-matrixlab \\
+  -p 8000:8000 \\
+  -v /var/run/docker.sock:/var/run/docker.sock \\
+  ruslanmv/matrixlab-runner:latest`}</pre>
+      </details>
+
+      <details style={{ marginTop: 12 }}>
+        <summary style={{ cursor: "pointer", fontSize: 11, color: "#9092b5" }}>
+          Developer options · Unsafe modes
+        </summary>
+        <div style={{ marginTop: 8, fontSize: 11, color: "#fca5a5" }}>
+          Pass-through runs code directly on the host without isolation. Use
+          only for local development.
+        </div>
+      </details>
+    </div>
+  );
+}
+
+function Backdrop({ children, onClose }) {
+  return (
+    <div
+      onClick={onClose}
+      style={{
+        position: "fixed", inset: 0,
+        background: "rgba(0,0,0,0.6)",
+        display: "flex", alignItems: "center", justifyContent: "center",
+        zIndex: 100,
+      }}
+    >
+      <div onClick={(e) => e.stopPropagation()}>{children}</div>
+    </div>
+  );
+}
+
+function ModalShell({ title, subtitle, onClose, children }) {
+  return (
+    <div style={{
+      width: "min(640px, 92vw)",
+      maxHeight: "90vh", overflow: "auto",
+      background: "#1a1b26",
+      border: "1px solid #2a2b36",
+      borderRadius: 10,
+      padding: 20,
+      color: "#e6e8ff",
+    }}>
+      <div style={{ display: "flex", justifyContent: "space-between", alignItems: "flex-start", marginBottom: 4 }}>
+        <h3 style={{ margin: 0, fontSize: 18 }}>{title}</h3>
+        <button
+          type="button"
+          onClick={onClose}
+          style={{
+            background: "transparent", border: "none",
+            color: "#9092b5", cursor: "pointer", fontSize: 18,
+          }}
+          aria-label="Close"
+        >
+          ✕
+        </button>
+      </div>
+      <div style={{ fontSize: 12, color: "#9092b5", marginBottom: 16 }}>{subtitle}</div>
+      {children}
+    </div>
+  );
+}
+
+const btnSecondary = {
+  padding: "8px 14px",
+  fontSize: 12,
+  background: "transparent",
+  color: "#c3c5dd",
+  border: "1px solid #2c2d46",
+  borderRadius: 6,
+  cursor: "pointer",
+};
+
+const btnPrimary = {
+  padding: "8px 14px",
+  fontSize: 12,
+  fontWeight: 600,
+  background: "#3B82F6",
+  color: "#fff",
+  border: "none",
+  borderRadius: 6,
+  cursor: "pointer",
+};
+
+// "Reinstall and remove data" is destructive — surface it with a
+// danger tone so the operator pauses before clicking.
+const btnDanger = {
+  padding: "8px 14px",
+  fontSize: 12,
+  fontWeight: 600,
+  background: "#7f1d1d",
+  color: "#fecaca",
+  border: "1px solid #991b1b",
+  borderRadius: 6,
+  cursor: "pointer",
+};
+
+const btnGhost = {
+  padding: "8px 14px",
+  fontSize: 12,
+  background: "transparent",
+  color: "#9092b5",
+  border: "none",
+  cursor: "pointer",
+};
+
+const fieldLabel = { fontSize: 12, color: "#c3c5dd" };
+const fieldInput = {
+  fontSize: 12, padding: "4px 6px",
+  background: "#14152a", color: "#e6e8ff",
+  border: "1px solid #2c2d46", borderRadius: 4,
+};
+
+const btnPrimarySmall = {
+  padding: "4px 10px", fontSize: 11, fontWeight: 600,
+  background: "#3B82F6", color: "#fff",
+  border: "none", borderRadius: 4, cursor: "pointer",
+};
+const btnSecondarySmall = {
+  padding: "4px 10px", fontSize: 11,
+  background: "transparent", color: "#c3c5dd",
+  border: "1px solid #2c2d46", borderRadius: 4, cursor: "pointer",
+};
diff --git a/frontend/components/AdminTabs/SandboxTab.jsx b/frontend/components/AdminTabs/SandboxTab.jsx
new file mode 100644
index 0000000..b006b4b
--- /dev/null
+++ b/frontend/components/AdminTabs/SandboxTab.jsx
@@ -0,0 +1,218 @@
+// frontend/components/AdminTabs/SandboxTab.jsx
+import React, { useCallback, useEffect, useState } from "react";
+import { apiUrl } from "../../utils/api.js";
+import MatrixLabInstallModal from "./MatrixLabInstallModal.jsx";
+
+/**
+ * Sandbox tab — enterprise default view.
+ *
+ * Surfaces a single MatrixLab addon card plus a clean Local-sandbox
+ * card. Implementation knobs (Runner URL, token, image, network,
+ * timeout, pass-through, lifecycle env flag) live behind the install
+ * modal's Advanced disclosure — the primary view never shows them.
+ *
+ * Status pill is driven off /api/matrixlab/status so we never end up
+ * with the "Unreachable + Running" contradiction the legacy panel
+ * produced.
+ */
+
+function StatusPill({ status }) {
+  const map = {
+    not_installed:    { label: "Not installed",    bg: "#374151", fg: "#d1d5db" },
+    installing:       { label: "Installing",       bg: "#0d3320", fg: "#86efac" },
+    starting:         { label: "Starting",         bg: "#0d3320", fg: "#86efac" },
+    stopping:         { label: "Stopping",         bg: "#3d2d11", fg: "#fde68a" },
+    checking:         { label: "Checking",         bg: "#0d3320", fg: "#86efac" },
+    ready:            { label: "Ready",            bg: "#0d3320", fg: "#86efac" },
+    needs_attention:  { label: "Needs attention",  bg: "#3d2d11", fg: "#fde68a" },
+    failed:           { label: "Failed",           bg: "#3d1111", fg: "#fca5a5" },
+  };
+  const pill = map[status] || map.not_installed;
+  return (
+    <span style={{
+      display: "inline-flex", alignItems: "center", gap: 6,
+      fontSize: 11, fontWeight: 600, padding: "2px 10px", borderRadius: 12,
+      background: pill.bg, color: pill.fg,
+    }}>
+      <span style={{ width: 6, height: 6, borderRadius: "50%", background: pill.fg }} />
+      {pill.label}
+    </span>
+  );
+}
+
+export default function SandboxTab({ showToast }) {
+  const [matrixlab, setMatrixlab] = useState(null);  // /api/matrixlab/status payload
+  const [sandbox, setSandbox] = useState(null);      // /api/sandbox/status payload
+  const [loading, setLoading] = useState(true);
+  const [modalOpen, setModalOpen] = useState(false);
+
+  const load = useCallback(async () => {
+    try {
+      const [ml, sb] = await Promise.all([
+        fetch(apiUrl("/api/matrixlab/status")).then((r) => r.json()).catch(() => null),
+        fetch(apiUrl("/api/sandbox/status")).then((r) => r.json()).catch(() => null),
+      ]);
+      setMatrixlab(ml);
+      setSandbox(sb);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  const useLocal = useCallback(async () => {
+    try {
+      const r = await fetch(apiUrl("/api/sandbox/config"), {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ backend: "subprocess" }),
+      });
+      const data = await r.json();
+      if (r.ok) {
+        setSandbox(data);
+        showToast?.("Switched to Local sandbox", "Code runs in a host subprocess with a workspace jail.");
+      }
+    } catch (err) {
+      // surfaced through the next load()
+    }
+  }, [showToast]);
+
+  if (loading) {
+    return (
+      <div>
+        <h3 style={{ marginBottom: 16 }}>Sandbox</h3>
+        <div style={{
+          background: "#1a1b26", borderRadius: 8,
+          padding: "40px 20px", textAlign: "center",
+          border: "1px solid #2a2b36", fontSize: 12, opacity: 0.6,
+        }}>
+          Loading sandbox status…
+        </div>
+      </div>
+    );
+  }
+
+  const activeBackend = (sandbox?.backend || "subprocess").toLowerCase();
+  const mlStatus = matrixlab?.status || "not_installed";
+
+  return (
+    <div>
+      <h3 style={{ marginBottom: 8 }}>Sandbox</h3>
+      <p style={{ fontSize: 12, opacity: 0.7, marginBottom: 20 }}>
+        Pick where GitPilot executes code: the local subprocess sandbox or
+        the MatrixLab Runner. The choice applies to the Run button on chat
+        code blocks and the agent's EXECUTE action.
+      </p>
+
+      {/* MatrixLab addon card */}
+      <div style={cardStyle}>
+        <div style={{ display: "flex", alignItems: "flex-start", gap: 14 }}>
+          <div style={{ flex: 1 }}>
+            <div style={{ display: "flex", alignItems: "center", gap: 10, marginBottom: 6 }}>
+              <h4 style={{ margin: 0, fontSize: 15 }}>MatrixLab Addon</h4>
+              <StatusPill status={mlStatus} />
+              {activeBackend === "matrixlab" && (
+                <span style={{
+                  fontSize: 10, fontWeight: 600,
+                  padding: "1px 6px", borderRadius: 8,
+                  background: "#1e3a5f", color: "#93c5fd",
+                  border: "1px solid #3B82F6",
+                }}>ACTIVE</span>
+              )}
+            </div>
+            <p style={{ fontSize: 12, opacity: 0.75, margin: 0, lineHeight: 1.55 }}>
+              Run code safely in isolated, temporary containers. Recommended
+              for enterprise deployments and untrusted code.
+            </p>
+            {mlStatus !== "not_installed" && matrixlab?.message && (
+              <p style={{ fontSize: 11, opacity: 0.6, marginTop: 6, marginBottom: 0 }}>
+                {matrixlab.message}
+              </p>
+            )}
+          </div>
+          <button
+            type="button"
+            onClick={() => setModalOpen(true)}
+            style={{
+              padding: "8px 16px", fontSize: 12, fontWeight: 600,
+              background: mlStatus === "ready" ? "transparent" : "#3B82F6",
+              color: mlStatus === "ready" ? "#93c5fd" : "#fff",
+              border: mlStatus === "ready" ? "1px solid #3B82F6" : "none",
+              borderRadius: 6, cursor: "pointer",
+              whiteSpace: "nowrap",
+            }}
+          >
+            {mlStatus === "ready" ? "Manage" :
+             mlStatus === "needs_attention" ? "Fix connection" :
+             mlStatus === "failed" ? "Retry install" :
+             "Install and Start"}
+          </button>
+        </div>
+      </div>
+
+      {/* Local sandbox card */}
+      <div style={cardStyle}>
+        <div style={{ display: "flex", alignItems: "flex-start", gap: 14 }}>
+          <div style={{ flex: 1 }}>
+            <div style={{ display: "flex", alignItems: "center", gap: 10, marginBottom: 6 }}>
+              <h4 style={{ margin: 0, fontSize: 15 }}>Local sandbox</h4>
+              {activeBackend === "subprocess" && (
+                <span style={{
+                  fontSize: 10, fontWeight: 600,
+                  padding: "1px 6px", borderRadius: 8,
+                  background: "#1e3a5f", color: "#93c5fd",
+                  border: "1px solid #3B82F6",
+                }}>ACTIVE</span>
+              )}
+            </div>
+            <p style={{ fontSize: 12, opacity: 0.75, margin: 0, lineHeight: 1.55 }}>
+              Host subprocess with a workspace jail. No Docker required —
+              best for trying simple snippets quickly.
+            </p>
+          </div>
+          <button
+            type="button"
+            onClick={useLocal}
+            disabled={activeBackend === "subprocess"}
+            style={{
+              padding: "8px 16px", fontSize: 12, fontWeight: 600,
+              background: activeBackend === "subprocess" ? "transparent" : "#374151",
+              color: activeBackend === "subprocess" ? "#9092b5" : "#fff",
+              border: activeBackend === "subprocess" ? "1px solid #2c2d46" : "none",
+              borderRadius: 6,
+              cursor: activeBackend === "subprocess" ? "default" : "pointer",
+              whiteSpace: "nowrap",
+            }}
+          >
+            {activeBackend === "subprocess" ? "Active" : "Use Local"}
+          </button>
+        </div>
+      </div>
+
+      {modalOpen && (
+        <MatrixLabInstallModal
+          onClose={() => {
+            setModalOpen(false);
+            load();
+          }}
+          onActivated={(data) => {
+            showToast?.("MatrixLab ready", "Code now runs in MatrixLab sandboxes.");
+            // Refresh both panels so the ACTIVE badge moves to the addon card.
+            load();
+          }}
+        />
+      )}
+    </div>
+  );
+}
+
+const cardStyle = {
+  background: "#1a1b26",
+  borderRadius: 8,
+  padding: 16,
+  border: "1px solid #2a2b36",
+  marginBottom: 12,
+};
diff --git a/frontend/components/AdminTabs/index.js b/frontend/components/AdminTabs/index.js
index 44e9547..4775db1 100644
--- a/frontend/components/AdminTabs/index.js
+++ b/frontend/components/AdminTabs/index.js
@@ -7,3 +7,4 @@ export { default as MCPServersTab } from "./MCPServersTab.jsx";
 export { default as SkillsTab } from "./SkillsTab.jsx";
 export { default as SessionsTab } from "./SessionsTab.jsx";
 export { default as AdvancedTab } from "./AdvancedTab.jsx";
+export { default as SandboxTab } from "./SandboxTab.jsx";
diff --git a/frontend/components/AssistantMessage.jsx b/frontend/components/AssistantMessage.jsx
index ec75621..9a19965 100644
--- a/frontend/components/AssistantMessage.jsx
+++ b/frontend/components/AssistantMessage.jsx
@@ -1,177 +1,429 @@
-import React from "react";
+import React, { useState } from "react";
 import PlanView from "./PlanView.jsx";
 import RunnableCodeBlock, { splitFences } from "./RunnableCodeBlock.jsx";
+import ExecutionPlanCard from "./ExecutionPlanCard.jsx";
 
-export default function AssistantMessage({ answer, plan, executionLog, planStatus }) {
-  // ``planStatus`` is optional metadata about the lifecycle of the plan
-  // attached to this message: "executed" | "rejected" | null.  It drives
-  // the badge next to the Action Plan header so the user can tell at a
-  // glance, in chat history, whether a previous plan was approved or
-  // dismissed.  Defaults to null (no badge) to keep the legacy render
-  // path untouched.
-  const styles = {
-    container: {
-      marginBottom: "20px",
-      padding: "20px",
-      backgroundColor: "#18181B", // Zinc-900
-      borderRadius: "12px",
-      border: "1px solid #27272A", // Zinc-800
-      color: "#F4F4F5", // Zinc-100
-      fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
-      boxShadow: "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)",
-    },
-    section: {
-      marginBottom: "20px",
-    },
-    lastSection: {
-      marginBottom: "0",
-    },
-    header: {
-      display: "flex",
-      alignItems: "center",
-      marginBottom: "12px",
-      paddingBottom: "8px",
-      borderBottom: "1px solid #3F3F46", // Zinc-700
-    },
-    title: {
-      fontSize: "12px",
-      fontWeight: "600",
-      textTransform: "uppercase",
-      letterSpacing: "0.05em",
-      color: "#A1A1AA", // Zinc-400
-      margin: 0,
-    },
-    content: {
-      fontSize: "14px",
-      lineHeight: "1.6",
-      whiteSpace: "pre-wrap",
-    },
-    executionList: {
-      listStyle: "none",
-      padding: 0,
-      margin: 0,
-      display: "flex",
-      flexDirection: "column",
-      gap: "8px",
-    },
-    executionStep: {
-      display: "flex",
-      flexDirection: "column",
-      gap: "4px",
-      padding: "10px",
-      backgroundColor: "#09090B", // Zinc-950
-      borderRadius: "6px",
-      border: "1px solid #27272A",
-      fontSize: "13px",
-    },
-    stepNumber: {
-      fontSize: "11px",
-      fontWeight: "600",
-      color: "#10B981", // Emerald-500
-      textTransform: "uppercase",
-    },
-    stepSummary: {
-      color: "#D4D4D8", // Zinc-300
-      fontFamily: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace",
-    },
+export default function AssistantMessage({
+  answer,
+  plan,
+  executionLog,
+  planStatus,
+  owner,
+  repo,
+  onApproveExecution,
+  nextActions,
+  relatedPlan,
+  diff,
+  branch,
+}) {
+  // Approval-first sandbox: when the planner returns an execution_plan,
+  // render the green ExecutionPlanCard instead of the orange Action Plan.
+  const executionPlan = plan?.execution_plan || null;
+  const [runResult, setRunResult] = useState(null);
+  const [runError, setRunError] = useState(null);
+  const [runBusy, setRunBusy] = useState(false);
+
+  const approveExecution = async (ep) => {
+    if (onApproveExecution) {
+      onApproveExecution(ep, plan);
+      return;
+    }
+    setRunBusy(true);
+    setRunError(null);
+    setRunResult(null);
+    try {
+      const body = ep.file
+        ? { language: ep.language, code: null }
+        : { language: ep.language, code: ep.inline_code, timeout_sec: ep.timeout_sec };
+      const res = await fetch("/api/sandbox/run", {
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      });
+      const data = await res.json();
+      if (!res.ok) setRunError(data.detail || `HTTP ${res.status}`);
+      else setRunResult(data);
+    } catch (e) { setRunError(e.message); }
+    finally { setRunBusy(false); }
   };
 
-  // Only show Action Plan section when there are actual file actions.
-  // For Lite Mode Q&A responses (all steps have 0 files), the plan
-  // just duplicates the answer — hiding it avoids showing the same text 3x.
-  const hasFileActions = plan?.steps?.some(s => s.files?.length > 0);
+  const hasFileActions = plan?.steps?.some((s) => s.files?.length > 0);
+  const answerText = typeof answer === "string" ? answer.trim() : "";
+  // Suppress the answer prose when it would just duplicate what the
+  // plan card or success receipt already says.
+  const showAnswerProse =
+    answerText &&
+    !executionLog &&
+    !(plan && hasFileActions && !executionPlan && answerText === plan.summary);
 
   return (
-    <div className="chat-message-ai" style={styles.container}>
-      {/* Answer section.  ``splitFences`` cuts the answer at fenced code
-          blocks so each runnable snippet gets its own RunnableCodeBlock
-          (with a per-block Run button); the surrounding prose still
-          renders as the existing pre-wrapped paragraph. */}
-      <section style={styles.section}>
-        <header style={styles.header}>
-          <h3 style={styles.title}>Answer</h3>
-        </header>
-        <div style={styles.content}>
-          {splitFences(answer).map((seg, i) =>
+    <div className="chat-message-ai assistant-card">
+      {/* Free-form answer prose. Rendered without a section header so
+          short answers feel like a chat reply, not a debug log. */}
+      {showAnswerProse && (
+        <div className="assistant-answer">
+          {splitFences(answerText).map((seg, i) =>
             seg.type === "code" ? (
-              <RunnableCodeBlock key={i} language={seg.language} code={seg.code} />
+              <RunnableCodeBlock
+                key={i}
+                language={seg.language}
+                code={seg.code}
+                owner={owner}
+                repo={repo}
+              />
             ) : (
-              <p key={i} style={{ margin: "0 0 8px" }}>{seg.value}</p>
-            )
+              <p key={i} className="assistant-answer__p">
+                {seg.value}
+              </p>
+            ),
           )}
         </div>
-      </section>
-
-      {/* Action Plan section — only when there are file changes */}
-      {plan && hasFileActions && (
-        <section style={styles.section}>
-          <header style={{ ...styles.header, display: "flex", alignItems: "center", gap: "10px" }}>
-            <h3 style={{ ...styles.title, color: "#D95C3D", margin: 0 }}>Action Plan</h3>
-            {planStatus === "executed" && (
-              <span
-                style={{
-                  display: "inline-flex",
-                  alignItems: "center",
-                  gap: "4px",
-                  fontSize: "11px",
-                  fontWeight: 600,
-                  color: "#10B981",
-                  border: "1px solid rgba(16, 185, 129, 0.35)",
-                  background: "rgba(16, 185, 129, 0.08)",
-                  borderRadius: "6px",
-                  padding: "2px 6px",
-                  letterSpacing: "0.02em",
-                }}
-                title="This plan was approved and executed."
-              >
-                ✓ Executed
-              </span>
-            )}
-            {planStatus === "rejected" && (
-              <span
-                style={{
-                  display: "inline-flex",
-                  alignItems: "center",
-                  gap: "4px",
-                  fontSize: "11px",
-                  fontWeight: 600,
-                  color: "#9CA3AF",
-                  border: "1px solid rgba(156, 163, 175, 0.35)",
-                  background: "rgba(156, 163, 175, 0.08)",
-                  borderRadius: "6px",
-                  padding: "2px 6px",
-                  letterSpacing: "0.02em",
-                }}
-                title="This plan was rejected. No files were changed."
-              >
-                ✕ Rejected
+      )}
+
+      {/* Sandbox approval card. */}
+      {executionPlan && (
+        <div className="assistant-block">
+          <ExecutionPlanCard
+            plan={executionPlan}
+            variant="full"
+            busy={runBusy}
+            onApprove={approveExecution}
+            onCancel={() => { /* no-op */ }}
+          />
+          {runError && (
+            <div className="assistant-run-error">Run error: {runError}</div>
+          )}
+          {runResult && (
+            <pre className="assistant-run-output">
+              {runResult.stdout || runResult.stderr || "(no output)"}
+            </pre>
+          )}
+        </div>
+      )}
+
+      {/* Proposed execution plan — only when there are file changes
+          and no execution log is present yet. */}
+      {plan && hasFileActions && !executionPlan && !executionLog && (
+        <div className="assistant-block">
+          <PlanView plan={plan} planStatus={planStatus} />
+        </div>
+      )}
+
+      {/* Completed execution receipt. */}
+      {executionLog && (
+        <SuccessReceipt
+          executionLog={executionLog}
+          relatedPlan={relatedPlan}
+          owner={owner}
+          repo={repo}
+          branch={branch}
+          diff={diff}
+          nextActions={nextActions}
+        />
+      )}
+
+      {/* Next actions when there is no execution log (e.g. simple answers). */}
+      {!executionLog && Array.isArray(nextActions) && nextActions.length > 0 && (
+        <div className="assistant-next-row">
+          {nextActions.map((a, i) => (
+            <NextActionButton key={i} action={a} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function NextActionButton({ action }) {
+  const onClick = () => {
+    if (action.kind === "run_file" && action.payload?.file) {
+      window.dispatchEvent(
+        new CustomEvent("gitpilot:run-file", {
+          detail: { path: action.payload.file },
+        }),
+      );
+    } else if (action.kind === "open_workspace" && action.payload?.file) {
+      window.dispatchEvent(
+        new CustomEvent("gitpilot:open-workspace", {
+          detail: { path: action.payload.file },
+        }),
+      );
+    } else if (action.kind === "open_in_canvas" && action.payload?.file) {
+      window.dispatchEvent(
+        new CustomEvent("gitpilot:open-in-canvas", {
+          detail: { path: action.payload.file },
+        }),
+      );
+    }
+  };
+
+  const isPrimary = action.kind === "run_file";
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className={
+        "next-action-btn" +
+        (isPrimary ? " next-action-btn--primary" : " next-action-btn--ghost")
+      }
+    >
+      <span className="next-action-btn__glyph" aria-hidden="true">
+        {action.kind === "run_file"
+          ? "▶"
+          : action.kind === "open_workspace"
+          ? "📂"
+          : "⊞"}
+      </span>
+      {action.label}
+    </button>
+  );
+}
+
+function SuccessReceipt({
+  executionLog,
+  relatedPlan,
+  owner,
+  repo,
+  branch,
+  diff,
+  nextActions,
+}) {
+  const steps = executionLog?.steps || [];
+  const totalSteps = steps.length;
+
+  // Aggregate every file action across steps so "Files changed (N)" can
+  // be a single top-level section instead of per-step duplication.
+  const allFiles = [];
+  if (relatedPlan?.steps?.length) {
+    for (const s of relatedPlan.steps) {
+      for (const f of s.files || []) {
+        if (f.action !== "INDEX") allFiles.push(f);
+      }
+    }
+  }
+  const totalDuration = steps.reduce((acc, s) => {
+    return acc + (s.executions || []).reduce(
+      (a, ex) => a + (typeof ex.duration_ms === "number" ? ex.duration_ms : 0),
+      0,
+    );
+  }, 0);
+
+  // Short headline outcome lines (max 2): "Created X", "Modified Y".
+  const headlines = [];
+  for (const action of ["CREATE", "MODIFY", "DELETE"]) {
+    for (const f of allFiles) {
+      if (f.action === action && headlines.length < 2) {
+        headlines.push({ verb: verbFor(action), path: f.path });
+      }
+    }
+  }
+
+  // The bottom-bar already owns Create PR. Only show a pointer text here
+  // when there is a meaningful PR path (branch + file changes).
+  const hasPRPath = Boolean(branch && allFiles.length > 0);
+
+  // Filter out create-PR-style next-actions (handled by bottom bar);
+  // keep ▶ run / 📂 open as inline buttons.
+  const inlineNextActions = (nextActions || []).filter(
+    (a) => a && a.kind && a.kind !== "create_pr",
+  );
+
+  const hasTechLog =
+    totalDuration > 0 ||
+    steps.some((s) => s.summary || (s.executions || []).length > 0);
+
+  return (
+    <div className="success-card">
+      <div className="success-card__head">
+        <div className="success-card__icon" aria-hidden="true">
+          <svg width="22" height="22" viewBox="0 0 24 24" fill="none"
+               stroke="currentColor" strokeWidth="2.4" strokeLinecap="round"
+               strokeLinejoin="round">
+            <polyline points="20 6 9 17 4 12" />
+          </svg>
+        </div>
+        <div className="success-card__head-text">
+          <div className="success-card__title">Execution completed</div>
+          <div className="success-card__subtitle">
+            Successfully executed {totalSteps} step{totalSteps === 1 ? "" : "s"}
+            <span className="success-card__dot">·</span>
+            <span className="success-card__time-inline">Just now</span>
+          </div>
+        </div>
+        <span className="exec-status-badge exec-status-badge--ok success-card__badge">
+          <svg width="13" height="13" viewBox="0 0 24 24" fill="none"
+               stroke="currentColor" strokeWidth="3" strokeLinecap="round"
+               strokeLinejoin="round" aria-hidden="true">
+            <polyline points="20 6 9 17 4 12" />
+          </svg>
+          Executed
+        </span>
+      </div>
+
+      {headlines.length > 0 && (
+        <ul className="success-headlines">
+          {headlines.map((h, i) => (
+            <li key={i} className="success-headline">
+              <span className="success-headline__verb">{h.verb}</span>
+              <code className="success-headline__path">{h.path}</code>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      {(owner || branch) && (
+        <div className="success-meta">
+          {owner && repo && (
+            <div className="success-meta__item">
+              <span className="success-meta__label">Repository</span>
+              <span className="success-meta__value">{owner}/{repo}</span>
+            </div>
+          )}
+          {branch && (
+            <div className="success-meta__item">
+              <span className="success-meta__label">Branch</span>
+              <span className="success-meta__value success-meta__value--mono">
+                {branch}
               </span>
-            )}
-          </header>
-          <div>
-            <PlanView plan={plan} />
+            </div>
+          )}
+        </div>
+      )}
+
+      {allFiles.length > 0 && (
+        <div className="success-files">
+          <div className="success-files__label">
+            Files changed ({allFiles.length})
           </div>
-        </section>
+          <ul className="success-action-list">
+            {allFiles.map((f, i) => (
+              <li key={i} className="success-action-row">
+                <span className="success-action__check" aria-hidden="true">✓</span>
+                <span
+                  className={`exec-badge exec-badge--${f.action.toLowerCase()}`}
+                >
+                  {f.action}
+                </span>
+                <code className="success-action__path">{f.path}</code>
+                <span className="success-action__meta">
+                  {actionMeta(f.action)}
+                </span>
+              </li>
+            ))}
+          </ul>
+        </div>
       )}
 
-      {/* Execution Log section (shown after execution) */}
-      {executionLog && (
-        <section style={styles.lastSection}>
-          <header style={styles.header}>
-            <h3 style={{ ...styles.title, color: "#10B981" }}>Execution Log</h3>
-          </header>
-          <div>
-            <ul style={styles.executionList}>
-              {executionLog.steps.map((s) => (
-                <li key={s.step_number} style={styles.executionStep}>
-                  <span style={styles.stepNumber}>Step {s.step_number}</span>
-                  <span style={styles.stepSummary}>{s.summary}</span>
-                </li>
+      {inlineNextActions.length > 0 && (
+        <div className="success-next-row">
+          {inlineNextActions.map((a, i) => (
+            <NextActionButton key={i} action={a} />
+          ))}
+        </div>
+      )}
+
+      {hasTechLog && (
+        <details className="success-techlog">
+          <summary>
+            View execution log
+            {totalDuration > 0 && (
+              <span className="success-techlog__time">
+                · {(totalDuration / 1000).toFixed(1)}s
+              </span>
+            )}
+          </summary>
+          {steps.map((s) => (
+            <div key={s.step_number} className="success-techlog__step">
+              <div className="success-techlog__step-title">
+                Step {s.step_number}
+                {totalSteps > 1 ? ` of ${totalSteps}` : ""}
+              </div>
+              {s.summary && (
+                <pre className="success-techlog__pre">{s.summary}</pre>
+              )}
+              {Array.isArray(s.executions) && s.executions.map((ex, i) => (
+                <ExecutionCard key={i} ex={ex} />
               ))}
-            </ul>
-          </div>
-        </section>
+            </div>
+          ))}
+        </details>
+      )}
+
+      {hasPRPath && (
+        <div className="success-hint">
+          Next: Create a pull request when ready.
+        </div>
+      )}
+    </div>
+  );
+}
+
+function actionMeta(action) {
+  switch (action) {
+    case "READ":   return "Read-only";
+    case "CREATE": return "Created";
+    case "MODIFY": return "Modified";
+    case "DELETE": return "Deleted";
+    case "INDEX":  return "Indexed";
+    default:       return "";
+  }
+}
+
+function verbFor(action) {
+  switch (action) {
+    case "CREATE": return "Created";
+    case "MODIFY": return "Modified";
+    case "DELETE": return "Deleted";
+    default:       return action;
+  }
+}
+
+function ExecutionCard({ ex }) {
+  const status = ex.status || "pending";
+  const statusClass =
+    status === "completed" ? "exec-card-inner--ok" :
+    status === "failed"    ? "exec-card-inner--bad" :
+    status === "skipped"   ? "exec-card-inner--warn" :
+                             "exec-card-inner--info";
+  return (
+    <div className={`exec-card-inner ${statusClass}`}>
+      <div className="exec-card-inner__head">
+        <div>
+          <strong className="exec-card-inner__path">{ex.path}</strong>
+          {ex.sandbox && (
+            <span className="exec-card-inner__sandbox">· {ex.sandbox}</span>
+          )}
+        </div>
+        <span className="exec-card-inner__status">
+          {status === "completed" && `Exit ${ex.exit_code} · ${ex.duration_ms} ms`}
+          {status === "failed" && (typeof ex.exit_code === "number"
+            ? `Failed · exit ${ex.exit_code}` : "Failed")}
+          {status === "skipped" && "Skipped"}
+          {status === "pending" && "Running…"}
+        </span>
+      </div>
+      {ex.command && (
+        <div className="exec-card-inner__cmd">$ {ex.command}</div>
+      )}
+      {ex.stdout && (
+        <details open style={{ marginTop: 4 }}>
+          <summary className="exec-card-inner__stdout-summary">stdout</summary>
+          <pre className="exec-card-inner__pre">{ex.stdout}</pre>
+        </details>
+      )}
+      {ex.stderr && (
+        <details open={status === "failed"} style={{ marginTop: 4 }}>
+          <summary className="exec-card-inner__stderr-summary">stderr</summary>
+          <pre className="exec-card-inner__pre exec-card-inner__pre--err">
+            {ex.stderr}
+          </pre>
+        </details>
+      )}
+      {ex.error && !ex.stderr && (
+        <div className="exec-card-inner__error">{ex.error}</div>
+      )}
+      {ex.reason && (
+        <div className="exec-card-inner__reason">{ex.reason}</div>
       )}
     </div>
   );
-}
\ No newline at end of file
+}
diff --git a/frontend/components/ChatPanel.jsx b/frontend/components/ChatPanel.jsx
index 4ccce56..6f0f6bc 100644
--- a/frontend/components/ChatPanel.jsx
+++ b/frontend/components/ChatPanel.jsx
@@ -8,8 +8,22 @@ import DiffStats from "./DiffStats.jsx";
 import DiffViewer from "./DiffViewer.jsx";
 import CreatePRButton from "./CreatePRButton.jsx";
 import StreamingMessage from "./StreamingMessage.jsx";
+import SandboxCanvas from "./SandboxCanvas.jsx";
+import FilePreviewPanel from "./FilePreviewPanel.jsx";
 import { SessionWebSocket } from "../utils/ws.js";
 
+// Map a file extension to the canonical sandbox language tag.  Used
+// when "Open in Canvas" needs to seed SandboxCanvas with the right
+// language hint pulled straight from a repo file path.
+const _LANG_FROM_EXT = {
+  py: "python", js: "javascript", mjs: "javascript", cjs: "javascript",
+  sh: "bash", bash: "bash",
+};
+function languageFromPath(path) {
+  if (!path || !path.includes(".")) return "python";
+  return _LANG_FROM_EXT[path.split(".").pop().toLowerCase()] || "python";
+}
+
 // Helper to get headers (inline safety if utility is missing)
 const getHeaders = () => ({
   "Content-Type": "application/json",
@@ -46,12 +60,34 @@ export default function ChatPanel({
   const [streamingEvents, setStreamingEvents] = useState([]);
   const [diffData, setDiffData] = useState(null);
   const [showDiffViewer, setShowDiffViewer] = useState(false);
+  // SandboxCanvas state — opened by the "Open in Canvas" CTA on
+  // post-CREATE next_actions and ExecutionCard footers. ``canvasSpec``
+  // is { filename, language, code } or null when closed.
+  const [canvasSpec, setCanvasSpec] = useState(null);
+  const [canvasError, setCanvasError] = useState(null);
+  // FilePreviewPanel state — opened by clicking a file row in the
+  // sidebar (gitpilot:open-file).  Read-first surface; users can pick
+  // "Prepare Run" / "Open Workspace" / "Ask GitPilot" from there.
+  const [previewPath, setPreviewPath] = useState(null);
+  const [previewContent, setPreviewContent] = useState(null);
+  const [previewLoading, setPreviewLoading] = useState(false);
+  const [previewError, setPreviewError] = useState(null);
+  const [previewErrorCode, setPreviewErrorCode] = useState(null);
+  // "preview" (narrow drawer) or "workspace" (wide editor).
+  const [previewMode, setPreviewMode] = useState("preview");
   const wsRef = useRef(null);
 
   // Ref mirrors streamingEvents so WS callbacks avoid stale closures
   const streamingEventsRef = useRef([]);
   useEffect(() => { streamingEventsRef.current = streamingEvents; }, [streamingEvents]);
 
+  // Tracks files that were just CREATE'd / MODIFY'd by a fresh execution.
+  // Used to (a) auto-retry once on 404 (GitHub contents API has brief
+  // eventual-consistency lag) and (b) classify the file viewer's empty
+  // state as "still syncing" instead of a generic 404.
+  const fileWasJustCreatedRef = useRef(new Set());
+  const fileWasJustDeletedRef = useRef(new Set());
+
   // Skip the session-sync useEffect reset when we just created a session
   // (the parent already seeded the messages into chatBySession)
   const skipNextSyncRef = useRef(false);
@@ -189,6 +225,138 @@ export default function ChatPanel({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [currentBranch, repo?.full_name, sessionId]);
 
+  // ---------------------------------------------------------------------------
+  // 1b) FILE ▶ RUN: listen for run-file events from the sidebar.
+  // ---------------------------------------------------------------------------
+  //
+  // FileTree dispatches ``gitpilot:run-file`` with the clicked file's
+  // path.  We turn that into a normal chat message ("run <path>")
+  // which goes through /api/chat/plan, hits the deterministic
+  // short-circuit, and renders an ExecutionPlanCard — exactly the
+  // same flow as typing the command. One handler, one approval surface,
+  // zero duplicated logic.
+  useEffect(() => {
+    const onRunFile = (e) => {
+      const path = e?.detail?.path;
+      if (!path || !repo) return;
+      send({ goal: `run ${path}` });
+    };
+    // "Open in Canvas" handler — fetches the file's content from the
+    // active branch and opens SandboxCanvas seeded with it.  Logs a
+    // friendly error banner when the fetch fails so a misconfigured
+    // token / wrong branch doesn't silently swallow the click.
+    const onOpenInCanvas = async (e) => {
+      const path = e?.detail?.path;
+      if (!path || !repo) return;
+      setCanvasError(null);
+      const branch = currentBranch || "HEAD";
+      try {
+        const url = `/api/repos/${repo.owner}/${repo.name}/file`
+                  + `?path=${encodeURIComponent(path)}`
+                  + `&ref=${encodeURIComponent(branch)}`;
+        const res = await fetch(url, { headers: getHeaders() });
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok) {
+          setCanvasError(data.detail || `Could not load ${path} (HTTP ${res.status})`);
+          // Still open the canvas with empty content so the user can
+          // paste something — better than nothing happening on click.
+          setCanvasSpec({
+            filename: path, language: languageFromPath(path), code: "",
+          });
+          return;
+        }
+        setCanvasSpec({
+          filename: path,
+          language: languageFromPath(path),
+          code: data.content || "",
+        });
+      } catch (err) {
+        setCanvasError(err?.message || "Could not load file for Canvas");
+        setCanvasSpec({
+          filename: path, language: languageFromPath(path), code: "",
+        });
+      }
+    };
+    // "Open file" — clicking a file row in the sidebar mounts the
+    // read-first FilePreviewPanel.  Calmer than dropping straight
+    // into Canvas: the user sees the file, can pick "Prepare Run"
+    // when they're ready (or "Open Workspace" for a wider editing
+    // surface).  The ``mode`` detail toggles the panel's geometry:
+    //   "preview"   ── narrow right drawer for a quick look
+    //   "workspace" ── wide right-side editor for serious review
+    const openFile = async (path, mode = "preview") => {
+      if (!path || !repo) return;
+      setPreviewPath(path);
+      setPreviewMode(mode);
+      setPreviewContent(null);
+      setPreviewError(null);
+      setPreviewErrorCode(null);
+      setPreviewLoading(true);
+      // Tell the sidebar which file is currently focused so it can
+      // light up the row with the ◄ marker.
+      try {
+        window.dispatchEvent(new CustomEvent("gitpilot:file-opened", { detail: { path } }));
+      } catch (_e) { /* old browser */ }
+      const branch = currentBranch || "HEAD";
+      const fetchOnce = async () => {
+        const url = `/api/repos/${repo.owner}/${repo.name}/file`
+                  + `?path=${encodeURIComponent(path)}`
+                  + `&ref=${encodeURIComponent(branch)}`;
+        const res = await fetch(url, { headers: getHeaders() });
+        const data = await res.json().catch(() => ({}));
+        return { res, data };
+      };
+      try {
+        let { res, data } = await fetchOnce();
+        // Auto-retry once on 404 for recently created files — GitHub
+        // contents API has brief eventual-consistency lag after a
+        // freshly published commit.
+        if (res.status === 404 && fileWasJustCreatedRef.current?.has(path)) {
+          await new Promise((r) => setTimeout(r, 900));
+          ({ res, data } = await fetchOnce());
+        }
+        if (!res.ok) {
+          setPreviewError(data.detail || `HTTP ${res.status}`);
+          setPreviewErrorCode(res.status);
+        } else {
+          setPreviewContent(data.content || "");
+        }
+      } catch (err) {
+        setPreviewError(err?.message || "Could not load file");
+        setPreviewErrorCode(null);
+      } finally {
+        setPreviewLoading(false);
+      }
+    };
+    const onOpenFile      = (e) => openFile(e?.detail?.path, "preview");
+    const onOpenWorkspace = (e) => openFile(e?.detail?.path, "workspace");
+    // "Ask GitPilot" — seed the chat input with a contextual question
+    // about the clicked file.  Pure additive: focuses the input and
+    // pre-fills it; the user can edit or send as-is.
+    const onAskAboutFile = (e) => {
+      const path = e?.detail?.path;
+      if (!path) return;
+      setGoal(`Tell me about ${path}.`);
+      const ta = document.querySelector(".chat-input");
+      if (ta) { ta.focus(); ta.setSelectionRange(ta.value.length, ta.value.length); }
+    };
+    window.addEventListener("gitpilot:run-file", onRunFile);
+    window.addEventListener("gitpilot:open-in-canvas", onOpenInCanvas);
+    window.addEventListener("gitpilot:open-file", onOpenFile);
+    window.addEventListener("gitpilot:open-workspace", onOpenWorkspace);
+    window.addEventListener("gitpilot:ask-about-file", onAskAboutFile);
+    return () => {
+      window.removeEventListener("gitpilot:run-file", onRunFile);
+      window.removeEventListener("gitpilot:open-in-canvas", onOpenInCanvas);
+      window.removeEventListener("gitpilot:open-file", onOpenFile);
+      window.removeEventListener("gitpilot:open-workspace", onOpenWorkspace);
+      window.removeEventListener("gitpilot:ask-about-file", onAskAboutFile);
+    };
+    // ``send`` is stable enough across renders for this use case —
+    // we don't want to re-bind on every keystroke.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [repo?.full_name, currentBranch, sessionId]);
+
   // ---------------------------------------------------------------------------
   // 2) PERSISTENCE: Save chat to Parent (no loop now because sync only on branch)
   // ---------------------------------------------------------------------------
@@ -260,6 +428,8 @@ export default function ChatPanel({
     if (m.executionLog) meta.executionLog = m.executionLog;
     if (m.diff)         meta.diff         = m.diff;
     if (m.actions)      meta.actions      = m.actions;
+    if (m.nextActions)  meta.nextActions  = m.nextActions;
+    if (m.branch)       meta.branch       = m.branch;
     // Informational plans (READ-only answers to "what does X do?" style
     // questions) carry no Approve/Reject controls — pin the flag so the
     // session reload re-renders the same shape.
@@ -562,6 +732,36 @@ export default function ChatPanel({
 
       setStatus(data.message || "Execution completed.");
 
+      // Track files touched by this execution so the file viewer can
+      // give "still syncing" / "deleted" classifications and so the
+      // sidebar refreshes off the freshly-pushed branch tree.
+      if (plan?.steps) {
+        for (const step of plan.steps) {
+          for (const f of step.files || []) {
+            if (f.action === "CREATE" || f.action === "MODIFY") {
+              fileWasJustCreatedRef.current.add(f.path);
+            } else if (f.action === "DELETE") {
+              fileWasJustDeletedRef.current.add(f.path);
+            }
+          }
+        }
+      }
+      // Forget the marker after 30 s so older "syncing" badges don't
+      // stick around forever.
+      window.setTimeout(() => {
+        fileWasJustCreatedRef.current.clear();
+        fileWasJustDeletedRef.current.clear();
+      }, 30000);
+
+      // Ask the sidebar's file tree to refetch off the newly-published
+      // branch. Fires after a small delay so GitHub's contents API has
+      // a chance to catch up.
+      window.setTimeout(() => {
+        try {
+          window.dispatchEvent(new CustomEvent("gitpilot:refresh-tree"));
+        } catch (_e) { /* old browser */ }
+      }, 600);
+
       const completionMsg = {
         from: "ai",
         role: "assistant",
@@ -569,6 +769,11 @@ export default function ChatPanel({
         content: data.message || "Execution completed.",
         executionLog: data.executionLog,
         diff: data.diff,
+        // Backend-suggested follow-ups (e.g. "Run demo.py" after CREATE
+        // of a runnable file).  Rendered as a button row in the
+        // completion message — one click, no typing.
+        nextActions: data.next_actions,
+        branch: data.branch || data.branch_name,
       };
 
       // Show completion immediately (keeps old "Execution Log" section)
@@ -792,6 +997,19 @@ export default function ChatPanel({
             }
           }
 
+          // Find the plan that was approved for this completion, so the
+          // success receipt can label actions (READ/CREATE/...) instead of
+          // showing only an opaque execution dump.
+          let linkedPlan = null;
+          if (m.executionLog) {
+            for (let i = idx - 1; i >= 0; i--) {
+              if (messages[i].plan?.steps) {
+                linkedPlan = messages[i].plan;
+                break;
+              }
+            }
+          }
+
           return (
             <div key={idx}>
               <AssistantMessage
@@ -799,6 +1017,13 @@ export default function ChatPanel({
                 plan={m.plan}
                 executionLog={m.executionLog}
                 planStatus={planStatus}
+                owner={repo?.owner}
+                repo={repo?.name}
+                onApproveExecution={() => execute()}
+                nextActions={m.nextActions}
+                relatedPlan={linkedPlan}
+                diff={m.diff}
+                branch={m.branch || currentBranch}
               />
               {/* Diff stats indicator (Claude-Code-on-Web parity) */}
               {m.diff && (
@@ -1069,6 +1294,77 @@ export default function ChatPanel({
           onClose={() => setShowDiffViewer(false)}
         />
       )}
+
+      {/* FilePreviewPanel — read-first viewer.  Opens on a file row
+          click in the sidebar.  Header carries Prepare Run (runnable
+          only), Open Workspace, and an overflow menu. */}
+      {previewPath && (
+        <FilePreviewPanel
+          path={previewPath}
+          content={previewContent}
+          loading={previewLoading}
+          error={previewError}
+          errorCode={previewErrorCode}
+          notFoundKind={
+            fileWasJustDeletedRef.current.has(previewPath)
+              ? "deleted"
+              : fileWasJustCreatedRef.current.has(previewPath)
+                ? "syncing"
+                : "unavailable"
+          }
+          mode={previewMode}
+          branch={currentBranch}
+          onModeChange={setPreviewMode}
+          onRefreshTree={() => {
+            try {
+              window.dispatchEvent(new CustomEvent("gitpilot:refresh-tree"));
+            } catch (_e) { /* old browser */ }
+          }}
+          onRetry={() => {
+            const p = previewPath;
+            const m = previewMode;
+            setPreviewPath(null);
+            // Fire the same window event we listened to — keeps the
+            // retry path identical to the original load and lets any
+            // future side-effects (e.g. analytics) see one event class.
+            setTimeout(() => window.dispatchEvent(new CustomEvent(
+              m === "workspace" ? "gitpilot:open-workspace" : "gitpilot:open-file",
+              { detail: { path: p } },
+            )), 0);
+          }}
+          onClose={() => {
+            try {
+              window.dispatchEvent(new CustomEvent("gitpilot:file-closed"));
+            } catch (_e) {/* old browser */}
+            setPreviewPath(null);
+            setPreviewContent(null);
+            setPreviewError(null);
+            setPreviewErrorCode(null);
+          }}
+        />
+      )}
+
+      {/* SandboxCanvas overlay — opened by "Open in Canvas" next_action
+          buttons and ExecutionCard footers via the
+          gitpilot:open-in-canvas window event. */}
+      {canvasSpec && (
+        <SandboxCanvas
+          initialLanguage={canvasSpec.language}
+          initialCode={canvasSpec.code}
+          filename={canvasSpec.filename}
+          onClose={() => { setCanvasSpec(null); setCanvasError(null); }}
+        />
+      )}
+      {canvasError && canvasSpec && (
+        <div style={{
+          position: "fixed", bottom: 16, right: 16, zIndex: 110,
+          padding: "8px 12px", maxWidth: 380, fontSize: 12,
+          color: "#fca5a5", background: "#3d1111",
+          border: "1px solid #7f1d1d", borderRadius: 6,
+        }}>
+          {canvasError}
+        </div>
+      )}
     </div>
   );
 }
diff --git a/frontend/components/ExecutionPlanCard.jsx b/frontend/components/ExecutionPlanCard.jsx
new file mode 100644
index 0000000..e7f5cf9
--- /dev/null
+++ b/frontend/components/ExecutionPlanCard.jsx
@@ -0,0 +1,275 @@
+// frontend/components/ExecutionPlanCard.jsx
+//
+// The approval-first surface for sandbox runs.  Renders a
+// deterministic ExecutionPlan returned by POST /api/sandbox/plan
+// and gates the actual run on an explicit user click.
+//
+// Two visual variants, same component:
+//
+//   variant = "full"    — used in chat for file-run and chat-command
+//                         plans.  Big card, every safety check / warning
+//                         visible, primary CTA "Run in Sandbox".
+//   variant = "compact" — used as a popover above a code-block ▶ click.
+//                         Same info, less chrome.
+//
+// The component is stateless about the run itself: it produces an
+// approval event (onApprove with the plan object) and lets the
+// parent decide how to execute.  This keeps the streaming/state
+// machine work for Batch 3 — here we only render and consent.
+
+import React from "react";
+
+const SEVERITY_STYLE = {
+  high:   { bg: "#3d1111", fg: "#fca5a5", border: "#7f1d1d", icon: "⛔" },
+  medium: { bg: "#3d2d11", fg: "#fde68a", border: "#854d0e", icon: "⚠" },
+  low:    { bg: "#1f2937", fg: "#a5b4fc", border: "#3730a3", icon: "ⓘ" },
+};
+
+const BACKEND_LABELS = {
+  subprocess: "Local",
+  matrixlab: "MatrixLab",
+  off: "Pass-through",
+};
+
+export default function ExecutionPlanCard({
+  plan,
+  variant = "full",
+  busy = false,
+  onApprove,
+  onCancel,
+  onOpenFile,
+}) {
+  if (!plan) return null;
+  const isCompact = variant === "compact";
+  const styles = isCompact ? compactStyles : fullStyles;
+
+  const commandStr = Array.isArray(plan.command)
+    ? plan.command.join(" ")
+    : String(plan.command || "");
+
+  return (
+    <div style={styles.card} role="region" aria-label="Execution plan">
+      <header style={styles.header}>
+        <span style={styles.badge}>EXECUTION PLAN</span>
+        <h3 style={styles.title}>{plan.goal || "Run in sandbox"}</h3>
+      </header>
+
+      <dl style={styles.fields}>
+        {plan.file && (
+          <Field label="File" value={<code>{plan.file}</code>} />
+        )}
+        <Field label="Command" value={<code>{commandStr}</code>} />
+        <Field
+          label="Sandbox"
+          value={BACKEND_LABELS[plan.sandbox] || plan.sandbox}
+        />
+        <Field label="Timeout" value={`${plan.timeout_sec}s`} />
+        <Field
+          label="Network"
+          value={plan.network ? "Enabled" : "Disabled"}
+        />
+        {plan.workdir && plan.workdir !== "." && (
+          <Field label="Working dir" value={<code>{plan.workdir}</code>} />
+        )}
+      </dl>
+
+      {/* Safety checks — always green, no opinion */}
+      {Array.isArray(plan.safety?.checks) && plan.safety.checks.length > 0 && (
+        <ul style={styles.checks}>
+          {plan.safety.checks.map((c, i) => (
+            <li key={i} style={styles.check}>
+              <span style={styles.checkIcon}>✓</span>
+              {c.label}
+            </li>
+          ))}
+        </ul>
+      )}
+
+      {/* Warnings — non-blocking, sorted high → low by the backend */}
+      {Array.isArray(plan.safety?.warnings) && plan.safety.warnings.length > 0 && (
+        <ul style={styles.warnings}>
+          {plan.safety.warnings.map((w, i) => {
+            const st = SEVERITY_STYLE[w.severity] || SEVERITY_STYLE.low;
+            return (
+              <li key={i} style={{
+                ...styles.warning,
+                background: st.bg, color: st.fg, borderColor: st.border,
+              }}>
+                <span style={styles.warnIcon}>{st.icon}</span>
+                <span>
+                  <strong>{w.label}</strong>
+                  {w.detail && <span style={styles.warnDetail}> — {w.detail}</span>}
+                </span>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+
+      {plan.inline_code && (
+        <details style={styles.snippetWrap}>
+          <summary style={styles.snippetLabel}>
+            Snippet to run ({plan.inline_code.length} chars)
+          </summary>
+          <pre style={styles.snippet}>{plan.inline_code}</pre>
+        </details>
+      )}
+
+      <footer style={styles.footer}>
+        <button
+          type="button"
+          style={{ ...styles.primary, opacity: busy ? 0.6 : 1 }}
+          onClick={() => onApprove?.(plan)}
+          disabled={busy}
+          autoFocus
+        >
+          {busy ? "Starting…" : "▶ Run in Sandbox"}
+        </button>
+        {plan.file && onOpenFile && (
+          <button type="button" style={styles.secondary}
+                  onClick={() => onOpenFile(plan.file)}>
+            Open {plan.file.split("/").pop()}
+          </button>
+        )}
+        <button
+          type="button"
+          style={styles.tertiary}
+          onClick={() => onCancel?.(plan)}
+          disabled={busy}
+        >
+          Cancel
+        </button>
+      </footer>
+    </div>
+  );
+}
+
+function Field({ label, value }) {
+  return (
+    <>
+      <dt style={dtStyle}>{label}</dt>
+      <dd style={ddStyle}>{value}</dd>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Approve helper — single source of truth so chat, codeblock, canvas
+// all build the plan the same way.  Returns the plan object or throws.
+// ---------------------------------------------------------------------------
+
+export async function fetchExecutionPlan(payload) {
+  const res = await fetch("/api/sandbox/plan", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(data.detail || `Plan failed (HTTP ${res.status})`);
+  }
+  return data.plan;
+}
+
+// ---------------------------------------------------------------------------
+// Styles
+// ---------------------------------------------------------------------------
+
+const dtStyle = {
+  fontSize: 11, color: "#9092b5", textTransform: "uppercase",
+  letterSpacing: "0.05em", margin: 0,
+};
+const ddStyle = { margin: "0 0 6px", fontSize: 13, color: "#e4e4e7" };
+
+const fullStyles = {
+  card: {
+    margin: "8px 0",
+    background: "#0d1117",
+    border: "1px solid #1f2937",
+    borderLeft: "3px solid #10B981",
+    borderRadius: 10,
+    padding: 16,
+    color: "#e4e4e7",
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+  },
+  header: { display: "flex", alignItems: "center", gap: 10, marginBottom: 10 },
+  badge: {
+    fontSize: 10, fontWeight: 700, letterSpacing: "0.06em",
+    padding: "2px 8px", borderRadius: 4,
+    background: "#0d3320", color: "#86efac", textTransform: "uppercase",
+  },
+  title: { margin: 0, fontSize: 15, fontWeight: 600 },
+  fields: {
+    display: "grid", gridTemplateColumns: "120px 1fr",
+    rowGap: 4, columnGap: 12, margin: "10px 0",
+  },
+  checks: {
+    listStyle: "none", padding: 0, margin: "8px 0",
+    display: "flex", flexWrap: "wrap", gap: 6,
+  },
+  check: {
+    fontSize: 11, color: "#86efac",
+    background: "rgba(16,185,129,0.08)",
+    border: "1px solid rgba(16,185,129,0.25)",
+    borderRadius: 4, padding: "2px 8px",
+  },
+  checkIcon: { marginRight: 4 },
+  warnings: { listStyle: "none", padding: 0, margin: "10px 0 4px" },
+  warning: {
+    fontSize: 12,
+    padding: "6px 10px", borderRadius: 4, border: "1px solid",
+    marginBottom: 4, display: "flex", gap: 8, alignItems: "flex-start",
+  },
+  warnIcon: { fontSize: 14, lineHeight: 1 },
+  warnDetail: { opacity: 0.8 },
+  snippetWrap: {
+    margin: "8px 0",
+    border: "1px solid #1f2937", borderRadius: 6, padding: "6px 10px",
+  },
+  snippetLabel: { fontSize: 11, color: "#9092b5", cursor: "pointer" },
+  snippet: {
+    margin: "6px 0 0", padding: 8, fontSize: 12,
+    fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+    background: "#000", color: "#d4d4d8", borderRadius: 4,
+    maxHeight: 240, overflow: "auto", whiteSpace: "pre-wrap",
+  },
+  footer: { display: "flex", gap: 8, marginTop: 12 },
+  primary: {
+    background: "#10B981", color: "#052e1c", border: "0",
+    borderRadius: 6, padding: "8px 16px", fontSize: 13, fontWeight: 600,
+    cursor: "pointer",
+  },
+  secondary: {
+    background: "transparent", color: "#a1a1aa",
+    border: "1px solid #3F3F46", borderRadius: 6,
+    padding: "7px 14px", fontSize: 13, cursor: "pointer",
+  },
+  tertiary: {
+    background: "transparent", color: "#71717a",
+    border: "1px solid #27272a", borderRadius: 6,
+    padding: "7px 14px", fontSize: 13, cursor: "pointer",
+    marginLeft: "auto",
+  },
+};
+
+// Compact variant — same structure, denser padding, no inline snippet
+// expander.  Used for code-block Run confirmation popovers.
+const compactStyles = {
+  ...fullStyles,
+  card: {
+    ...fullStyles.card,
+    padding: 10,
+    margin: "6px 0",
+    borderRadius: 8,
+  },
+  title: { margin: 0, fontSize: 13, fontWeight: 600 },
+  fields: {
+    ...fullStyles.fields,
+    gridTemplateColumns: "90px 1fr",
+    rowGap: 2,
+    margin: "6px 0",
+  },
+  primary: { ...fullStyles.primary, padding: "6px 12px", fontSize: 12 },
+  secondary: { ...fullStyles.secondary, padding: "5px 10px", fontSize: 12 },
+  tertiary: { ...fullStyles.tertiary, padding: "5px 10px", fontSize: 12 },
+};
diff --git a/frontend/components/FilePreviewPanel.jsx b/frontend/components/FilePreviewPanel.jsx
new file mode 100644
index 0000000..6dd06d2
--- /dev/null
+++ b/frontend/components/FilePreviewPanel.jsx
@@ -0,0 +1,463 @@
+// frontend/components/FilePreviewPanel.jsx
+//
+// Read-first file viewer with two density modes.
+//
+//   mode="preview"    Narrow right-side drawer for a quick look.
+//                     ~520px wide, primary CTA "Prepare Run".
+//   mode="workspace"  Wide right-side editor for serious review.
+//                     ~85vw, same actions, much more reading room.
+//
+// Header vocabulary follows the enterprise verbs the design review
+// nailed down:
+//
+//   [▶ Prepare Run]   only on runnable files (hidden on README etc.)
+//   [Open Workspace]  upgrades preview → workspace (or back)
+//   [⋯]               overflow: Ask GitPilot · Open Canvas ·
+//                     Copy path · Copy contents
+//
+// "Prepare Run" never runs anything directly — it dispatches the
+// gitpilot:run-file event which lands on the green ExecutionPlanCard
+// in chat, where the user approves before the sandbox starts.
+//
+// Error state: when the file content fetch fails we hide every action
+// that depends on having content (Prepare Run / Canvas / Ask).  Only
+// safe actions remain (Retry / Copy path).
+
+import React, { useEffect, useMemo, useRef, useState } from "react";
+
+const RUNNABLE_FILE_EXTS = new Set(["py", "js", "mjs", "cjs", "sh", "bash"]);
+
+const LANG_LABEL = {
+  py: "Python", js: "JavaScript", mjs: "JavaScript", cjs: "JavaScript",
+  sh: "Shell", bash: "Shell",
+  md: "Markdown", json: "JSON", yml: "YAML", yaml: "YAML", toml: "TOML",
+  html: "HTML", css: "CSS", ts: "TypeScript", tsx: "TypeScript",
+  rs: "Rust", go: "Go", java: "Java", c: "C", cpp: "C++", h: "C/C++",
+};
+
+function extOf(path) {
+  if (!path || !path.includes(".")) return "";
+  return path.split(".").pop().toLowerCase();
+}
+
+function bytesPretty(n) {
+  if (n == null) return "";
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / 1024 / 1024).toFixed(2)} MB`;
+}
+
+// ---------------------------------------------------------------------------
+// Overflow menu — secondary actions live here so the header stays calm.
+// ---------------------------------------------------------------------------
+
+function OverflowMenu({ path, content, runnable, onClose }) {
+  useEffect(() => {
+    const onKey = (e) => { if (e.key === "Escape") onClose?.(); };
+    const onDown = () => onClose?.();
+    window.addEventListener("keydown", onKey);
+    window.addEventListener("mousedown", onDown);
+    return () => {
+      window.removeEventListener("keydown", onKey);
+      window.removeEventListener("mousedown", onDown);
+    };
+  }, [onClose]);
+
+  const copy = (text) => {
+    if (navigator?.clipboard && text != null) navigator.clipboard.writeText(text).catch(() => {});
+  };
+  const items = [
+    { label: "Ask GitPilot",
+      onClick: () => window.dispatchEvent(new CustomEvent("gitpilot:ask-about-file", { detail: { path } })) },
+    { label: "Open in Canvas",  runnable: true,
+      onClick: () => window.dispatchEvent(new CustomEvent("gitpilot:open-in-canvas", { detail: { path } })) },
+    { divider: true },
+    { label: "Copy path",     onClick: () => copy(path) },
+    { label: "Copy contents", onClick: () => copy(content), disabled: !content },
+  ];
+
+  return (
+    <div role="menu"
+         onMouseDown={(e) => e.stopPropagation()}
+         style={{
+           position: "absolute", right: 6, top: 36, zIndex: 50,
+           minWidth: 200,
+           background: "#18181B", border: "1px solid #3F3F46",
+           borderRadius: 6, padding: "4px 0",
+           boxShadow: "0 8px 20px rgba(0,0,0,0.45)",
+         }}>
+      {items.map((it, i) => {
+        if (it.divider) return <div key={i} style={{ height: 1, background: "#27272A", margin: "4px 0" }} />;
+        if (it.runnable && !runnable) return null;
+        return (
+          <button
+            key={i}
+            role="menuitem"
+            type="button"
+            disabled={!!it.disabled}
+            onClick={(e) => { e.stopPropagation(); it.onClick(); onClose?.(); }}
+            style={{
+              width: "100%", textAlign: "left",
+              background: "transparent",
+              color: it.disabled ? "#52525B" : "#E4E4E7",
+              border: "none",
+              padding: "6px 12px", fontSize: 12,
+              cursor: it.disabled ? "not-allowed" : "pointer",
+            }}
+            onMouseEnter={(e) => { if (!it.disabled) e.currentTarget.style.background = "#27272A"; }}
+            onMouseLeave={(e) => e.currentTarget.style.background = "transparent"}
+          >
+            {it.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Main panel
+// ---------------------------------------------------------------------------
+
+export default function FilePreviewPanel({
+  path,
+  content,
+  loading,
+  error,
+  errorCode,            // numeric HTTP status when known (e.g. 404)
+  notFoundKind,         // "deleted" | "syncing" | "unavailable"
+  mode = "preview",     // "preview" | "workspace"
+  branch,
+  onModeChange,
+  onClose,
+  onRetry,
+  onRefreshTree,
+}) {
+  const ext = extOf(path);
+  const lang = LANG_LABEL[ext] || ext.toUpperCase() || "Text";
+  const runnable = RUNNABLE_FILE_EXTS.has(ext);
+  const size = content ? new Blob([content]).size : null;
+  const filename = path ? path.split("/").pop() : "";
+  const [menuOpen, setMenuOpen] = useState(false);
+  const menuBtnRef = useRef(null);
+
+  // Esc closes — keyboard contract every modal/drawer in GitPilot uses.
+  useEffect(() => {
+    const onKey = (e) => { if (e.key === "Escape") onClose?.(); };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [onClose]);
+
+  const prepareRun = () => {
+    window.dispatchEvent(new CustomEvent("gitpilot:run-file", { detail: { path } }));
+    onClose?.();
+  };
+  const toggleWorkspace = () => {
+    if (onModeChange) onModeChange(mode === "workspace" ? "preview" : "workspace");
+  };
+
+  const lines = useMemo(() => (content || "").split("\n"), [content]);
+
+  // Width contract: preview = peek, workspace = serious reading.
+  const widthCss = mode === "workspace"
+    ? "min(1280px, 86vw)"
+    : "min(520px, 44vw)";
+
+  // Decide which actions to show.  Two rules:
+  //   1. While loading, secondary actions exist but disabled.
+  //   2. On error, hide every action that requires content; we show
+  //      Retry + Copy path only.
+  const showActions = !error;
+
+  return (
+    <aside style={{ ...s.shell, width: widthCss }} role="region" aria-label="File preview">
+      <header style={s.header}>
+        <div style={s.titleRow}>
+          <div style={{ minWidth: 0 }}>
+            <div style={s.filename}>{filename || "Untitled"}</div>
+            <div style={s.subpath}>
+              <span style={{ opacity: 0.8 }}>Path:</span> {path}
+              {branch && (
+                <>
+                  <span style={s.dot}>·</span>
+                  <span style={{ opacity: 0.8 }}>Branch:</span> {branch}
+                </>
+              )}
+            </div>
+          </div>
+          <div style={s.metaPills}>
+            <span style={s.pill}>{lang}</span>
+            {size != null && <span style={s.pillDim}>{bytesPretty(size)}</span>}
+            <button type="button" style={s.btnClose} onClick={onClose} aria-label="Close preview">
+              ✕
+            </button>
+          </div>
+        </div>
+
+        <div style={s.actions}>
+          {showActions && runnable && (
+            <button
+              type="button" style={s.btnPrimary} onClick={prepareRun}
+              disabled={loading || !content}
+              title="Build an Execution Plan you can review before running"
+            >
+              ▶ Prepare Run
+            </button>
+          )}
+          {showActions && (
+            <button type="button" style={s.btnSecondary} onClick={toggleWorkspace}
+                    title={mode === "workspace" ? "Collapse to preview" : "Open a wider editor view"}>
+              {mode === "workspace" ? "Collapse" : "Open Workspace"}
+            </button>
+          )}
+          {/* Error-only actions */}
+          {error && (
+            <button type="button" style={s.btnPrimary} onClick={onRetry}>
+              Retry
+            </button>
+          )}
+          {error && (
+            <button
+              type="button" style={s.btnSecondary}
+              onClick={() => {
+                if (navigator?.clipboard && path) navigator.clipboard.writeText(path).catch(() => {});
+              }}
+            >
+              Copy path
+            </button>
+          )}
+
+          {/* Overflow menu — only on the happy path; on error we
+              already trimmed the safe-only action set above. */}
+          {showActions && (
+            <div style={{ marginLeft: "auto", position: "relative" }}>
+              <button
+                type="button" ref={menuBtnRef}
+                style={s.btnSecondary}
+                aria-haspopup="menu" aria-expanded={menuOpen}
+                onMouseDown={(e) => e.stopPropagation()}
+                onClick={() => setMenuOpen((v) => !v)}
+                title="More actions"
+              >
+                ⋯
+              </button>
+              {menuOpen && (
+                <OverflowMenu
+                  path={path}
+                  content={content}
+                  runnable={runnable}
+                  onClose={() => setMenuOpen(false)}
+                />
+              )}
+            </div>
+          )}
+        </div>
+      </header>
+
+      <div style={s.body}>
+        {loading && <div style={s.empty}>Loading {path}…</div>}
+
+        {error && !loading && (
+          <NotAvailableCard
+            path={path}
+            branch={branch}
+            error={error}
+            errorCode={errorCode}
+            kind={notFoundKind}
+            onRetry={onRetry}
+            onRefreshTree={onRefreshTree}
+          />
+        )}
+
+        {!loading && !error && (
+          <pre style={s.code}>
+            {lines.map((line, i) => (
+              <div key={i} style={s.lineRow}>
+                <span style={s.lineNo}>{i + 1}</span>
+                <span style={s.lineCode}>{line || " "}</span>
+              </div>
+            ))}
+          </pre>
+        )}
+      </div>
+    </aside>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Calm empty state — replaces the harsh red "Couldn't load this file"
+// box. Same component, classifies the situation into one of:
+//   deleted     → execution removed the file from this branch
+//   syncing     → execution created the file but content isn't ready yet
+//   unavailable → file simply isn't on this branch
+// ---------------------------------------------------------------------------
+
+function NotAvailableCard({ path, branch, error, errorCode, kind, onRetry, onRefreshTree }) {
+  const isNotFound =
+    errorCode === 404 ||
+    /not\s*found/i.test(String(error || "")) ||
+    /HTTP\s*404/i.test(String(error || ""));
+
+  const effectiveKind = isNotFound ? (kind || "unavailable") : "error";
+
+  const copy = {
+    deleted: {
+      icon: "🗑",
+      title: "File deleted",
+      body: `${path ? path.split("/").pop() : "This file"} was removed by the latest execution. View the execution summary for details.`,
+      tone: "muted",
+    },
+    syncing: {
+      icon: "↻",
+      title: "File still syncing",
+      body: "GitPilot just created this file. Its content is being published to the active branch — try again in a moment.",
+      tone: "info",
+    },
+    unavailable: {
+      icon: "○",
+      title: "File unavailable",
+      body: "This file isn't available on the current branch. It may have been moved, renamed, or never committed here.",
+      tone: "muted",
+    },
+    error: {
+      icon: "!",
+      title: "Couldn't load this file",
+      body: "Something went wrong fetching the file content. Try again, or refresh the file tree.",
+      tone: "warn",
+    },
+  }[effectiveKind];
+
+  return (
+    <div
+      className={`file-notavail file-notavail--${copy.tone}`}
+      role="status"
+      aria-live="polite"
+    >
+      <div className="file-notavail__icon" aria-hidden="true">{copy.icon}</div>
+      <div className="file-notavail__title">{copy.title}</div>
+      <div className="file-notavail__body">{copy.body}</div>
+
+      <dl className="file-notavail__fields">
+        <dt>Path</dt>
+        <dd><code>{path}</code></dd>
+        {branch && (
+          <>
+            <dt>Branch</dt>
+            <dd><code>{branch}</code></dd>
+          </>
+        )}
+      </dl>
+
+      <div className="file-notavail__actions">
+        <button type="button" className="file-notavail__btn file-notavail__btn--primary" onClick={onRetry}>
+          Retry
+        </button>
+        {onRefreshTree && (
+          <button type="button" className="file-notavail__btn" onClick={onRefreshTree}>
+            Refresh files
+          </button>
+        )}
+        <button
+          type="button"
+          className="file-notavail__btn"
+          onClick={() => {
+            if (navigator?.clipboard && path) {
+              navigator.clipboard.writeText(path).catch(() => {});
+            }
+          }}
+        >
+          Copy path
+        </button>
+      </div>
+
+      {effectiveKind === "error" && error && (
+        <details className="file-notavail__details">
+          <summary>Technical details</summary>
+          <pre>{String(error)}</pre>
+        </details>
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Styles
+// ---------------------------------------------------------------------------
+
+const s = {
+  shell: {
+    position: "fixed",
+    top: 0, right: 0, bottom: 0,
+    // ``width`` is set per-mode in the component.
+    background: "#0d0e17",
+    borderLeft: "1px solid #2a2b36",
+    display: "flex", flexDirection: "column",
+    zIndex: 90,
+    color: "#e4e4e7",
+    fontFamily: "system-ui, sans-serif",
+    boxShadow: "-12px 0 32px rgba(0,0,0,0.45)",
+    transition: "width 0.15s ease",
+  },
+  header: {
+    padding: "12px 16px 10px",
+    borderBottom: "1px solid #2a2b36",
+    background: "#14152a",
+  },
+  titleRow: { display: "flex", justifyContent: "space-between", gap: 12 },
+  filename: {
+    fontSize: 16, fontWeight: 600,
+    fontFamily: "ui-monospace, monospace",
+    whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis",
+  },
+  subpath: {
+    fontSize: 11, color: "#9092b5", marginTop: 2,
+    fontFamily: "ui-monospace, monospace",
+    whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis",
+  },
+  dot: { margin: "0 6px", color: "#52525B" },
+  metaPills: { display: "flex", alignItems: "flex-start", gap: 6, flexShrink: 0 },
+  pill: {
+    fontSize: 11, padding: "2px 8px", borderRadius: 4,
+    background: "#1e3a5f", color: "#93c5fd",
+    border: "1px solid #3B82F6",
+  },
+  pillDim: {
+    fontSize: 11, padding: "2px 8px", borderRadius: 4,
+    background: "#0d0e17", color: "#9092b5",
+    border: "1px solid #2c2d46",
+  },
+  actions: { display: "flex", gap: 8, marginTop: 10, flexWrap: "wrap", alignItems: "center" },
+  btnPrimary: {
+    padding: "6px 14px", fontSize: 12, fontWeight: 600,
+    background: "#10B981", color: "#052e1c",
+    border: "0", borderRadius: 6, cursor: "pointer",
+  },
+  btnSecondary: {
+    padding: "6px 12px", fontSize: 12,
+    background: "transparent", color: "#c3c5dd",
+    border: "1px solid #2c2d46", borderRadius: 6, cursor: "pointer",
+  },
+  btnClose: {
+    marginLeft: 6,
+    padding: "2px 8px", fontSize: 14,
+    background: "transparent", color: "#9092b5",
+    border: "1px solid #2c2d46", borderRadius: 6, cursor: "pointer",
+  },
+  body: { flex: 1, overflow: "auto", padding: "12px 0" },
+  empty: { padding: 30, textAlign: "center", color: "#9092b5", fontSize: 13 },
+  code: {
+    margin: 0, padding: 0,
+    fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+    fontSize: 12.5, lineHeight: 1.55,
+    color: "#D4D4D8",
+    background: "transparent",
+    whiteSpace: "pre",
+  },
+  lineRow: { display: "grid", gridTemplateColumns: "48px 1fr", gap: 12, padding: "0 18px" },
+  lineNo: {
+    color: "#52525B", textAlign: "right",
+    userSelect: "none",
+    fontVariantNumeric: "tabular-nums",
+  },
+  lineCode: { whiteSpace: "pre-wrap", wordBreak: "break-word" },
+};
diff --git a/frontend/components/FileTree.jsx b/frontend/components/FileTree.jsx
index 74352c4..bc5cb67 100644
--- a/frontend/components/FileTree.jsx
+++ b/frontend/components/FileTree.jsx
@@ -10,6 +10,28 @@ export default function FileTree({ repo, refreshTrigger, branch }) {
   const [isSwitchingBranch, setIsSwitchingBranch] = useState(false);
   const [error, setError] = useState(null);
   const [localRefresh, setLocalRefresh] = useState(0);
+  // Search query for the in-sidebar filter.  Empty string == no filter.
+  // Filter runs case-insensitively on path basenames *and* full paths
+  // so users can pinpoint a file even in deeply nested folders.
+  const [query, setQuery] = useState("");
+  // Which file is currently focused in the preview panel — populated
+  // by the ``gitpilot:file-opened`` event ChatPanel emits when the
+  // preview finishes loading.  Drives the ◄ marker + active row tint.
+  const [selectedPath, setSelectedPath] = useState(null);
+
+  useEffect(() => {
+    const onOpened = (e) => setSelectedPath(e?.detail?.path || null);
+    const onClosed = () => setSelectedPath(null);
+    const onRefresh = () => setLocalRefresh((n) => n + 1);
+    window.addEventListener("gitpilot:file-opened", onOpened);
+    window.addEventListener("gitpilot:file-closed", onClosed);
+    window.addEventListener("gitpilot:refresh-tree", onRefresh);
+    return () => {
+      window.removeEventListener("gitpilot:file-opened", onOpened);
+      window.removeEventListener("gitpilot:file-closed", onClosed);
+      window.removeEventListener("gitpilot:refresh-tree", onRefresh);
+    };
+  }, []);
 
   useEffect(() => {
     if (!repo) return;
@@ -205,50 +227,290 @@ export default function FileTree({ repo, refreshTrigger, branch }) {
       )}
 
       {tree.length > 0 && (
-        <div style={{
-          ...styles.treeContainer,
-          opacity: isSwitchingBranch ? 0.5 : 1,
-          transition: "opacity 0.15s ease",
-        }}>
-          {tree.map((node) => (
-            <TreeNode key={node.path} node={node} level={0} />
-          ))}
-        </div>
+        <>
+          {/* In-sidebar file search.  Enterprise repos run to hundreds
+              of files; the explorer needs a quick narrowing affordance
+              before any of the contextual menus matter. */}
+          <input
+            type="text"
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            placeholder="🔍 Search files…"
+            spellCheck={false}
+            style={{
+              width: "100%", boxSizing: "border-box",
+              margin: "4px 0 8px",
+              padding: "6px 10px", fontSize: 12,
+              background: "#0d0e17", color: "#e4e4e7",
+              border: "1px solid #27272A", borderRadius: 6,
+              outline: "none",
+              fontFamily: "system-ui, sans-serif",
+            }}
+          />
+
+          <div style={{
+            ...styles.treeContainer,
+            opacity: isSwitchingBranch ? 0.5 : 1,
+            transition: "opacity 0.15s ease",
+          }}>
+            {tree.map((node) => (
+              <TreeNode
+                key={node.path}
+                node={node}
+                level={0}
+                filter={query.trim().toLowerCase()}
+                selectedPath={selectedPath}
+              />
+            ))}
+          </div>
+        </>
       )}
     </div>
   );
 }
 
+// Files with these extensions get a "Prepare Run" menu item.  Mirrors
+// the backend's _RUNNABLE_EXTENSIONS so the menu only offers a run
+// where the sandbox planner would actually accept the file.
+const RUNNABLE_FILE_EXTS = new Set(["py", "js", "mjs", "cjs", "sh", "bash"]);
+
+function isRunnableFile(name, type) {
+  if (type === "tree") return false;
+  if (!name || !name.includes(".")) return false;
+  const ext = name.split(".").pop().toLowerCase();
+  return RUNNABLE_FILE_EXTS.has(ext);
+}
+
+// Window-event dispatch helpers — keep FileTree decoupled from
+// ChatPanel.  Same pattern as the existing approval-flow events.
+function dispatchOpenFile(path) {
+  try {
+    window.dispatchEvent(new CustomEvent("gitpilot:open-file", { detail: { path } }));
+  } catch (_e) { /* old browser */ }
+}
+function dispatchOpenInCanvas(path) {
+  try {
+    window.dispatchEvent(new CustomEvent("gitpilot:open-in-canvas", { detail: { path } }));
+  } catch (_e) { /* old browser */ }
+}
+function dispatchRunFile(path) {
+  try {
+    window.dispatchEvent(new CustomEvent("gitpilot:run-file", { detail: { path } }));
+  } catch (_e) { /* old browser */ }
+}
+function dispatchAskAboutFile(path) {
+  try {
+    window.dispatchEvent(new CustomEvent("gitpilot:ask-about-file", { detail: { path } }));
+  } catch (_e) { /* old browser */ }
+}
+function copyToClipboard(text) {
+  if (navigator?.clipboard) navigator.clipboard.writeText(text).catch(() => {});
+}
+
+// Tiny dropdown — positioned absolutely below the row's ⋯ trigger.
+// Closes on outside click or Escape.  Built-in <select> would be
+// faster to write but the visual contract for an enterprise file
+// explorer demands a real menu (icons, separators, descriptions).
+function FileActionsMenu({ path, runnable, onClose }) {
+  React.useEffect(() => {
+    const onKey = (e) => { if (e.key === "Escape") onClose?.(); };
+    const onDown = () => onClose?.();
+    window.addEventListener("keydown", onKey);
+    window.addEventListener("mousedown", onDown);
+    return () => {
+      window.removeEventListener("keydown", onKey);
+      window.removeEventListener("mousedown", onDown);
+    };
+  }, [onClose]);
+
+  // Menu vocabulary maps 1:1 to the design's recommended verbs.  "Open
+  // Preview" is the calm default; "Open Workspace" widens the panel
+  // for serious reading/editing; "Prepare Run…" surfaces the
+  // ExecutionPlanCard.  Canvas (the runnable split editor) is moved
+  // to the overflow because it's the heaviest mode and shouldn't
+  // compete with Preview / Workspace for attention.
+  const items = [
+    { label: "Open Preview",   onClick: () => dispatchOpenFile(path) },
+    {
+      label: "Open Workspace",
+      onClick: () => window.dispatchEvent(
+        new CustomEvent("gitpilot:open-workspace", { detail: { path } })
+      ),
+    },
+    {
+      label: "Prepare Run…",
+      onClick: () => dispatchRunFile(path),
+      runnable: true,
+      primary: true,
+    },
+    { divider: true },
+    { label: "Ask GitPilot",   onClick: () => dispatchAskAboutFile(path) },
+    { label: "Open in Canvas", onClick: () => dispatchOpenInCanvas(path), runnable: true },
+    { label: "Copy path",      onClick: () => copyToClipboard(path) },
+  ];
+
+  return (
+    <div
+      role="menu"
+      onMouseDown={(e) => e.stopPropagation()}
+      style={{
+        position: "absolute", right: 4, top: 22, zIndex: 50,
+        minWidth: 180,
+        background: "#18181B", border: "1px solid #3F3F46",
+        borderRadius: 6, padding: "4px 0",
+        boxShadow: "0 8px 20px rgba(0,0,0,0.45)",
+        fontFamily: "system-ui, sans-serif",
+      }}
+    >
+      {items.map((it, i) => {
+        if (it.divider) {
+          return <div key={i} style={{ height: 1, background: "#27272A", margin: "4px 0" }} />;
+        }
+        if (it.runnable && !runnable) return null;
+        return (
+          <button
+            key={i}
+            role="menuitem"
+            type="button"
+            onClick={(e) => { e.stopPropagation(); it.onClick(); onClose?.(); }}
+            style={{
+              width: "100%", textAlign: "left",
+              background: "transparent",
+              color: it.primary ? "#86efac" : "#E4E4E7",
+              border: "none",
+              padding: "6px 12px", fontSize: 12, cursor: "pointer",
+            }}
+            onMouseEnter={(e) => e.currentTarget.style.background = "#27272A"}
+            onMouseLeave={(e) => e.currentTarget.style.background = "transparent"}
+          >
+            {it.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+// True when ``node`` or any descendant path/basename contains ``filter``.
+// Folders are rendered if any descendant matches so the filter looks
+// like a flat search even though the tree is recursive.
+function _matchesFilter(node, filter) {
+  if (!filter) return true;
+  const inThis =
+    (node.path && node.path.toLowerCase().includes(filter)) ||
+    (node.name && node.name.toLowerCase().includes(filter));
+  if (inThis) return true;
+  if (!node.children) return false;
+  return node.children.some((c) => _matchesFilter(c, filter));
+}
+
 // Recursive Node Component
-function TreeNode({ node, level }) {
-  const [expanded, setExpanded] = useState(false);
+function TreeNode({ node, level, filter = "", selectedPath = null }) {
+  const [userExpanded, setUserExpanded] = useState(false);
+  const [hovered, setHovered] = useState(false);
+  const [menuOpen, setMenuOpen] = useState(false);
   const isFolder = node.children && node.children.length > 0;
-  
+  const runnable = !isFolder && isRunnableFile(node.name, node.type);
+  const isSelected = !isFolder && selectedPath === node.path;
+
+  // Honor the filter: drop subtrees that don't match anywhere.  When
+  // the filter is active, folders auto-expand so users see the matches
+  // without having to chase carets.
+  if (filter && !_matchesFilter(node, filter)) return null;
+  const expanded = userExpanded || Boolean(filter);
+
   const icon = isFolder ? (expanded ? "📂" : "📁") : "📄";
 
+  const onRowClick = () => {
+    if (isFolder) setUserExpanded(!userExpanded);
+    else dispatchOpenFile(node.path);
+  };
+
   return (
-    <div>
-      <div 
-        onClick={() => isFolder && setExpanded(!expanded)}
-        style={{ 
-          padding: "4px 0", 
+    <div style={{ position: "relative" }}>
+      <div
+        onClick={onRowClick}
+        onMouseEnter={() => setHovered(true)}
+        onMouseLeave={() => { setHovered(false); /* menu closes on outside-click */ }}
+        style={{
+          padding: "4px 0",
           paddingLeft: `${level * 12}px`,
-          cursor: isFolder ? "pointer" : "default",
+          paddingRight: 6,
+          cursor: "pointer",
           display: "flex",
           alignItems: "center",
           gap: "6px",
-          color: isFolder ? "#EDEDED" : "#A1A1AA",
-          whiteSpace: "nowrap"
+          color: isFolder
+            ? "#EDEDED"
+            : (isSelected ? "#86efac" : "#D4D4D8"),
+          whiteSpace: "nowrap",
+          borderRadius: 4,
+          background: isSelected
+            ? "rgba(16,185,129,0.10)"
+            : (hovered ? "#1f1f23" : "transparent"),
+          borderLeft: isSelected ? "2px solid #10B981" : "2px solid transparent",
         }}
+        title={isFolder ? "" : "Click to open · ⋯ for actions"}
       >
         <span style={{ fontSize: "14px", opacity: 0.7 }}>{icon}</span>
-        <span>{node.name}</span>
+        <span style={{
+          flex: 1, overflow: "hidden", textOverflow: "ellipsis",
+          fontWeight: isSelected ? 600 : 400,
+        }}>
+          {node.name}
+        </span>
+        {/* Selected marker — orient users when scanning a long list. */}
+        {isSelected && (
+          <span style={{ color: "#10B981", fontSize: 11 }}>◄</span>
+        )}
+
+        {/* Per-row ⋯ menu trigger — visible on hover only so the
+            list reads as a clean inventory at rest. */}
+        {!isFolder && hovered && (
+          <button
+            type="button"
+            aria-haspopup="menu"
+            aria-expanded={menuOpen}
+            onMouseDown={(e) => e.stopPropagation()}
+            onClick={(e) => {
+              e.stopPropagation();
+              setMenuOpen((v) => !v);
+            }}
+            title="File actions"
+            style={{
+              background: "transparent",
+              border: "1px solid transparent",
+              color: "#A1A1AA",
+              cursor: "pointer",
+              fontSize: 14,
+              lineHeight: 1,
+              padding: "0 6px",
+              borderRadius: 4,
+            }}
+          >
+            ⋯
+          </button>
+        )}
       </div>
-      
+
+      {menuOpen && (
+        <FileActionsMenu
+          path={node.path}
+          runnable={runnable}
+          onClose={() => setMenuOpen(false)}
+        />
+      )}
+
       {isFolder && expanded && (
         <div>
           {node.children.map(child => (
-            <TreeNode key={child.path} node={child} level={level + 1} />
+            <TreeNode
+              key={child.path}
+              node={child}
+              level={level + 1}
+              filter={filter}
+              selectedPath={selectedPath}
+            />
           ))}
         </div>
       )}
diff --git a/frontend/components/PlanView.jsx b/frontend/components/PlanView.jsx
index b543f82..c4906fe 100644
--- a/frontend/components/PlanView.jsx
+++ b/frontend/components/PlanView.jsx
@@ -1,274 +1,143 @@
 import React from "react";
 
-export default function PlanView({ plan }) {
+/**
+ * PlanView — enterprise "Proposed execution plan" card.
+ *
+ * One main card. Subtle internal spacing instead of bordered nested boxes.
+ * Steps are rendered as a vertical numbered timeline; file actions become
+ * compact pill badges (READ / CREATE / MODIFY / DELETE / INDEX).
+ *
+ * The card itself is borderless — the surrounding AssistantMessage
+ * already provides the outer container.
+ */
+export default function PlanView({ plan, planStatus }) {
   if (!plan) return null;
 
-  // Calculate totals for each action type
-  const totals = { CREATE: 0, MODIFY: 0, DELETE: 0, INDEX: 0 };
+  const totals = { CREATE: 0, MODIFY: 0, DELETE: 0, INDEX: 0, READ: 0 };
   plan.steps.forEach((step) => {
     step.files.forEach((file) => {
       totals[file.action] = (totals[file.action] || 0) + 1;
     });
   });
 
-  const theme = {
-    bg: "#18181B",
-    border: "#27272A",
-    textPrimary: "#EDEDED",
-    textSecondary: "#A1A1AA",
-    successBg: "rgba(16, 185, 129, 0.1)",
-    successText: "#10B981",
-    warningBg: "rgba(245, 158, 11, 0.1)",
-    warningText: "#F59E0B",
-    dangerBg: "rgba(239, 68, 68, 0.1)",
-    dangerText: "#EF4444",
-  };
-
-  const styles = {
-    container: {
-      display: "flex",
-      flexDirection: "column",
-      gap: "20px",
-      fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
-    },
-    header: {
-      display: "flex",
-      flexDirection: "column",
-      gap: "8px",
-      paddingBottom: "16px",
-      borderBottom: `1px solid ${theme.border}`,
-    },
-    goal: {
-      fontSize: "14px",
-      fontWeight: "600",
-      color: theme.textPrimary,
-    },
-    summary: {
-      fontSize: "13px",
-      color: theme.textSecondary,
-      lineHeight: "1.5",
-    },
-    totals: {
-      display: "flex",
-      gap: "12px",
-      flexWrap: "wrap",
-    },
-    totalBadge: {
-      fontSize: "11px",
-      fontWeight: "500",
-      padding: "4px 8px",
-      borderRadius: "4px",
-      border: "1px solid transparent",
-    },
-    totalCreate: {
-      backgroundColor: theme.successBg,
-      color: theme.successText,
-      borderColor: "rgba(16, 185, 129, 0.2)",
-    },
-    totalModify: {
-      backgroundColor: theme.warningBg,
-      color: theme.warningText,
-      borderColor: "rgba(245, 158, 11, 0.2)",
-    },
-    totalDelete: {
-      backgroundColor: theme.dangerBg,
-      color: theme.dangerText,
-      borderColor: "rgba(239, 68, 68, 0.2)",
-    },
-    totalIndex: {
-      // GitPilot orange — the same brand colour the rest of the app
-      // uses for "infrastructure / one-time" actions.  Visually
-      // distinct from CREATE / MODIFY / DELETE so users know this
-      // step doesn't write code.
-      backgroundColor: "rgba(217, 92, 61, 0.10)",
-      color: "#D95C3D",
-      borderColor: "rgba(217, 92, 61, 0.25)",
-    },
-    indexNotice: {
-      marginTop: "8px",
-      fontSize: "12px",
-      color: "#D95C3D",
-      backgroundColor: "rgba(217, 92, 61, 0.05)",
-      padding: "8px 12px",
-      borderRadius: "6px",
-      border: "1px solid rgba(217, 92, 61, 0.15)",
-      lineHeight: "1.5",
-    },
-    stepsList: {
-      listStyle: "none",
-      padding: 0,
-      margin: 0,
-      display: "flex",
-      flexDirection: "column",
-      gap: "24px",
-    },
-    step: {
-      display: "flex",
-      flexDirection: "column",
-      gap: "8px",
-      position: "relative",
-    },
-    stepHeader: {
-      display: "flex",
-      alignItems: "baseline",
-      gap: "8px",
-      fontSize: "13px",
-      fontWeight: "600",
-      color: theme.textPrimary,
-    },
-    stepNumber: {
-      color: theme.textSecondary,
-      fontSize: "11px",
-      textTransform: "uppercase",
-      letterSpacing: "0.05em",
-    },
-    stepDescription: {
-      fontSize: "13px",
-      color: theme.textSecondary,
-      lineHeight: "1.5",
-      margin: 0,
-    },
-    fileList: {
-      marginTop: "8px",
-      display: "flex",
-      flexDirection: "column",
-      gap: "4px",
-      backgroundColor: "#131316",
-      padding: "8px 12px",
-      borderRadius: "6px",
-      border: `1px solid ${theme.border}`,
-    },
-    fileItem: {
-      display: "flex",
-      alignItems: "center",
-      gap: "10px",
-      fontSize: "12px",
-      fontFamily: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace",
-    },
-    actionBadge: {
-      padding: "2px 6px",
-      borderRadius: "4px",
-      fontSize: "10px",
-      fontWeight: "bold",
-      textTransform: "uppercase",
-      minWidth: "55px",
-      textAlign: "center",
-      letterSpacing: "0.02em",
-    },
-    path: {
-      color: "#D4D4D8",
-      whiteSpace: "nowrap",
-      overflow: "hidden",
-      textOverflow: "ellipsis",
-    },
-    risks: {
-      marginTop: "8px",
-      fontSize: "12px",
-      color: theme.warningText,
-      backgroundColor: "rgba(245, 158, 11, 0.05)",
-      padding: "8px 12px",
-      borderRadius: "6px",
-      border: "1px solid rgba(245, 158, 11, 0.1)",
-      display: "flex",
-      gap: "6px",
-      alignItems: "flex-start",
-    },
-  };
-
-  const getActionStyle = (action) => {
-    switch (action) {
-      case "CREATE": return styles.totalCreate;
-      case "MODIFY": return styles.totalModify;
-      case "DELETE": return styles.totalDelete;
-      case "INDEX":  return styles.totalIndex;
-      default: return {};
-    }
-  };
-
   return (
-    <div style={styles.container}>
-      {/* Header & Summary */}
-      <div style={styles.header}>
-        <div style={styles.goal}>Goal: {plan.goal}</div>
-        <div style={styles.summary}>{plan.summary}</div>
-      </div>
+    <div className="exec-card exec-card--plan">
+      <div className="exec-card__head">
+        <div className="exec-card__icon exec-card__icon--plan" aria-hidden="true">
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none"
+               stroke="currentColor" strokeWidth="2" strokeLinecap="round"
+               strokeLinejoin="round">
+            <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" />
+            <polyline points="14 2 14 8 20 8" />
+            <line x1="8" y1="13" x2="16" y2="13" />
+            <line x1="8" y1="17" x2="13" y2="17" />
+          </svg>
+        </div>
+        <div className="exec-card__head-text">
+          <div className="exec-card__eyebrow">Proposed execution plan</div>
+          <div className="exec-card__title">{plan.goal}</div>
+        </div>
 
-      {/* Totals Summary */}
-      <div style={styles.totals}>
-        {totals.CREATE > 0 && (
-          <span style={{ ...styles.totalBadge, ...styles.totalCreate }}>
-            {totals.CREATE} to create
-          </span>
-        )}
-        {totals.MODIFY > 0 && (
-          <span style={{ ...styles.totalBadge, ...styles.totalModify }}>
-            {totals.MODIFY} to modify
-          </span>
-        )}
-        {totals.DELETE > 0 && (
-          <span style={{ ...styles.totalBadge, ...styles.totalDelete }}>
-            {totals.DELETE} to delete
-          </span>
-        )}
-        {totals.INDEX > 0 && (
-          <span style={{ ...styles.totalBadge, ...styles.totalIndex }}>
-            {totals.INDEX === 1 ? "1 setup step" : `${totals.INDEX} setup steps`}
-          </span>
-        )}
+        <div className="exec-card__head-right">
+          {planStatus === "executed" && (
+            <span className="exec-status-badge exec-status-badge--ok">
+              <svg width="13" height="13" viewBox="0 0 24 24" fill="none"
+                   stroke="currentColor" strokeWidth="3" strokeLinecap="round"
+                   strokeLinejoin="round" aria-hidden="true">
+                <polyline points="20 6 9 17 4 12" />
+              </svg>
+              Executed
+            </span>
+          )}
+          {planStatus === "rejected" && (
+            <span className="exec-status-badge exec-status-badge--muted">
+              <svg width="12" height="12" viewBox="0 0 24 24" fill="none"
+                   stroke="currentColor" strokeWidth="2.6" strokeLinecap="round"
+                   strokeLinejoin="round" aria-hidden="true">
+                <line x1="18" y1="6" x2="6" y2="18" />
+                <line x1="6" y1="6" x2="18" y2="18" />
+              </svg>
+              Rejected
+            </span>
+          )}
+
+          <div className="exec-card__totals">
+            {totals.CREATE > 0 && (
+              <span className="exec-total exec-total--create">
+                {totals.CREATE} create
+              </span>
+            )}
+            {totals.MODIFY > 0 && (
+              <span className="exec-total exec-total--modify">
+                {totals.MODIFY} modify
+              </span>
+            )}
+            {totals.DELETE > 0 && (
+              <span className="exec-total exec-total--delete">
+                {totals.DELETE} delete
+              </span>
+            )}
+            {totals.INDEX > 0 && (
+              <span className="exec-total exec-total--index">
+                {totals.INDEX === 1 ? "1 setup" : `${totals.INDEX} setup`}
+              </span>
+            )}
+          </div>
+        </div>
       </div>
 
-      {/* Steps List */}
-      <ol style={styles.stepsList}>
-        {plan.steps.map((s) => (
-          <li key={s.step_number} style={styles.step}>
-            <div style={styles.stepHeader}>
-              <span style={styles.stepNumber}>Step {s.step_number}</span>
-              <span>{s.title}</span>
+      <ol className="exec-timeline">
+        {plan.steps.map((s, idx) => (
+          <li key={s.step_number} className="exec-step">
+            <div className="exec-step__rail" aria-hidden="true">
+              <div className="exec-step__num">{s.step_number}</div>
+              {idx < plan.steps.length - 1 && (
+                <div className="exec-step__line" />
+              )}
             </div>
-            <p style={styles.stepDescription}>{s.description}</p>
+            <div className="exec-step__body">
+              <div className="exec-step__title">{s.title}</div>
+              {s.description && (
+                <p className="exec-step__desc">{s.description}</p>
+              )}
 
-            {/* Files List */}
-            {s.files && s.files.length > 0 && (
-              <div style={styles.fileList}>
-                {s.files.map((file, idx) => (
-                  <div key={idx} style={styles.fileItem}>
-                    <span style={{ ...styles.actionBadge, ...getActionStyle(file.action) }}>
-                      {file.action}
-                    </span>
-                    <span style={styles.path}>
-                      {file.action === "INDEX"
-                        ? "Build semantic index for this repo"
-                        : file.path}
-                    </span>
-                  </div>
-                ))}
-              </div>
-            )}
+              {s.files && s.files.length > 0 && (
+                <ul className="exec-actions">
+                  {s.files.map((file, fi) => (
+                    <li key={fi} className="exec-action-row">
+                      <span
+                        className={`exec-badge exec-badge--${file.action.toLowerCase()}`}
+                      >
+                        {file.action}
+                      </span>
+                      <code className="exec-action__path">
+                        {file.action === "INDEX"
+                          ? "Build semantic index for this repo"
+                          : file.path}
+                      </code>
+                    </li>
+                  ))}
+                </ul>
+              )}
 
-            {/* B9: explain the INDEX step's cost so users can decide
-                informedly before clicking Approve. */}
-            {s.files && s.files.some((f) => f.action === "INDEX") && (
-              <div style={styles.indexNotice}>
-                📦 One-time semantic index build.
-                Embeds every file locally with MiniLM-L6-v2 (~80 MB
-                model on first run, ~30 s wall time for a typical
-                repo, ~12 MB on disk).  No cloud calls.  Makes future
-                "find / where / how" queries instant.  Click{" "}
-                <strong>Reject plan</strong> to skip — you'll be
-                offered the grep fallback.
-              </div>
-            )}
+              {s.files && s.files.some((f) => f.action === "INDEX") && (
+                <div className="exec-notice">
+                  One-time semantic index build (~80 MB model, ~30 s, ~12 MB on
+                  disk). No cloud calls. Click <strong>Reject plan</strong> to
+                  skip — you'll be offered the grep fallback.
+                </div>
+              )}
 
-            {/* Risks */}
-            {s.risks && (
-              <div style={styles.risks}>
-                <span>⚠️</span>
-                <span>{s.risks}</span>
-              </div>
-            )}
+              {s.risks && (
+                <div className="exec-risk">
+                  <span aria-hidden="true">⚠</span>
+                  <span>{s.risks}</span>
+                </div>
+              )}
+            </div>
           </li>
         ))}
       </ol>
     </div>
   );
-}
\ No newline at end of file
+}
diff --git a/frontend/components/ProjectContextPanel.jsx b/frontend/components/ProjectContextPanel.jsx
index 0a480e9..fdf9a63 100644
--- a/frontend/components/ProjectContextPanel.jsx
+++ b/frontend/components/ProjectContextPanel.jsx
@@ -1,6 +1,7 @@
 import React, { useEffect, useMemo, useRef, useState } from "react";
 import FileTree from "./FileTree.jsx";
 import BranchPicker from "./BranchPicker.jsx";
+import SandboxStatusWidget from "./SandboxStatusWidget.jsx";
 
 // --- INJECTED STYLES FOR ANIMATIONS ---
 const animationStyles = `
@@ -567,6 +568,14 @@ export default function ProjectContextPanel({
       <div style={styles.treeWrapper}>
         <FileTree repo={repo} refreshTrigger={refreshTrigger} branch={branch} />
       </div>
+
+      {/* Sandbox status — always visible.  Click "Change" / "Repair"
+          to open Settings (matches the existing settings affordance
+          at the top), or "Use Local" to one-click flip the backend
+          when MatrixLab is unreachable. */}
+      <div style={{ marginTop: 12 }}>
+        <SandboxStatusWidget onOpenSettings={onSettingsClick} />
+      </div>
     </div>
   );
 }
\ No newline at end of file
diff --git a/frontend/components/RunnableCodeBlock.jsx b/frontend/components/RunnableCodeBlock.jsx
index 4e03d66..818e495 100644
--- a/frontend/components/RunnableCodeBlock.jsx
+++ b/frontend/components/RunnableCodeBlock.jsx
@@ -1,4 +1,6 @@
 import React, { useState } from "react";
+import SandboxCanvas from "./SandboxCanvas.jsx";
+import ExecutionPlanCard, { fetchExecutionPlan } from "./ExecutionPlanCard.jsx";
 
 // Languages the Run button supports.  Anything not in this set still
 // renders as a normal code block (no button) — keeps the visual contract
@@ -29,16 +31,76 @@ const LANG_DISPLAY = {
   shell: "bash",
 };
 
-/** A single fenced code block with a per-block Run button. */
-export default function RunnableCodeBlock({ language, code }) {
+// Default file extension per language — used when the user clicks
+// "Save to repo" and we need to seed a plausible filename.
+const LANG_EXT = {
+  python: "py", py: "py",
+  javascript: "js", js: "js", node: "js",
+  bash: "sh", sh: "sh", shell: "sh",
+};
+
+// Mirror executor's _looks_like_matplotlib heuristic so plt.show()
+// snippets don't hang the headless sandbox.  False positives are
+// harmless (Agg is a valid backend for any Python script).
+function looksLikeMatplotlib(code) {
+  if (!code) return false;
+  const lower = code.toLowerCase();
+  return /import\s+matplotlib|from\s+matplotlib|plt\.show|pyplot/.test(lower);
+}
+
+function applyMatplotlibShim(language, code) {
+  if (language !== "python" && language !== "py") return code;
+  if (!looksLikeMatplotlib(code)) return code;
+  return (
+    "import os as _gp_os\n" +
+    '_gp_os.environ.setdefault("MPLBACKEND", "Agg")\n' +
+    code
+  );
+}
+
+/** A single fenced code block with a per-block Run button.
+ *
+ * Optional ``owner``/``repo`` props enable the "Save to repo" button by
+ * giving the save call a real target.  When absent the button is
+ * hidden — keeps the contract honest: no button without somewhere to
+ * save. */
+export default function RunnableCodeBlock({ language, code, owner, repo }) {
   const lang = (language || "").trim().toLowerCase();
   const canRun = RUNNABLE.has(lang);
   const [busy, setBusy] = useState(false);
   const [result, setResult] = useState(null);
   const [error, setError] = useState(null);
+  const [canvasOpen, setCanvasOpen] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [saveMsg, setSaveMsg] = useState(null);
+  // Approval-first: clicking ▶ Run first fetches a deterministic
+  // ExecutionPlan and surfaces it inline.  The actual sandbox call
+  // is gated on the user clicking "Run in Sandbox" inside the plan.
+  const [pendingPlan, setPendingPlan] = useState(null);
+  const [planError, setPlanError] = useState(null);
   const display = LANG_DISPLAY[lang] || lang || "text";
 
-  const onRun = async () => {
+  const onRunClick = async () => {
+    setPlanError(null);
+    setResult(null);
+    setError(null);
+    setBusy(true);
+    try {
+      const shipped = applyMatplotlibShim(lang, code);
+      const plan = await fetchExecutionPlan({
+        code: shipped,
+        language: lang,
+        source: "code_block",
+      });
+      setPendingPlan(plan);
+    } catch (err) {
+      setPlanError(err.message || "Could not build execution plan");
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const onApprovePlan = async (plan) => {
     setBusy(true);
     setResult(null);
     setError(null);
@@ -46,7 +108,11 @@ export default function RunnableCodeBlock({ language, code }) {
       const res = await fetch("/api/sandbox/run", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ language: lang, code }),
+        body: JSON.stringify({
+          language: plan.language,
+          code: plan.inline_code,
+          timeout_sec: plan.timeout_sec,
+        }),
       });
       const data = await res.json();
       if (!res.ok) {
@@ -54,6 +120,7 @@ export default function RunnableCodeBlock({ language, code }) {
         return;
       }
       setResult(data);
+      setPendingPlan(null);
     } catch (err) {
       setError(err.message || "Run failed");
     } finally {
@@ -61,10 +128,52 @@ export default function RunnableCodeBlock({ language, code }) {
     }
   };
 
+  const onCancelPlan = () => {
+    setPendingPlan(null);
+    setPlanError(null);
+  };
+
   const copy = () => {
     if (navigator?.clipboard) navigator.clipboard.writeText(code).catch(() => {});
   };
 
+  // POST the snippet to /api/repos/{owner}/{repo}/file with a path
+  // chosen by the user.  Pure client-side prompt — no new backend
+  // wiring needed because the endpoint already exists.
+  const saveToRepo = async (snippet, snippetLang) => {
+    if (!owner || !repo) {
+      setSaveMsg("No repository context — open this chat inside a repo to save.");
+      return;
+    }
+    const ext = LANG_EXT[(snippetLang || lang).toLowerCase()] || "txt";
+    const suggested = `snippets/inline.${ext}`;
+    const path = window.prompt("Save snippet to path (inside repo):", suggested);
+    if (!path) return;
+    setSaving(true);
+    setSaveMsg(null);
+    try {
+      const res = await fetch(`/api/repos/${owner}/${repo}/file`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          path,
+          content: snippet,
+          message: `Save snippet from chat (${path})`,
+        }),
+      });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        setSaveMsg(data.detail || `Save failed (HTTP ${res.status})`);
+        return;
+      }
+      setSaveMsg(`Saved to ${path}`);
+    } catch (err) {
+      setSaveMsg(err.message || "Save failed");
+    } finally {
+      setSaving(false);
+    }
+  };
+
   return (
     <div style={styles.wrap}>
       <div style={styles.head}>
@@ -73,21 +182,55 @@ export default function RunnableCodeBlock({ language, code }) {
           <button type="button" style={styles.iconBtn} onClick={copy} title="Copy code">
             Copy
           </button>
+          {canRun && (
+            <button
+              type="button"
+              style={styles.iconBtn}
+              onClick={() => setCanvasOpen(true)}
+              title="Open the snippet in the Canvas split-view editor"
+            >
+              ⊞ Canvas
+            </button>
+          )}
+          {canRun && owner && repo && (
+            <button
+              type="button"
+              style={{ ...styles.iconBtn, opacity: saving ? 0.6 : 1 }}
+              onClick={() => saveToRepo(code, lang)}
+              disabled={saving}
+              title="Save this snippet as a file in the current repository"
+            >
+              {saving ? "Saving…" : "Save"}
+            </button>
+          )}
           {canRun && (
             <button
               type="button"
               style={{ ...styles.runBtn, opacity: busy ? 0.6 : 1 }}
-              onClick={onRun}
-              disabled={busy}
-              title="Execute this snippet in the configured sandbox"
+              onClick={onRunClick}
+              disabled={busy || !!pendingPlan}
+              title="Review an execution plan before running this snippet"
             >
-              {busy ? "Running…" : "▶ Run"}
+              {busy && !pendingPlan ? "Preparing…" : "▶ Run"}
             </button>
           )}
         </div>
       </div>
       <pre style={styles.code}>{code}</pre>
 
+      {pendingPlan && (
+        <ExecutionPlanCard
+          plan={pendingPlan}
+          variant="compact"
+          busy={busy}
+          onApprove={onApprovePlan}
+          onCancel={onCancelPlan}
+        />
+      )}
+      {planError && (
+        <div style={styles.errorBanner}>Plan error: {planError}</div>
+      )}
+
       {(result || error) && (
         <div style={styles.output}>
           <div style={styles.outputHead}>
@@ -111,11 +254,36 @@ export default function RunnableCodeBlock({ language, code }) {
           {error && <pre style={styles.stderr}>{error}</pre>}
           {result?.stdout && <pre style={styles.stdout}>{result.stdout}</pre>}
           {result?.stderr && <pre style={styles.stderr}>{result.stderr}</pre>}
+          {Array.isArray(result?.artifacts) && result.artifacts.length > 0 && (
+            <div style={styles.artifactsBox}>
+              <div style={styles.outputLabel}>Artifacts ({result.artifacts.length})</div>
+              <ul style={styles.artifactList}>
+                {result.artifacts.map((a, i) => (
+                  <li key={i} style={styles.artifactItem}>
+                    <code>{a.name || a.id}</code>
+                    {a.size && <span style={styles.dim}> · {a.size} bytes</span>}
+                    {a.mime && <span style={styles.dim}> · {a.mime}</span>}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          )}
           {result && !result.stdout && !result.stderr && (
             <div style={styles.dim}>(no output)</div>
           )}
         </div>
       )}
+
+      {saveMsg && <div style={styles.saveBanner}>{saveMsg}</div>}
+
+      {canvasOpen && (
+        <SandboxCanvas
+          initialLanguage={lang}
+          initialCode={code}
+          onClose={() => setCanvasOpen(false)}
+          onSaveAsFile={owner && repo ? saveToRepo : undefined}
+        />
+      )}
     </div>
   );
 }
@@ -280,4 +448,39 @@ const styles = {
     whiteSpace: "pre-wrap",
     wordBreak: "break-word",
   },
+  artifactsBox: {
+    marginTop: 8,
+    padding: "6px 8px",
+    background: "#0a0a0f",
+    border: "1px solid #27272A",
+    borderRadius: 4,
+  },
+  artifactList: {
+    listStyle: "none",
+    padding: 0,
+    margin: "4px 0 0",
+  },
+  artifactItem: {
+    padding: "2px 0",
+    fontSize: 12,
+    color: "#D4D4D8",
+    fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+  },
+  saveBanner: {
+    margin: "0",
+    padding: "6px 12px",
+    fontSize: 11,
+    color: "#A1A1AA",
+    background: "#0c0c10",
+    borderTop: "1px solid #27272A",
+  },
+  errorBanner: {
+    margin: "6px 0",
+    padding: "8px 10px",
+    fontSize: 12,
+    color: "#fca5a5",
+    background: "#3d1111",
+    border: "1px solid #7f1d1d",
+    borderRadius: 6,
+  },
 };
diff --git a/frontend/components/SandboxCanvas.jsx b/frontend/components/SandboxCanvas.jsx
new file mode 100644
index 0000000..8b98fdc
--- /dev/null
+++ b/frontend/components/SandboxCanvas.jsx
@@ -0,0 +1,1052 @@
+// frontend/components/SandboxCanvas.jsx
+//
+// File-aware Canvas: a modal that adapts to the file type it was
+// opened with.  Three modes:
+//
+//   code      → split editor + sandbox output.  Prepare-Run flow.
+//                 Used for .py / .js / .sh / inline snippets.
+//   markdown  → split source + rendered preview.  No Run button.
+//                 Used for .md / .markdown.
+//   text      → source-only viewer (read-only by default).
+//                 Used for everything else: .json, .yml, .csv,
+//                 .html, .txt, ...
+//
+// Mode is computed from the ``filename`` prop's extension.  When
+// ``filename`` is null (an anonymous inline snippet from a chat code
+// block) we fall back to code mode using the ``initialLanguage`` tag.
+//
+// The sandbox approval contract is unchanged: Prepare Run dispatches
+// /api/sandbox/plan, the user approves a green ExecutionPlanCard,
+// only then /api/sandbox/run actually executes.
+
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { fetchExecutionPlan } from "./ExecutionPlanCard.jsx";
+
+const BACKEND_LABELS = {
+  subprocess: "Local",
+  matrixlab: "MatrixLab",
+  off: "Pass-through",
+};
+
+const LANG_DISPLAY = {
+  py: "python", js: "javascript", node: "javascript",
+  sh: "bash", shell: "bash",
+};
+
+// Extensions that route through the sandbox.  Everything else gets
+// a viewer-only canvas — README.md must NOT show a Python execution
+// plan, JSON must NOT pretend it can run.
+const RUNNABLE_EXTS = new Set(["py", "js", "mjs", "cjs", "sh", "bash"]);
+const MARKDOWN_EXTS = new Set(["md", "markdown", "mdx"]);
+
+// Map extension → canonical sandbox language tag used by the planner.
+const EXT_TO_LANG = {
+  py: "python", js: "javascript", mjs: "javascript", cjs: "javascript",
+  sh: "bash", bash: "bash",
+};
+
+// Display label per file type — keeps the header honest about what
+// the Canvas is showing.
+const TYPE_LABEL = {
+  python: "Python", javascript: "JavaScript", bash: "Shell",
+  markdown: "Markdown", json: "JSON", yaml: "YAML", csv: "CSV",
+  html: "HTML", text: "Text",
+};
+
+function extOf(name) {
+  if (!name || !name.includes(".")) return "";
+  return name.split(".").pop().toLowerCase();
+}
+
+// Decide which Canvas branch to render based on the opening context.
+// Pure function so tests can pin it.
+function resolveCanvasMode({ filename, initialLanguage }) {
+  const ext = extOf(filename || "");
+  if (filename && MARKDOWN_EXTS.has(ext)) {
+    return { kind: "markdown", typeLabel: "Markdown", language: "markdown" };
+  }
+  if (filename && RUNNABLE_EXTS.has(ext)) {
+    const lang = EXT_TO_LANG[ext];
+    return { kind: "code", typeLabel: TYPE_LABEL[lang], language: lang };
+  }
+  if (filename) {
+    // Known-but-non-runnable: json / yaml / csv / html / txt / etc.
+    const known = { json: "json", yml: "yaml", yaml: "yaml",
+                    csv: "csv", html: "html", txt: "text" }[ext];
+    if (known) {
+      return { kind: "text", typeLabel: TYPE_LABEL[known], language: known };
+    }
+    return { kind: "text", typeLabel: ext.toUpperCase() || "Text", language: "text" };
+  }
+  // No filename → inline snippet from a chat code block.  Honor the
+  // language tag the chat fence carried.
+  const tag = (initialLanguage || "python").toLowerCase();
+  if (tag === "py" || tag === "python") return { kind: "code", typeLabel: "Python snippet", language: "python" };
+  if (tag === "js" || tag === "javascript" || tag === "node")
+    return { kind: "code", typeLabel: "JavaScript snippet", language: "javascript" };
+  if (tag === "sh" || tag === "bash" || tag === "shell")
+    return { kind: "code", typeLabel: "Shell snippet", language: "bash" };
+  return { kind: "text", typeLabel: "Text", language: "text" };
+}
+
+// Minimal, dependency-free Markdown → HTML renderer.  Covers the
+// patterns that matter for README files: headings, bold, italic,
+// inline code, fenced code blocks, lists, links.  Escapes HTML to
+// avoid XSS when README contains <script> or similar.
+function escapeHtml(s) {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+function renderMarkdown(src) {
+  if (!src) return "";
+  let s = escapeHtml(src);
+  // Fenced code blocks first so their content isn't re-processed.
+  s = s.replace(/```([\w-]*)\n([\s\S]*?)```/g, (_m, _lang, code) =>
+    `<pre class="md-code"><code>${code}</code></pre>`,
+  );
+  // Headings — process before line-based replacements.
+  s = s.replace(/^######\s+(.+)$/gm, "<h6>$1</h6>");
+  s = s.replace(/^#####\s+(.+)$/gm, "<h5>$1</h5>");
+  s = s.replace(/^####\s+(.+)$/gm,  "<h4>$1</h4>");
+  s = s.replace(/^###\s+(.+)$/gm,   "<h3>$1</h3>");
+  s = s.replace(/^##\s+(.+)$/gm,    "<h2>$1</h2>");
+  s = s.replace(/^#\s+(.+)$/gm,     "<h1>$1</h1>");
+  // Bold / italic / inline code.
+  s = s.replace(/\*\*([^*\n]+)\*\*/g, "<strong>$1</strong>");
+  s = s.replace(/(^|[^*])\*([^*\n]+)\*/g, "$1<em>$2</em>");
+  s = s.replace(/`([^`\n]+)`/g, "<code>$1</code>");
+  // Links: [text](url) — only allow http(s) + mailto + relative paths.
+  s = s.replace(/\[([^\]]+)\]\(((?:https?:\/\/|mailto:|\/|\.)[^)\s]+)\)/g,
+                '<a href="$2" target="_blank" rel="noopener noreferrer">$1</a>');
+  // Unordered list items.
+  s = s.replace(/^[ \t]*[-*]\s+(.+)$/gm, "<li>$1</li>");
+  s = s.replace(/(<li>[\s\S]*?<\/li>(?:\n<li>[\s\S]*?<\/li>)*)/g,
+                (m) => `<ul>${m.replace(/\n/g, "")}</ul>`);
+  // Paragraphs — blank-line separated runs that aren't already block-tagged.
+  s = s.split(/\n{2,}/).map((para) => {
+    if (/^<(h\d|ul|pre|p|blockquote)/.test(para.trim())) return para;
+    return `<p>${para.replace(/\n/g, " ")}</p>`;
+  }).join("\n");
+  return s;
+}
+
+// Mirrors the executor's _looks_like_matplotlib heuristic so plt.show()
+// snippets don't hang the headless sandbox.  False positives are
+// harmless (Agg is a valid backend for any Python script); false
+// negatives cause a hang on a plot window that never opens.
+function looksLikeMatplotlib(code) {
+  if (!code) return false;
+  const lower = code.toLowerCase();
+  return /import\s+matplotlib|from\s+matplotlib|plt\.show|pyplot/.test(lower);
+}
+
+function applyMatplotlibShim(language, code) {
+  if (language !== "python" && language !== "py") return code;
+  if (!looksLikeMatplotlib(code)) return code;
+  return (
+    "import os as _gp_os\n" +
+    '_gp_os.environ.setdefault("MPLBACKEND", "Agg")\n' +
+    code
+  );
+}
+
+export default function SandboxCanvas(props) {
+  // Branch by mode at the top so non-runnable file types never see
+  // the sandbox plumbing.  Each branch is a focused subcomponent —
+  // easier to read and easier to test than a single 400-line function
+  // with three conditional render paths.
+  const mode = resolveCanvasMode({
+    filename: props.filename,
+    initialLanguage: props.initialLanguage,
+  });
+  if (mode.kind === "markdown") return <MarkdownCanvas {...props} mode={mode} />;
+  if (mode.kind === "text") return <TextCanvas {...props} mode={mode} />;
+  return <CodeCanvas {...props} mode={mode} />;
+}
+
+// ---------------------------------------------------------------------------
+// CodeCanvas — the original sandbox-enabled Canvas, now scoped to
+// runnable code.  Uses ``filename`` (when present and not "inline.*")
+// as the ``display_filename`` on the ExecutionPlan so the command
+// reads ``python demo.py`` instead of ``python inline.py``.
+// ---------------------------------------------------------------------------
+
+function CodeCanvas({
+  initialCode,
+  filename,
+  onClose,
+  onSaveAsFile,
+  mode,
+}) {
+  const language = mode.language;
+  const [code, setCode] = useState(initialCode || "");
+  const [busy, setBusy] = useState(false);
+  const [result, setResult] = useState(null);
+  const [error, setError] = useState(null);
+  const [startTime, setStartTime] = useState(null);
+  const [elapsed, setElapsed] = useState(0);
+  const tickRef = useRef(null);
+  // Approval-first: clicking Run fetches a deterministic plan first;
+  // the slim confirmation strip lets the user back out before any code
+  // actually executes in the sandbox.
+  const [pendingPlan, setPendingPlan] = useState(null);
+  const [planError, setPlanError] = useState(null);
+  const [showRunDetails, setShowRunDetails] = useState(false);
+  const [showMenu, setShowMenu] = useState(false);
+  const [finishedAt, setFinishedAt] = useState(null);
+  const [phase, setPhase] = useState("idle"); // idle | preparing | running | done | failed
+  const menuRef = useRef(null);
+
+  useEffect(() => {
+    if (!busy || !startTime) return;
+    tickRef.current = setInterval(() => {
+      setElapsed(Date.now() - startTime);
+    }, 100);
+    return () => {
+      if (tickRef.current) clearInterval(tickRef.current);
+      tickRef.current = null;
+    };
+  }, [busy, startTime]);
+
+  useEffect(() => {
+    if (!showMenu) return;
+    const onDown = (e) => {
+      if (menuRef.current && !menuRef.current.contains(e.target)) {
+        setShowMenu(false);
+      }
+    };
+    window.addEventListener("mousedown", onDown);
+    return () => window.removeEventListener("mousedown", onDown);
+  }, [showMenu]);
+
+  const requestPlan = useCallback(async () => {
+    setPlanError(null);
+    setError(null);
+    setBusy(true);
+    setPhase("preparing");
+    try {
+      const shipped = applyMatplotlibShim(language, code);
+      const isInlineName = (filename || "").toLowerCase().startsWith("inline.");
+      const displayFilename = filename && !isInlineName ? filename : undefined;
+      const plan = await fetchExecutionPlan({
+        code: shipped,
+        language,
+        source: "canvas",
+        display_filename: displayFilename,
+      });
+      setPendingPlan(plan);
+    } catch (err) {
+      setPlanError(err.message || "Could not build execution plan");
+      setPhase("failed");
+    } finally {
+      setBusy(false);
+    }
+  }, [language, code, filename]);
+
+  const approveRun = useCallback(async (plan) => {
+    setBusy(true);
+    setResult(null);
+    setError(null);
+    setStartTime(Date.now());
+    setElapsed(0);
+    setPhase("running");
+    try {
+      const res = await fetch("/api/sandbox/run", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          language: plan.language,
+          code: plan.inline_code,
+          timeout_sec: plan.timeout_sec,
+        }),
+      });
+      const data = await res.json();
+      if (!res.ok) {
+        setError(data.detail || `HTTP ${res.status}`);
+        setPhase("failed");
+        return;
+      }
+      setResult(data);
+      setPendingPlan(null);
+      setFinishedAt(Date.now());
+      setPhase(data.exit_code === 0 ? "done" : "failed");
+    } catch (err) {
+      setError(err.message || "Run failed");
+      setPhase("failed");
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  const run = requestPlan;
+  const cancelPending = () => { setPendingPlan(null); setPhase("idle"); };
+
+  useEffect(() => {
+    const onKey = (e) => {
+      if (e.key === "Escape" && !busy) onClose?.();
+      if ((e.metaKey || e.ctrlKey) && e.key === "Enter") run();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [run, busy, onClose]);
+
+  const exitOk = result?.exit_code === 0;
+  const displayLang = LANG_DISPLAY[language] || language;
+  const headerFilename = filename
+    || `inline.${displayLang === "javascript" ? "js" : displayLang === "bash" ? "sh" : "py"}`;
+
+  const isPython = language === "python";
+  const showMplNotice = isPython && looksLikeMatplotlib(code);
+  // Crude but useful: flag scripts that read env vars so users can spot
+  // sandbox-scoped variable scoping issues before they run.
+  const readsEnvVars = /os\.environ|process\.env|getenv/.test(code || "");
+
+  const runCommand = useMemo(() => {
+    const base = headerFilename.split("/").pop();
+    if (language === "python") return `python ${base}`;
+    if (language === "javascript") return `node ${base}`;
+    if (language === "bash") return `bash ${base}`;
+    return base;
+  }, [headerFilename, language]);
+
+  const lineCount = (code || "").split("\n").length;
+  const charCount = (code || "").length;
+
+  const statusText =
+    phase === "preparing" ? "Preparing sandbox…" :
+    phase === "running"   ? `Running ${runCommand}…` :
+    phase === "done"      ? `Completed in ${((finishedAt - startTime) / 1000).toFixed(1)}s` :
+    phase === "failed"    ? "Execution failed" :
+                            "Ready to run";
+
+  const statusTone =
+    phase === "preparing" || phase === "running" ? "info" :
+    phase === "done"   ? "ok" :
+    phase === "failed" ? "bad" :
+                          "ok";
+
+  return (
+    <div style={s.backdrop} onClick={onClose}>
+      <div className="canvas-modal" style={s.modal} onClick={(e) => e.stopPropagation()}>
+        <header className="canvas-header">
+          <div className="canvas-header__left">
+            <div className="canvas-header__glyph" aria-hidden="true">
+              <svg width="16" height="16" viewBox="0 0 24 24" fill="none"
+                   stroke="currentColor" strokeWidth="2" strokeLinecap="round"
+                   strokeLinejoin="round">
+                <polyline points="4 17 10 11 4 5" />
+                <line x1="12" y1="19" x2="20" y2="19" />
+              </svg>
+            </div>
+            <div className="canvas-header__title">{headerFilename.split("/").pop()}</div>
+            <span className="canvas-pill canvas-pill--lang">
+              <span className="canvas-pill__dot" />
+              {mode.typeLabel}
+            </span>
+            <span className="canvas-pill canvas-pill--sandbox">
+              <svg width="12" height="12" viewBox="0 0 24 24" fill="none"
+                   stroke="currentColor" strokeWidth="2" strokeLinecap="round"
+                   strokeLinejoin="round" aria-hidden="true">
+                <path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z" />
+              </svg>
+              Local sandbox
+            </span>
+          </div>
+          <div className="canvas-header__right">
+            <button
+              type="button"
+              className="canvas-run-btn"
+              onClick={pendingPlan ? () => approveRun(pendingPlan) : requestPlan}
+              disabled={busy && phase !== "running"}
+            >
+              {phase === "running" ? (
+                <>
+                  <span className="canvas-run-btn__spinner" />
+                  Running {(elapsed / 1000).toFixed(1)}s
+                </>
+              ) : phase === "preparing" ? (
+                "Preparing…"
+              ) : pendingPlan ? (
+                <>▶ Confirm & run</>
+              ) : (
+                <>▶ Run</>
+              )}
+            </button>
+            <div className="canvas-menu" ref={menuRef}>
+              <button
+                type="button"
+                className="canvas-icon-btn"
+                onClick={() => setShowMenu((v) => !v)}
+                aria-label="More actions"
+                aria-haspopup="menu"
+                aria-expanded={showMenu}
+              >
+                ⋮
+              </button>
+              {showMenu && (
+                <div className="canvas-menu__panel" role="menu">
+                  {onSaveAsFile && (
+                    <button
+                      type="button"
+                      className="canvas-menu__item"
+                      onClick={() => { setShowMenu(false); onSaveAsFile(code, language); }}
+                    >
+                      Save to repo…
+                    </button>
+                  )}
+                  <button
+                    type="button"
+                    className="canvas-menu__item"
+                    onClick={() => {
+                      if (navigator?.clipboard) {
+                        navigator.clipboard.writeText(code).catch(() => {});
+                      }
+                      setShowMenu(false);
+                    }}
+                  >
+                    Copy source
+                  </button>
+                  <button
+                    type="button"
+                    className="canvas-menu__item"
+                    onClick={() => { setShowMenu(false); onClose?.(); }}
+                  >
+                    Close canvas
+                  </button>
+                </div>
+              )}
+            </div>
+            <button type="button" className="canvas-icon-btn canvas-icon-btn--close"
+                    onClick={onClose} aria-label="Close">
+              ✕
+            </button>
+          </div>
+        </header>
+
+        <div className="canvas-status">
+          <div className={`canvas-status__dot canvas-status__dot--${statusTone}`} aria-hidden="true">
+            {phase === "done" ? "✓" :
+             phase === "failed" ? "✕" :
+             phase === "preparing" || phase === "running" ? "" :
+             "▸"}
+          </div>
+          <div className="canvas-status__text">
+            <div className="canvas-status__title">{statusText}</div>
+            <div className="canvas-status__sub">
+              <code>{runCommand}</code>
+              <span className="canvas-status__sep">·</span>
+              Timeout 120s
+              <span className="canvas-status__sep">·</span>
+              Network disabled
+            </div>
+          </div>
+          <button
+            type="button"
+            className="canvas-status__details"
+            onClick={() => setShowRunDetails((v) => !v)}
+            aria-expanded={showRunDetails}
+          >
+            Details {showRunDetails ? "▴" : "▾"}
+          </button>
+        </div>
+
+        {showRunDetails && (
+          <div className="canvas-run-config">
+            <div className="canvas-run-config__row">
+              <span className="canvas-run-config__label">Command</span>
+              <code className="canvas-run-config__val">{runCommand}</code>
+            </div>
+            <div className="canvas-run-config__row">
+              <span className="canvas-run-config__label">Environment</span>
+              <span className="canvas-run-config__val">Local sandbox (isolated)</span>
+            </div>
+            <div className="canvas-run-config__row">
+              <span className="canvas-run-config__label">Timeout</span>
+              <span className="canvas-run-config__val">120s</span>
+            </div>
+            <div className="canvas-run-config__row">
+              <span className="canvas-run-config__label">Network</span>
+              <span className="canvas-run-config__val">Disabled</span>
+            </div>
+            <div className="canvas-run-config__row">
+              <span className="canvas-run-config__label">Snippet</span>
+              <span className="canvas-run-config__val">{lineCount} lines · {charCount} chars</span>
+            </div>
+          </div>
+        )}
+
+        {(showMplNotice || readsEnvVars) && (
+          <div className="canvas-notices">
+            <div className="canvas-notices__label">Notices</div>
+            <div className="canvas-notices__row">
+              {readsEnvVars && (
+                <div className="canvas-notice canvas-notice--info">
+                  <div className="canvas-notice__icon" aria-hidden="true">ⓘ</div>
+                  <div className="canvas-notice__body">
+                    <div className="canvas-notice__title">Reads environment variables</div>
+                    <div className="canvas-notice__desc">
+                      Script reads env vars — only sandbox-scoped variables are present.
+                    </div>
+                  </div>
+                </div>
+              )}
+              {showMplNotice && (
+                <div className="canvas-notice canvas-notice--accent">
+                  <div className="canvas-notice__icon" aria-hidden="true">
+                    <svg width="14" height="14" viewBox="0 0 24 24" fill="none"
+                         stroke="currentColor" strokeWidth="2" strokeLinecap="round"
+                         strokeLinejoin="round">
+                      <polyline points="3 17 9 11 13 15 21 7" />
+                    </svg>
+                  </div>
+                  <div className="canvas-notice__body">
+                    <div className="canvas-notice__title">Matplotlib detected</div>
+                    <div className="canvas-notice__desc">
+                      Plots will render inline in the sandbox output.
+                    </div>
+                  </div>
+                </div>
+              )}
+            </div>
+          </div>
+        )}
+
+        {pendingPlan && (
+          <div className="canvas-confirm">
+            <div className="canvas-confirm__text">
+              GitPilot will run <code>{runCommand}</code> in the local sandbox.
+              Click <strong>Confirm & run</strong> to proceed.
+            </div>
+            <button type="button" className="canvas-confirm__cancel" onClick={cancelPending}>
+              Cancel
+            </button>
+          </div>
+        )}
+        {planError && (
+          <div className="canvas-plan-error">Plan error: {planError}</div>
+        )}
+
+        <div className="canvas-body">
+          <div className="canvas-pane canvas-pane--source">
+            <div className="canvas-pane__head">
+              <div className="canvas-pane__title">Source</div>
+              <div className="canvas-pane__head-right">
+                <span className="canvas-pane__meta">{mode.typeLabel}</span>
+                <button
+                  type="button"
+                  className="canvas-pane__icon"
+                  title="Copy source"
+                  onClick={() => {
+                    if (navigator?.clipboard) {
+                      navigator.clipboard.writeText(code).catch(() => {});
+                    }
+                  }}
+                >
+                  <svg width="14" height="14" viewBox="0 0 24 24" fill="none"
+                       stroke="currentColor" strokeWidth="2" strokeLinecap="round"
+                       strokeLinejoin="round">
+                    <rect x="9" y="9" width="13" height="13" rx="2" />
+                    <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+                  </svg>
+                </button>
+              </div>
+            </div>
+            <div className="canvas-editor-wrap">
+              <pre className="canvas-editor-gutter" aria-hidden="true">
+                {Array.from({ length: Math.max(lineCount, 1) }, (_, i) => (
+                  <div key={i} className="canvas-editor-gutter__line">{i + 1}</div>
+                ))}
+              </pre>
+              <textarea
+                className="canvas-editor"
+                value={code}
+                onChange={(e) => setCode(e.target.value)}
+                spellCheck={false}
+              />
+            </div>
+            <div className="canvas-statusbar">
+              <span>{lineCount} lines</span>
+              <span className="canvas-statusbar__sep">·</span>
+              <span>{mode.typeLabel}</span>
+              <span className="canvas-statusbar__spacer" />
+              <span className="canvas-statusbar__kbd">⌘/Ctrl+Enter to run · Esc to close</span>
+            </div>
+          </div>
+
+          <div className="canvas-pane canvas-pane--output">
+            <div className="canvas-pane__head">
+              <div className="canvas-pane__title">Sandbox output</div>
+              {result && (
+                <button
+                  type="button"
+                  className="canvas-pane__icon-btn"
+                  title="Clear output"
+                  onClick={() => { setResult(null); setError(null); setPhase("idle"); }}
+                >
+                  <svg width="12" height="12" viewBox="0 0 24 24" fill="none"
+                       stroke="currentColor" strokeWidth="2" strokeLinecap="round"
+                       strokeLinejoin="round" aria-hidden="true">
+                    <polyline points="3 6 5 6 21 6" />
+                    <path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6" />
+                  </svg>
+                  Clear
+                </button>
+              )}
+            </div>
+
+            <div className="canvas-output-body">
+              {!result && !error && phase === "idle" && (
+                <div className="canvas-output-empty">
+                  <div className="canvas-output-empty__title">Ready to run</div>
+                  <div className="canvas-output-empty__sub">
+                    Click <strong>▶ Run</strong> to execute this snippet in the local sandbox.
+                  </div>
+                </div>
+              )}
+
+              {(phase === "preparing" || phase === "running") && (
+                <div className="canvas-output-running">
+                  <span className="canvas-output-running__spinner" aria-hidden="true" />
+                  <span>
+                    {phase === "preparing" ? "Preparing sandbox…" : `Running… ${(elapsed / 1000).toFixed(1)}s`}
+                  </span>
+                </div>
+              )}
+
+              {error && phase === "failed" && (
+                <div className="canvas-result-head canvas-result-head--bad">
+                  <span className="canvas-result-icon">✕</span>
+                  <div>
+                    <div className="canvas-result-title">Execution failed</div>
+                    <pre className="canvas-result-err">{error}</pre>
+                  </div>
+                </div>
+              )}
+
+              {result && (
+                <>
+                  <div className={`canvas-result-head canvas-result-head--${exitOk ? "ok" : "bad"}`}>
+                    <span className="canvas-result-icon">{exitOk ? "✓" : "✕"}</span>
+                    <div className="canvas-result-headtext">
+                      <div className="canvas-result-title">
+                        {exitOk ? `Completed in ${((finishedAt - startTime) / 1000).toFixed(1)}s` : `Failed (exit ${result.exit_code})`}
+                      </div>
+                      <div className="canvas-result-sub">
+                        {BACKEND_LABELS[result.backend] || result.backend}
+                        {typeof result.duration_ms === "number" && ` · ${result.duration_ms} ms`}
+                        {result.timed_out && " · timed out"}
+                        {result.truncated && " · truncated"}
+                      </div>
+                    </div>
+                    <span className="canvas-result-time">
+                      {new Date(finishedAt || Date.now()).toLocaleTimeString([], {
+                        hour: "numeric", minute: "2-digit",
+                      })}
+                    </span>
+                  </div>
+
+                  {result.stdout && (
+                    <div className="canvas-output-section">
+                      <div className="canvas-output-section__label">
+                        <span>STDOUT</span>
+                      </div>
+                      <pre className="canvas-output-pre">{result.stdout}</pre>
+                    </div>
+                  )}
+
+                  {Array.isArray(result.artifacts) && result.artifacts.length > 0 && (
+                    <div className="canvas-output-section">
+                      <div className="canvas-output-section__label">
+                        Artifacts <span className="canvas-output-section__count">{result.artifacts.length}</span>
+                      </div>
+                      <ul className="canvas-artifacts">
+                        {result.artifacts.map((a, i) => (
+                          <ArtifactItem key={i} artifact={a} />
+                        ))}
+                      </ul>
+                    </div>
+                  )}
+
+                  {result.stderr && (
+                    <div className="canvas-output-section">
+                      <div className="canvas-output-section__label canvas-output-section__label--err">
+                        STDERR
+                      </div>
+                      <pre className="canvas-output-pre canvas-output-pre--err">{result.stderr}</pre>
+                    </div>
+                  )}
+
+                  {!result.stdout && !result.stderr && (!result.artifacts || result.artifacts.length === 0) && (
+                    <div className="canvas-output-empty">
+                      <div className="canvas-output-empty__sub">
+                        {exitOk
+                          ? "The script completed without producing any output."
+                          : "The script failed without producing any output."}
+                      </div>
+                    </div>
+                  )}
+                </>
+              )}
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function ArtifactItem({ artifact }) {
+  const name = artifact.name || artifact.id || "artifact";
+  const isImage =
+    (artifact.mime && artifact.mime.startsWith("image/")) ||
+    /\.(png|jpg|jpeg|gif|svg|webp)$/i.test(name);
+  const src =
+    artifact.data_url ||
+    artifact.url ||
+    (artifact.content_b64 && artifact.mime
+      ? `data:${artifact.mime};base64,${artifact.content_b64}`
+      : null);
+
+  return (
+    <li className="canvas-artifact">
+      {isImage && src && (
+        <img src={src} alt={name} className="canvas-artifact__img" />
+      )}
+      <div className="canvas-artifact__row">
+        <div className="canvas-artifact__icon" aria-hidden="true">
+          {isImage ? (
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none"
+                 stroke="currentColor" strokeWidth="2" strokeLinecap="round"
+                 strokeLinejoin="round">
+              <rect x="3" y="3" width="18" height="18" rx="2" />
+              <circle cx="8.5" cy="8.5" r="1.5" />
+              <polyline points="21 15 16 10 5 21" />
+            </svg>
+          ) : (
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none"
+                 stroke="currentColor" strokeWidth="2" strokeLinecap="round"
+                 strokeLinejoin="round">
+              <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" />
+              <polyline points="14 2 14 8 20 8" />
+            </svg>
+          )}
+        </div>
+        <code className="canvas-artifact__name">{name}</code>
+        {isImage && src && (
+          <span className="canvas-artifact__badge">Plot rendered inline</span>
+        )}
+        {artifact.size != null && (
+          <span className="canvas-artifact__meta">
+            {typeof artifact.size === "number" ? `${artifact.size} bytes` : artifact.size}
+          </span>
+        )}
+        {src && (
+          <a
+            href={src}
+            download={name}
+            className="canvas-artifact__download"
+            title="Download artifact"
+          >
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none"
+                 stroke="currentColor" strokeWidth="2" strokeLinecap="round"
+                 strokeLinejoin="round">
+              <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+              <polyline points="7 10 12 15 17 10" />
+              <line x1="12" y1="15" x2="12" y2="3" />
+            </svg>
+          </a>
+        )}
+      </div>
+    </li>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MarkdownCanvas — split source / rendered preview.  No Run button,
+// no execution plan.  Mode switch lets users pick Source / Preview /
+// Split.  Renderer is dependency-free (escapes HTML, then formats
+// the patterns README files actually use).
+// ---------------------------------------------------------------------------
+
+function MarkdownCanvas({ initialCode, filename, onClose, mode }) {
+  const [view, setView] = useState("split"); // "source" | "preview" | "split"
+  const html = useMemo(() => renderMarkdown(initialCode || ""), [initialCode]);
+  // Inject the rendered-markdown stylesheet once.  Cheaper than a
+  // styled-component dance and keeps the renderer dependency-free.
+  useEffect(() => {
+    const id = "gitpilot-md-style";
+    if (document.getElementById(id)) return;
+    const style = document.createElement("style");
+    style.id = id;
+    style.textContent = `
+      .gp-md h1 { font-size: 22px; margin: 18px 0 8px; padding-bottom: 6px; border-bottom: 1px solid #2c2d46; color: #f4f4f5; }
+      .gp-md h2 { font-size: 18px; margin: 16px 0 6px; padding-bottom: 4px; border-bottom: 1px solid #1f2937; color: #f4f4f5; }
+      .gp-md h3 { font-size: 15px; margin: 14px 0 4px; color: #f4f4f5; }
+      .gp-md h4, .gp-md h5, .gp-md h6 { font-size: 13px; margin: 12px 0 4px; color: #e4e4e7; }
+      .gp-md p  { margin: 8px 0; color: #d4d4d8; }
+      .gp-md ul { margin: 6px 0 6px 18px; padding: 0; color: #d4d4d8; }
+      .gp-md li { margin: 3px 0; }
+      .gp-md a  { color: #93c5fd; }
+      .gp-md code { background: #000; color: #86efac; padding: 1px 5px; border-radius: 3px; font-family: ui-monospace, monospace; font-size: 12.5px; }
+      .gp-md pre.md-code { background: #000; color: #d4d4d8; padding: 10px 12px; border-radius: 6px; overflow: auto; }
+      .gp-md pre.md-code code { background: transparent; color: inherit; padding: 0; }
+      .gp-md strong { color: #f4f4f5; }
+    `;
+    document.head.appendChild(style);
+  }, []);
+  useEffect(() => {
+    const onKey = (e) => { if (e.key === "Escape") onClose?.(); };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [onClose]);
+
+  const copy = () => {
+    if (navigator?.clipboard) navigator.clipboard.writeText(initialCode || "").catch(() => {});
+  };
+
+  return (
+    <div style={s.backdrop} onClick={onClose}>
+      <div style={s.modal} onClick={(e) => e.stopPropagation()}>
+        <header style={s.header}>
+          <div style={s.headerLeft}>
+            <span style={s.canvasBadge}>Canvas</span>
+            <span style={s.filename}>{filename || "untitled.md"}</span>
+            <span style={s.langPill}>{mode.typeLabel}</span>
+          </div>
+          <div style={s.headerRight}>
+            {/* Mode switch — Source / Preview / Split.  Default split
+                because users often want to compare raw markdown to
+                rendered output side-by-side. */}
+            <div style={s.segGroup} role="tablist">
+              {["source", "preview", "split"].map((v) => (
+                <button
+                  key={v}
+                  type="button"
+                  role="tab"
+                  aria-selected={view === v}
+                  onClick={() => setView(v)}
+                  style={view === v ? s.segActive : s.seg}
+                >
+                  {v[0].toUpperCase() + v.slice(1)}
+                </button>
+              ))}
+            </div>
+            <button type="button" style={s.btn} onClick={copy}>
+              Copy
+            </button>
+            <button type="button" style={s.btnClose} onClick={onClose} aria-label="Close">
+              ✕
+            </button>
+          </div>
+        </header>
+
+        <div style={view === "split" ? s.body : s.bodySingle}>
+          {(view === "source" || view === "split") && (
+            <div style={s.editorPane}>
+              <div style={s.paneLabel}>Markdown source</div>
+              <pre style={s.mdSource}>{initialCode || ""}</pre>
+            </div>
+          )}
+          {(view === "preview" || view === "split") && (
+            <div style={s.outputPane}>
+              <div style={s.paneLabel}>Rendered preview</div>
+              <div
+                className="gp-md"
+                style={s.mdRendered}
+                // Renderer escapes HTML before formatting, so the
+                // injected string is safe.  No <script>, no event
+                // handlers slip through.
+                dangerouslySetInnerHTML={{ __html: html }}
+              />
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// TextCanvas — viewer-only Canvas for non-runnable, non-markdown
+// file types (JSON, YAML, CSV, HTML, plain text, ...).  No Run, no
+// plan, no markdown rendering.  Useful when a user clicks Open in
+// Canvas on, say, a config file just to read it.
+// ---------------------------------------------------------------------------
+
+function TextCanvas({ initialCode, filename, onClose, mode }) {
+  useEffect(() => {
+    const onKey = (e) => { if (e.key === "Escape") onClose?.(); };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [onClose]);
+
+  const copy = () => {
+    if (navigator?.clipboard) navigator.clipboard.writeText(initialCode || "").catch(() => {});
+  };
+
+  return (
+    <div style={s.backdrop} onClick={onClose}>
+      <div style={s.modal} onClick={(e) => e.stopPropagation()}>
+        <header style={s.header}>
+          <div style={s.headerLeft}>
+            <span style={s.canvasBadge}>Canvas</span>
+            <span style={s.filename}>{filename || "untitled"}</span>
+            <span style={s.langPill}>{mode.typeLabel}</span>
+          </div>
+          <div style={s.headerRight}>
+            <button type="button" style={s.btn} onClick={copy}>
+              Copy
+            </button>
+            <button type="button" style={s.btnClose} onClick={onClose} aria-label="Close">
+              ✕
+            </button>
+          </div>
+        </header>
+
+        <div style={s.bodySingle}>
+          <div style={s.editorPane}>
+            <div style={s.paneLabel}>Source</div>
+            <pre style={s.mdSource}>{initialCode || ""}</pre>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+const s = {
+  backdrop: {
+    position: "fixed", inset: 0, background: "rgba(0,0,0,0.6)",
+    display: "flex", alignItems: "center", justifyContent: "center",
+    zIndex: 100,
+  },
+  modal: {
+    width: "min(1200px, 96vw)", height: "min(800px, 92vh)",
+    background: "#1a1b26", border: "1px solid #2a2b36", borderRadius: 10,
+    display: "flex", flexDirection: "column",
+    color: "#e6e8ff", overflow: "hidden",
+  },
+  header: {
+    display: "flex", alignItems: "center", justifyContent: "space-between",
+    padding: "10px 14px", borderBottom: "1px solid #2a2b36",
+    background: "#14152a",
+  },
+  headerLeft:  { display: "flex", alignItems: "center", gap: 10 },
+  headerRight: { display: "flex", alignItems: "center", gap: 8 },
+  canvasBadge: {
+    fontSize: 10, fontWeight: 700, letterSpacing: "0.06em",
+    padding: "2px 8px", borderRadius: 4,
+    background: "#1e3a5f", color: "#93c5fd", textTransform: "uppercase",
+  },
+  filename: { fontFamily: "ui-monospace, monospace", fontSize: 13 },
+  langPill: {
+    fontSize: 11, color: "#9092b5",
+    padding: "1px 6px", borderRadius: 4, background: "#0e0f24",
+    border: "1px solid #2c2d46",
+  },
+  btn: {
+    padding: "6px 12px", fontSize: 12, fontWeight: 600,
+    background: "#3B82F6", color: "#fff",
+    border: "none", borderRadius: 6, cursor: "pointer",
+  },
+  btnClose: {
+    padding: "4px 10px", fontSize: 14,
+    background: "transparent", color: "#9092b5",
+    border: "1px solid #2c2d46", borderRadius: 6, cursor: "pointer",
+  },
+  body: { flex: 1, display: "grid", gridTemplateColumns: "1fr 1fr", overflow: "hidden" },
+  editorPane: {
+    display: "flex", flexDirection: "column",
+    borderRight: "1px solid #2a2b36", padding: 12, gap: 6,
+  },
+  outputPane: {
+    display: "flex", flexDirection: "column",
+    padding: 12, gap: 6, overflow: "auto",
+  },
+  paneLabel: { fontSize: 11, color: "#9092b5", textTransform: "uppercase", letterSpacing: "0.06em" },
+  editor: {
+    flex: 1, resize: "none",
+    background: "#0d0e17", color: "#e6e8ff",
+    border: "1px solid #2c2d46", borderRadius: 6, padding: 10,
+    fontFamily: "ui-monospace, SFMono-Regular, monospace", fontSize: 13, lineHeight: 1.5,
+  },
+  editorFoot: { display: "flex", justifyContent: "space-between", fontSize: 11, color: "#9092b5" },
+  shimHint:  { color: "#86efac" },
+  kbdHint:   { color: "#6b7280" },
+  empty: { color: "#9092b5", fontSize: 13, padding: "20px 8px", textAlign: "center" },
+  resultHead: { display: "flex", flexWrap: "wrap", gap: 6, marginBottom: 8 },
+  outputSection: { marginTop: 6 },
+  outputLabel: { cursor: "pointer", fontSize: 11, color: "#9092b5" },
+  stdout: {
+    margin: "4px 0 0", padding: "8px 10px", borderRadius: 4,
+    background: "#000", color: "#d4d4d8", fontSize: 12,
+    fontFamily: "ui-monospace, monospace", whiteSpace: "pre-wrap",
+  },
+  stderr: {
+    margin: "4px 0 0", padding: "8px 10px", borderRadius: 4,
+    background: "#000", color: "#fca5a5", fontSize: 12,
+    fontFamily: "ui-monospace, monospace", whiteSpace: "pre-wrap",
+  },
+  errorBox: {
+    padding: "8px 10px", borderRadius: 6,
+    background: "#3d1111", border: "1px solid #7f1d1d", color: "#fca5a5", fontSize: 12,
+  },
+  errorPre: { margin: "4px 0 0", whiteSpace: "pre-wrap" },
+  okPill:      { padding: "2px 8px", borderRadius: 10, fontSize: 11, fontWeight: 600, background: "#0d3320", color: "#86efac", border: "1px solid #166534" },
+  failPill:    { padding: "2px 8px", borderRadius: 10, fontSize: 11, fontWeight: 600, background: "#3d1111", color: "#fca5a5", border: "1px solid #7f1d1d" },
+  warnPill:    { padding: "2px 8px", borderRadius: 10, fontSize: 11, fontWeight: 600, background: "#3d2d11", color: "#fde68a", border: "1px solid #854d0e" },
+  backendPill: { padding: "2px 8px", borderRadius: 10, fontSize: 11, color: "#c3c5dd", border: "1px solid #2c2d46" },
+  dim: { fontSize: 11, color: "#9092b5" },
+  artifactList: { listStyle: "none", padding: 0, margin: "6px 0 0" },
+  artifactItem: { padding: "3px 0", fontSize: 12 },
+  planStrip: {
+    padding: "8px 12px",
+    background: "#0d0e17",
+    borderBottom: "1px solid #2a2b36",
+  },
+  planErrorStrip: {
+    padding: "8px 12px",
+    fontSize: 12,
+    color: "#fca5a5",
+    background: "#3d1111",
+    borderBottom: "1px solid #7f1d1d",
+  },
+  // Single-pane layout used by MarkdownCanvas (when not in split) and
+  // TextCanvas.  Stretches the single child column across the full
+  // modal body width.
+  bodySingle: { flex: 1, display: "grid", gridTemplateColumns: "1fr", overflow: "hidden" },
+  // Source / Preview / Split segmented control.
+  segGroup: { display: "inline-flex", background: "#0d0e17", border: "1px solid #2c2d46", borderRadius: 6, overflow: "hidden" },
+  seg: {
+    padding: "5px 10px", fontSize: 11,
+    background: "transparent", color: "#9092b5",
+    border: "none", cursor: "pointer",
+  },
+  segActive: {
+    padding: "5px 10px", fontSize: 11, fontWeight: 600,
+    background: "#1e3a5f", color: "#fff",
+    border: "none", cursor: "pointer",
+  },
+  // Markdown source pane — read-only preformatted view, distinct from
+  // the editable <textarea> the CodeCanvas uses.
+  mdSource: {
+    flex: 1, margin: 0, padding: 12,
+    background: "#0d0e17", color: "#e6e8ff",
+    border: "1px solid #2c2d46", borderRadius: 6,
+    fontFamily: "ui-monospace, SFMono-Regular, monospace", fontSize: 13, lineHeight: 1.55,
+    whiteSpace: "pre-wrap", wordBreak: "break-word",
+    overflow: "auto",
+  },
+  // Rendered preview pane.  Subset of CSS that matches the look of
+  // GitHub's rendered README without pulling in a markdown library.
+  mdRendered: {
+    flex: 1, padding: "8px 16px 24px",
+    background: "#0d0e17", color: "#e6e8ff",
+    border: "1px solid #2c2d46", borderRadius: 6,
+    overflow: "auto",
+    fontSize: 14, lineHeight: 1.6,
+  },
+};
diff --git a/frontend/components/SandboxStatusWidget.jsx b/frontend/components/SandboxStatusWidget.jsx
new file mode 100644
index 0000000..56370c7
--- /dev/null
+++ b/frontend/components/SandboxStatusWidget.jsx
@@ -0,0 +1,176 @@
+// frontend/components/SandboxStatusWidget.jsx
+//
+// Always-visible sandbox health pill for the sidebar.  Polls
+// /api/sandbox/status every 30s and surfaces:
+//
+//   ● MatrixLab Ready          (backend up, /health green)
+//   ⚠ MatrixLab unavailable     (network/timeout on /health)
+//   ● Local active              (using subprocess by choice)
+//
+// When degraded, offers two one-click recoveries:
+//   * Repair  — opens Settings → Sandbox to run the install/repair flow
+//   * Use Local — flips backend to subprocess via PUT /api/sandbox/config
+//
+// Purely informational: failures here never block the chat / planner.
+
+import React, { useCallback, useEffect, useRef, useState } from "react";
+
+const POLL_MS = 30_000;
+
+const BACKEND_LABEL = {
+  subprocess: "Local",
+  matrixlab: "MatrixLab",
+  off: "Pass-through",
+};
+
+export default function SandboxStatusWidget({ onOpenSettings }) {
+  const [status, setStatus] = useState(null);
+  const [error, setError] = useState(null);
+  const [switching, setSwitching] = useState(false);
+  const timerRef = useRef(null);
+
+  const refresh = useCallback(async () => {
+    try {
+      const res = await fetch("/api/sandbox/status");
+      const data = await res.json();
+      if (!res.ok) {
+        setError(data.detail || `HTTP ${res.status}`);
+        return;
+      }
+      setStatus(data);
+      setError(null);
+    } catch (err) {
+      setError(err.message || "Unable to reach sandbox status");
+    }
+  }, []);
+
+  useEffect(() => {
+    refresh();
+    timerRef.current = setInterval(refresh, POLL_MS);
+    return () => clearInterval(timerRef.current);
+  }, [refresh]);
+
+  const switchToLocal = async () => {
+    setSwitching(true);
+    try {
+      await fetch("/api/sandbox/config", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ backend: "subprocess" }),
+      });
+      await refresh();
+    } finally {
+      setSwitching(false);
+    }
+  };
+
+  if (!status && !error) {
+    return (
+      <div style={s.shell}>
+        <div style={s.title}>Sandbox</div>
+        <div style={s.dim}>Checking…</div>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div style={s.shell}>
+        <div style={s.title}>Sandbox</div>
+        <div style={{ ...s.statusRow, color: "#fca5a5" }}>
+          <span>⚠</span> Status check failed
+        </div>
+        <div style={s.dim}>{error}</div>
+      </div>
+    );
+  }
+
+  const backend = status.backend || "subprocess";
+  const ok = !!status.ok;
+  const label = BACKEND_LABEL[backend] || backend;
+  const dot = ok ? "●" : "⚠";
+  const dotColor = ok ? "#10B981" : "#f59e0b";
+  const stateText = ok ? "Ready" : "Unavailable";
+
+  return (
+    <div style={s.shell}>
+      <div style={s.titleRow}>
+        <span style={s.title}>Sandbox</span>
+        <button type="button" onClick={refresh} style={s.refresh}
+                title="Refresh sandbox status">↻</button>
+      </div>
+      <div style={s.statusRow}>
+        <span style={{ color: dotColor, marginRight: 6 }}>{dot}</span>
+        <strong>{label}</strong>
+        <span style={s.dim}> · {stateText}</span>
+      </div>
+      {status.matrixlab_url && backend === "matrixlab" && (
+        <div style={s.metaRow}>
+          <span style={s.metaKey}>URL</span>
+          <span style={s.metaVal}>{status.matrixlab_url}</span>
+        </div>
+      )}
+      <div style={s.metaRow}>
+        <span style={s.metaKey}>Timeout</span>
+        <span style={s.metaVal}>{status.timeout_sec}s</span>
+      </div>
+      <div style={s.metaRow}>
+        <span style={s.metaKey}>Network</span>
+        <span style={s.metaVal}>
+          {status.allow_network ? "Enabled" : "Disabled"}
+        </span>
+      </div>
+
+      <div style={s.actions}>
+        {onOpenSettings && (
+          <button type="button" onClick={onOpenSettings} style={s.action}>
+            {ok ? "Change" : "Repair"}
+          </button>
+        )}
+        {!ok && backend === "matrixlab" && (
+          <button
+            type="button"
+            onClick={switchToLocal}
+            disabled={switching}
+            style={{ ...s.action, opacity: switching ? 0.6 : 1 }}
+            title="Switch the sandbox backend to Local subprocess"
+          >
+            {switching ? "Switching…" : "Use Local"}
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+const s = {
+  shell: {
+    padding: "10px 12px",
+    background: "#0d0e17",
+    border: "1px solid #1f2937",
+    borderRadius: 8,
+    fontFamily: "system-ui, sans-serif",
+    fontSize: 12,
+    color: "#e4e4e7",
+  },
+  titleRow: { display: "flex", justifyContent: "space-between", alignItems: "center" },
+  title: {
+    fontSize: 10, fontWeight: 700, letterSpacing: "0.06em",
+    color: "#9092b5", textTransform: "uppercase",
+  },
+  refresh: {
+    background: "transparent", color: "#71717a", border: "none",
+    cursor: "pointer", fontSize: 14, padding: 0,
+  },
+  statusRow: { marginTop: 6, display: "flex", alignItems: "center" },
+  metaRow: { marginTop: 4, display: "flex", justifyContent: "space-between" },
+  metaKey: { color: "#9092b5", fontSize: 11 },
+  metaVal: { color: "#d4d4d8", fontSize: 11, fontFamily: "ui-monospace, monospace" },
+  actions: { display: "flex", gap: 6, marginTop: 8 },
+  action: {
+    flex: 1, padding: "4px 8px", fontSize: 11,
+    background: "transparent", color: "#a1a1aa",
+    border: "1px solid #3F3F46", borderRadius: 4, cursor: "pointer",
+  },
+  dim: { color: "#71717a", fontSize: 11 },
+};
diff --git a/frontend/components/SessionItem.jsx b/frontend/components/SessionItem.jsx
index acf2ce3..462166a 100644
--- a/frontend/components/SessionItem.jsx
+++ b/frontend/components/SessionItem.jsx
@@ -3,28 +3,37 @@ import React, { useState } from "react";
 /**
  * SessionItem — a single row in the sessions sidebar.
  *
- * Shows status dot (pulsing/static), title, timestamp, message count.
- * Claude-Code-on-Web parity: active=amber pulse, completed=green,
- * failed=red, waiting=blue.
+ * Status mapping:
+ *   running / executing  → orange animated pulse  (truly alive)
+ *   selected-idle        → static muted orange    (current, not running)
+ *   inactive / idle      → static dim gray        (old history)
+ *   failed / error       → static red             (warning)
+ *   completed / closed   → static gray            (archived)
  */
 export default function SessionItem({ session, isActive, onSelect, onDelete }) {
   const [hovering, setHovering] = useState(false);
 
-  const status = session.status || "active";
+  const rawStatus = (session.status || "").toLowerCase();
+  const isRunning = rawStatus === "running" || rawStatus === "executing";
+  const isFailed = rawStatus === "failed" || rawStatus === "error";
+  const isCompleted = rawStatus === "completed" || rawStatus === "closed";
 
-  const dotColor = {
-    active: "#F59E0B",
-    completed: "#10B981",
-    failed: "#EF4444",
-    waiting: "#3B82F6",
-    paused: "#6B7280",
-  }[status] || "#6B7280";
-
-  const isPulsing = status === "active";
+  let dotClass;
+  if (isRunning) {
+    dotClass = "session-dot session-dot--active";
+  } else if (isFailed) {
+    dotClass = "session-dot session-dot--failed";
+  } else if (isCompleted) {
+    dotClass = "session-dot session-dot--completed";
+  } else if (isActive) {
+    dotClass = "session-dot session-dot--idle";
+  } else {
+    dotClass = "session-dot session-dot--inactive";
+  }
 
   const timeAgo = formatTimeAgo(session.updated_at);
+  const metaPrimary = isRunning ? "Active now" : timeAgo;
 
-  // Prefer name (set from first user prompt) over generic fallback
   const title =
     session.name ||
     (session.branch ? `${session.branch}` : `Session ${session.id?.slice(0, 8)}`);
@@ -34,37 +43,29 @@ export default function SessionItem({ session, isActive, onSelect, onDelete }) {
       style={{
         ...styles.row,
         backgroundColor: isActive
-          ? "rgba(59, 130, 246, 0.08)"
+          ? "rgba(255, 122, 60, 0.07)"
           : hovering
           ? "rgba(255,255,255,0.03)"
           : "transparent",
-        borderLeft: isActive ? "2px solid #3B82F6" : "2px solid transparent",
+        borderLeft: isActive
+          ? "2px solid rgba(255, 122, 60, 0.7)"
+          : "2px solid transparent",
       }}
       onClick={onSelect}
       onMouseEnter={() => setHovering(true)}
       onMouseLeave={() => setHovering(false)}
     >
-      <style>{`
-        @keyframes session-pulse {
-          0%, 100% { opacity: 1; }
-          50% { opacity: 0.4; }
-        }
-      `}</style>
-
-      {/* Status dot */}
-      <div
-        style={{
-          ...styles.dot,
-          backgroundColor: dotColor,
-          animation: isPulsing ? "session-pulse 1.5s ease-in-out infinite" : "none",
-        }}
-      />
+      <span className={dotClass} aria-hidden="true" />
 
       {/* Content */}
       <div style={styles.content}>
         <div style={styles.title}>{title}</div>
         <div style={styles.meta}>
-          {timeAgo}
+          <span
+            style={isRunning ? styles.metaActive : undefined}
+          >
+            {metaPrimary}
+          </span>
           {session.mode && (
             <span style={{
               ...styles.badge,
@@ -120,7 +121,7 @@ const styles = {
   row: {
     display: "flex",
     alignItems: "center",
-    gap: 8,
+    gap: 10,
     padding: "8px 10px",
     borderRadius: 6,
     cursor: "pointer",
@@ -129,12 +130,6 @@ const styles = {
     marginBottom: 2,
     animation: "session-fade-in 0.25s ease-out",
   },
-  dot: {
-    width: 8,
-    height: 8,
-    borderRadius: "50%",
-    flexShrink: 0,
-  },
   content: {
     flex: 1,
     minWidth: 0,
@@ -156,6 +151,10 @@ const styles = {
     alignItems: "center",
     gap: 6,
   },
+  metaActive: {
+    color: "#ffb089",
+    fontWeight: 600,
+  },
   badge: {
     fontSize: 9,
     background: "#27272A",
diff --git a/frontend/components/SettingsModal.jsx b/frontend/components/SettingsModal.jsx
index 61a44dd..d69f8e3 100644
--- a/frontend/components/SettingsModal.jsx
+++ b/frontend/components/SettingsModal.jsx
@@ -542,7 +542,7 @@ export default function SettingsModal({ onClose }) {
                     value={sandbox.matrixlab_url || ""}
                     onChange={(e) => setSandbox({ ...sandbox, matrixlab_url: e.target.value })}
                     onBlur={() => updateSandbox({ matrixlab_url: sandbox.matrixlab_url })}
-                    placeholder="http://localhost:8000"
+                    placeholder="http://localhost:8765"
                     style={{
                       fontSize: 12, padding: "4px 6px",
                       background: "#14152a", color: "#e6e8ff",
diff --git a/frontend/components/StartupScreen.jsx b/frontend/components/StartupScreen.jsx
index a9c19e8..0695b48 100644
--- a/frontend/components/StartupScreen.jsx
+++ b/frontend/components/StartupScreen.jsx
@@ -1,4 +1,4 @@
-import React from "react";
+import React, { useEffect, useState } from "react";
 
 function normalizeProvider(provider) {
   if (!provider) return "Checking...";
@@ -20,26 +20,57 @@ function normalizeVersion(version) {
   return String(version);
 }
 
+function phaseLabel(phase) {
+  switch (phase) {
+    case "booting":
+      return "Starting services";
+    case "checking-backend":
+      return "Checking backend";
+    case "validating-auth":
+      return "Validating session";
+    case "restoring-session":
+      return "Restoring workspace";
+    case "ready":
+      return "Ready";
+    case "fallback":
+      return "Starting services";
+    default:
+      return "Checking backend";
+  }
+}
+
 export default function StartupScreen({
   appName = "GitPilot",
   subtitle = "Enterprise Workspace Copilot",
   frontendVersion = "Checking...",
   backendVersion = "Checking...",
   provider = "Checking...",
-  statusMessage = "Starting application...",
-  detailMessage = "Initializing authentication, provider, and workspace context.",
-  phase = "booting",
+  statusMessage = "Connecting to backend...",
+  detailMessage = "Preparing your workspace. First launch may take a few seconds.",
+  phase = "checking-backend",
+  onRetry,
 }) {
   const providerLabel = normalizeProvider(provider);
   const frontendLabel = normalizeVersion(frontendVersion);
   const backendLabel = normalizeVersion(backendVersion);
 
+  const [elapsedSec, setElapsedSec] = useState(0);
+  useEffect(() => {
+    const start = Date.now();
+    const id = setInterval(() => {
+      setElapsedSec(Math.floor((Date.now() - start) / 1000));
+    }, 1000);
+    return () => clearInterval(id);
+  }, []);
+
+  const showSlowHint = elapsedSec >= 8 && elapsedSec < 20;
+  const showRetry = elapsedSec >= 20;
+
   return (
     <div className="startup-screen" role="status" aria-live="polite">
       <div className="startup-card">
         <div className="startup-brand-row">
-          <div className="startup-brand-mark" aria-hidden="true">
-            <div className="startup-brand-ring" />
+          <div className="startup-brand-mark startup-brand-mark--static" aria-hidden="true">
             <div className="startup-brand-core" />
           </div>
 
@@ -50,21 +81,45 @@ export default function StartupScreen({
         </div>
 
         <div className="startup-loader-wrap" aria-hidden="true">
-          <div className="startup-loader">
-            <div className="startup-loader-ring startup-loader-ring-outer" />
-            <div className="startup-loader-ring startup-loader-ring-inner" />
+          <div className="startup-orb-loader">
+            <div className="startup-orb-ring-track" />
+            <div className="startup-orb-ring-progress" />
+            <div className="startup-orb-core" />
           </div>
         </div>
 
         <div className="startup-status-block">
           <div className="startup-status">{statusMessage}</div>
           <div className="startup-detail">{detailMessage}</div>
+          {showSlowHint && (
+            <div className="startup-detail startup-detail--hint">
+              Still starting. This can take a little longer on first launch.
+            </div>
+          )}
         </div>
 
         <div className="startup-phase-row">
-          <span className="startup-phase-badge">{phase}</span>
+          <span className="startup-phase-badge">
+            <span className="startup-phase-dot" />
+            {phaseLabel(phase)}
+          </span>
         </div>
 
+        {showRetry && (
+          <div className="startup-action-row">
+            <div className="startup-action-text">
+              Taking longer than expected.
+            </div>
+            <button
+              type="button"
+              className="startup-action-btn"
+              onClick={() => (onRetry ? onRetry() : window.location.reload())}
+            >
+              Retry connection
+            </button>
+          </div>
+        )}
+
         <div className="startup-meta-grid">
           <div className="startup-meta-item">
             <div className="startup-meta-label">Frontend</div>
@@ -89,4 +144,4 @@ export default function StartupScreen({
       </div>
     </div>
   );
-}
\ No newline at end of file
+}
diff --git a/frontend/styles.css b/frontend/styles.css
index 03c11e9..4d95c4a 100644
--- a/frontend/styles.css
+++ b/frontend/styles.css
@@ -3121,6 +3121,14 @@ body {
   animation: startup-spin 1.1s linear infinite;
 }
 
+.startup-brand-mark--static .startup-brand-ring {
+  display: none;
+}
+
+.startup-brand-mark--static .startup-brand-core {
+  inset: 0;
+}
+
 .startup-brand-core {
   position: absolute;
   inset: 11px;
@@ -3152,7 +3160,7 @@ body {
   display: flex;
   align-items: center;
   justify-content: center;
-  padding-top: 4px;
+  padding: 8px 0 4px;
 }
 
 .startup-loader {
@@ -3180,6 +3188,49 @@ body {
   animation: startup-spin-reverse 1.4s linear infinite;
 }
 
+/* Single branded orb loader: static glowing core + one thin rotating ring */
+.startup-orb-loader {
+  position: relative;
+  width: 112px;
+  height: 112px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.startup-orb-ring-track {
+  position: absolute;
+  inset: 0;
+  border-radius: 50%;
+  border: 1.5px solid rgba(255, 255, 255, 0.06);
+}
+
+.startup-orb-ring-progress {
+  position: absolute;
+  inset: 0;
+  border-radius: 50%;
+  border: 1.5px solid transparent;
+  border-top-color: #ff7a3c;
+  border-right-color: rgba(255, 122, 60, 0.55);
+  animation: startup-spin 1.4s linear infinite;
+}
+
+.startup-orb-core {
+  width: 44px;
+  height: 44px;
+  border-radius: 50%;
+  background: radial-gradient(
+    circle at 35% 35%,
+    #ffd2b3 0%,
+    #ff9a5c 30%,
+    #ff7a3c 60%,
+    rgba(255, 122, 60, 0.25) 100%
+  );
+  box-shadow:
+    0 0 18px rgba(255, 122, 60, 0.45),
+    0 0 40px rgba(255, 122, 60, 0.25);
+}
+
 .startup-status-block {
   text-align: center;
 }
@@ -3207,8 +3258,9 @@ body {
   display: inline-flex;
   align-items: center;
   justify-content: center;
+  gap: 8px;
   min-height: 28px;
-  padding: 0 12px;
+  padding: 0 14px;
   border-radius: 999px;
   background: rgba(255, 122, 60, 0.12);
   border: 1px solid rgba(255, 122, 60, 0.24);
@@ -3219,6 +3271,51 @@ body {
   text-transform: uppercase;
 }
 
+.startup-phase-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 999px;
+  background: #ff7a3c;
+  box-shadow: 0 0 0 0 rgba(255, 122, 60, 0.45);
+  animation: startup-phase-pulse 1.6s ease-in-out infinite;
+}
+
+.startup-detail--hint {
+  margin-top: 10px;
+  color: #cbd5e1;
+  font-style: italic;
+}
+
+.startup-action-row {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+}
+
+.startup-action-text {
+  font-size: 12px;
+  color: #94a3b8;
+}
+
+.startup-action-btn {
+  appearance: none;
+  border: 1px solid rgba(255, 122, 60, 0.45);
+  background: rgba(255, 122, 60, 0.10);
+  color: #ffb089;
+  font-size: 13px;
+  font-weight: 600;
+  padding: 8px 16px;
+  border-radius: 10px;
+  cursor: pointer;
+  transition: background 0.15s ease, border-color 0.15s ease;
+}
+
+.startup-action-btn:hover {
+  background: rgba(255, 122, 60, 0.18);
+  border-color: rgba(255, 122, 60, 0.65);
+}
+
 .startup-meta-grid {
   display: grid;
   grid-template-columns: repeat(2, minmax(0, 1fr));
@@ -3277,6 +3374,18 @@ body {
   }
 }
 
+@keyframes startup-phase-pulse {
+  0% {
+    box-shadow: 0 0 0 0 rgba(255, 122, 60, 0.45);
+  }
+  70% {
+    box-shadow: 0 0 0 6px rgba(255, 122, 60, 0);
+  }
+  100% {
+    box-shadow: 0 0 0 0 rgba(255, 122, 60, 0);
+  }
+}
+
 @media (max-width: 640px) {
   .startup-screen {
     padding: 20px;
@@ -3298,4 +3407,1859 @@ body {
   .startup-meta-item-wide {
     grid-column: auto;
   }
-}
\ No newline at end of file
+}
+
+/* =========================================================
+   Session list status dots
+   ========================================================= */
+
+.session-dot {
+  flex-shrink: 0;
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 999px;
+  background: #5b6472;
+  opacity: 0.7;
+}
+
+.session-dot--active {
+  width: 9px;
+  height: 9px;
+  background: #ff7a3c;
+  box-shadow: 0 0 0 4px rgba(255, 122, 60, 0.12);
+  animation: sessionPulse 1.6s ease-in-out infinite;
+  opacity: 1;
+}
+
+.session-dot--idle {
+  width: 8px;
+  height: 8px;
+  background: #b7791f;
+  opacity: 0.85;
+  animation: none;
+}
+
+.session-dot--inactive {
+  width: 6px;
+  height: 6px;
+  background: #3f4654;
+  opacity: 0.6;
+  animation: none;
+}
+
+.session-dot--failed {
+  width: 8px;
+  height: 8px;
+  background: #ef4444;
+  opacity: 0.9;
+  animation: none;
+}
+
+.session-dot--completed {
+  width: 7px;
+  height: 7px;
+  background: #6b7280;
+  opacity: 0.7;
+  animation: none;
+}
+
+@keyframes sessionPulse {
+  0% {
+    box-shadow: 0 0 0 0 rgba(249, 115, 22, 0.35);
+  }
+  70% {
+    box-shadow: 0 0 0 7px rgba(249, 115, 22, 0);
+  }
+  100% {
+    box-shadow: 0 0 0 0 rgba(249, 115, 22, 0);
+  }
+}
+/* =========================================================
+   Assistant message — enterprise execution card
+   ========================================================= */
+
+.assistant-card {
+  margin-bottom: 20px;
+  padding: 20px 22px;
+  background: #18181B;
+  border: 1px solid #27272A;
+  border-radius: 12px;
+  color: #F4F4F5;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  box-shadow:
+    0 4px 6px -1px rgba(0, 0, 0, 0.1),
+    0 2px 4px -1px rgba(0, 0, 0, 0.06);
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+}
+
+.assistant-answer {
+  font-size: 14px;
+  line-height: 1.6;
+}
+
+.assistant-answer__p {
+  margin: 0 0 8px;
+  white-space: pre-wrap;
+}
+
+.assistant-answer__p:last-child {
+  margin-bottom: 0;
+}
+
+.assistant-block {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.assistant-run-error {
+  color: #fca5a5;
+  font-size: 12px;
+}
+
+.assistant-run-output {
+  margin: 0;
+  padding: 8px;
+  font-size: 12px;
+  color: #d4d4d8;
+  background: #000;
+  border-radius: 4px;
+  white-space: pre-wrap;
+}
+
+/* Read-only success status pill (no toggle shape). */
+.exec-status-badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 4px 10px;
+  border-radius: 999px;
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+  line-height: 1;
+  border: 1px solid transparent;
+}
+
+.exec-status-badge--ok {
+  color: #34d399;
+  background: rgba(52, 211, 153, 0.08);
+  border-color: rgba(52, 211, 153, 0.28);
+}
+
+.exec-status-badge--muted {
+  color: #9CA3AF;
+  background: rgba(156, 163, 175, 0.06);
+  border-color: rgba(156, 163, 175, 0.25);
+}
+
+/* ----- Execution plan card (proposed) ----- */
+
+.exec-card {
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+}
+
+.exec-card__head {
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+  align-items: center;
+  gap: 14px;
+  padding-bottom: 14px;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.exec-card__icon {
+  width: 32px;
+  height: 32px;
+  border-radius: 8px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.exec-card__icon--plan {
+  color: #D95C3D;
+  background: rgba(217, 92, 61, 0.10);
+  border: 1px solid rgba(217, 92, 61, 0.25);
+}
+
+.exec-card__head-text {
+  min-width: 0;
+}
+
+.exec-card__eyebrow {
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: #D95C3D;
+  margin-bottom: 4px;
+}
+
+.exec-card__title {
+  font-size: 16px;
+  font-weight: 600;
+  color: #F4F4F5;
+  line-height: 1.4;
+}
+
+.exec-card__head-right {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 8px;
+}
+
+.exec-card__totals {
+  display: flex;
+  gap: 6px;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+}
+
+.exec-total {
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  padding: 3px 8px;
+  border-radius: 999px;
+  border: 1px solid transparent;
+}
+
+.exec-total--create {
+  color: #10B981;
+  background: rgba(16, 185, 129, 0.10);
+  border-color: rgba(16, 185, 129, 0.25);
+}
+
+.exec-total--modify {
+  color: #F59E0B;
+  background: rgba(245, 158, 11, 0.10);
+  border-color: rgba(245, 158, 11, 0.25);
+}
+
+.exec-total--delete {
+  color: #EF4444;
+  background: rgba(239, 68, 68, 0.10);
+  border-color: rgba(239, 68, 68, 0.25);
+}
+
+.exec-total--index {
+  color: #D95C3D;
+  background: rgba(217, 92, 61, 0.10);
+  border-color: rgba(217, 92, 61, 0.25);
+}
+
+/* ----- Timeline of steps ----- */
+
+.exec-timeline {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+}
+
+.exec-step {
+  display: grid;
+  grid-template-columns: 36px 1fr;
+  gap: 14px;
+}
+
+.exec-step__rail {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+}
+
+.exec-step__num {
+  width: 28px;
+  height: 28px;
+  border-radius: 999px;
+  border: 1.5px solid #D95C3D;
+  color: #D95C3D;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 12px;
+  font-weight: 700;
+  background: rgba(217, 92, 61, 0.08);
+  flex-shrink: 0;
+}
+
+.exec-step__line {
+  flex: 1;
+  width: 1.5px;
+  background: linear-gradient(180deg,
+    rgba(217, 92, 61, 0.35) 0%,
+    rgba(217, 92, 61, 0.08) 100%);
+  min-height: 16px;
+}
+
+.exec-step__body {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  padding-top: 2px;
+  min-width: 0;
+}
+
+.exec-step__title {
+  font-size: 14px;
+  font-weight: 600;
+  color: #F4F4F5;
+}
+
+.exec-step__desc {
+  margin: 0;
+  font-size: 13px;
+  line-height: 1.55;
+  color: #A1A1AA;
+}
+
+.exec-actions {
+  list-style: none;
+  padding: 0;
+  margin: 4px 0 0;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.exec-action-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 6px 4px;
+  font-size: 12.5px;
+}
+
+.exec-action__path {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 12.5px;
+  color: #D4D4D8;
+  background: rgba(255, 255, 255, 0.04);
+  padding: 2px 8px;
+  border-radius: 5px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 100%;
+}
+
+/* Compact action badges */
+.exec-badge {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 64px;
+  padding: 4px 10px;
+  border-radius: 6px;
+  font-size: 10.5px;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  font-family: ui-monospace, SFMono-Regular, monospace;
+  flex-shrink: 0;
+  border: 1px solid transparent;
+}
+
+.exec-badge--read {
+  color: #60a5fa;
+  background: rgba(96, 165, 250, 0.10);
+  border-color: rgba(96, 165, 250, 0.30);
+}
+
+.exec-badge--create {
+  color: #10B981;
+  background: rgba(16, 185, 129, 0.10);
+  border-color: rgba(16, 185, 129, 0.30);
+}
+
+.exec-badge--modify {
+  color: #F59E0B;
+  background: rgba(245, 158, 11, 0.10);
+  border-color: rgba(245, 158, 11, 0.30);
+}
+
+.exec-badge--delete {
+  color: #EF4444;
+  background: rgba(239, 68, 68, 0.10);
+  border-color: rgba(239, 68, 68, 0.30);
+}
+
+.exec-badge--index {
+  color: #D95C3D;
+  background: rgba(217, 92, 61, 0.10);
+  border-color: rgba(217, 92, 61, 0.30);
+}
+
+.exec-notice {
+  margin-top: 4px;
+  font-size: 12px;
+  color: #D95C3D;
+  background: rgba(217, 92, 61, 0.05);
+  padding: 8px 12px;
+  border-radius: 6px;
+  border: 1px solid rgba(217, 92, 61, 0.15);
+  line-height: 1.5;
+}
+
+.exec-risk {
+  display: flex;
+  gap: 8px;
+  align-items: flex-start;
+  font-size: 12px;
+  color: #F59E0B;
+  background: rgba(245, 158, 11, 0.05);
+  padding: 8px 12px;
+  border-radius: 6px;
+  border: 1px solid rgba(245, 158, 11, 0.15);
+  line-height: 1.5;
+}
+
+/* ----- Success receipt (Execution completed) ----- */
+
+.success-card {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.success-card__head {
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+  align-items: center;
+  gap: 14px;
+  padding-bottom: 14px;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.success-card__icon {
+  width: 36px;
+  height: 36px;
+  border-radius: 999px;
+  color: #10B981;
+  background: rgba(16, 185, 129, 0.12);
+  border: 1px solid rgba(16, 185, 129, 0.30);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.success-card__title {
+  font-size: 17px;
+  font-weight: 700;
+  color: #F4F4F5;
+  line-height: 1.2;
+}
+
+.success-card__subtitle {
+  margin-top: 4px;
+  font-size: 12.5px;
+  color: #A1A1AA;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.success-card__dot {
+  color: #52525B;
+}
+
+.success-card__time-inline {
+  color: #71717A;
+}
+
+.success-card__badge {
+  align-self: center;
+}
+
+.success-headlines {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.success-headline {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 14px;
+  color: #F4F4F5;
+}
+
+.success-headline__verb {
+  font-weight: 600;
+}
+
+.success-headline__path {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 13px;
+  color: #D4D4D8;
+  background: rgba(255, 255, 255, 0.04);
+  padding: 2px 8px;
+  border-radius: 5px;
+}
+
+.success-files {
+  padding: 14px 16px;
+  background: rgba(255, 255, 255, 0.025);
+  border: 1px solid rgba(255, 255, 255, 0.06);
+  border-radius: 8px;
+}
+
+.success-files__label {
+  font-size: 12px;
+  font-weight: 600;
+  color: #A1A1AA;
+  margin-bottom: 10px;
+}
+
+.success-next-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.success-hint {
+  font-size: 12.5px;
+  color: #71717A;
+  font-style: italic;
+}
+
+.success-techlog__step + .success-techlog__step {
+  margin-top: 10px;
+  padding-top: 10px;
+  border-top: 1px dashed rgba(255, 255, 255, 0.06);
+}
+
+.success-techlog__step-title {
+  font-size: 11.5px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: #71717A;
+  margin: 6px 0 4px;
+}
+
+.success-meta {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 14px;
+  padding: 10px 0;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.success-meta__item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-width: 0;
+}
+
+.success-meta__label {
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: #71717A;
+  flex-shrink: 0;
+}
+
+.success-meta__value {
+  font-size: 12.5px;
+  color: #D4D4D8;
+  font-weight: 500;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.success-meta__value--mono {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 12px;
+}
+
+.success-action-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.success-action-row {
+  display: grid;
+  grid-template-columns: auto auto 1fr auto;
+  align-items: center;
+  gap: 10px;
+  font-size: 12.5px;
+}
+
+.success-action__check {
+  color: #10B981;
+  font-weight: 700;
+  font-size: 13px;
+}
+
+.success-action__path {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 12.5px;
+  color: #D4D4D8;
+  background: rgba(255, 255, 255, 0.04);
+  padding: 2px 8px;
+  border-radius: 5px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.success-action__meta {
+  font-size: 11.5px;
+  color: #71717A;
+  white-space: nowrap;
+}
+
+.next-action-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  border-radius: 6px;
+  padding: 7px 14px;
+  font-size: 12.5px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: background 0.15s ease, border-color 0.15s ease;
+  border: 1px solid transparent;
+}
+
+.next-action-btn__glyph {
+  font-size: 11px;
+}
+
+.next-action-btn--primary {
+  background: #10B981;
+  color: #052e1c;
+  border-color: #10B981;
+}
+
+.next-action-btn--primary:hover {
+  background: #0ea271;
+  border-color: #0ea271;
+}
+
+.next-action-btn--ghost {
+  background: transparent;
+  color: #10B981;
+  border-color: rgba(16, 185, 129, 0.45);
+}
+
+.next-action-btn--ghost:hover {
+  background: rgba(16, 185, 129, 0.10);
+  border-color: rgba(16, 185, 129, 0.65);
+}
+
+.assistant-next-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.success-techlog {
+  margin-top: 6px;
+}
+
+.success-techlog > summary {
+  cursor: pointer;
+  font-size: 12px;
+  color: #71717A;
+  padding: 6px 0;
+  list-style: none;
+  user-select: none;
+}
+
+.success-techlog > summary::-webkit-details-marker {
+  display: none;
+}
+
+.success-techlog > summary::before {
+  content: "▸ ";
+  display: inline-block;
+  margin-right: 4px;
+  transition: transform 0.15s ease;
+}
+
+.success-techlog[open] > summary::before {
+  content: "▾ ";
+}
+
+.success-techlog__time {
+  margin-left: 4px;
+  color: #52525B;
+}
+
+.success-techlog__pre {
+  margin: 4px 0 8px;
+  padding: 8px 10px;
+  font-size: 11.5px;
+  color: #A1A1AA;
+  background: #0d0d0f;
+  border-radius: 6px;
+  border: 1px solid rgba(255, 255, 255, 0.04);
+  white-space: pre-wrap;
+  font-family: ui-monospace, SFMono-Regular, monospace;
+}
+
+/* ----- Inner technical execution card (collapsed by default) ----- */
+
+.exec-card-inner {
+  margin-top: 8px;
+  padding: 10px 12px;
+  border-radius: 8px;
+  background: #0d0e17;
+  border: 1px solid #1f2937;
+  font-family: system-ui, sans-serif;
+  font-size: 12.5px;
+}
+
+.exec-card-inner--ok    { border-color: #166534; }
+.exec-card-inner--bad   { border-color: #7f1d1d; }
+.exec-card-inner--warn  { border-color: #854d0e; }
+.exec-card-inner--info  { border-color: #3B82F6; }
+
+.exec-card-inner__head {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  margin-bottom: 6px;
+  gap: 8px;
+}
+
+.exec-card-inner__path {
+  font-family: ui-monospace, monospace;
+}
+
+.exec-card-inner__sandbox {
+  margin-left: 8px;
+  font-size: 11px;
+  color: #9092b5;
+}
+
+.exec-card-inner__status {
+  padding: 2px 8px;
+  border-radius: 999px;
+  font-size: 10.5px;
+  font-weight: 600;
+  background: rgba(255, 255, 255, 0.04);
+  color: #A1A1AA;
+  border: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.exec-card-inner__cmd {
+  font-size: 11.5px;
+  padding: 6px 10px;
+  border-radius: 4px;
+  background: #000;
+  color: #93c5fd;
+  font-family: ui-monospace, SFMono-Regular, monospace;
+  margin-bottom: 8px;
+}
+
+.exec-card-inner__pre {
+  margin: 6px 0 0;
+  padding: 8px 10px;
+  border-radius: 4px;
+  background: #000;
+  color: #d4d4d8;
+  font-size: 11.5px;
+  font-family: ui-monospace, monospace;
+  max-height: 240px;
+  overflow: auto;
+  white-space: pre-wrap;
+}
+
+.exec-card-inner__pre--err { color: #fca5a5; }
+
+.exec-card-inner__stdout-summary {
+  cursor: pointer;
+  font-size: 11px;
+  color: #86efac;
+}
+
+.exec-card-inner__stderr-summary {
+  cursor: pointer;
+  font-size: 11px;
+  color: #fca5a5;
+}
+
+.exec-card-inner__error,
+.exec-card-inner__reason {
+  font-size: 11.5px;
+  color: #9092b5;
+  margin-top: 4px;
+}
+
+.exec-card-inner__error { color: #fca5a5; }
+
+@media (max-width: 640px) {
+  .exec-card__head {
+    grid-template-columns: auto 1fr;
+  }
+  .exec-card__totals {
+    grid-column: 1 / -1;
+    justify-content: flex-start;
+  }
+  .success-card__head {
+    grid-template-columns: auto 1fr;
+  }
+  .success-card__badge {
+    grid-column: 1 / -1;
+    justify-self: flex-start;
+  }
+  .success-meta {
+    grid-template-columns: 1fr;
+    gap: 8px;
+  }
+  .success-action-row {
+    grid-template-columns: auto auto 1fr;
+  }
+  .success-action__meta {
+    grid-column: 1 / -1;
+    margin-left: 88px;
+  }
+}
+
+/* =========================================================
+   File viewer — calm "not available" state
+   ========================================================= */
+
+.file-notavail {
+  margin: 24px 18px;
+  padding: 22px 22px 18px;
+  border-radius: 10px;
+  background: rgba(255, 255, 255, 0.025);
+  border: 1px solid rgba(255, 255, 255, 0.06);
+  color: #E4E4E7;
+  font-family: system-ui, sans-serif;
+}
+
+.file-notavail__icon {
+  width: 36px;
+  height: 36px;
+  border-radius: 999px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 16px;
+  font-weight: 700;
+  margin-bottom: 12px;
+}
+
+.file-notavail--muted { /* deleted, unavailable */ }
+.file-notavail--muted .file-notavail__icon {
+  background: rgba(156, 163, 175, 0.10);
+  color: #9CA3AF;
+  border: 1px solid rgba(156, 163, 175, 0.30);
+}
+
+.file-notavail--info .file-notavail__icon { /* syncing */
+  background: rgba(96, 165, 250, 0.10);
+  color: #60a5fa;
+  border: 1px solid rgba(96, 165, 250, 0.30);
+  animation: file-notavail-spin 1.6s linear infinite;
+}
+
+.file-notavail--warn .file-notavail__icon { /* generic error */
+  background: rgba(245, 158, 11, 0.10);
+  color: #F59E0B;
+  border: 1px solid rgba(245, 158, 11, 0.30);
+}
+
+@keyframes file-notavail-spin {
+  from { transform: rotate(0deg); }
+  to   { transform: rotate(360deg); }
+}
+
+.file-notavail__title {
+  font-size: 16px;
+  font-weight: 600;
+  color: #F4F4F5;
+  margin-bottom: 6px;
+}
+
+.file-notavail__body {
+  font-size: 13px;
+  color: #A1A1AA;
+  line-height: 1.55;
+  margin-bottom: 14px;
+}
+
+.file-notavail__fields {
+  display: grid;
+  grid-template-columns: 70px 1fr;
+  row-gap: 6px;
+  column-gap: 14px;
+  font-size: 12px;
+  margin: 0 0 16px;
+  padding: 10px 12px;
+  background: rgba(0, 0, 0, 0.25);
+  border-radius: 6px;
+  border: 1px solid rgba(255, 255, 255, 0.04);
+}
+
+.file-notavail__fields dt {
+  margin: 0;
+  color: #71717A;
+  font-weight: 500;
+}
+
+.file-notavail__fields dd {
+  margin: 0;
+  color: #D4D4D8;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.file-notavail__fields code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 11.5px;
+  word-break: break-all;
+}
+
+.file-notavail__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.file-notavail__btn {
+  padding: 6px 14px;
+  font-size: 12px;
+  font-weight: 500;
+  border-radius: 6px;
+  cursor: pointer;
+  background: transparent;
+  color: #c3c5dd;
+  border: 1px solid #2c2d46;
+  transition: background 0.15s ease, border-color 0.15s ease;
+}
+
+.file-notavail__btn:hover {
+  background: rgba(255, 255, 255, 0.04);
+  border-color: #3F3F46;
+}
+
+.file-notavail__btn--primary {
+  background: #D95C3D;
+  color: #ffffff;
+  border-color: #D95C3D;
+}
+
+.file-notavail__btn--primary:hover {
+  background: #c54f30;
+  border-color: #c54f30;
+}
+
+.file-notavail__details {
+  margin-top: 14px;
+}
+
+.file-notavail__details > summary {
+  cursor: pointer;
+  font-size: 11.5px;
+  color: #71717A;
+  list-style: none;
+}
+
+.file-notavail__details > summary::-webkit-details-marker {
+  display: none;
+}
+
+.file-notavail__details > summary::before {
+  content: "▸ ";
+  margin-right: 4px;
+}
+
+.file-notavail__details[open] > summary::before {
+  content: "▾ ";
+}
+
+.file-notavail__details pre {
+  margin: 6px 0 0;
+  padding: 8px 10px;
+  font-size: 11px;
+  background: #000;
+  color: #A1A1AA;
+  border-radius: 4px;
+  white-space: pre-wrap;
+  font-family: ui-monospace, monospace;
+}
+
+/* =========================================================
+   Sandbox Canvas — enterprise runner
+   ========================================================= */
+
+.canvas-modal {
+  display: flex;
+  flex-direction: column;
+  background: #0c0d18;
+  border: 1px solid #1f2030;
+  border-radius: 12px;
+  overflow: hidden;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+}
+
+.canvas-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 12px 16px;
+  border-bottom: 1px solid #1f2030;
+  background: #0c0d18;
+}
+
+.canvas-header__left,
+.canvas-header__right {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.canvas-header__glyph {
+  width: 28px;
+  height: 28px;
+  border-radius: 6px;
+  background: rgba(255, 255, 255, 0.04);
+  border: 1px solid rgba(255, 255, 255, 0.06);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: #c3c5dd;
+  flex-shrink: 0;
+}
+
+.canvas-header__title {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 14px;
+  font-weight: 600;
+  color: #F4F4F5;
+  margin-right: 6px;
+}
+
+.canvas-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 4px 10px;
+  border-radius: 999px;
+  font-size: 11px;
+  font-weight: 500;
+  border: 1px solid transparent;
+  line-height: 1;
+}
+
+.canvas-pill__dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 999px;
+  background: currentColor;
+}
+
+.canvas-pill--lang {
+  color: #fbbf24;
+  background: rgba(251, 191, 36, 0.08);
+  border-color: rgba(251, 191, 36, 0.25);
+}
+
+.canvas-pill--sandbox {
+  color: #34d399;
+  background: rgba(52, 211, 153, 0.08);
+  border-color: rgba(52, 211, 153, 0.25);
+}
+
+.canvas-run-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 18px;
+  border-radius: 8px;
+  background: #2563eb;
+  color: #ffffff;
+  border: none;
+  font-size: 13px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: background 0.15s ease;
+}
+
+.canvas-run-btn:hover:not(:disabled) {
+  background: #1d4ed8;
+}
+
+.canvas-run-btn:disabled {
+  opacity: 0.7;
+  cursor: not-allowed;
+}
+
+.canvas-run-btn__spinner {
+  width: 10px;
+  height: 10px;
+  border-radius: 999px;
+  border: 2px solid rgba(255, 255, 255, 0.4);
+  border-top-color: #ffffff;
+  animation: canvas-spin 0.9s linear infinite;
+}
+
+@keyframes canvas-spin {
+  from { transform: rotate(0deg); }
+  to   { transform: rotate(360deg); }
+}
+
+.canvas-icon-btn {
+  width: 32px;
+  height: 32px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  background: transparent;
+  border: 1px solid #2c2d46;
+  border-radius: 6px;
+  color: #9092b5;
+  font-size: 16px;
+  cursor: pointer;
+  transition: background 0.15s ease, border-color 0.15s ease;
+}
+
+.canvas-icon-btn:hover {
+  background: rgba(255, 255, 255, 0.04);
+  border-color: #3F3F46;
+  color: #c3c5dd;
+}
+
+.canvas-icon-btn--close {
+  font-size: 14px;
+}
+
+.canvas-menu {
+  position: relative;
+}
+
+.canvas-menu__panel {
+  position: absolute;
+  right: 0;
+  top: 38px;
+  min-width: 180px;
+  background: #14152a;
+  border: 1px solid #2c2d46;
+  border-radius: 8px;
+  box-shadow: 0 12px 28px rgba(0, 0, 0, 0.5);
+  padding: 4px 0;
+  z-index: 30;
+}
+
+.canvas-menu__item {
+  display: block;
+  width: 100%;
+  text-align: left;
+  background: transparent;
+  border: none;
+  color: #E4E4E7;
+  font-size: 13px;
+  padding: 8px 14px;
+  cursor: pointer;
+}
+
+.canvas-menu__item:hover {
+  background: rgba(255, 255, 255, 0.04);
+}
+
+/* ----- Calm status strip ----- */
+
+.canvas-status {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 14px 18px;
+  background: #0c0d18;
+  border-bottom: 1px solid #1f2030;
+}
+
+.canvas-status__dot {
+  width: 28px;
+  height: 28px;
+  border-radius: 999px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  font-size: 14px;
+  font-weight: 700;
+  border: 1.5px solid transparent;
+}
+
+.canvas-status__dot--ok {
+  color: #34d399;
+  background: rgba(52, 211, 153, 0.12);
+  border-color: rgba(52, 211, 153, 0.35);
+}
+
+.canvas-status__dot--bad {
+  color: #f87171;
+  background: rgba(248, 113, 113, 0.12);
+  border-color: rgba(248, 113, 113, 0.35);
+}
+
+.canvas-status__dot--info {
+  color: #60a5fa;
+  background: rgba(96, 165, 250, 0.12);
+  border-color: rgba(96, 165, 250, 0.35);
+  position: relative;
+}
+
+.canvas-status__dot--info::after {
+  content: "";
+  position: absolute;
+  inset: 4px;
+  border-radius: 999px;
+  border: 1.5px solid transparent;
+  border-top-color: #60a5fa;
+  animation: canvas-spin 1.1s linear infinite;
+}
+
+.canvas-status__text {
+  flex: 1;
+  min-width: 0;
+}
+
+.canvas-status__title {
+  font-size: 14px;
+  font-weight: 600;
+  color: #F4F4F5;
+}
+
+.canvas-status__sub {
+  margin-top: 2px;
+  font-size: 12px;
+  color: #9092b5;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 6px;
+}
+
+.canvas-status__sub code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 11.5px;
+  background: rgba(255, 255, 255, 0.04);
+  padding: 1px 6px;
+  border-radius: 4px;
+  color: #c3c5dd;
+}
+
+.canvas-status__sep { color: #4b5563; }
+
+.canvas-status__details {
+  background: transparent;
+  border: none;
+  color: #60a5fa;
+  font-size: 12px;
+  cursor: pointer;
+  padding: 4px 8px;
+  border-radius: 4px;
+}
+
+.canvas-status__details:hover {
+  background: rgba(96, 165, 250, 0.08);
+}
+
+.canvas-run-config {
+  padding: 12px 18px 14px;
+  background: rgba(255, 255, 255, 0.02);
+  border-bottom: 1px solid #1f2030;
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 8px 24px;
+}
+
+.canvas-run-config__row {
+  display: flex;
+  gap: 12px;
+  align-items: baseline;
+}
+
+.canvas-run-config__label {
+  width: 110px;
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: #71717A;
+  font-weight: 600;
+}
+
+.canvas-run-config__val {
+  font-size: 12.5px;
+  color: #D4D4D8;
+}
+
+.canvas-run-config__val code,
+code.canvas-run-config__val {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  background: rgba(255, 255, 255, 0.04);
+  padding: 1px 6px;
+  border-radius: 4px;
+  font-size: 12px;
+}
+
+/* ----- Notices ----- */
+
+.canvas-notices {
+  padding: 12px 18px 14px;
+  border-bottom: 1px solid #1f2030;
+}
+
+.canvas-notices__label {
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: #71717A;
+  margin-bottom: 8px;
+}
+
+.canvas-notices__row {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  gap: 10px;
+}
+
+.canvas-notice {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  padding: 12px 14px;
+  border-radius: 8px;
+  background: rgba(255, 255, 255, 0.025);
+  border: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.canvas-notice__icon {
+  width: 26px;
+  height: 26px;
+  border-radius: 6px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  font-weight: 700;
+  font-size: 13px;
+}
+
+.canvas-notice--info .canvas-notice__icon {
+  color: #60a5fa;
+  background: rgba(96, 165, 250, 0.10);
+  border: 1px solid rgba(96, 165, 250, 0.25);
+}
+
+.canvas-notice--accent .canvas-notice__icon {
+  color: #34d399;
+  background: rgba(52, 211, 153, 0.10);
+  border: 1px solid rgba(52, 211, 153, 0.25);
+}
+
+.canvas-notice__title {
+  font-size: 13px;
+  font-weight: 600;
+  color: #F4F4F5;
+}
+
+.canvas-notice__desc {
+  margin-top: 2px;
+  font-size: 12px;
+  color: #9092b5;
+  line-height: 1.5;
+}
+
+/* ----- Approval confirmation strip ----- */
+
+.canvas-confirm {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  padding: 10px 18px;
+  background: rgba(96, 165, 250, 0.06);
+  border-bottom: 1px solid rgba(96, 165, 250, 0.2);
+  font-size: 12.5px;
+  color: #c3c5dd;
+}
+
+.canvas-confirm__text { flex: 1; }
+
+.canvas-confirm__text code {
+  font-family: ui-monospace, monospace;
+  background: rgba(255, 255, 255, 0.06);
+  padding: 1px 6px;
+  border-radius: 4px;
+}
+
+.canvas-confirm__cancel {
+  background: transparent;
+  border: 1px solid #2c2d46;
+  color: #c3c5dd;
+  padding: 5px 12px;
+  font-size: 12px;
+  border-radius: 6px;
+  cursor: pointer;
+}
+
+.canvas-confirm__cancel:hover {
+  background: rgba(255, 255, 255, 0.04);
+}
+
+.canvas-plan-error {
+  padding: 8px 18px;
+  font-size: 12px;
+  color: #fca5a5;
+  background: rgba(127, 29, 29, 0.25);
+  border-bottom: 1px solid #7f1d1d;
+}
+
+/* ----- Split body ----- */
+
+.canvas-body {
+  flex: 1;
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  overflow: hidden;
+  min-height: 0;
+}
+
+.canvas-pane {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  background: #0c0d18;
+}
+
+.canvas-pane--source {
+  border-right: 1px solid #1f2030;
+}
+
+.canvas-pane__head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 16px;
+  border-bottom: 1px solid #1f2030;
+  background: rgba(255, 255, 255, 0.015);
+}
+
+.canvas-pane__title {
+  font-size: 13px;
+  font-weight: 600;
+  color: #E4E4E7;
+}
+
+.canvas-pane__head-right {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.canvas-pane__meta {
+  font-size: 11px;
+  color: #71717A;
+}
+
+.canvas-pane__icon {
+  width: 26px;
+  height: 26px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  background: transparent;
+  border: 1px solid #2c2d46;
+  border-radius: 5px;
+  color: #9092b5;
+  cursor: pointer;
+}
+
+.canvas-pane__icon:hover {
+  background: rgba(255, 255, 255, 0.04);
+}
+
+.canvas-pane__icon-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  background: transparent;
+  border: 1px solid #2c2d46;
+  border-radius: 6px;
+  padding: 4px 10px;
+  font-size: 11.5px;
+  color: #9092b5;
+  cursor: pointer;
+}
+
+.canvas-pane__icon-btn:hover {
+  background: rgba(255, 255, 255, 0.04);
+  color: #c3c5dd;
+}
+
+/* ----- Editor with gutter ----- */
+
+.canvas-editor-wrap {
+  flex: 1;
+  display: grid;
+  grid-template-columns: 56px 1fr;
+  min-height: 0;
+  overflow: hidden;
+}
+
+.canvas-editor-gutter {
+  margin: 0;
+  padding: 12px 0;
+  background: #0c0d18;
+  color: #4b5563;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 12.5px;
+  line-height: 1.6;
+  text-align: right;
+  border-right: 1px solid #1f2030;
+  overflow: hidden;
+  user-select: none;
+}
+
+.canvas-editor-gutter__line {
+  padding: 0 12px;
+  font-variant-numeric: tabular-nums;
+}
+
+.canvas-editor {
+  flex: 1;
+  resize: none;
+  background: #0c0d18;
+  color: #e6e8ff;
+  border: none;
+  padding: 12px 14px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 12.5px;
+  line-height: 1.6;
+  outline: none;
+  white-space: pre;
+  overflow: auto;
+}
+
+.canvas-statusbar {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 16px;
+  border-top: 1px solid #1f2030;
+  background: rgba(255, 255, 255, 0.015);
+  font-size: 11px;
+  color: #71717A;
+}
+
+.canvas-statusbar__sep { color: #3F3F46; }
+.canvas-statusbar__spacer { flex: 1; }
+.canvas-statusbar__kbd { color: #52525B; }
+
+/* ----- Output pane ----- */
+
+.canvas-output-body {
+  flex: 1;
+  overflow: auto;
+  padding: 16px 18px;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.canvas-output-empty {
+  text-align: center;
+  padding: 40px 20px;
+  color: #9092b5;
+}
+
+.canvas-output-empty__title {
+  font-size: 14px;
+  font-weight: 600;
+  color: #c3c5dd;
+  margin-bottom: 6px;
+}
+
+.canvas-output-empty__sub {
+  font-size: 12.5px;
+  color: #71717A;
+  line-height: 1.55;
+}
+
+.canvas-output-running {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 14px;
+  border-radius: 8px;
+  background: rgba(96, 165, 250, 0.06);
+  border: 1px solid rgba(96, 165, 250, 0.2);
+  color: #93c5fd;
+  font-size: 12.5px;
+  align-self: flex-start;
+}
+
+.canvas-output-running__spinner {
+  width: 12px;
+  height: 12px;
+  border-radius: 999px;
+  border: 2px solid rgba(96, 165, 250, 0.4);
+  border-top-color: #60a5fa;
+  animation: canvas-spin 0.9s linear infinite;
+}
+
+.canvas-result-head {
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+  align-items: center;
+  gap: 12px;
+  padding: 10px 14px;
+  border-radius: 8px;
+  border: 1px solid transparent;
+}
+
+.canvas-result-head--ok {
+  background: rgba(52, 211, 153, 0.05);
+  border-color: rgba(52, 211, 153, 0.2);
+}
+
+.canvas-result-head--bad {
+  background: rgba(239, 68, 68, 0.05);
+  border-color: rgba(239, 68, 68, 0.25);
+}
+
+.canvas-result-icon {
+  width: 30px;
+  height: 30px;
+  border-radius: 999px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 700;
+  font-size: 14px;
+}
+
+.canvas-result-head--ok .canvas-result-icon {
+  background: rgba(52, 211, 153, 0.15);
+  color: #34d399;
+}
+
+.canvas-result-head--bad .canvas-result-icon {
+  background: rgba(239, 68, 68, 0.15);
+  color: #f87171;
+}
+
+.canvas-result-title {
+  font-size: 14px;
+  font-weight: 600;
+  color: #F4F4F5;
+}
+
+.canvas-result-sub {
+  margin-top: 2px;
+  font-size: 11.5px;
+  color: #9092b5;
+}
+
+.canvas-result-time {
+  font-size: 11.5px;
+  color: #71717A;
+}
+
+.canvas-result-err {
+  margin: 4px 0 0;
+  padding: 6px 8px;
+  background: rgba(0, 0, 0, 0.35);
+  border-radius: 4px;
+  font-family: ui-monospace, monospace;
+  font-size: 12px;
+  color: #fca5a5;
+  white-space: pre-wrap;
+}
+
+.canvas-output-section {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.canvas-output-section__label {
+  font-size: 10.5px;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: #9092b5;
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.canvas-output-section__label--err {
+  color: #fca5a5;
+}
+
+.canvas-output-section__count {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 18px;
+  height: 18px;
+  padding: 0 6px;
+  border-radius: 999px;
+  background: rgba(96, 165, 250, 0.15);
+  color: #93c5fd;
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 0;
+}
+
+.canvas-output-pre {
+  margin: 0;
+  padding: 12px 14px;
+  background: #06070f;
+  border: 1px solid #1f2030;
+  border-radius: 8px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 12px;
+  line-height: 1.55;
+  color: #d4d4d8;
+  white-space: pre-wrap;
+  overflow: auto;
+  max-height: 320px;
+}
+
+.canvas-output-pre--err {
+  color: #fca5a5;
+  border-color: rgba(127, 29, 29, 0.6);
+  background: rgba(127, 29, 29, 0.10);
+}
+
+/* ----- Artifacts ----- */
+
+.canvas-artifacts {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.canvas-artifact {
+  background: rgba(255, 255, 255, 0.025);
+  border: 1px solid rgba(255, 255, 255, 0.06);
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+.canvas-artifact__img {
+  display: block;
+  width: 100%;
+  max-height: 360px;
+  object-fit: contain;
+  background: #ffffff;
+}
+
+.canvas-artifact__row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px 12px;
+  border-top: 1px solid rgba(255, 255, 255, 0.04);
+}
+
+.canvas-artifact:first-child .canvas-artifact__row {
+  border-top: none;
+}
+
+.canvas-artifact__icon {
+  width: 26px;
+  height: 26px;
+  border-radius: 6px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(96, 165, 250, 0.10);
+  color: #60a5fa;
+  border: 1px solid rgba(96, 165, 250, 0.25);
+  flex-shrink: 0;
+}
+
+.canvas-artifact__name {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 12.5px;
+  color: #D4D4D8;
+}
+
+.canvas-artifact__badge {
+  font-size: 10.5px;
+  font-weight: 600;
+  letter-spacing: 0.03em;
+  padding: 2px 8px;
+  border-radius: 999px;
+  background: rgba(96, 165, 250, 0.12);
+  color: #93c5fd;
+  border: 1px solid rgba(96, 165, 250, 0.25);
+}
+
+.canvas-artifact__meta {
+  margin-left: auto;
+  font-size: 11px;
+  color: #71717A;
+}
+
+.canvas-artifact__download {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 26px;
+  border-radius: 5px;
+  background: transparent;
+  border: 1px solid #2c2d46;
+  color: #9092b5;
+  text-decoration: none;
+  transition: background 0.15s ease;
+}
+
+.canvas-artifact__download:hover {
+  background: rgba(255, 255, 255, 0.04);
+  color: #c3c5dd;
+}
+
+@media (max-width: 900px) {
+  .canvas-body {
+    grid-template-columns: 1fr;
+  }
+  .canvas-pane--source {
+    border-right: none;
+    border-bottom: 1px solid #1f2030;
+  }
+  .canvas-run-config {
+    grid-template-columns: 1fr;
+  }
+}
diff --git a/gitpilot/_api_core.py b/gitpilot/_api_core.py
index bea4091..8aad3b7 100644
--- a/gitpilot/_api_core.py
+++ b/gitpilot/_api_core.py
@@ -507,10 +507,11 @@ async def api_get_file(
     owner: str = FPath(...),
     repo: str = FPath(...),
     path: str = Query(...),
+    ref: Optional[str] = Query(None),
     authorization: Optional[str] = Header(None),
 ):
     token = get_github_token(authorization)
-    content = await get_file(owner, repo, path, token=token)
+    content = await get_file(owner, repo, path, token=token, ref=ref)
     return FileContent(path=path, content=content)
 
 
diff --git a/gitpilot/agent_prompts.py b/gitpilot/agent_prompts.py
index a284da8..6e6c5d4 100644
--- a/gitpilot/agent_prompts.py
+++ b/gitpilot/agent_prompts.py
@@ -185,6 +185,15 @@
 - Match the action to what the user goal asks for.
 """
 
+PLAN_TASK_RULES_EXECUTE = """\
+Rules:
+- The user asked to run / execute a script that already exists.
+- Use EXECUTE for runnable files (.py, .js, .sh) in the existing-files list.
+- Do not CREATE, MODIFY, or DELETE unless the goal asks for it.
+- The executor will run the file through the configured sandbox (Local
+  subprocess or MatrixLab Runner) and report stdout / stderr / exit code.
+"""
+
 # Schema block kept tight — one example object, no prose explanations.
 PLAN_TASK_SCHEMA = """\
 Return one JSON object only (no markdown fences, no prose):
@@ -206,7 +215,7 @@
 }
 
 JSON rules:
-- "action" is one of: CREATE, MODIFY, DELETE, READ, INDEX
+- "action" is one of: CREATE, MODIFY, DELETE, READ, INDEX, EXECUTE
 - "step_number" is a positive integer
 - "risks" is either a string or null (the JSON null literal)
 - The entire response is the JSON object — nothing before or after
@@ -231,6 +240,7 @@
     "delete":  PLAN_TASK_RULES_DELETE,
     "find":    PLAN_TASK_RULES_FIND,
     "info":    PLAN_TASK_RULES_INFO,
+    "execute": PLAN_TASK_RULES_EXECUTE,
     "unknown": PLAN_TASK_RULES_UNKNOWN,
 }
 
diff --git a/gitpilot/agentic.py b/gitpilot/agentic.py
index 22f2883..2b9ea3f 100644
--- a/gitpilot/agentic.py
+++ b/gitpilot/agentic.py
@@ -4,7 +4,7 @@
 import contextvars
 import logging
 from textwrap import dedent
-from typing import Any, Dict, List, Literal, Optional
+from typing import Any, Dict, List, Literal, Optional, Sequence
 
 from pydantic import BaseModel, Field, ValidationError as _PydanticValidationError
 from .agent_router import AgentType, RequestCategory, WorkflowPlan, route as route_request
@@ -271,7 +271,7 @@ class PlanFile(BaseModel):
     """
     path: str
     action: Literal[
-        "CREATE", "MODIFY", "DELETE", "READ", "INDEX",
+        "CREATE", "MODIFY", "DELETE", "READ", "INDEX", "EXECUTE",
     ] = "MODIFY"
 
 
@@ -286,10 +286,217 @@ class PlanStep(BaseModel):
 
 
 class PlanResult(BaseModel):
-    """The complete execution plan."""
+    """The complete execution plan.
+
+    ``execution_plan`` is the approval-first Sandbox ExecutionPlan
+    described in :mod:`gitpilot.sandbox_plan`.  When the router
+    detects an unambiguous RUN_FILE intent it is populated here so
+    the chat UI can render the green ExecutionPlanCard *instead of*
+    the orange Action Plan — sandbox execution and repo changes
+    require visibly different consent surfaces.
+
+    Always ``None`` for create/modify/delete plans.  Always present
+    for execute plans the short-circuit accepts.
+    """
     goal: str
     summary: str
     steps: List[PlanStep]
+    execution_plan: Optional[Dict[str, Any]] = None
+
+
+# ---------------------------------------------------------------------------
+# EXECUTE short-circuit
+#
+# When the user's request is unambiguously "run this file" and the file
+# exists in the repo with a runnable extension, we skip the LLM planner
+# entirely.  Two wins:
+#
+# 1. Correctness — the planner running through a small / ReAct-trained
+#    LLM has been observed to interpret "EXECUTE" as a CrewAI tool name
+#    rather than a JSON action value, fail repeatedly, then downgrade
+#    the action to "READ".  A deterministic plan eliminates that
+#    failure class entirely.
+#
+# 2. Latency — no LLM round-trip; the next request reaches the
+#    executor in milliseconds and the user sees an execution card
+#    almost immediately.
+
+_RUNNABLE_EXTENSIONS = frozenset({"py", "js", "mjs", "cjs", "sh", "bash"})
+
+
+def _is_runnable_path(path: str) -> bool:
+    """True when ``path`` ends in a sandbox-runnable extension."""
+    if "." not in path:
+        return False
+    ext = path.rsplit(".", 1)[-1].lower()
+    return ext in _RUNNABLE_EXTENSIONS
+
+
+_MATPLOTLIB_HINTS = (
+    "import matplotlib", "from matplotlib", "plt.show", "pyplot",
+)
+
+
+def _looks_like_matplotlib(code: str) -> bool:
+    """Quick check for matplotlib usage so we can inject the Agg backend
+    only when needed.  False positives are harmless (Agg works for any
+    Python script); false negatives cause the sandbox to hang on
+    ``plt.show()``, which is what this guard prevents."""
+    lowered = code.lower()
+    return any(hint in lowered for hint in _MATPLOTLIB_HINTS)
+
+
+# Last-ditch extractor for runnable-looking paths in a goal string.
+# Used when the router's verified ``target_files`` is empty — typical
+# when the user names a file that's freshly created on the branch and
+# the cached tree fetch doesn't show it yet.  Trusting the user's text
+# is much better UX than rejecting the short-circuit and falling through
+# to the LLM, which then returns an empty plan.
+import re as _re_runnable
+_RUNNABLE_PATH_RE = _re_runnable.compile(
+    r"[\w\-./]+\.(?:py|js|mjs|cjs|sh|bash)\b", _re_runnable.IGNORECASE,
+)
+
+
+def _extract_runnable_paths_from_goal(goal: str) -> List[str]:
+    """Return runnable-extension path tokens mentioned in ``goal``.
+
+    Deduplicated, original order preserved. Trims surrounding
+    punctuation that the bareword regex sometimes pulls in.
+    """
+    out: List[str] = []
+    seen: set[str] = set()
+    for m in _RUNNABLE_PATH_RE.finditer(goal or ""):
+        tok = m.group(0).strip(".,:;()[]{}'\"`")
+        if tok and tok not in seen:
+            seen.add(tok)
+            out.append(tok)
+    return out
+
+
+def try_execute_short_circuit(
+    *,
+    goal: str,
+    intent: Optional[str],
+    target_files: Sequence[str],
+    repo_files: Sequence[str],
+) -> Optional["PlanResult"]:
+    """Return a deterministic EXECUTE plan when one is unambiguous.
+
+    Triggers when:
+      * routing intent is ``execute``
+      * exactly one runnable file is implied — either named explicitly
+        in ``target_files`` (router-verified to exist), extracted from
+        the goal text when verification dropped it (race / stale cache),
+        or the only runnable file in the repo when the user said
+        "run the script" without naming one.
+
+    Returns ``None`` to fall through to the LLM planner otherwise.
+    """
+    if (intent or "").lower() != "execute":
+        return None
+
+    # The "file freshly created but not yet in the tree fetch" race is
+    # the most common reason verification drops a perfectly good target
+    # — track whether we had to fall back so the executor / UI can
+    # adjust the safety check label accordingly.
+    file_verified_against_repo = False
+    candidates: List[str] = [p for p in target_files if _is_runnable_path(p)]
+    if candidates:
+        file_verified_against_repo = True
+    else:
+        # Try extracting runnable-shaped paths directly from the goal.
+        # Trust the user — the executor reports a clean "file not found"
+        # if the path turns out to be wrong, which is far better UX
+        # than the LLM's "empty plan" failure mode.
+        extracted = _extract_runnable_paths_from_goal(goal)
+        if extracted:
+            candidates = extracted
+        else:
+            # User said "run the script" without naming a file.  Resolve
+            # by uniqueness: a single runnable in the repo wins; anything
+            # else falls through to the LLM so it can ask.
+            repo_runnable = [p for p in repo_files if _is_runnable_path(p)]
+            if len(repo_runnable) == 1:
+                candidates = repo_runnable
+                file_verified_against_repo = True
+    if len(candidates) != 1:
+        return None
+
+    path = candidates[0]
+
+    # Attach a deterministic ExecutionPlan so the chat UI can render
+    # the green approval card.  The Action-Plan-style PlanStep below
+    # stays in place so callers that still consume that shape (and
+    # the executor itself) work unchanged.
+    execution_plan_dict: Optional[Dict[str, Any]] = None
+    try:
+        from .sandbox_plan import build_execution_plan_for_file
+        from .settings import get_settings
+
+        _settings = get_settings()
+        _sb = _settings.sandbox
+        _sandbox_label = "matrixlab" if (_sb.backend or "").lower() == "matrixlab" else "subprocess"
+        # When we couldn't verify the file against the repo tree, pass
+        # the path itself as the repo_files list so the builder's
+        # membership check passes — the safety check below clarifies
+        # the verification state honestly.
+        _repo_files_for_plan = list(repo_files) if file_verified_against_repo else [path]
+        ep = build_execution_plan_for_file(
+            file=path,
+            repo_files=_repo_files_for_plan,
+            sandbox=_sandbox_label,  # type: ignore[arg-type]
+            timeout_sec=int(_sb.timeout_sec or 120),
+            network=bool(_sb.allow_network),
+            source="chat",
+        )
+        if ep is not None:
+            execution_plan_dict = ep.to_dict()
+            if not file_verified_against_repo:
+                # Adjust the safety surface: flip the "File exists"
+                # check to ok=False and add a low-severity warning so
+                # the user can still approve, but with clear context.
+                for c in execution_plan_dict.get("safety", {}).get("checks", []):
+                    if c.get("label") == "File exists":
+                        c["ok"] = False
+                        c["label"] = (
+                            f"File path: {path} (existence not verified)"
+                        )
+                execution_plan_dict.setdefault("safety", {}).setdefault(
+                    "warnings", []
+                ).insert(0, {
+                    "severity": "low",
+                    "label": "File not in cached repo tree",
+                    "detail": (
+                        "GitPilot didn't see this file in the latest repo "
+                        "tree fetch — usually a stale cache or a file that "
+                        "was created on this branch but not yet pushed. "
+                        "The sandbox will report a clean 'file not found' "
+                        "if the path is wrong."
+                    ),
+                })
+    except Exception:  # pragma: no cover - defensive
+        execution_plan_dict = None
+
+    return PlanResult(
+        goal=goal,
+        summary=(
+            f"Run {path} in the configured sandbox and report stdout, "
+            f"stderr, exit code, and duration."
+        ),
+        steps=[PlanStep(
+            step_number=1,
+            title=f"Run {path}",
+            description=(
+                f"Execute {path} through the active sandbox backend "
+                f"(Local subprocess or MatrixLab Runner). The executor "
+                f"reads the file at apply time and POSTs to /api/sandbox/run."
+            ),
+            files=[PlanFile(path=path, action="EXECUTE")],
+            risks=None,
+        )],
+        execution_plan=execution_plan_dict,
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -664,7 +871,8 @@ def _explore():
                     {{"path": "file/path.py", "action": "CREATE"}},
                     {{"path": "another/file.py", "action": "MODIFY"}},
                     {{"path": "old/file.py", "action": "DELETE"}},
-                    {{"path": "README.md", "action": "READ"}}
+                    {{"path": "README.md", "action": "READ"}},
+                    {{"path": "hello.py", "action": "EXECUTE"}}
                   ],
                   "risks": "Optional risk description or null"
                 }}
@@ -676,7 +884,13 @@ def _explore():
             - STRICTLY NO COMMENTS allowed (no // or #).
             - Double quotes around all keys and string values.
             - No trailing commas.
-            - "action" MUST be exactly one of: "CREATE", "MODIFY", "DELETE", "READ"
+            - "action" MUST be exactly one of: "CREATE", "MODIFY", "DELETE", "READ", "EXECUTE"
+              (use EXECUTE to run an existing runnable file — .py, .js, .sh — through the configured sandbox)
+            - "EXECUTE" is a JSON STRING VALUE only.  It is NOT a tool name.
+              Never write "Action: EXECUTE" or attempt to invoke EXECUTE as a tool —
+              your tools are exactly the ones listed above (repository inspection +
+              file reading).  Execution happens AFTER you return this JSON plan;
+              the GitPilot executor reads it and runs the file through the sandbox.
             - "step_number" MUST be an integer starting from 1
             - "risks" can be either a string or null (the JSON null value, without quotes)
             - Do NOT wrap the JSON in markdown code fences
@@ -693,7 +907,7 @@ def _explore():
               - step_number: integer
               - title: string
               - description: string
-              - files: array of { "path": string, "action": "CREATE" | "MODIFY" | "DELETE" | "READ" }
+              - files: array of { "path": string, "action": "CREATE" | "MODIFY" | "DELETE" | "READ" | "EXECUTE" }
               - risks: string or null
             The response must contain ONLY pure JSON (no markdown, no prose, no code fences, NO COMMENTS).
         """),
@@ -1196,6 +1410,11 @@ async def execute_plan_lite(
 
     for step in plan.steps:
         step_summary = f"Step {step.step_number}: {step.title}"
+        # Structured execution results for this step — emitted by the
+        # EXECUTE branch so the frontend can render an execution card
+        # (command, sandbox, exit_code, stdout, stderr, duration) rather
+        # than the plain ``summary`` string.
+        step_executions: List[Dict[str, Any]] = []
 
         for file in step.files:
             try:
@@ -1299,7 +1518,10 @@ def _modify():
                 logger.exception("Lite: Error processing %s: %s", file.path, e)
                 step_summary += f"\n  ! Error: {file.path}: {e}"
 
-        execution_steps.append({"step_number": step.step_number, "summary": step_summary})
+        step_record: Dict[str, Any] = {"step_number": step.step_number, "summary": step_summary}
+        if step_executions:
+            step_record["executions"] = step_executions
+        execution_steps.append(step_record)
 
     return {
         "status": "completed",
@@ -1374,6 +1596,11 @@ async def execute_plan(
 
     for step in plan.steps:
         step_summary = f"Step {step.step_number}: {step.title}"
+        # Structured execution results for this step — emitted by the
+        # EXECUTE branch so the frontend can render an execution card
+        # (command, sandbox, exit_code, stdout, stderr, duration) rather
+        # than the plain ``summary`` string.
+        step_executions: List[Dict[str, Any]] = []
 
         for file in step.files:
             try:
@@ -1533,6 +1760,116 @@ def _modify():
                 elif file.action == "READ":
                     step_summary += f"\n  ℹ️ READ-only: inspected {file.path}"
 
+                elif file.action == "EXECUTE":
+                    # Pull the file's content from the active branch and
+                    # ship it to whichever sandbox the user selected in
+                    # Settings → Sandbox (Local subprocess or MatrixLab
+                    # Runner). Both reach the runner through the same
+                    # /api/sandbox/run handler so behaviour matches the
+                    # Run button on chat code blocks.
+                    #
+                    # The structured ``execution`` dict appended to the
+                    # step record is what the frontend renders as an
+                    # execution card (command, sandbox, exit code,
+                    # stdout, stderr, duration) instead of a plain
+                    # answer string.
+                    execution_card: Dict[str, Any] = {
+                        "path": file.path,
+                        "status": "pending",
+                    }
+                    try:
+                        content = await get_file(
+                            owner, repo, file.path, token=token, ref=branch_name,
+                        )
+                        ext = file.path.rsplit(".", 1)[-1].lower() if "." in file.path else ""
+                        lang_map = {
+                            "py": "python", "js": "javascript", "mjs": "javascript",
+                            "cjs": "javascript", "sh": "bash", "bash": "bash",
+                        }
+                        language = lang_map.get(ext)
+                        command_str = {
+                            "python": f"python {file.path}",
+                            "javascript": f"node {file.path}",
+                            "bash": f"bash {file.path}",
+                        }.get(language or "")
+                        execution_card.update(
+                            language=language,
+                            command=command_str,
+                        )
+                        if language is None:
+                            execution_card.update(status="skipped", reason=(
+                                f"extension {ext!r} is not runnable in the sandbox"
+                            ))
+                            step_summary += (
+                                f"\n  ⚠️ EXECUTE skipped: {file.path} extension "
+                                f"{ext!r} is not runnable in the sandbox"
+                            )
+                        else:
+                            # Matplotlib's default backend opens a window — that
+                            # hangs forever in a headless sandbox.  Prepend an
+                            # ``import os`` shim that forces the Agg backend so
+                            # plots are renderable to file but plt.show() is a
+                            # no-op.  Only injected when we can see matplotlib
+                            # imports so non-plotting scripts run untouched.
+                            shipped_code = content
+                            if language == "python" and _looks_like_matplotlib(content):
+                                shipped_code = (
+                                    'import os as _gp_os\n'
+                                    '_gp_os.environ.setdefault("MPLBACKEND", "Agg")\n'
+                                ) + content
+                                execution_card["matplotlib_shim"] = True
+
+                            from .sandbox_api import (
+                                SandboxRunRequest,
+                                api_sandbox_run,
+                            )
+                            result = await api_sandbox_run(
+                                SandboxRunRequest(language=language, code=shipped_code),
+                            )
+                            execution_card.update(
+                                status="completed" if result.exit_code == 0 else "failed",
+                                sandbox=result.backend,
+                                exit_code=result.exit_code,
+                                stdout=result.stdout or "",
+                                stderr=result.stderr or "",
+                                duration_ms=result.duration_ms,
+                                truncated=bool(result.truncated),
+                                timed_out=bool(result.timed_out),
+                            )
+                            ok_glyph = "✓" if result.exit_code == 0 else "✗"
+                            step_summary += (
+                                f"\n  {ok_glyph} EXECUTE {file.path} on "
+                                f"{result.backend} (exit {result.exit_code}, "
+                                f"{result.duration_ms} ms)"
+                            )
+                            if result.stdout:
+                                stdout_preview = result.stdout.strip()
+                                if len(stdout_preview) > 1000:
+                                    stdout_preview = stdout_preview[:1000] + "…"
+                                step_summary += f"\n     stdout: {stdout_preview}"
+                            if result.stderr:
+                                stderr_preview = result.stderr.strip()
+                                if len(stderr_preview) > 500:
+                                    stderr_preview = stderr_preview[:500] + "…"
+                                step_summary += f"\n     stderr: {stderr_preview}"
+                    except HTTPException as exc:
+                        execution_card.update(
+                            status="failed",
+                            error=f"{exc.detail} (HTTP {exc.status_code})",
+                        )
+                        step_summary += (
+                            f"\n  ✗ EXECUTE {file.path} failed: "
+                            f"{exc.detail} (HTTP {exc.status_code})"
+                        )
+                    except Exception as exc:  # noqa: BLE001
+                        logger.exception(
+                            "Failed to execute file %s in step %s: %s",
+                            file.path, step.step_number, exc,
+                        )
+                        execution_card.update(status="failed", error=str(exc))
+                        step_summary += f"\n  ✗ EXECUTE {file.path} failed: {exc}"
+                    step_executions.append(execution_card)
+
                 elif file.action == "INDEX":
                     # Batch B9 — triggers the per-repo RAG index build.
                     summary_line = await _execute_index_action(
@@ -1549,7 +1886,40 @@ def _modify():
                 )
                 step_summary += f"\n  ✗ Error processing {file.path}: {str(e)}"
 
-        execution_steps.append({"step_number": step.step_number, "summary": step_summary})
+        step_record: Dict[str, Any] = {"step_number": step.step_number, "summary": step_summary}
+        if step_executions:
+            step_record["executions"] = step_executions
+        execution_steps.append(step_record)
+
+    # Suggest the obvious next action: any runnable file the plan
+    # just created or modified gets a "Run <path>" CTA in the
+    # completion card.  Deterministic — no LLM needed — so the
+    # user never has to type "execute demo.py" after asking
+    # GitPilot to create it.
+    next_actions: List[Dict[str, Any]] = []
+    seen_paths: set[str] = set()
+    for step in plan.steps:
+        for pf in getattr(step, "files", []) or []:
+            action = (getattr(pf, "action", None) or "").upper()
+            path = getattr(pf, "path", None)
+            if not path or path in seen_paths:
+                continue
+            if action in {"CREATE", "MODIFY"} and _is_runnable_path(path):
+                seen_paths.add(path)
+                # "Prepare Run" — not "Run" — because clicking opens an
+                # ExecutionPlan approval card, not silent execution.
+                # The wording is the single biggest enterprise-UX cue
+                # that the click is consented, not autopilot.
+                next_actions.append({
+                    "kind": "run_file",
+                    "label": f"Prepare Run {path}",
+                    "payload": {"file": path},
+                })
+                next_actions.append({
+                    "kind": "open_workspace",
+                    "label": "Open Workspace",
+                    "payload": {"file": path},
+                })
 
     return {
         "status": "completed",
@@ -1557,6 +1927,7 @@ def _modify():
         "branch": branch_name,
         "branch_url": f"https://github.com/{repo_full_name}/tree/{branch_name}",
         "executionLog": {"steps": execution_steps},
+        "next_actions": next_actions,
     }
 
 
diff --git a/gitpilot/api.py b/gitpilot/api.py
index 75fcc85..8f256a5 100644
--- a/gitpilot/api.py
+++ b/gitpilot/api.py
@@ -322,6 +322,18 @@ def _env_bool(name: str, default: bool) -> bool:
 except Exception:  # noqa: BLE001
     logger.exception("Sandbox API failed to mount; Run button will be disabled")
 
+# MatrixLab addon admin API (Settings → Sandbox → Install MatrixLab modal).
+# Sits on top of /api/sandbox/* and normalises every response so the UI
+# never has to interpret raw Docker / HTTP errors.  Same non-fatal mount
+# pattern as the sandbox router.
+try:
+    from .matrixlab_admin_api import router as matrixlab_admin_router
+
+    app.include_router(matrixlab_admin_router)
+    logger.info("MatrixLab admin API enabled (mounting /api/matrixlab/* endpoints)")
+except Exception:  # noqa: BLE001
+    logger.exception("MatrixLab admin API failed to mount; install modal will be disabled")
+
 # GitPilot-as-MCP-server (turns GitPilot into an MCP server other agents
 # can drive). Off by default; mount only when GITPILOT_EXPOSE_MCP_SERVER=true.
 try:
@@ -1047,10 +1059,11 @@ async def api_get_file(
     owner: str = FPath(...),
     repo: str = FPath(...),
     path: str = Query(...),
+    ref: Optional[str] = Query(None),
     authorization: Optional[str] = Header(None),
 ):
     token = get_github_token(authorization)
-    content = await get_file(owner, repo, path, token=token)
+    content = await get_file(owner, repo, path, token=token, ref=ref)
     return FileContent(path=path, content=content)
 
 
@@ -1402,6 +1415,8 @@ async def api_chat_plan(req: ChatPlanRequest, authorization: Optional[str] = Hea
         # back to today's no-hint behaviour rather than 500-ing.
         routing_hint = None
         routing_intent: Optional[str] = None
+        routing_targets: list[str] = []
+        repo_paths: list[str] = []
         try:
             from . import flags as _flags
             if _flags.is_on("query_router", default=True):
@@ -1411,7 +1426,6 @@ async def api_chat_plan(req: ChatPlanRequest, authorization: Optional[str] = Hea
                 # Cheap path: a flat list of repo files for the
                 # classifier's path-verification step.  Failure is
                 # tolerated — router falls back to "no targets".
-                repo_paths: list[str] = []
                 try:
                     from .github_api import get_repo_tree
                     _tree = await get_repo_tree(
@@ -1434,7 +1448,28 @@ async def api_chat_plan(req: ChatPlanRequest, authorization: Optional[str] = Hea
                 )
                 routing_hint = render_planner_hint(decision)
                 routing_intent = decision.intent
+                routing_targets = list(decision.target_files or [])
                 logger.info("[router] %s", decision.rationale)
+
+                # EXECUTE short-circuit — skip the LLM when "run this
+                # file" is unambiguous.  Cheap, deterministic, and
+                # avoids the small-LLM failure mode where the planner
+                # tries to call EXECUTE as a CrewAI tool, fails, then
+                # downgrades to READ — the bug pattern we documented
+                # in agentic.try_execute_short_circuit's docstring.
+                from .agentic import try_execute_short_circuit
+                short = try_execute_short_circuit(
+                    goal=req.goal,
+                    intent=routing_intent,
+                    target_files=decision.target_files or [],
+                    repo_files=repo_paths,
+                )
+                if short is not None:
+                    logger.info(
+                        "[router] EXECUTE short-circuit: skipping LLM planner; "
+                        "target=%s", short.steps[0].files[0].path,
+                    )
+                    return short
         except Exception as _route_err:  # pragma: no cover - defensive
             logger.debug("[router] skipped: %s", _route_err)
             routing_hint = None
@@ -1447,6 +1482,68 @@ async def api_chat_plan(req: ChatPlanRequest, authorization: Optional[str] = Hea
                 routing_hint=routing_hint,
                 intent=routing_intent,
             )
+
+            # Belt-and-suspenders for the "execute" path: if the
+            # short-circuit didn't fire pre-LLM (router didn't classify,
+            # or no path candidates surfaced) and the planner came back
+            # with an empty / answer-only plan, retry the short-circuit
+            # post-LLM so the user gets a real EXECUTE action instead
+            # of "execute the existing file" plain text.
+            try:
+                from .agentic import try_execute_short_circuit
+                no_actionable = (
+                    not getattr(plan, "steps", None)
+                    or all(
+                        not getattr(step, "files", None)
+                        or all(
+                            getattr(f, "action", None) in {None, "READ"}
+                            for f in step.files
+                        )
+                        for step in plan.steps
+                    )
+                )
+                if no_actionable:
+                    goal_lower = req.goal.lower()
+                    looks_like_execute = any(
+                        kw in goal_lower
+                        for kw in ("execute", "run the", "run hello",
+                                   "run main", "run demo", "run my",
+                                   "in the sandbox", "in sandbox",
+                                   "please run", "can you run")
+                    )
+                    if looks_like_execute:
+                        # ``repo_paths`` was computed during routing; if
+                        # routing was skipped, fall back to a quick tree
+                        # fetch so the short-circuit has a chance.
+                        if not repo_paths:
+                            try:
+                                from .github_api import get_repo_tree
+                                _tree = await get_repo_tree(
+                                    req.repo_owner, req.repo_name,
+                                    token=token, ref=req.branch_name,
+                                )
+                                repo_paths = [t["path"] for t in (_tree or []) if t.get("path")]
+                            except Exception:
+                                pass
+
+                        # Try the explicitly-mentioned target first, then
+                        # fall back to "single runnable in repo".
+                        fallback = try_execute_short_circuit(
+                            goal=req.goal, intent="execute",
+                            target_files=routing_targets,
+                            repo_files=repo_paths,
+                        )
+                        if fallback is not None:
+                            logger.info(
+                                "[router] post-LLM EXECUTE rescue: planner returned no "
+                                "actionable steps for an execute-looking goal — "
+                                "substituting deterministic plan for %s",
+                                fallback.steps[0].files[0].path,
+                            )
+                            return fallback
+            except Exception as _rescue_err:  # pragma: no cover - defensive
+                logger.debug("[router] post-LLM execute rescue skipped: %s", _rescue_err)
+
             return plan
         except Exception as exc:
             error_msg = str(exc)
diff --git a/gitpilot/matrixlab_admin_api.py b/gitpilot/matrixlab_admin_api.py
new file mode 100644
index 0000000..c4b7a40
--- /dev/null
+++ b/gitpilot/matrixlab_admin_api.py
@@ -0,0 +1,1287 @@
+"""Enterprise install/lifecycle surface for the MatrixLab addon.
+
+Sits on top of :mod:`gitpilot.sandbox_api` and normalises every response
+into the single :class:`MatrixLabStatus` shape the install modal renders.
+The goal is to keep raw Docker / HTTP failures out of the UI: every
+error gets classified into a stable ``errorCode`` + a human ``message``,
+with the verbatim trace surfaced only under ``technicalDetails`` for
+operators who open the disclosure.
+
+Endpoints under ``/api/matrixlab/*``:
+
+* ``GET    /status``    — current lifecycle + health, normalised
+* ``POST   /install``   — idempotent: pull images then start runner
+* ``POST   /start``     — start (or no-op if running)
+* ``POST   /stop``      — stop the runner
+* ``POST   /restart``   — stop+start sequence
+* ``POST   /test``      — re-probe /health, return normalised status
+* ``POST   /activate``  — set sandbox backend = matrixlab once ready
+* ``GET    /logs``      — tail of the lifecycle transcript
+
+All of these are additive — :mod:`sandbox_api` continues to back the
+existing Run button and the legacy Settings modal.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Literal, Optional
+
+import httpx
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from .sandbox_api import (
+    DEFAULT_CONTAINER_NAME,
+    DEFAULT_RUNNER_IMAGE,
+    ENV_LIFECYCLE,
+    MatrixLabLifecycleResponse,
+    SandboxConfigUpdate,
+    _docker_available,
+    _gather_lifecycle_status,
+    _lifecycle_enabled,
+    _matrixlab_running,
+    _run_shell,
+    api_matrixlab_install as _legacy_install,
+    api_matrixlab_start as _legacy_start,
+    api_matrixlab_stop as _legacy_stop,
+    api_sandbox_config as _legacy_config,
+)
+from .settings import get_settings
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/matrixlab", tags=["matrixlab"])
+
+
+# ----------------------------------------------------------------------
+# Normalised response shape
+# ----------------------------------------------------------------------
+
+StatusName = Literal[
+    "not_installed",
+    "installing",
+    "starting",
+    "stopping",
+    "checking",
+    "ready",
+    "needs_attention",
+    "failed",
+]
+
+
+class TechnicalDetails(BaseModel):
+    """Verbatim trace for operators; hidden behind a disclosure in the UI."""
+
+    expected: Optional[str] = None
+    actual: Optional[str] = None
+    rawError: Optional[str] = None
+    rawCommand: Optional[str] = None
+    rawStdout: Optional[str] = None
+    rawStderr: Optional[str] = None
+
+
+class MatrixLabStatus(BaseModel):
+    """Single source of truth the install modal binds to."""
+
+    status: StatusName
+    installed: bool
+    running: bool
+    reachable: bool
+    lifecycleEnabled: bool
+    dockerAvailable: bool
+    activeSandbox: str
+    runnerUrl: str
+    message: str
+    errorCode: Optional[str] = None
+    technicalDetails: Optional[TechnicalDetails] = None
+    runnerImage: str = DEFAULT_RUNNER_IMAGE
+    version: Optional[str] = None
+    # Last lifecycle step transcript — populated by install/start/stop
+    # so the UI's "Open logs" affordance has something to show without
+    # a second round trip.
+    steps: List[Dict[str, Any]] = Field(default_factory=list)
+    # When the persisted ``runnerUrl`` is unreachable but a different
+    # candidate URL (e.g. localhost:8765 vs the stale localhost:8000)
+    # responds on /health, the modal surfaces a one-click "Use
+    # ``discoveredUrl``" CTA.  ``None`` when no discrepancy is found.
+    discoveredUrl: Optional[str] = None
+
+
+# ----------------------------------------------------------------------
+# Pure helpers — kept side-effect free so they're trivially unit-testable
+# ----------------------------------------------------------------------
+
+# Order matters: more specific phrases first.  Each entry is
+# (substring-to-match, errorCode, user-facing message).  Match is
+# case-insensitive on a lowercased raw_error string.
+_ERROR_CLASSIFIERS: List[tuple[str, str, str]] = [
+    (
+        "expecting value",
+        "INVALID_HEALTH_RESPONSE",
+        "The runner responded, but not with the expected health response.",
+    ),
+    (
+        "json",
+        "INVALID_HEALTH_RESPONSE",
+        "The runner responded, but not with the expected health response.",
+    ),
+    (
+        "connection refused",
+        "CONNECTION_REFUSED",
+        "GitPilot could not connect to the MatrixLab runner.",
+    ),
+    (
+        "refused",
+        "CONNECTION_REFUSED",
+        "GitPilot could not connect to the MatrixLab runner.",
+    ),
+    (
+        "timed out",
+        "TIMEOUT",
+        "MatrixLab took too long to respond.",
+    ),
+    (
+        "timeout",
+        "TIMEOUT",
+        "MatrixLab took too long to respond.",
+    ),
+    (
+        "name or service not known",
+        "DNS_ERROR",
+        "The runner hostname could not be resolved.",
+    ),
+    (
+        "cannot connect to the docker daemon",
+        "DOCKER_NOT_RUNNING",
+        "Docker is not running. Start Docker and try again.",
+    ),
+    (
+        "docker daemon",
+        "DOCKER_NOT_RUNNING",
+        "Docker is not running. Start Docker and try again.",
+    ),
+    (
+        "port is already allocated",
+        "PORT_IN_USE",
+        "The MatrixLab port is already in use by another service.",
+    ),
+    (
+        "address already in use",
+        "PORT_IN_USE",
+        "The MatrixLab port is already in use by another service.",
+    ),
+    (
+        "permission denied",
+        "PERMISSION_DENIED",
+        "GitPilot does not have permission to start MatrixLab.",
+    ),
+    (
+        "no such image",
+        "IMAGE_MISSING",
+        "The MatrixLab runner image is missing. Try installing again.",
+    ),
+    (
+        "not on path",
+        "DOCKER_NOT_INSTALLED",
+        "Docker is not installed on the GitPilot host.",
+    ),
+]
+
+
+def classify_error(raw_error: Optional[str]) -> tuple[str, str]:
+    """Map a raw error string into ``(errorCode, humanMessage)``.
+
+    Pure. Never raises. Returns ``("", "")`` when ``raw_error`` is empty
+    so callers can use truthiness to detect "no classifiable error".
+    """
+    if not raw_error:
+        return ("", "")
+    needle = raw_error.lower()
+    for substring, code, message in _ERROR_CLASSIFIERS:
+        if substring in needle:
+            return (code, message)
+    return ("UNKNOWN", "MatrixLab encountered an unexpected error.")
+
+
+def derive_status(
+    *,
+    lifecycle: MatrixLabLifecycleResponse,
+    reachable: bool,
+    health_error: Optional[str],
+    active_sandbox: str,
+    in_flight: Optional[StatusName] = None,
+) -> MatrixLabStatus:
+    """Combine lifecycle + connection probe into a single ``MatrixLabStatus``.
+
+    Pure. ``in_flight`` lets POST handlers report ``installing`` /
+    ``starting`` / ``stopping`` while a long-running shell-out is mid
+    way — GET /status never sets it.
+    """
+    docker_ok = lifecycle.docker_available
+    installed = lifecycle.installed
+    running = lifecycle.running
+
+    if in_flight is not None:
+        return MatrixLabStatus(
+            status=in_flight,
+            installed=installed,
+            running=running,
+            reachable=reachable,
+            lifecycleEnabled=lifecycle.lifecycle_enabled,
+            dockerAvailable=docker_ok,
+            activeSandbox=active_sandbox,
+            runnerUrl=lifecycle.matrixlab_url,
+            runnerImage=lifecycle.runner_image,
+            message=_in_flight_message(in_flight),
+        )
+
+    # Terminal states resolved from the lifecycle facts.
+    if not docker_ok:
+        code, msg = classify_error("docker not on path")
+        return MatrixLabStatus(
+            status="needs_attention",
+            installed=installed, running=running, reachable=reachable,
+            lifecycleEnabled=lifecycle.lifecycle_enabled,
+            dockerAvailable=False,
+            activeSandbox=active_sandbox,
+            runnerUrl=lifecycle.matrixlab_url,
+            runnerImage=lifecycle.runner_image,
+            message=msg,
+            errorCode=code,
+        )
+
+    if not installed and not running:
+        return MatrixLabStatus(
+            status="not_installed",
+            installed=False, running=False, reachable=False,
+            lifecycleEnabled=lifecycle.lifecycle_enabled,
+            dockerAvailable=docker_ok,
+            activeSandbox=active_sandbox,
+            runnerUrl=lifecycle.matrixlab_url,
+            runnerImage=lifecycle.runner_image,
+            message="MatrixLab is not installed yet.",
+        )
+
+    if running and reachable:
+        return MatrixLabStatus(
+            status="ready",
+            installed=True, running=True, reachable=True,
+            lifecycleEnabled=lifecycle.lifecycle_enabled,
+            dockerAvailable=docker_ok,
+            activeSandbox=active_sandbox,
+            runnerUrl=lifecycle.matrixlab_url,
+            runnerImage=lifecycle.runner_image,
+            message="MatrixLab is ready.",
+        )
+
+    # running but not reachable — runner is alive but /health failed
+    if running and not reachable:
+        code, msg = classify_error(health_error or "connection refused")
+        details = TechnicalDetails(
+            expected="JSON health response from /health",
+            actual="empty or invalid response" if code == "INVALID_HEALTH_RESPONSE"
+                   else "no response",
+            rawError=health_error or None,
+        )
+        return MatrixLabStatus(
+            status="needs_attention",
+            installed=True, running=True, reachable=False,
+            lifecycleEnabled=lifecycle.lifecycle_enabled,
+            dockerAvailable=docker_ok,
+            activeSandbox=active_sandbox,
+            runnerUrl=lifecycle.matrixlab_url,
+            runnerImage=lifecycle.runner_image,
+            # "Installed but cannot connect" reads as a single coherent
+            # state in the install modal.  The runner URL itself is
+            # promoted to ``technicalDetails`` rather than embedded in
+            # the headline message — see derive_status caller.
+            message="MatrixLab is installed, but GitPilot cannot connect to the runner.",
+            errorCode=code or "CONNECTION_REFUSED",
+            technicalDetails=details,
+        )
+
+    # installed but not running — typical post-Stop or crash state
+    return MatrixLabStatus(
+        status="needs_attention",
+        installed=True, running=False, reachable=False,
+        lifecycleEnabled=lifecycle.lifecycle_enabled,
+        dockerAvailable=docker_ok,
+        activeSandbox=active_sandbox,
+        runnerUrl=lifecycle.matrixlab_url,
+        runnerImage=lifecycle.runner_image,
+        message="MatrixLab is installed but not running.",
+        errorCode="STOPPED",
+    )
+
+
+def _in_flight_message(state: StatusName) -> str:
+    return {
+        "installing": "Installing MatrixLab…",
+        "starting": "Starting MatrixLab…",
+        "stopping": "Stopping MatrixLab…",
+        "checking": "Checking connection…",
+    }.get(state, "Working…")
+
+
+async def _probe_health() -> tuple[bool, Optional[str], Optional[str]]:
+    """Return ``(reachable, raw_error, version)`` for the configured runner.
+
+    Distinct from :func:`sandbox_api._matrixlab_running` because we
+    need the error text (to classify) and the version (to surface)
+    rather than a yes/no.
+    """
+    cfg = get_settings().sandbox
+    base = (cfg.matrixlab_url or "http://localhost:8000").rstrip("/")
+    return await _probe_url(base)
+
+
+async def _probe_url(base: str) -> tuple[bool, Optional[str], Optional[str]]:
+    """Health-probe one explicit URL.  Same shape as :func:`_probe_health`
+    so the auto-detect path can reuse the parsing logic."""
+    try:
+        async with httpx.AsyncClient(timeout=3.0) as client:
+            resp = await client.get(f"{base}/health")
+            if resp.status_code != 200:
+                return (False, f"HTTP {resp.status_code}: {resp.text[:200]}", None)
+            try:
+                data = resp.json()
+            except Exception as exc:  # noqa: BLE001 - we want the raw text
+                return (False, str(exc), None)
+            return (True, None, str(data.get("version")) if data.get("version") else None)
+    except httpx.HTTPError as exc:
+        return (False, str(exc), None)
+
+
+# Candidate URLs the auto-detector tries when the persisted runner URL
+# doesn't respond.  Kept short and deterministic so the modal's
+# "looking for runner..." spinner doesn't blow past 1-2s.
+#
+# Order matters: the canonical post-:8000-collision port (8765) comes
+# first because that's where ``make install`` puts the runner today.
+# The stale :8000 default is included for completeness — when a user
+# is mid-migration, this is the URL their persisted settings still
+# point at.
+_CANDIDATE_URLS = (
+    "http://localhost:8765",
+    "http://127.0.0.1:8765",
+    "http://localhost:8000",
+    "http://127.0.0.1:8000",
+)
+
+
+async def _discover_live_url(current_url: str) -> Optional[str]:
+    """Return the first candidate URL whose /health responds, excluding
+    ``current_url`` (which the caller has already established is down).
+    None when nothing else answers — keeps the call honest about the
+    "configured URL is stale" advisory.
+    """
+    current_norm = (current_url or "").rstrip("/")
+    for candidate in _CANDIDATE_URLS:
+        if candidate == current_norm:
+            continue
+        reachable, _err, _ver = await _probe_url(candidate)
+        if reachable:
+            return candidate
+    return None
+
+
+def _steps_to_dicts(lifecycle: MatrixLabLifecycleResponse) -> List[Dict[str, Any]]:
+    """Pull the lifecycle step transcript out as plain dicts for the UI."""
+    out: List[Dict[str, Any]] = []
+    for step in lifecycle.steps or []:
+        out.append({
+            "cmd": step.cmd,
+            "exitCode": step.exit_code,
+            "stdout": step.stdout,
+            "stderr": step.stderr,
+            "durationMs": step.duration_ms,
+        })
+    return out
+
+
+def _attach_steps(status: MatrixLabStatus, lifecycle: MatrixLabLifecycleResponse) -> MatrixLabStatus:
+    """Return a copy of ``status`` with the lifecycle transcript attached."""
+    return status.model_copy(update={"steps": _steps_to_dicts(lifecycle)})
+
+
+async def _current_status() -> MatrixLabStatus:
+    """Build a fresh :class:`MatrixLabStatus` from the live world."""
+    lifecycle = await _gather_lifecycle_status()
+    reachable, raw_error, version = await _probe_health()
+    active_sandbox = (get_settings().sandbox.backend or "subprocess").lower()
+    status = derive_status(
+        lifecycle=lifecycle,
+        reachable=reachable,
+        health_error=raw_error,
+        active_sandbox=active_sandbox,
+    )
+    if version and status.status == "ready":
+        status = status.model_copy(update={"version": version})
+
+    # Stale-URL heal: when the configured runner URL is down but a
+    # different candidate URL responds on /health, surface it as
+    # ``discoveredUrl`` so the modal can show a one-click "Use ..." CTA.
+    # Especially common after the legacy :8000 → :8765 port migration —
+    # users have a runner up on 8765 but persisted settings still say
+    # 8000.  Cheap (one or two ~30ms HTTP attempts), so we do it on
+    # every status fetch rather than gating behind a refresh button.
+    if not reachable:
+        try:
+            discovered = await _discover_live_url(get_settings().sandbox.matrixlab_url or "")
+            if discovered:
+                status = status.model_copy(update={"discoveredUrl": discovered})
+        except Exception:  # pragma: no cover - never break status on a probe error
+            pass
+    return status
+
+
+# ----------------------------------------------------------------------
+# Endpoints
+# ----------------------------------------------------------------------
+
+@router.get("/status", response_model=MatrixLabStatus)
+async def matrixlab_status() -> MatrixLabStatus:
+    """Single GET the install modal polls for state changes."""
+    return await _current_status()
+
+
+@router.post("/install", response_model=MatrixLabStatus)
+async def matrixlab_install() -> MatrixLabStatus:
+    """Idempotent install: pulls images then starts the runner.
+
+    Safe to call repeatedly — running container is left alone, missing
+    images are pulled, stopped containers are started.  All errors come
+    back as a normalised :class:`MatrixLabStatus` rather than HTTP 4xx
+    so the modal can render the right recovery action.
+    """
+    if not _lifecycle_enabled():
+        return MatrixLabStatus(
+            status="failed",
+            installed=False, running=False, reachable=False,
+            lifecycleEnabled=False,
+            dockerAvailable=_docker_available(),
+            activeSandbox=(get_settings().sandbox.backend or "subprocess").lower(),
+            runnerUrl=get_settings().sandbox.matrixlab_url,
+            message=(
+                "MatrixLab lifecycle automation is disabled. This GitPilot "
+                "backend was started with GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE=0. "
+                "Restart it without that variable (the default is enabled), or "
+                "use manual setup."
+            ),
+            errorCode="LIFECYCLE_DISABLED",
+            technicalDetails=TechnicalDetails(
+                rawError=f"Set {ENV_LIFECYCLE}=1 on the GitPilot backend and restart it.",
+            ),
+        )
+
+    if not _docker_available():
+        return MatrixLabStatus(
+            status="failed",
+            installed=False, running=False, reachable=False,
+            lifecycleEnabled=True,
+            dockerAvailable=False,
+            activeSandbox=(get_settings().sandbox.backend or "subprocess").lower(),
+            runnerUrl=get_settings().sandbox.matrixlab_url,
+            message="Docker is not installed on the GitPilot host.",
+            errorCode="DOCKER_NOT_INSTALLED",
+        )
+
+    # Re-use the existing lifecycle handlers so we don't duplicate the
+    # docker pull / docker run logic.  They already return the step
+    # transcript; we just translate the final state.
+    try:
+        pull_lifecycle = await _legacy_install()
+    except HTTPException as exc:
+        return MatrixLabStatus(
+            status="failed",
+            installed=False, running=False, reachable=False,
+            lifecycleEnabled=_lifecycle_enabled(),
+            dockerAvailable=_docker_available(),
+            activeSandbox=(get_settings().sandbox.backend or "subprocess").lower(),
+            runnerUrl=get_settings().sandbox.matrixlab_url,
+            message="MatrixLab could not be installed automatically.",
+            errorCode="INSTALL_FAILED",
+            technicalDetails=TechnicalDetails(rawError=str(exc.detail)),
+        )
+
+    if not pull_lifecycle.running:
+        try:
+            start_lifecycle = await _legacy_start()
+        except HTTPException as exc:
+            failure = derive_status(
+                lifecycle=pull_lifecycle,
+                reachable=False,
+                health_error=str(exc.detail),
+                active_sandbox=(get_settings().sandbox.backend or "subprocess").lower(),
+            )
+            return _attach_steps(
+                failure.model_copy(update={
+                    "status": "failed",
+                    "errorCode": "START_FAILED",
+                    "message": "MatrixLab installed but failed to start.",
+                    "technicalDetails": TechnicalDetails(rawError=str(exc.detail)),
+                }),
+                pull_lifecycle,
+            )
+        merged_steps = list(pull_lifecycle.steps) + list(start_lifecycle.steps)
+        pull_lifecycle = pull_lifecycle.model_copy(update={
+            "installed": start_lifecycle.installed,
+            "running": start_lifecycle.running,
+            "steps": merged_steps,
+        })
+
+    reachable, raw_error, version = await _probe_health()
+    status = derive_status(
+        lifecycle=pull_lifecycle,
+        reachable=reachable,
+        health_error=raw_error,
+        active_sandbox=(get_settings().sandbox.backend or "subprocess").lower(),
+    )
+    if version and status.status == "ready":
+        status = status.model_copy(update={"version": version})
+    return _attach_steps(status, pull_lifecycle)
+
+
+@router.post("/start", response_model=MatrixLabStatus)
+async def matrixlab_start() -> MatrixLabStatus:
+    if not _lifecycle_enabled():
+        status = await _current_status()
+        return status.model_copy(update={
+            "status": "failed",
+            "errorCode": "LIFECYCLE_DISABLED",
+            "message": "Automatic start is disabled on this GitPilot backend.",
+        })
+    try:
+        lifecycle = await _legacy_start()
+    except HTTPException as exc:
+        status = await _current_status()
+        return status.model_copy(update={
+            "status": "failed",
+            "errorCode": "START_FAILED",
+            "message": "MatrixLab failed to start.",
+            "technicalDetails": TechnicalDetails(rawError=str(exc.detail)),
+        })
+
+    reachable, raw_error, version = await _probe_health()
+    status = derive_status(
+        lifecycle=lifecycle,
+        reachable=reachable,
+        health_error=raw_error,
+        active_sandbox=(get_settings().sandbox.backend or "subprocess").lower(),
+    )
+    if version and status.status == "ready":
+        status = status.model_copy(update={"version": version})
+    return _attach_steps(status, lifecycle)
+
+
+@router.post("/stop", response_model=MatrixLabStatus)
+async def matrixlab_stop() -> MatrixLabStatus:
+    if not _lifecycle_enabled():
+        status = await _current_status()
+        return status.model_copy(update={
+            "status": "failed",
+            "errorCode": "LIFECYCLE_DISABLED",
+            "message": "Automatic stop is disabled on this GitPilot backend.",
+        })
+    try:
+        lifecycle = await _legacy_stop()
+    except HTTPException as exc:
+        status = await _current_status()
+        return status.model_copy(update={
+            "status": "failed",
+            "errorCode": "STOP_FAILED",
+            "message": "MatrixLab failed to stop.",
+            "technicalDetails": TechnicalDetails(rawError=str(exc.detail)),
+        })
+    status = derive_status(
+        lifecycle=lifecycle,
+        reachable=False,
+        health_error=None,
+        active_sandbox=(get_settings().sandbox.backend or "subprocess").lower(),
+    )
+    return _attach_steps(status, lifecycle)
+
+
+@router.post("/restart", response_model=MatrixLabStatus)
+async def matrixlab_restart() -> MatrixLabStatus:
+    """Stop then start. Lifecycle-gated like the underlying actions."""
+    await matrixlab_stop()
+    return await matrixlab_start()
+
+
+@router.post("/test", response_model=MatrixLabStatus)
+async def matrixlab_test() -> MatrixLabStatus:
+    """Re-probe /health and return the normalised status.
+
+    Drives the modal's ``Repair connection`` / one-off test affordances.
+    """
+    return await _current_status()
+
+
+# ----------------------------------------------------------------------
+# Repair and reinstall — recovery actions the install modal surfaces.
+# ----------------------------------------------------------------------
+
+@router.post("/url/auto-detect", response_model=MatrixLabStatus)
+async def matrixlab_url_auto_detect() -> MatrixLabStatus:
+    """Probe candidate URLs and adopt the first one that responds.
+
+    The "stale URL" recovery primitive — used directly by the modal's
+    "Use ``discoveredUrl``" CTA, and by ``/repair`` before it touches
+    the container.  Idempotent: when the configured URL is already
+    live, this is a no-op and returns the current status unchanged.
+    """
+    reachable, _err, _ver = await _probe_health()
+    if reachable:
+        return await _current_status()
+    current = get_settings().sandbox.matrixlab_url or ""
+    discovered = await _discover_live_url(current)
+    if discovered is None:
+        status = await _current_status()
+        return status.model_copy(update={
+            "status": "needs_attention",
+            "errorCode": "NO_RUNNER_FOUND",
+            "message": (
+                "No MatrixLab runner found on the candidate ports. "
+                "Start one with: make install-matrixlab"
+            ),
+        })
+    # Adopt the discovered URL via the canonical config writer so the
+    # change persists and any in-process sandbox instance gets refreshed.
+    try:
+        await _legacy_config(SandboxConfigUpdate(matrixlab_url=discovered))
+    except HTTPException as exc:
+        status = await _current_status()
+        return status.model_copy(update={
+            "status": "failed",
+            "errorCode": "CONFIG_UPDATE_FAILED",
+            "message": f"Found runner at {discovered} but could not persist the URL.",
+            "technicalDetails": TechnicalDetails(rawError=str(exc.detail)),
+        })
+    return await _current_status()
+
+
+@router.post("/repair", response_model=MatrixLabStatus)
+async def matrixlab_repair() -> MatrixLabStatus:
+    """Repair an unreachable MatrixLab install.
+
+    Strategy:
+      1. URL auto-detect first — most "needs_attention" cases on
+         upgrading installs are stale persisted URLs from the
+         :8000 → :8765 port move; switching the URL alone fixes them
+         without touching the container.
+      2. If still unreachable, restart the runner container (``docker
+         stop`` + ``docker start``) and re-probe.
+      3. Re-activate the MatrixLab backend on success.
+
+    Idempotent — safe to call from any non-``ready`` state.  Won't
+    pull images or re-create the container; for that use ``/reinstall``.
+    """
+    if not _lifecycle_enabled():
+        status = await _current_status()
+        return status.model_copy(update={
+            "status": "failed",
+            "errorCode": "LIFECYCLE_DISABLED",
+            "message": "Automatic repair is disabled on this GitPilot backend.",
+        })
+
+    # 0. Cheap win: try URL auto-detect before restarting anything.
+    #    Saves a 5-10s restart cycle when the only thing wrong is a
+    #    stale persisted URL.
+    detected_status = await matrixlab_url_auto_detect()
+    if detected_status.status == "ready":
+        try:
+            await _legacy_config(SandboxConfigUpdate(backend="matrixlab"))
+            detected_status = detected_status.model_copy(update={"activeSandbox": "matrixlab"})
+        except HTTPException:
+            pass
+        return detected_status
+
+    # 1. Best-effort stop (no-op when already stopped).
+    try:
+        await _legacy_stop()
+    except HTTPException:
+        pass  # we'll try to start it anyway
+
+    # 2. Start (also no-op when already running).
+    try:
+        await _legacy_start()
+    except HTTPException as exc:
+        status = await _current_status()
+        return status.model_copy(update={
+            "status": "failed",
+            "errorCode": "REPAIR_FAILED",
+            "message": "MatrixLab could not be restarted.",
+            "technicalDetails": TechnicalDetails(rawError=str(exc.detail)),
+        })
+
+    # 3. Re-detect URL (the just-started container may bind a fresh
+    #    port mapping) and re-activate if healthy.
+    status = await matrixlab_url_auto_detect()
+    if status.status == "ready":
+        try:
+            await _legacy_config(SandboxConfigUpdate(backend="matrixlab"))
+            status = status.model_copy(update={"activeSandbox": "matrixlab"})
+        except HTTPException:
+            # Activation is non-fatal — surface the healthy status.
+            pass
+    return status
+
+
+class _ReinstallRequest(BaseModel):
+    """Toggles for :func:`matrixlab_reinstall`.
+
+    ``remove_data`` is opt-in, off by default, so a misclick can't wipe
+    the operator's docker images or job workspaces.  Reinstall itself
+    is non-destructive otherwise.
+    """
+    remove_data: bool = False
+
+
+@router.post("/reinstall", response_model=MatrixLabStatus)
+async def matrixlab_reinstall(req: _ReinstallRequest | None = None) -> MatrixLabStatus:
+    """Clean reinstall: stop → remove container → pull → start → test → activate.
+
+    Idempotent — every step tolerates the "already done" case so the
+    operator can click Reinstall again after a partial failure.
+
+    When ``remove_data=True``, also removes the cached MatrixLab runner
+    image so the next install pulls fresh.  Sandbox images and any data
+    written to ``GITPILOT_MATRIXLAB_JOBS_DIR`` are preserved either way.
+    """
+    options = req or _ReinstallRequest()
+
+    if not _lifecycle_enabled():
+        status = await _current_status()
+        return status.model_copy(update={
+            "status": "failed",
+            "errorCode": "LIFECYCLE_DISABLED",
+            "message": "Automatic reinstall is disabled on this GitPilot backend.",
+        })
+    if not _docker_available():
+        status = await _current_status()
+        return status.model_copy(update={
+            "status": "failed",
+            "errorCode": "DOCKER_NOT_INSTALLED",
+            "message": "Docker is not installed on the GitPilot host.",
+        })
+
+    steps: List[Dict[str, Any]] = []
+
+    # 1. Stop (no-op if already stopped) and remove the container so
+    #    `install` re-creates it with current env vars / mounts.
+    stop_step = await _run_shell(["docker", "stop", DEFAULT_CONTAINER_NAME], timeout=30)
+    steps.append({
+        "cmd": stop_step.cmd, "exitCode": stop_step.exit_code,
+        "stdout": stop_step.stdout, "stderr": stop_step.stderr,
+        "durationMs": stop_step.duration_ms,
+    })
+    rm_step = await _run_shell(["docker", "rm", "-f", DEFAULT_CONTAINER_NAME], timeout=30)
+    steps.append({
+        "cmd": rm_step.cmd, "exitCode": rm_step.exit_code,
+        "stdout": rm_step.stdout, "stderr": rm_step.stderr,
+        "durationMs": rm_step.duration_ms,
+    })
+
+    # 2. Optionally drop the runner image so the next pull is fresh.
+    if options.remove_data:
+        rmi_step = await _run_shell(
+            ["docker", "rmi", "-f", DEFAULT_RUNNER_IMAGE], timeout=60,
+        )
+        steps.append({
+            "cmd": rmi_step.cmd, "exitCode": rmi_step.exit_code,
+            "stdout": rmi_step.stdout, "stderr": rmi_step.stderr,
+            "durationMs": rmi_step.duration_ms,
+        })
+
+    # 3. Re-run the full install (pull + start), bubbling its step list.
+    installed = await matrixlab_install()
+    merged_steps = steps + list(installed.steps or [])
+
+    # 4. If install reached "ready", flip the active sandbox; otherwise
+    #    surface the partial state so the modal can show recovery copy.
+    if installed.status == "ready":
+        try:
+            await _legacy_config(SandboxConfigUpdate(backend="matrixlab"))
+            installed = installed.model_copy(update={"activeSandbox": "matrixlab"})
+        except HTTPException:
+            pass
+    return installed.model_copy(update={"steps": merged_steps})
+
+
+@router.post("/activate", response_model=MatrixLabStatus)
+async def matrixlab_activate() -> MatrixLabStatus:
+    """Flip the active sandbox to matrixlab after a successful install.
+
+    Only flips when MatrixLab is reachable, so users can't accidentally
+    point the Run button at a dead backend by clicking activate too early.
+    """
+    status = await _current_status()
+    if status.status != "ready":
+        return status.model_copy(update={
+            "message": "MatrixLab is not ready yet — connection check failed.",
+        })
+    try:
+        await _legacy_config(SandboxConfigUpdate(backend="matrixlab"))
+    except HTTPException as exc:
+        return status.model_copy(update={
+            "status": "needs_attention",
+            "errorCode": "ACTIVATE_FAILED",
+            "message": "MatrixLab is ready, but could not be set as the active sandbox.",
+            "technicalDetails": TechnicalDetails(rawError=str(exc.detail)),
+        })
+    return status.model_copy(update={"activeSandbox": "matrixlab"})
+
+
+# ----------------------------------------------------------------------
+# Native install path (Advanced) — git clone + venv + runner
+# ----------------------------------------------------------------------
+#
+# Operators who can't (or don't want to) run Docker on the GitPilot host
+# can opt into a host-process install: clone the matrixlab repo, build
+# a dedicated venv, install the runner's requirements, and start
+# ``uvicorn app.main:app`` from ``runner/``.  Same lifecycle gate as
+# the docker path so a web request can't shell out unless the operator
+# explicitly enabled it.
+#
+# Note: the runner still spawns per-language *sandboxes* via Docker,
+# so the host needs ``docker`` on PATH even with the native install —
+# this option only avoids running the Runner itself inside a container.
+
+MATRIXLAB_GIT_URL = os.environ.get(
+    "GITPILOT_MATRIXLAB_GIT_URL",
+    "https://github.com/agent-matrix/matrixlab.git",
+)
+MATRIXLAB_LOCAL_DIR = Path(os.environ.get(
+    "GITPILOT_MATRIXLAB_LOCAL_DIR",
+    str(Path.home() / ".gitpilot" / "matrixlab"),
+))
+MATRIXLAB_PID_FILE = MATRIXLAB_LOCAL_DIR / ".gitpilot-runner.pid"
+MATRIXLAB_LOG_FILE = MATRIXLAB_LOCAL_DIR / ".gitpilot-runner.log"
+
+
+def _venv_python(venv: Path) -> Path:
+    """Return the python interpreter path inside ``venv`` (cross-platform)."""
+    candidates = [
+        venv / "bin" / "python",
+        venv / "bin" / "python3",
+        venv / "Scripts" / "python.exe",
+    ]
+    for c in candidates:
+        if c.exists():
+            return c
+    # Fall back to the unix layout even if missing — the caller will
+    # see the error from the subsequent shell-out.
+    return venv / "bin" / "python"
+
+
+def _read_pid() -> Optional[int]:
+    try:
+        return int(MATRIXLAB_PID_FILE.read_text().strip())
+    except (OSError, ValueError):
+        return None
+
+
+def _pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except (ProcessLookupError, PermissionError, OSError):
+        return False
+
+
+def _native_running() -> bool:
+    pid = _read_pid()
+    return pid is not None and _pid_alive(pid)
+
+
+async def _native_status() -> Dict[str, Any]:
+    """Synthesise a lifecycle-shaped dict for the native install path."""
+    repo_present = (MATRIXLAB_LOCAL_DIR / ".git").exists()
+    venv_present = (MATRIXLAB_LOCAL_DIR / ".venv").exists()
+    runner_present = repo_present and (MATRIXLAB_LOCAL_DIR / "runner" / "app" / "main.py").exists()
+    installed = repo_present and venv_present and runner_present
+    running = installed and _native_running()
+    return {
+        "installed": installed,
+        "running": running,
+        "repo_present": repo_present,
+        "venv_present": venv_present,
+        "runner_present": runner_present,
+        "local_dir": str(MATRIXLAB_LOCAL_DIR),
+        "git_url": MATRIXLAB_GIT_URL,
+        "pid": _read_pid() if running else None,
+    }
+
+
+@router.get("/native/status")
+async def matrixlab_native_status() -> Dict[str, Any]:
+    """Inspection-only — never raises, never blocks."""
+    info = await _native_status()
+    info["lifecycleEnabled"] = _lifecycle_enabled()
+    return info
+
+
+@router.post("/install_local", response_model=MatrixLabStatus)
+async def matrixlab_install_local() -> MatrixLabStatus:
+    """Native install: ``git clone`` → ``python -m venv`` → ``pip install``.
+
+    Idempotent: an existing checkout is reused (``git pull`` skipped on
+    purpose to keep the operator in control of which revision they
+    run).  Lifecycle gated like every other mutating endpoint.
+    """
+    if not _lifecycle_enabled():
+        return MatrixLabStatus(
+            status="failed",
+            installed=False, running=False, reachable=False,
+            lifecycleEnabled=False,
+            dockerAvailable=_docker_available(),
+            activeSandbox=(get_settings().sandbox.backend or "subprocess").lower(),
+            runnerUrl=get_settings().sandbox.matrixlab_url,
+            message=(
+                "Automatic installation is disabled on this GitPilot backend. "
+                "Ask your administrator to enable MatrixLab lifecycle automation."
+            ),
+            errorCode="LIFECYCLE_DISABLED",
+            technicalDetails=TechnicalDetails(
+                rawError=f"Set {ENV_LIFECYCLE}=1 on the GitPilot backend and restart it.",
+            ),
+        )
+
+    import shutil as _shutil
+    if not _shutil.which("git"):
+        return MatrixLabStatus(
+            status="failed",
+            installed=False, running=False, reachable=False,
+            lifecycleEnabled=True,
+            dockerAvailable=_docker_available(),
+            activeSandbox=(get_settings().sandbox.backend or "subprocess").lower(),
+            runnerUrl=get_settings().sandbox.matrixlab_url,
+            message="Git is not installed on the GitPilot host.",
+            errorCode="GIT_NOT_INSTALLED",
+        )
+
+    MATRIXLAB_LOCAL_DIR.parent.mkdir(parents=True, exist_ok=True)
+    steps: List[Dict[str, Any]] = []
+
+    # 1. Clone (or skip if already present)
+    if not (MATRIXLAB_LOCAL_DIR / ".git").exists():
+        clone_step = await _run_shell(
+            ["git", "clone", "--depth", "1", MATRIXLAB_GIT_URL, str(MATRIXLAB_LOCAL_DIR)],
+            timeout=300,
+        )
+        steps.append({
+            "cmd": clone_step.cmd, "exitCode": clone_step.exit_code,
+            "stdout": clone_step.stdout, "stderr": clone_step.stderr,
+            "durationMs": clone_step.duration_ms,
+        })
+        if clone_step.exit_code != 0:
+            return _native_failure(
+                "MatrixLab repository clone failed.",
+                "CLONE_FAILED", clone_step.stderr or clone_step.stdout,
+                steps,
+            )
+
+    # 2. Create venv if missing
+    venv = MATRIXLAB_LOCAL_DIR / ".venv"
+    if not venv.exists():
+        import sys as _sys
+        venv_step = await _run_shell(
+            [_sys.executable, "-m", "venv", str(venv)],
+            timeout=120,
+        )
+        steps.append({
+            "cmd": venv_step.cmd, "exitCode": venv_step.exit_code,
+            "stdout": venv_step.stdout, "stderr": venv_step.stderr,
+            "durationMs": venv_step.duration_ms,
+        })
+        if venv_step.exit_code != 0:
+            return _native_failure(
+                "Python virtualenv could not be created.",
+                "VENV_CREATE_FAILED", venv_step.stderr or venv_step.stdout,
+                steps,
+            )
+
+    # 3. Install runner requirements into the venv
+    py = _venv_python(venv)
+    req = MATRIXLAB_LOCAL_DIR / "runner" / "requirements.txt"
+    if not req.exists():
+        return _native_failure(
+            "Runner requirements.txt not found in the cloned repository.",
+            "RUNNER_LAYOUT_UNEXPECTED",
+            f"expected {req}",
+            steps,
+        )
+    pip_step = await _run_shell(
+        [str(py), "-m", "pip", "install", "--upgrade", "pip"],
+        timeout=180,
+    )
+    steps.append({
+        "cmd": pip_step.cmd, "exitCode": pip_step.exit_code,
+        "stdout": pip_step.stdout, "stderr": pip_step.stderr,
+        "durationMs": pip_step.duration_ms,
+    })
+    install_step = await _run_shell(
+        [str(py), "-m", "pip", "install", "-r", str(req)],
+        timeout=600,
+    )
+    steps.append({
+        "cmd": install_step.cmd, "exitCode": install_step.exit_code,
+        "stdout": install_step.stdout, "stderr": install_step.stderr,
+        "durationMs": install_step.duration_ms,
+    })
+    if install_step.exit_code != 0:
+        return _native_failure(
+            "MatrixLab requirements installation failed.",
+            "PIP_INSTALL_FAILED",
+            install_step.stderr or install_step.stdout,
+            steps,
+        )
+
+    # 4. Start the runner
+    return await _start_native_runner(extra_steps=steps)
+
+
+@router.post("/start_local", response_model=MatrixLabStatus)
+async def matrixlab_start_local() -> MatrixLabStatus:
+    """Start the native runner if installed but stopped."""
+    if not _lifecycle_enabled():
+        return _native_failure(
+            "Automatic start is disabled on this GitPilot backend.",
+            "LIFECYCLE_DISABLED", None, [],
+        )
+    info = await _native_status()
+    if not info["installed"]:
+        return _native_failure(
+            "MatrixLab is not installed locally yet. Run the local install first.",
+            "NOT_INSTALLED", None, [],
+        )
+    return await _start_native_runner(extra_steps=[])
+
+
+@router.post("/stop_local", response_model=MatrixLabStatus)
+async def matrixlab_stop_local() -> MatrixLabStatus:
+    """Stop the native runner (if one is recorded in our pidfile)."""
+    if not _lifecycle_enabled():
+        return _native_failure(
+            "Automatic stop is disabled on this GitPilot backend.",
+            "LIFECYCLE_DISABLED", None, [],
+        )
+    pid = _read_pid()
+    if pid and _pid_alive(pid):
+        import signal as _signal
+        try:
+            os.kill(pid, _signal.SIGTERM)
+        except OSError as exc:
+            return _native_failure(
+                "Could not signal the MatrixLab runner.",
+                "STOP_FAILED", str(exc), [],
+            )
+    try:
+        MATRIXLAB_PID_FILE.unlink(missing_ok=True)  # type: ignore[call-arg]
+    except OSError:
+        pass
+
+    cfg = get_settings().sandbox
+    return MatrixLabStatus(
+        status="needs_attention",
+        installed=True, running=False, reachable=False,
+        lifecycleEnabled=True,
+        dockerAvailable=_docker_available(),
+        activeSandbox=(cfg.backend or "subprocess").lower(),
+        runnerUrl=cfg.matrixlab_url,
+        message="MatrixLab runner stopped.",
+        errorCode="STOPPED",
+    )
+
+
+async def _start_native_runner(*, extra_steps: List[Dict[str, Any]]) -> MatrixLabStatus:
+    """Spawn ``uvicorn app.main:app`` from the cloned runner directory."""
+    info = await _native_status()
+    cfg = get_settings().sandbox
+    if info["running"]:
+        # Already up — re-probe health and report.
+        reachable, raw_error, version = await _probe_health()
+        status = derive_status(
+            lifecycle=await _gather_lifecycle_status(),
+            reachable=reachable,
+            health_error=raw_error,
+            active_sandbox=(cfg.backend or "subprocess").lower(),
+        )
+        return status.model_copy(update={
+            "installed": True, "running": True,
+            "version": version,
+            "steps": extra_steps,
+        })
+
+    py = _venv_python(MATRIXLAB_LOCAL_DIR / ".venv")
+    if not py.exists():
+        return _native_failure(
+            "MatrixLab virtualenv is missing — run the local install first.",
+            "VENV_MISSING", f"expected {py}", extra_steps,
+        )
+
+    # Resolve the configured URL's port so /api/sandbox/run reaches the
+    # native runner without further config.
+    port = 8000
+    try:
+        from urllib.parse import urlparse
+        parsed = urlparse(cfg.matrixlab_url or "http://localhost:8000")
+        if parsed.port:
+            port = int(parsed.port)
+    except Exception:  # noqa: BLE001
+        port = 8000
+
+    runner_cwd = MATRIXLAB_LOCAL_DIR / "runner"
+    log_fh = MATRIXLAB_LOG_FILE.open("ab")
+    import subprocess as _subprocess
+    try:
+        proc = _subprocess.Popen(
+            [str(py), "-m", "uvicorn", "app.main:app",
+             "--host", "0.0.0.0", "--port", str(port)],
+            cwd=str(runner_cwd),
+            stdout=log_fh, stderr=log_fh,
+            stdin=_subprocess.DEVNULL,
+            start_new_session=True,
+        )
+    except OSError as exc:
+        return _native_failure(
+            "Could not launch the MatrixLab runner process.",
+            "SPAWN_FAILED", str(exc), extra_steps,
+        )
+    MATRIXLAB_PID_FILE.write_text(str(proc.pid))
+
+    # Give uvicorn a moment to come up before probing /health.
+    import asyncio as _asyncio
+    for _ in range(20):  # up to ~4s
+        await _asyncio.sleep(0.2)
+        reachable, raw_error, version = await _probe_health()
+        if reachable:
+            break
+
+    lifecycle = await _gather_lifecycle_status()
+    # Native install bypasses the docker image presence check, so the
+    # lifecycle ``installed`` flag won't reflect us — patch it.
+    lifecycle = lifecycle.model_copy(update={
+        "installed": True, "running": True,
+    })
+    status = derive_status(
+        lifecycle=lifecycle,
+        reachable=reachable,
+        health_error=raw_error,
+        active_sandbox=(cfg.backend or "subprocess").lower(),
+    )
+    update = {"steps": extra_steps}
+    if version and status.status == "ready":
+        update["version"] = version
+    return status.model_copy(update=update)
+
+
+def _native_failure(
+    message: str,
+    code: str,
+    raw: Optional[str],
+    steps: List[Dict[str, Any]],
+) -> MatrixLabStatus:
+    cfg = get_settings().sandbox
+    return MatrixLabStatus(
+        status="failed",
+        installed=False, running=False, reachable=False,
+        lifecycleEnabled=_lifecycle_enabled(),
+        dockerAvailable=_docker_available(),
+        activeSandbox=(cfg.backend or "subprocess").lower(),
+        runnerUrl=cfg.matrixlab_url,
+        message=message,
+        errorCode=code,
+        technicalDetails=TechnicalDetails(rawError=raw) if raw else None,
+        steps=steps,
+    )
+
+
+@router.get("/logs")
+async def matrixlab_logs(tail: int = 200) -> Dict[str, Any]:
+    """Tail the gitpilot-matrixlab container log.
+
+    Returns a structured payload so the modal can show stdout / stderr
+    distinctly, with an actionable ``error`` when docker isn't available
+    or the container doesn't exist yet.  When the expected container
+    is missing we also list any matrixlab-shaped containers we can
+    find so the operator knows the runner is up under a different name.
+    """
+    from .sandbox_api import DEFAULT_CONTAINER_NAME
+
+    if not _docker_available():
+        return {
+            "ok": False,
+            "error": "Docker is not available on this GitPilot backend.",
+            "errorCode": "DOCKER_NOT_INSTALLED",
+            "hint": "Install Docker, then re-run: make install-matrixlab",
+            "lines": [],
+            "container": DEFAULT_CONTAINER_NAME,
+        }
+    step = await _run_shell(
+        ["docker", "logs", "--tail", str(max(1, int(tail))), DEFAULT_CONTAINER_NAME],
+        timeout=15,
+    )
+    if step.exit_code != 0:
+        stderr = (step.stderr or "").strip()
+        looks_like_missing = (
+            "No such container" in stderr
+            or "no such object" in stderr.lower()
+        )
+        # When the expected container is absent, list any other
+        # matrixlab-shaped containers so the user knows whether the
+        # install ran but produced a different name (env override),
+        # or simply never ran at all.
+        candidates: List[str] = []
+        if looks_like_missing:
+            try:
+                list_step = await _run_shell(
+                    ["docker", "ps", "-a", "--format", "{{.Names}}\t{{.Status}}"],
+                    timeout=10,
+                )
+                for raw in (list_step.stdout or "").splitlines():
+                    name = raw.split("\t", 1)[0].strip()
+                    if name and "matrixlab" in name.lower():
+                        candidates.append(raw.strip())
+            except Exception:  # pragma: no cover - diagnostic-only
+                pass
+
+        if looks_like_missing:
+            if candidates:
+                friendly = (
+                    f"No container named '{DEFAULT_CONTAINER_NAME}'. "
+                    f"Found other matrixlab-shaped containers — set "
+                    f"GITPILOT_MATRIXLAB_CONTAINER to one of them, or "
+                    f"reinstall to recreate the expected one."
+                )
+            else:
+                friendly = (
+                    f"No container named '{DEFAULT_CONTAINER_NAME}' exists yet. "
+                    f"Install with: make install-matrixlab"
+                )
+            return {
+                "ok": False,
+                "error": friendly,
+                "errorCode": "CONTAINER_NOT_FOUND",
+                "hint": "make install-matrixlab",
+                "lines": [],
+                "container": DEFAULT_CONTAINER_NAME,
+                "candidates": candidates,
+                "rawError": stderr,
+            }
+        return {
+            "ok": False,
+            "error": "Could not read MatrixLab logs.",
+            "errorCode": "LOGS_UNAVAILABLE",
+            "lines": (stderr or step.stdout or "").splitlines(),
+            "container": DEFAULT_CONTAINER_NAME,
+            "rawError": stderr,
+        }
+    combined = (step.stdout or "") + (step.stderr or "")
+    return {
+        "ok": True,
+        "lines": combined.splitlines(),
+        "container": DEFAULT_CONTAINER_NAME,
+    }
diff --git a/gitpilot/query_router.py b/gitpilot/query_router.py
index b78f431..ceabe35 100644
--- a/gitpilot/query_router.py
+++ b/gitpilot/query_router.py
@@ -40,6 +40,7 @@
     "create",
     "delete",
     "modify",
+    "execute",
     "unknown",
 )
 
@@ -47,6 +48,27 @@
 # when several intents match (first hit wins, except "fix" beats
 # "modify" because every fix is a modify but not every modify is a fix).
 _INTENT_TRIGGERS: list[tuple[str, tuple[str, ...]]] = [
+    # "execute" sits above "fix" because "run the failing test" is an
+    # execute request, not a fix request — the user wants to see output,
+    # not change the file.  Triggers kept narrow enough that "modify
+    # the code" still hits modify, broad enough that the natural ways
+    # operators phrase a run-request all classify here:
+    #
+    #   execute / run / invoke / launch / interpret / evaluate
+    #   "in the sandbox" / "in sandbox" — explicit sandbox routing
+    #   "test the script" / "try running" — colloquial run synonyms
+    ("execute", ("execute ",                      # execute this / the / demo.py / it
+                 "run the ", "run this",          # run the script / run this file
+                 "run hello", "run main", "run demo",
+                 "run my ", "run our ",            # run my script / run our test
+                 "invoke ", "launch the script", "launch the program",
+                 "interpret the script", "evaluate the script",
+                 "in the sandbox", "in sandbox",   # explicit sandbox routing
+                 "try running",                    # "try running this"
+                 "test the script", "test this script",
+                 "test the file",   "test this file",
+                 "please execute", "can you execute",
+                 "please run",      "can you run")),
     ("fix",    ("fix ", "bug", " error", "broken", "doesn't work",
                 "doesnt work", "crash", "traceback", "exception",
                 "fails", "failing", "regression")),
@@ -116,7 +138,7 @@
 # Public types
 # ----------------------------------------------------------------------
 
-Intent = Literal["fix", "find", "info", "create", "delete", "modify", "unknown"]
+Intent = Literal["fix", "find", "info", "create", "delete", "modify", "execute", "unknown"]
 EditStrategy = Literal["surgical", "regenerate", "reject"]
 
 
@@ -360,6 +382,12 @@ def classify(
     elif intent == "delete":
         tools = ["Find files matching a pattern",
                  "Delete a file from the repository"]
+    elif intent == "execute":
+        # The EXECUTE action in the planner needs the file's content so
+        # the executor can ship it to the sandbox. Reading is the only
+        # prerequisite — execution itself happens at apply-time, not
+        # plan-time.
+        tools = ["Read file content"]
     else:
         # unknown — default to the safe exploration set.
         tools = [
diff --git a/gitpilot/sandbox.py b/gitpilot/sandbox.py
index fa0d6ed..4a184bf 100644
--- a/gitpilot/sandbox.py
+++ b/gitpilot/sandbox.py
@@ -17,7 +17,7 @@
 * :class:`SubprocessSandbox` — host subprocess with cwd jail, env
   scrub, output cap, blocked-pattern checks.  Always available.
 * :class:`MatrixLabSandbox` — delegates execution to a MatrixLab
-  Runner over HTTP (default ``http://localhost:8000``).  Containerised
+  Runner over HTTP (default ``http://localhost:8765``).  Containerised
   isolation: ephemeral filesystem, resource limits, no host access.
 
 Selection precedence::
@@ -61,7 +61,11 @@
 
 DEFAULT_TIMEOUT_SEC = 120
 MAX_OUTPUT_BYTES = 512_000
-DEFAULT_MATRIXLAB_URL = "http://localhost:8000"
+# MatrixLab's docker-compose binds to host :8765 (not :8000) so the
+# Runner doesn't collide with GitPilot's own FastAPI backend on :8000.
+# Operators with an older MatrixLab install on :8000 can override with
+# GITPILOT_MATRIXLAB_URL or via Settings → Sandbox.
+DEFAULT_MATRIXLAB_URL = "http://localhost:8765"
 
 # Conservative deny patterns reused across backends.
 BLOCKED_PATTERNS: Tuple[str, ...] = (
@@ -331,7 +335,7 @@ class MatrixLabSandbox(Sandbox):
     container, the workspace is mounted read-write into the container's
     scratch directory, and resource limits are enforced by the runner.
 
-    The runner endpoint defaults to ``http://localhost:8000``; override
+    The runner endpoint defaults to ``http://localhost:8765``; override
     via the ``GITPILOT_MATRIXLAB_URL`` environment variable or by
     passing ``base_url`` to the constructor.
 
diff --git a/gitpilot/sandbox_api.py b/gitpilot/sandbox_api.py
index 54d09fb..fef0e79 100644
--- a/gitpilot/sandbox_api.py
+++ b/gitpilot/sandbox_api.py
@@ -118,6 +118,43 @@ class SandboxRunResponse(BaseModel):
     sandbox_id: Optional[str] = None
 
 
+# ----------------------------------------------------------------------
+# Execution-plan models (approval-first sandbox)
+# ----------------------------------------------------------------------
+#
+# Every sandbox run starts as a deterministic ExecutionPlan the user
+# must approve.  These models are the over-the-wire shape — the
+# canonical builder lives in :mod:`gitpilot.sandbox_plan` and stays
+# free of FastAPI / Pydantic so it can be unit-tested in isolation.
+
+class SandboxPlanRequest(BaseModel):
+    # Exactly one of (file) or (code+language) must be set.
+    file: Optional[str] = None
+    code: Optional[str] = None
+    language: Optional[str] = None
+    # Source of the request — drives the badge in the approval card
+    # and lets us tell file-run vs code-block-run apart in analytics.
+    source: str = Field(default="chat")
+    # Optional Rerun lineage so the new ExecutionCard can reference
+    # the run it replays.
+    parent_run_id: Optional[str] = None
+    # Override timeout per-plan; falls back to sandbox.timeout_sec.
+    timeout_sec: Optional[int] = Field(default=None, ge=1, le=600)
+    # The list of files in the active repo, used to verify file-run
+    # plans.  Sent by the client so the planner is stateless and
+    # repo-aware without re-reading the tree on every plan call.
+    repo_files: Optional[List[str]] = None
+    # Inline plans only: override the synthetic "inline.<ext>" name
+    # in the displayed command.  Used by the file-aware Canvas so a
+    # repo file opened for editing produces a plan that reads
+    # ``python demo.py`` instead of ``python inline.py``.  Cosmetic.
+    display_filename: Optional[str] = None
+
+
+class SandboxPlanResponse(BaseModel):
+    plan: Dict[str, Any]
+
+
 # ----------------------------------------------------------------------
 # Helpers
 # ----------------------------------------------------------------------
@@ -234,6 +271,91 @@ async def api_sandbox_config(update: SandboxConfigUpdate) -> SandboxStatusRespon
     return _status_from(cfg, health)
 
 
+@router.post("/plan", response_model=SandboxPlanResponse)
+async def api_sandbox_plan(req: SandboxPlanRequest) -> SandboxPlanResponse:
+    """Return a deterministic ExecutionPlan for the next sandbox run.
+
+    The plan is *not* executed here — the UI shows it to the user and
+    POSTs to :func:`api_sandbox_run` (Batch 2 will introduce
+    ``/execute`` with streaming) only after explicit approval. The
+    plan is built without any LLM round-trip so the user sees the
+    approval card in milliseconds and the "empty plan" failure mode
+    is eliminated for run requests entirely.
+
+    Exactly one of ``file`` or ``code + language`` must be set:
+      * ``file`` — file-run path (chat command, sidebar ▶, Rerun).
+      * ``code`` + ``language`` — inline path (code-block, Canvas).
+    """
+    from .sandbox_plan import (  # local import: keeps cold start lean
+        build_execution_plan_for_file,
+        build_execution_plan_for_inline,
+    )
+
+    s: AppSettings = get_settings()
+    cfg = s.sandbox
+    backend_name = (cfg.backend or BACKEND_SUBPROCESS).strip().lower()
+    # The plan card surfaces the *effective* backend.  We collapse
+    # "off" into "subprocess" for display because pass-through runs
+    # still execute through the subprocess pipeline; the safety
+    # advisory ("Network: disabled") is identical either way.
+    sandbox_label = "matrixlab" if backend_name == BACKEND_MATRIXLAB else "subprocess"
+    timeout = int(req.timeout_sec or cfg.timeout_sec or DEFAULT_TIMEOUT_SEC)
+
+    source = (req.source or "chat").strip().lower()
+    if source not in {"chat", "code_block", "file_run", "canvas", "rerun"}:
+        source = "chat"
+
+    if req.file:
+        plan = build_execution_plan_for_file(
+            file=req.file,
+            repo_files=req.repo_files or [req.file],
+            sandbox=sandbox_label,  # type: ignore[arg-type]
+            timeout_sec=timeout,
+            network=bool(cfg.allow_network),
+            source=source,  # type: ignore[arg-type]
+            parent_run_id=req.parent_run_id,
+        )
+        if plan is None:
+            raise HTTPException(
+                status_code=400,
+                detail=(
+                    f"cannot plan run for {req.file!r}: file not in repo "
+                    f"or extension not in the runnable allowlist."
+                ),
+            )
+        return SandboxPlanResponse(plan=plan.to_dict())
+
+    if req.code is not None:
+        if not (req.language or "").strip():
+            raise HTTPException(
+                status_code=400, detail="inline plan requires a language tag",
+            )
+        plan = build_execution_plan_for_inline(
+            code=req.code,
+            language=req.language or "",
+            source=source,  # type: ignore[arg-type]
+            sandbox=sandbox_label,  # type: ignore[arg-type]
+            timeout_sec=timeout,
+            network=bool(cfg.allow_network),
+            parent_run_id=req.parent_run_id,
+            display_filename=req.display_filename,
+        )
+        if plan is None:
+            raise HTTPException(
+                status_code=400,
+                detail=(
+                    f"cannot plan run for language {req.language!r}: "
+                    f"snippet is empty or language is not runnable."
+                ),
+            )
+        return SandboxPlanResponse(plan=plan.to_dict())
+
+    raise HTTPException(
+        status_code=400,
+        detail="provide either 'file' or 'code'+'language' to build a plan",
+    )
+
+
 @router.post("/run", response_model=SandboxRunResponse)
 async def api_sandbox_run(req: SandboxRunRequest) -> SandboxRunResponse:
     """Execute a fenced-code snippet through the configured sandbox.
@@ -347,7 +469,7 @@ async def _run_via_matrixlab_code_endpoint(
             status_code=400,
             detail=f"language {lang!r} is not supported by MatrixLab /code/run",
         )
-    base_url = (cfg.matrixlab_url or "http://localhost:8000").rstrip("/")
+    base_url = (cfg.matrixlab_url or "http://localhost:8765").rstrip("/")
     headers = {"Content-Type": "application/json"}
     if cfg.matrixlab_token:
         headers["Authorization"] = f"Bearer {cfg.matrixlab_token}"
@@ -413,11 +535,17 @@ async def _run_via_matrixlab_code_endpoint(
 )
 # Sandbox images the Runner spawns per language.  Pulling these at
 # install time means the first /code/run from the chat UI doesn't
-# stall on a multi-hundred-MB image fetch.
+# stall on a multi-hundred-MB image fetch.  Names match the
+# ``$(REGISTRY)/$(DOCKERHUB_NAMESPACE)/matrix-lab-sandbox-*`` tags
+# the matrixlab repo's Makefile builds and pushes via the
+# ``docker-publish`` GitHub workflow.
+_MATRIXLAB_NAMESPACE = os.environ.get(
+    "GITPILOT_MATRIXLAB_NAMESPACE", "ruslanmv",
+)
 DEFAULT_SANDBOX_IMAGES = [
-    "matrix-lab-sandbox-python:latest",
-    "matrix-lab-sandbox-node:latest",
-    "matrix-lab-sandbox-utils:latest",
+    f"{_MATRIXLAB_NAMESPACE}/matrix-lab-sandbox-python:latest",
+    f"{_MATRIXLAB_NAMESPACE}/matrix-lab-sandbox-node:latest",
+    f"{_MATRIXLAB_NAMESPACE}/matrix-lab-sandbox-utils:latest",
 ]
 DEFAULT_CONTAINER_NAME = os.environ.get(
     "GITPILOT_MATRIXLAB_CONTAINER",
@@ -448,7 +576,24 @@ class MatrixLabLifecycleResponse(BaseModel):
 
 
 def _lifecycle_enabled() -> bool:
-    return os.environ.get(ENV_LIFECYCLE, "").strip().lower() in {"1", "true", "yes", "on"}
+    """Decide whether ``/api/matrixlab/install`` / ``start`` / ``stop`` are allowed.
+
+    GitPilot ships as a single-tenant local tool; anyone who can reach
+    the backend can already execute arbitrary code via the existing
+    subprocess sandbox, so the addon-install endpoints don't materially
+    expand the attack surface.  Default is therefore **enabled** —
+    clicking ``Install MatrixLab Addon`` in the UI is the user's opt-in.
+
+    Hardened deployments (future multi-tenant, untrusted-reverse-proxy)
+    can flip this off by setting ``GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE=0``
+    (or ``false`` / ``no`` / ``off``).  The env var name is preserved
+    for backward compatibility; only the polarity inverted.
+    """
+    raw = os.environ.get(ENV_LIFECYCLE, "").strip().lower()
+    if raw in {"0", "false", "no", "off"}:
+        return False
+    # Anything else (empty, "1", "true", "yes", garbage) → enabled.
+    return True
 
 
 async def _run_shell(cmd: List[str], *, timeout: int = 600) -> _StepResult:
@@ -506,7 +651,7 @@ async def _docker_image_present(name: str) -> bool:
 async def _matrixlab_running() -> bool:
     """Probe the configured Runner URL for a healthy /health response."""
     cfg = get_settings().sandbox
-    base = (cfg.matrixlab_url or "http://localhost:8000").rstrip("/")
+    base = (cfg.matrixlab_url or "http://localhost:8765").rstrip("/")
     try:
         async with httpx.AsyncClient(timeout=3.0) as client:
             resp = await client.get(f"{base}/health")
@@ -612,9 +757,11 @@ async def api_matrixlab_start() -> MatrixLabLifecycleResponse:
 
     steps: List[_StepResult] = []
     # Determine which port to expose locally — derive it from the
-    # configured matrixlab_url so 'Start' agrees with /status.
+    # configured matrixlab_url so 'Start' agrees with /status.  The
+    # 8765 fallback matches MatrixLab's own docker-compose default,
+    # which moved off :8000 to avoid clashing with GitPilot's backend.
     cfg = get_settings().sandbox
-    port = 8000
+    port = 8765
     try:
         from urllib.parse import urlparse
 
@@ -622,7 +769,7 @@ async def api_matrixlab_start() -> MatrixLabLifecycleResponse:
         if parsed.port:
             port = int(parsed.port)
     except Exception:  # noqa: BLE001
-        port = 8000
+        port = 8765
 
     # Does a container with the canonical name already exist?
     inspect = await _run_shell(
@@ -634,11 +781,32 @@ async def api_matrixlab_start() -> MatrixLabLifecycleResponse:
         # Container exists — start it if stopped, otherwise leave it be.
         steps.append(await _run_shell(["docker", "start", DEFAULT_CONTAINER_NAME], timeout=60))
     else:
+        # Docker-in-Docker bind-mount fix.  The runner writes the per-
+        # request workspace under MATRIXLAB_LOCAL_JOBS_DIR (inside its
+        # own container), then asks the HOST docker daemon to mount
+        # that path into the sandbox at /workspace.  If the path isn't
+        # also visible on the host filesystem the bind ends up empty
+        # and ``python: can't open file '/workspace/main.py'`` results.
+        # Share a single host directory at the same path on both sides
+        # so docker's path-translation is a no-op.
+        jobs_dir = os.environ.get(
+            "GITPILOT_MATRIXLAB_JOBS_DIR",
+            "/tmp/gitpilot-matrixlab-jobs",
+        )
+        os.makedirs(jobs_dir, exist_ok=True)
+        try:
+            os.chmod(jobs_dir, 0o777)
+        except OSError:
+            pass
+
         run_cmd = [
             "docker", "run", "-d",
             "--name", DEFAULT_CONTAINER_NAME,
             "-p", f"{port}:8000",
             "-v", "/var/run/docker.sock:/var/run/docker.sock",
+            "-v", f"{jobs_dir}:{jobs_dir}",
+            "-e", f"MATRIXLAB_LOCAL_JOBS_DIR={jobs_dir}",
+            "-e", f"MATRIXLAB_HOST_JOBS_DIR={jobs_dir}",
             "--restart", "unless-stopped",
             DEFAULT_RUNNER_IMAGE,
         ]
diff --git a/gitpilot/sandbox_plan.py b/gitpilot/sandbox_plan.py
new file mode 100644
index 0000000..7d0f662
--- /dev/null
+++ b/gitpilot/sandbox_plan.py
@@ -0,0 +1,390 @@
+"""Deterministic Execution-Plan builder for the sandbox.
+
+The contract is approval-first: nothing runs in the sandbox until the
+user approves an :class:`ExecutionPlan` produced by this module. The
+plan is built *without* the LLM — purely from the router's classified
+intent, the resolved file path (or inline snippet), and a quick
+deterministic safety scan. That means:
+
+* No "empty plan" failures — the plan is computed in pure Python.
+* No model round-trip — the user sees the approval card in milliseconds.
+* Auditable — every check / warning is a single regex or stat call.
+
+The plan returned here is *not* the same shape as :class:`PlanResult`
+(which is a repo Action Plan: READ/CREATE/MODIFY/DELETE). It is a
+distinct surface so the UI can render a different card with a
+different colour, different verbs, and different next actions.
+
+This module is intentionally pure: it never reads settings, never
+issues network calls, never touches disk except through the
+``file_reader`` callback the caller provides. That keeps it trivial
+to unit-test and safe to call from any context.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Callable, List, Literal, Optional, Sequence
+
+# Re-use the executor's own runnable-extension set so the two stay in
+# lockstep — if a new extension is added there, it must be added here
+# too.  Failing closed (unknown extension → not runnable) is the
+# safe default.
+from .agentic import _RUNNABLE_EXTENSIONS, _is_runnable_path
+
+# ---------------------------------------------------------------------------
+# Public types
+# ---------------------------------------------------------------------------
+
+Severity = Literal["low", "medium", "high"]
+PlanSource = Literal["chat", "code_block", "file_run", "canvas", "rerun"]
+SandboxBackend = Literal["subprocess", "matrixlab"]
+
+
+@dataclass(frozen=True)
+class SafetyCheck:
+    """A passing precondition the user can see in the approval card."""
+    label: str
+    ok: bool = True
+
+
+@dataclass(frozen=True)
+class SafetyWarning:
+    """A non-blocking advisory shown above the Run button.
+
+    Warnings never reject a plan — that's the user's call. They make
+    the approval prompt honest about what the code does so consent
+    is informed.
+    """
+    severity: Severity
+    label: str
+    detail: str = ""
+
+
+@dataclass
+class ExecutionPlan:
+    """A deterministic, user-approvable description of one sandbox run.
+
+    Stable across both file-run and inline-code paths so the approval
+    card is one component. ``inline_code`` is mutually exclusive with
+    ``file``: a file run reads the content at execute time (so edits
+    between plan and approval are picked up), while an inline run
+    captures the snippet at plan time.
+    """
+
+    plan_id: str
+    goal: str
+    source: PlanSource
+    language: str                        # "python" | "node" | "bash"
+    command: List[str]                   # ["python", "demo.py"]
+    sandbox: SandboxBackend
+    timeout_sec: int
+    network: bool
+    workdir: str
+    capture_artifacts: bool = True
+    file: Optional[str] = None           # repo-relative path for file-run
+    inline_code: Optional[str] = None    # captured snippet for code_block/canvas
+    safety_checks: List[SafetyCheck] = field(default_factory=list)
+    safety_warnings: List[SafetyWarning] = field(default_factory=list)
+    requires_approval: bool = True
+    parent_run_id: Optional[str] = None  # set on Rerun
+
+    def to_dict(self) -> dict:
+        """JSON-safe representation for the HTTP layer."""
+        return {
+            "plan_id": self.plan_id,
+            "goal": self.goal,
+            "source": self.source,
+            "language": self.language,
+            "command": list(self.command),
+            "sandbox": self.sandbox,
+            "timeout_sec": self.timeout_sec,
+            "network": self.network,
+            "workdir": self.workdir,
+            "capture_artifacts": self.capture_artifacts,
+            "file": self.file,
+            "inline_code": self.inline_code,
+            "safety": {
+                "checks": [
+                    {"label": c.label, "ok": c.ok} for c in self.safety_checks
+                ],
+                "warnings": [
+                    {"severity": w.severity, "label": w.label, "detail": w.detail}
+                    for w in self.safety_warnings
+                ],
+            },
+            "requires_approval": self.requires_approval,
+            "parent_run_id": self.parent_run_id,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Language detection
+# ---------------------------------------------------------------------------
+
+# Mapping from file extension → (canonical language, interpreter argv[0]).
+# Kept in lockstep with sandbox_api's executor so the command shown in
+# the approval card is exactly the command that will run.
+_LANG_BY_EXT = {
+    "py":   ("python",     "python"),
+    "js":   ("javascript", "node"),
+    "mjs":  ("javascript", "node"),
+    "cjs":  ("javascript", "node"),
+    "sh":   ("bash",       "bash"),
+    "bash": ("bash",       "bash"),
+}
+
+
+def _language_for_path(path: str) -> tuple[str, str]:
+    ext = path.rsplit(".", 1)[-1].lower() if "." in path else ""
+    return _LANG_BY_EXT.get(ext, ("text", ""))
+
+
+def _language_for_inline(language: str) -> tuple[str, str]:
+    """Resolve a free-form language tag (``py``, ``python``, ``js`` …)
+    to its canonical name and interpreter."""
+    lang = (language or "").strip().lower()
+    aliases = {
+        "py": "py", "python": "py", "python3": "py",
+        "js": "js", "javascript": "js", "node": "js",
+        "sh": "sh", "bash": "sh", "shell": "sh",
+    }
+    canonical_ext = aliases.get(lang)
+    if not canonical_ext:
+        return ("text", "")
+    return _LANG_BY_EXT[canonical_ext]
+
+
+# ---------------------------------------------------------------------------
+# Safety analysis
+# ---------------------------------------------------------------------------
+#
+# Each rule is a regex over the source code. Matches add a warning but
+# never block — the user is the final arbiter. Rules are intentionally
+# coarse: false positives are cheap (one extra warning chip in the UI),
+# false negatives erode trust.
+
+_SAFETY_RULES: tuple[tuple[Severity, str, str, re.Pattern[str]], ...] = (
+    (
+        "high",
+        "Uses os.system / exec / eval",
+        "These primitives execute arbitrary shell or Python — review the snippet carefully.",
+        re.compile(r"\b(os\.system|subprocess\.(call|run|Popen)|\beval\(|\bexec\()"),
+    ),
+    (
+        "medium",
+        "Imports network library",
+        "Script may reach the network — disabled by default in the sandbox.",
+        re.compile(r"\b(import\s+(socket|urllib|http|requests|httpx|aiohttp)|from\s+(socket|urllib|http|requests|httpx|aiohttp))\b"),
+    ),
+    (
+        "low",
+        "Uses plt.show()",
+        "Headless sandbox cannot render windows — GitPilot will inject MPLBACKEND=Agg.",
+        re.compile(r"plt\.show\(|matplotlib\.pyplot\.show\("),
+    ),
+    (
+        "low",
+        "Writes files",
+        "Script writes files to the workspace — they appear as artifacts in the result.",
+        re.compile(r"\bopen\([^)]*['\"][rwa+xb]*['\"]\s*\)|\.write\(|savefig\(|to_csv\(|to_excel\("),
+    ),
+    (
+        "medium",
+        "Reads environment variables",
+        "Script reads env vars — only sandbox-scoped variables are present.",
+        re.compile(r"os\.environ|os\.getenv\("),
+    ),
+    (
+        "medium",
+        "Spawns child processes",
+        "Script spawns subprocesses — limited by the sandbox's process budget.",
+        re.compile(r"\bsubprocess\.|\bos\.spawn|\bos\.popen"),
+    ),
+)
+
+
+def analyze_safety(code: str, language: str) -> List[SafetyWarning]:
+    """Run the deterministic warning rules over a snippet.
+
+    Returns warnings sorted by severity descending so the UI can
+    surface the worst-case advisory first. Empty input → empty list,
+    never an exception.
+    """
+    if not code:
+        return []
+    out: List[SafetyWarning] = []
+    seen_labels: set[str] = set()
+    for severity, label, detail, pattern in _SAFETY_RULES:
+        if label in seen_labels:
+            continue
+        if pattern.search(code):
+            out.append(SafetyWarning(severity=severity, label=label, detail=detail))
+            seen_labels.add(label)
+    order = {"high": 0, "medium": 1, "low": 2}
+    out.sort(key=lambda w: order[w.severity])
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Plan builders
+# ---------------------------------------------------------------------------
+
+
+def _new_plan_id() -> str:
+    """Short ULID-ish id — good enough for a per-session plan."""
+    import secrets
+    return "plan_" + secrets.token_hex(8)
+
+
+def build_execution_plan_for_file(
+    *,
+    file: str,
+    repo_files: Sequence[str],
+    file_reader: Optional[Callable[[str], Optional[str]]] = None,
+    sandbox: SandboxBackend = "matrixlab",
+    timeout_sec: int = 120,
+    network: bool = False,
+    workdir: str = ".",
+    source: PlanSource = "chat",
+    parent_run_id: Optional[str] = None,
+) -> Optional[ExecutionPlan]:
+    """Build a deterministic plan to run an existing repo file.
+
+    Returns ``None`` when the file is not in the repo or its extension
+    isn't on the runnable allowlist. That's the safe failure mode —
+    callers must distinguish "no plan possible" from "plan ready".
+
+    ``file_reader`` is optional. When provided it's used to scan the
+    file's contents for safety warnings. When absent the plan still
+    builds (no warnings — the UI shows only the checks).
+    """
+    if file not in set(repo_files):
+        return None
+    if not _is_runnable_path(file):
+        return None
+
+    language, argv0 = _language_for_path(file)
+    if not argv0:
+        return None
+
+    checks = [
+        SafetyCheck(label="File exists"),
+        SafetyCheck(label=f"File is a runnable {language} file"),
+        SafetyCheck(label="Runs inside the sandbox"),
+        SafetyCheck(label=f"Timeout: {timeout_sec}s"),
+        SafetyCheck(label="Network: " + ("enabled" if network else "disabled")),
+    ]
+
+    warnings: List[SafetyWarning] = []
+    if file_reader is not None:
+        try:
+            content = file_reader(file)
+        except Exception:
+            content = None
+        if content:
+            warnings = analyze_safety(content, language)
+
+    return ExecutionPlan(
+        plan_id=_new_plan_id(),
+        goal=f"Run {file}",
+        source=source,
+        language=language,
+        command=[argv0, file],
+        sandbox=sandbox,
+        timeout_sec=timeout_sec,
+        network=network,
+        workdir=workdir,
+        file=file,
+        inline_code=None,
+        safety_checks=checks,
+        safety_warnings=warnings,
+        parent_run_id=parent_run_id,
+    )
+
+
+def build_execution_plan_for_inline(
+    *,
+    code: str,
+    language: str,
+    source: PlanSource = "code_block",
+    sandbox: SandboxBackend = "matrixlab",
+    timeout_sec: int = 120,
+    network: bool = False,
+    workdir: str = ".",
+    parent_run_id: Optional[str] = None,
+    display_filename: Optional[str] = None,
+) -> Optional[ExecutionPlan]:
+    """Build a deterministic plan to run an inline snippet.
+
+    The snippet is captured *at plan time* so the user approves the
+    exact bytes that will run. Editing the chat after approval can't
+    change what executes.
+
+    ``display_filename`` overrides the synthetic ``inline.<ext>`` name
+    in the displayed command — used by the file-aware Canvas so a
+    repo file opened for editing produces a plan that reads
+    ``python demo.py`` (the user's mental model) rather than
+    ``python inline.py``.  Pure cosmetic: the actual execution still
+    happens via the inline path the executor knows about.
+    """
+    if not code or not code.strip():
+        return None
+    canonical, argv0 = _language_for_inline(language)
+    if not argv0:
+        return None
+
+    suffix = {"python": "py", "javascript": "js", "bash": "sh"}[canonical]
+    # The synthetic filename is shown in the command line for clarity.
+    # The actual run streams the code via stdin / -c so no file is
+    # written to the repo at plan time.
+    pseudo_name = (display_filename or "").strip() or f"inline.{suffix}"
+
+    inline_label = (
+        f"Canvas edit of {display_filename}"
+        if display_filename else "Inline snippet captured"
+    )
+    checks = [
+        SafetyCheck(label=inline_label),
+        SafetyCheck(label=f"Runnable {canonical} code"),
+        SafetyCheck(label="Runs inside the sandbox"),
+        SafetyCheck(label=f"Timeout: {timeout_sec}s"),
+        SafetyCheck(label="Network: " + ("enabled" if network else "disabled")),
+    ]
+    warnings = analyze_safety(code, canonical)
+
+    # The displayed command is the one the user will mentally model.
+    # The executor itself may choose -c vs file-based dispatch.
+    display_command = {
+        "python": ["python", pseudo_name],
+        "javascript": ["node", pseudo_name],
+        "bash": ["bash", pseudo_name],
+    }[canonical]
+
+    return ExecutionPlan(
+        plan_id=_new_plan_id(),
+        goal=f"Run inline {canonical} snippet",
+        source=source,
+        language=canonical,
+        command=display_command,
+        sandbox=sandbox,
+        timeout_sec=timeout_sec,
+        network=network,
+        workdir=workdir,
+        file=None,
+        inline_code=code,
+        safety_checks=checks,
+        safety_warnings=warnings,
+        parent_run_id=parent_run_id,
+    )
+
+
+__all__ = [
+    "ExecutionPlan",
+    "SafetyCheck",
+    "SafetyWarning",
+    "analyze_safety",
+    "build_execution_plan_for_file",
+    "build_execution_plan_for_inline",
+]
diff --git a/gitpilot/settings.py b/gitpilot/settings.py
index 96252b2..f66a35e 100644
--- a/gitpilot/settings.py
+++ b/gitpilot/settings.py
@@ -82,7 +82,10 @@ class SandboxSettings(BaseModel):
     """
 
     backend: str = Field(default="subprocess")
-    matrixlab_url: str = Field(default="http://localhost:8000")
+    # MatrixLab maps its container :8000 to host :8765 to avoid clobbering
+    # GitPilot's own backend on :8000. Older installs on 8000 continue to
+    # work — only the default is shifted.
+    matrixlab_url: str = Field(default="http://localhost:8765")
     matrixlab_token: str = Field(default="")
     matrixlab_image: str = Field(default="")
     allow_network: bool = Field(default=False)
diff --git a/scripts/diagnose-matrixlab.sh b/scripts/diagnose-matrixlab.sh
new file mode 100755
index 0000000..4f8f2c4
--- /dev/null
+++ b/scripts/diagnose-matrixlab.sh
@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# scripts/diagnose-matrixlab.sh
+#
+# Pretty-prints every piece of state that explains the "MatrixLab is
+# installed, but GitPilot cannot connect to the runner" symptom.
+# Use when the install modal says ``Needs attention`` and you want
+# to see, side by side:
+#
+#   - what GitPilot thinks the runner URL is
+#   - what's actually listening on each candidate port
+#   - what /api/matrixlab/status returns
+#   - what /api/matrixlab/native/status returns
+#   - which Docker containers are up
+#   - last 40 lines of the runner log
+#
+# Output is plain-text and copy-paste friendly for bug reports.
+# No state is modified (read-only probe).
+set -uo pipefail
+
+GITPILOT_URL="${GITPILOT_URL:-http://127.0.0.1:8000}"
+PORTS=(8000 8765)
+
+if [ -t 1 ]; then
+  GREEN=$(printf '\033[32m'); RED=$(printf '\033[31m'); YELLOW=$(printf '\033[33m')
+  BLUE=$(printf '\033[34m'); BOLD=$(printf '\033[1m'); DIM=$(printf '\033[2m'); RESET=$(printf '\033[0m')
+else
+  GREEN=""; RED=""; YELLOW=""; BLUE=""; BOLD=""; DIM=""; RESET=""
+fi
+hdr() { printf "\n${BOLD}${BLUE}══ %s ══${RESET}\n" "$*"; }
+kv()  { printf "  ${BOLD}%-22s${RESET} %s\n" "$1" "$2"; }
+
+# -------------------------------------------------------------------------
+hdr "1 · System"
+kv "uname"      "$(uname -srm)"
+kv "docker"     "$(docker --version 2>/dev/null | head -c 80 || echo 'not on PATH')"
+kv "docker daemon" "$(docker info --format '{{.ServerVersion}}' 2>/dev/null || echo 'NOT REACHABLE')"
+kv "curl"       "$(curl --version 2>/dev/null | head -1 | head -c 60)"
+kv "python3"    "$(python3 --version 2>/dev/null || echo 'not on PATH')"
+
+# -------------------------------------------------------------------------
+hdr "2 · Candidate runner ports"
+for p in "${PORTS[@]}"; do
+  status=""
+  body=""
+  status=$(curl -fsS -m 2 -o /dev/null -w '%{http_code}' "http://localhost:${p}/health" 2>/dev/null || echo "unreachable")
+  if [ "${status}" = "200" ]; then
+    body=$(curl -fsS -m 2 "http://localhost:${p}/health" 2>/dev/null | head -c 200)
+    printf "  ${GREEN}✓${RESET} localhost:%-6s HTTP 200  %s\n" "${p}" "${body}"
+  else
+    printf "  ${RED}✗${RESET} localhost:%-6s %s\n" "${p}" "${status}"
+  fi
+done
+
+# -------------------------------------------------------------------------
+hdr "3 · Listening processes on candidate ports"
+for p in "${PORTS[@]}"; do
+  who=""
+  if command -v lsof >/dev/null 2>&1; then
+    who=$(lsof -nP -iTCP:"${p}" -sTCP:LISTEN 2>/dev/null | awk 'NR>1' | head -3)
+  elif command -v ss >/dev/null 2>&1; then
+    who=$(ss -tlnp "sport = :${p}" 2>/dev/null | awk 'NR>1' | head -3)
+  fi
+  if [ -z "${who}" ]; then
+    printf "  ${DIM}port %-6s no listener${RESET}\n" "${p}"
+  else
+    printf "  port %-6s\n%s\n" "${p}" "${who}" | sed 's/^/    /'
+  fi
+done
+
+# -------------------------------------------------------------------------
+hdr "4 · GitPilot's view of sandbox state"
+if ! curl -fsS -m 2 -o /dev/null "${GITPILOT_URL}/api/ping" 2>/dev/null; then
+  printf "  ${YELLOW}⚠${RESET} GitPilot backend not reachable at ${GITPILOT_URL} — skipping API probes\n"
+  printf "      start it with:  make run     (or:  make run-bare)\n"
+else
+  printf "  ${GREEN}✓${RESET} ${GITPILOT_URL}/api/ping responding\n\n"
+
+  for endpoint in \
+    "/api/sandbox/status" \
+    "/api/matrixlab/status" \
+    "/api/matrixlab/native/status" \
+    "/api/sandbox/matrixlab/lifecycle" ; do
+    printf "  ${BOLD}GET ${endpoint}${RESET}\n"
+    resp=$(curl -fsS -m 5 "${GITPILOT_URL}${endpoint}" 2>/dev/null || echo '{"error":"endpoint failed"}')
+    echo "${resp}" | python3 -m json.tool 2>/dev/null | sed 's/^/      /' || echo "      ${resp}"
+    echo
+  done
+fi
+
+# -------------------------------------------------------------------------
+hdr "5 · Docker containers"
+if docker info >/dev/null 2>&1; then
+  docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}' 2>/dev/null \
+    | head -20 | sed 's/^/  /'
+  echo
+  related=$(docker ps -a --format '{{.Names}}' 2>/dev/null \
+    | grep -E '^(gitpilot|matrix-lab|matrixlab)' | head -10)
+  if [ -n "${related}" ]; then
+    printf "  ${BOLD}Project-related containers (state):${RESET}\n"
+    while IFS= read -r name; do
+      st=$(docker inspect --format '{{.State.Status}} (exit={{.State.ExitCode}})' "${name}" 2>/dev/null)
+      printf "    %-40s  %s\n" "${name}" "${st}"
+    done <<< "${related}"
+  fi
+fi
+
+# -------------------------------------------------------------------------
+hdr "6 · MatrixLab runner logs (last 40 lines)"
+for candidate in gitpilot-matrixlab matrix-lab-runner-1 matrixlab-runner; do
+  if docker ps -a --format '{{.Names}}' 2>/dev/null | grep -qx "${candidate}"; then
+    printf "  ${BOLD}docker logs ${candidate} --tail 40${RESET}\n"
+    docker logs "${candidate}" --tail 40 2>&1 | sed 's/^/    /' | head -42
+    break
+  fi
+done
+
+# -------------------------------------------------------------------------
+hdr "7 · Recommended next step"
+if curl -fsS -m 2 -o /dev/null "http://localhost:8765/health" 2>/dev/null; then
+  printf "  ${GREEN}✓${RESET} Runner is alive on :8765\n"
+  # Check if GitPilot's configured URL agrees.
+  if curl -fsS -m 2 -o /dev/null "${GITPILOT_URL}/api/ping" 2>/dev/null; then
+    cfg_url=$(curl -fsS -m 2 "${GITPILOT_URL}/api/sandbox/status" 2>/dev/null \
+      | python3 -c "import sys,json; print(json.load(sys.stdin).get('matrixlab_url',''))" 2>/dev/null)
+    if [ "${cfg_url}" != "http://localhost:8765" ] && [ -n "${cfg_url}" ]; then
+      printf "  ${YELLOW}⚠${RESET} GitPilot's matrixlab_url is '${cfg_url}', should be 'http://localhost:8765'\n"
+      printf "  Fix:  ${BOLD}make fix-matrixlab-url${RESET}\n"
+    else
+      printf "  ${GREEN}✓${RESET} GitPilot's matrixlab_url is correctly set\n"
+    fi
+  fi
+elif curl -fsS -m 2 -o /dev/null "http://localhost:8000/health" 2>/dev/null; then
+  printf "  ${YELLOW}⚠${RESET} Runner is on legacy port :8000 (current default is :8765)\n"
+  printf "  Either move it to :8765 (recommended) or run:\n"
+  printf "      ${BOLD}make fix-matrixlab-url${RESET}     # accepts whichever port responds\n"
+else
+  printf "  ${RED}✗${RESET} Runner is not reachable on any candidate port.  Install it:\n"
+  printf "      ${BOLD}make install-matrixlab${RESET}\n"
+fi
+echo
diff --git a/scripts/doctor.sh b/scripts/doctor.sh
new file mode 100755
index 0000000..27a0db0
--- /dev/null
+++ b/scripts/doctor.sh
@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# scripts/doctor.sh
+#
+# Preflight + diagnose for GitPilot. Runs a set of cheap checks that
+# catch the failure modes a fresh-install operator can hit, and
+# prints a one-line fix command alongside each red ✗.
+#
+# Exits 0 when every required check passes, 1 otherwise.  Optional
+# checks (MatrixLab, MCP) print yellow ⚠ but don't fail the overall
+# run unless the relevant profile is active.
+set -uo pipefail
+
+# Resolve repo root so `bash scripts/doctor.sh` works from anywhere.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+cd "${REPO_ROOT}"
+
+# Colours — degrade gracefully when stdout isn't a TTY.
+if [ -t 1 ]; then
+  GREEN=$(printf '\033[32m'); RED=$(printf '\033[31m'); YELLOW=$(printf '\033[33m'); RESET=$(printf '\033[0m')
+else
+  GREEN=""; RED=""; YELLOW=""; RESET=""
+fi
+ok()    { printf "  ${GREEN}✓${RESET} %s\n" "$*"; }
+fail()  { printf "  ${RED}✗${RESET} %s\n" "$*"; FAILED=$((FAILED + 1)); }
+warn()  { printf "  ${YELLOW}⚠${RESET} %s\n" "$*"; }
+hint()  { printf "      ↳ fix: %s\n" "$*"; }
+section() { printf "\n%s\n" "$1"; }
+
+FAILED=0
+
+section "🔧 Host tools"
+
+if command -v docker >/dev/null 2>&1; then
+  if docker info >/dev/null 2>&1; then
+    ok "docker daemon reachable ($(docker --version | head -c 60))"
+  else
+    fail "docker installed but daemon not running"
+    hint "start Docker Desktop, or  sudo systemctl start docker"
+  fi
+else
+  fail "docker not on PATH"
+  hint "install Docker — https://docs.docker.com/get-docker/"
+fi
+
+if command -v uv >/dev/null 2>&1; then
+  uv_v=$(uv --version 2>/dev/null | awk '{print $2}')
+  ok "uv ${uv_v}"
+else
+  fail "uv not on PATH (needed for the Python runtime)"
+  hint "curl -LsSf https://astral.sh/uv/install.sh | sh"
+fi
+
+if command -v node >/dev/null 2>&1; then
+  node_v=$(node -v 2>/dev/null)
+  major=${node_v:1}; major=${major%%.*}
+  if [ "${major:-0}" -ge 20 ]; then
+    ok "node ${node_v} (≥ 20 OK)"
+  else
+    warn "node ${node_v} (recommend ≥ 20 for Vite 6)"
+  fi
+else
+  fail "node not on PATH (needed for the frontend build)"
+  hint "install via nvm:  nvm install 20 && nvm use 20"
+fi
+
+if command -v curl >/dev/null 2>&1; then
+  ok "curl present"
+else
+  fail "curl not on PATH"
+  hint "apt-get install curl  (used by readiness probes)"
+fi
+
+section "🌐 Network ports"
+
+# Check each port; "free" or "held by our own container" is OK.
+port_status() {
+  local port="$1"
+  local label="$2"
+  local our_container_pattern="${3:-}"
+
+  # Anything bound on this port?
+  if ! command -v lsof >/dev/null 2>&1 && ! command -v ss >/dev/null 2>&1; then
+    warn "port ${port} (${label}): can't probe — neither lsof nor ss present"
+    return
+  fi
+  local who=""
+  if command -v lsof >/dev/null 2>&1; then
+    who=$(lsof -nP -iTCP:"${port}" -sTCP:LISTEN 2>/dev/null | awk 'NR>1 {print $1}' | head -1)
+  fi
+  if [ -z "${who}" ] && command -v ss >/dev/null 2>&1; then
+    who=$(ss -tlnp "sport = :${port}" 2>/dev/null | awk 'NR>1' | head -1)
+  fi
+  if [ -z "${who}" ]; then
+    ok "port ${port} (${label}) free"
+    return
+  fi
+  # Held — is it our own container?
+  if [ -n "${our_container_pattern}" ] && docker ps --format '{{.Names}}' 2>/dev/null | grep -q "${our_container_pattern}"; then
+    ok "port ${port} (${label}) held by our own container"
+  else
+    fail "port ${port} (${label}) held by ${who}"
+    hint "stop the conflicting process, or  make stop"
+  fi
+}
+
+port_status 8000 "GitPilot backend"        "gitpilot-backend\|^gitpilot$"
+port_status 5173 "Vite dev frontend"       "gitpilot-frontend"
+port_status 4444 "MCP Context Forge"       "gitpilot-mcp-context-forge"
+port_status 8765 "MatrixLab runner"        "gitpilot-matrixlab\|matrix-lab-runner"
+
+section "📄 Configuration files"
+
+if [ -f .env ]; then
+  if grep -q '^GITHUB_CLIENT_ID=..*' .env 2>/dev/null \
+     && grep -q '^GITHUB_CLIENT_SECRET=..*' .env 2>/dev/null; then
+    ok ".env has GITHUB_CLIENT_ID + GITHUB_CLIENT_SECRET populated"
+  else
+    fail ".env exists but GitHub OAuth credentials are missing"
+    hint "set GITHUB_CLIENT_ID + GITHUB_CLIENT_SECRET in .env"
+  fi
+else
+  warn ".env not found — using template defaults"
+  hint "cp .env.template .env  and fill in GitHub OAuth credentials"
+fi
+
+if [ -f .mcp.env ]; then
+  if grep -q '^MCP_AUTH_TOKEN=..*' .mcp.env 2>/dev/null; then
+    ok ".mcp.env has MCP_AUTH_TOKEN populated"
+  else
+    fail ".mcp.env exists but MCP_AUTH_TOKEN is empty"
+    hint "make install-mcp  (regenerates the token)"
+  fi
+else
+  warn ".mcp.env not found — MCP stack won't start"
+  hint "make install-mcp"
+fi
+
+section "🐳 Local images"
+
+check_image() {
+  local image="$1"
+  local optional="${2:-required}"
+  if docker image inspect "${image}" >/dev/null 2>&1; then
+    ok "${image} present locally"
+  else
+    if [ "${optional}" = "optional" ]; then
+      warn "${image} not pulled (optional)"
+      hint "docker pull ${image}"
+    else
+      fail "${image} not pulled"
+      hint "docker pull ${image}  or  make build"
+    fi
+  fi
+}
+
+check_image "ghcr.io/ibm/mcp-context-forge:stable"    "optional"
+check_image "ruslanmv/matrixlab-runner:latest"        "optional"
+check_image "ruslanmv/matrix-lab-sandbox-python:latest" "optional"
+
+section "🧪 Running containers"
+
+if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+  running=$(docker ps --format '{{.Names}}' 2>/dev/null | grep -E '^(gitpilot|matrix-lab|matrixlab)-' | sort)
+  if [ -z "${running}" ]; then
+    ok "no GitPilot / MatrixLab containers running yet"
+  else
+    while IFS= read -r name; do
+      ok "container running: ${name}"
+    done <<< "${running}"
+  fi
+fi
+
+section "🔗 MCP token consistency"
+
+# Catches the silent-401 bug.  When Forge is up, ask it to validate the
+# token we'd send; mismatch → red ✗ + rotate hint.
+if docker ps --format '{{.Names}}' 2>/dev/null | grep -q 'gitpilot-mcp-context-forge'; then
+  if [ -f .mcp.env ] && grep -q '^MCP_AUTH_TOKEN=' .mcp.env; then
+    token=$(grep '^MCP_AUTH_TOKEN=' .mcp.env | head -1 | cut -d= -f2- | tr -d '"')
+    code=$(docker run --rm --network gitpilot-mcp curlimages/curl:8.10.1 \
+        -sS -o /dev/null -w '%{http_code}' \
+        -H "Authorization: Bearer ${token}" \
+        "http://mcp-context-forge:4444/gateways" 2>/dev/null || echo "000")
+    case "${code}" in
+      200|404)
+        ok ".mcp.env token matches the running Forge"
+        ;;
+      401|403)
+        # Soft signal — operator-recoverable, doesn't block ``make run``.
+        warn ".mcp.env token does NOT match Forge — auto-registration will skip"
+        hint "make rotate-mcp-token   (or just register servers from Settings → MCP Servers → Sync)"
+        ;;
+      *)
+        warn "Forge probe returned HTTP ${code} — inspect:  docker logs gitpilot-mcp-context-forge --tail 40"
+        ;;
+    esac
+  fi
+else
+  ok "MCP Forge not running — token check skipped"
+fi
+
+section "🧪 MatrixLab addon"
+
+# Only flagged when the operator already opted in.
+if [ -f .gitpilot/sandbox-settings.json ] && grep -q '"backend"[[:space:]]*:[[:space:]]*"matrixlab"' .gitpilot/sandbox-settings.json 2>/dev/null; then
+  matrixlab_url="http://localhost:8765"
+  if curl -fsS -m 2 "${matrixlab_url}/health" >/dev/null 2>&1; then
+    ok "MatrixLab runner reachable at ${matrixlab_url}/health"
+  else
+    fail "MatrixLab backend selected but runner is unreachable at ${matrixlab_url}"
+    hint "make install-matrixlab  or open the Install MatrixLab Addon modal"
+  fi
+else
+  warn "MatrixLab not the active sandbox backend (using local subprocess)"
+fi
+
+# Final verdict
+echo
+if [ "${FAILED}" -eq 0 ]; then
+  printf "${GREEN}✓ All required checks passed.${RESET}  Run:  make run\n"
+  exit 0
+else
+  printf "${RED}✗ ${FAILED} required check(s) failed.${RESET}  Fix the items above and re-run \`make doctor\`.\n"
+  exit 1
+fi
diff --git a/scripts/fix-matrixlab-url.sh b/scripts/fix-matrixlab-url.sh
new file mode 100755
index 0000000..19f42a9
--- /dev/null
+++ b/scripts/fix-matrixlab-url.sh
@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# scripts/fix-matrixlab-url.sh
+#
+# Detects which port the MatrixLab runner is actually listening on,
+# then writes that URL into GitPilot's sandbox settings.  Solves the
+# "Runner URL: http://localhost:8000 / Needs attention" symptom that
+# happens when a user's persisted settings.json has the old default
+# port (8000) but the runner was started on the new default (8765).
+#
+# Strategy:
+#   1. Probe http://localhost:{8765,8000}/health
+#   2. Pick the first one that answers
+#   3. PUT /api/sandbox/config with the matching URL
+#   4. POST /api/matrixlab/test to confirm GitPilot now sees it
+#
+# Idempotent.  Safe to run any number of times.  Additive only:
+# does not modify any source file, just talks to the running
+# GitPilot backend's HTTP API.
+set -uo pipefail
+
+GITPILOT_URL="${GITPILOT_URL:-http://127.0.0.1:8000}"
+CANDIDATES=(
+  "${MATRIXLAB_URL:-}"               # explicit override wins
+  "http://localhost:8765"            # current default (post port-shift)
+  "http://localhost:8000"            # legacy default (pre port-shift)
+  "http://host.docker.internal:8765" # Docker Desktop on macOS/Windows
+)
+
+# Colours — degrade gracefully when not a TTY.
+if [ -t 1 ]; then
+  GREEN=$(printf '\033[32m'); RED=$(printf '\033[31m'); YELLOW=$(printf '\033[33m'); BOLD=$(printf '\033[1m'); RESET=$(printf '\033[0m')
+else
+  GREEN=""; RED=""; YELLOW=""; BOLD=""; RESET=""
+fi
+ok()   { printf "${GREEN}✓${RESET} %s\n" "$*"; }
+warn() { printf "${YELLOW}⚠${RESET} %s\n" "$*"; }
+fail() { printf "${RED}✗${RESET} %s\n" "$*" 1>&2; }
+step() { printf "${BOLD}🔹${RESET} %s\n" "$*"; }
+
+# ---- 1. GitPilot reachable? ---------------------------------------------
+step "Probing GitPilot backend at ${GITPILOT_URL}"
+if ! curl -fsS -m 3 -o /dev/null "${GITPILOT_URL}/api/ping" 2>/dev/null; then
+  fail "GitPilot backend not reachable at ${GITPILOT_URL}/api/ping"
+  fail "Start it first:  make run     (or:  make run-bare)"
+  exit 2
+fi
+ok "GitPilot backend is up"
+
+# ---- 2. What does GitPilot currently think the matrixlab URL is? --------
+step "Reading current sandbox settings from /api/sandbox/status"
+current_payload=$(curl -fsS -m 5 "${GITPILOT_URL}/api/sandbox/status" 2>/dev/null || true)
+if [ -z "${current_payload}" ]; then
+  fail "/api/sandbox/status did not respond"
+  exit 3
+fi
+current_url=$(echo "${current_payload}" \
+  | python3 -c "import sys,json; print(json.load(sys.stdin).get('matrixlab_url',''))" 2>/dev/null)
+current_backend=$(echo "${current_payload}" \
+  | python3 -c "import sys,json; print(json.load(sys.stdin).get('backend',''))" 2>/dev/null)
+ok "Currently configured:  backend=${current_backend:-?}  matrixlab_url=${current_url:-?}"
+
+# ---- 3. Probe each candidate runner URL ---------------------------------
+step "Probing candidate runner URLs for a live /health"
+chosen_url=""
+for url in "${CANDIDATES[@]}"; do
+  [ -z "${url}" ] && continue
+  printf "   • %-45s " "${url}"
+  resp=$(curl -fsS -m 2 -o /dev/null -w '%{http_code}' "${url}/health" 2>/dev/null || true)
+  if [ "${resp}" = "200" ]; then
+    printf "${GREEN}✓ HTTP 200${RESET}\n"
+    if [ -z "${chosen_url}" ]; then
+      chosen_url="${url}"
+    fi
+  else
+    printf "%s\n" "${resp:-no-response}"
+  fi
+done
+
+if [ -z "${chosen_url}" ]; then
+  echo
+  fail "No candidate URL answered /health."
+  fail "Start the runner first:"
+  fail "    make install-matrixlab"
+  fail "or, if you have the addon image already:"
+  fail "    docker run -d --name gitpilot-matrixlab -p 8765:8000 \\"
+  fail "      -v /var/run/docker.sock:/var/run/docker.sock \\"
+  fail "      ruslanmv/matrixlab-runner:latest"
+  exit 4
+fi
+
+# ---- 4. Already pointing at the right URL? -------------------------------
+if [ "${current_url}" = "${chosen_url}" ]; then
+  ok "GitPilot's matrixlab_url already matches the live runner — nothing to fix."
+  # Still flip the backend if it isn't matrixlab yet — common when the
+  # operator just installed the addon and hasn't toggled in the UI.
+  if [ "${current_backend}" != "matrixlab" ]; then
+    warn "Active sandbox backend is '${current_backend}', flipping to 'matrixlab'..."
+    curl -fsS -X PUT "${GITPILOT_URL}/api/sandbox/config" \
+      -H 'Content-Type: application/json' \
+      -d '{"backend":"matrixlab"}' >/dev/null
+    ok "Backend flipped to matrixlab"
+  fi
+  exit 0
+fi
+
+# ---- 5. Update GitPilot's settings ---------------------------------------
+step "Updating GitPilot:  matrixlab_url  ${current_url:-?}  →  ${chosen_url}"
+body=$(python3 -c "import json,sys; print(json.dumps({'backend':'matrixlab','matrixlab_url':sys.argv[1]}))" "${chosen_url}")
+if ! curl -fsS -X PUT "${GITPILOT_URL}/api/sandbox/config" \
+     -H 'Content-Type: application/json' \
+     -d "${body}" >/dev/null; then
+  fail "PUT /api/sandbox/config failed."
+  exit 5
+fi
+ok "Settings updated"
+
+# ---- 6. Confirm GitPilot now sees the runner -----------------------------
+step "Confirming via /api/matrixlab/test"
+test_payload=$(curl -fsS -X POST "${GITPILOT_URL}/api/matrixlab/test" 2>/dev/null || true)
+status=$(echo "${test_payload}" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status','?'))" 2>/dev/null)
+case "${status}" in
+  ready)
+    ok "Status: ready"
+    echo
+    ok "Done.  Reload the Install MatrixLab Addon modal — it should now show 'Ready'."
+    ;;
+  needs_attention|failed)
+    err=$(echo "${test_payload}" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('errorCode','?'), '·', d.get('message','?'))" 2>/dev/null)
+    warn "Status after update: ${status} (${err})"
+    warn "URL is now correct, but the runner may need a restart.  Try:"
+    warn "    make install-matrixlab   # idempotent — re-up the container"
+    ;;
+  *)
+    warn "Unexpected status: ${status}"
+    echo "${test_payload}" | python3 -m json.tool 2>/dev/null || echo "${test_payload}"
+    ;;
+esac
diff --git a/scripts/install-matrixlab.sh b/scripts/install-matrixlab.sh
new file mode 100755
index 0000000..055644f
--- /dev/null
+++ b/scripts/install-matrixlab.sh
@@ -0,0 +1,310 @@
+#!/usr/bin/env bash
+# scripts/install-matrixlab.sh
+#
+# Declaratively provision MatrixLab as a legacy addon for GitPilot.
+# Fired by:
+#   make install-matrixlab
+#   make install WITH_MATRIXLAB=1
+#
+# What this script does (all idempotent):
+#
+#   1. Pull the published Docker images from Docker Hub.
+#   2. Write a host-side jobs directory that's bind-mounted into the
+#      runner so the Docker-in-Docker workspace path resolves
+#      correctly (the same recipe gitpilot's install modal uses).
+#   3. Start the runner on host port 8765 if it isn't already up.
+#   4. Probe /health until it answers.
+#   5. Print the curl smoke-test the operator should run next.
+#
+# Failure modes (each with a friendly hint, never a raw traceback):
+#   - docker not installed                → install Docker
+#   - docker daemon not reachable         → start Docker Desktop
+#   - port 8765 held by something else    → choose a different port
+#   - runner image pull rejected          → check registry credentials
+#   - /health never answers within 60s    → inspect docker logs
+#
+# Configurable via env vars (prefixed with MATRIXLAB_ for clarity):
+#
+#   MATRIXLAB_VERSION       Image tag — defaults to "latest".
+#                           Pin to v0.1.0 in production for reproducibility.
+#   MATRIXLAB_PORT          Host port mapping — defaults to 8765.
+#                           Avoid 8000 (GitPilot's own backend).
+#   MATRIXLAB_JOBS_DIR      Host path for the runner workspace —
+#                           defaults to /tmp/gitpilot-matrixlab-jobs.
+#                           Override to a persistent path like
+#                           /var/lib/matrixlab/jobs for production.
+#   MATRIXLAB_NAMESPACE     Image namespace — defaults to "ruslanmv".
+#                           Only change when running against a local
+#                           registry mirror.
+set -euo pipefail
+
+# ---- Resolve repo root ---------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+cd "${REPO_ROOT}"
+
+# ---- Colours / helpers ---------------------------------------------------
+if [ -t 1 ]; then
+  GREEN=$(printf '\033[32m'); RED=$(printf '\033[31m'); YELLOW=$(printf '\033[33m'); BOLD=$(printf '\033[1m'); RESET=$(printf '\033[0m')
+else
+  GREEN=""; RED=""; YELLOW=""; BOLD=""; RESET=""
+fi
+ok()    { printf "${GREEN}✓${RESET} %s\n" "$*"; }
+warn()  { printf "${YELLOW}⚠${RESET} %s\n" "$*"; }
+fail()  { printf "${RED}✗${RESET} %s\n" "$*" 1>&2; }
+step()  { printf "${BOLD}🔹${RESET} %s\n" "$*"; }
+hint()  { printf "      ↳ %s\n" "$*"; }
+
+# ---- Configuration -------------------------------------------------------
+MATRIXLAB_VERSION="${MATRIXLAB_VERSION:-latest}"
+MATRIXLAB_PORT="${MATRIXLAB_PORT:-8765}"
+MATRIXLAB_JOBS_DIR="${MATRIXLAB_JOBS_DIR:-/tmp/gitpilot-matrixlab-jobs}"
+MATRIXLAB_NAMESPACE="${MATRIXLAB_NAMESPACE:-ruslanmv}"
+MATRIXLAB_CONTAINER="${MATRIXLAB_CONTAINER:-gitpilot-matrixlab}"
+
+RUNNER_IMAGE="${MATRIXLAB_NAMESPACE}/matrixlab-runner:${MATRIXLAB_VERSION}"
+SANDBOX_PYTHON="${MATRIXLAB_NAMESPACE}/matrix-lab-sandbox-python:${MATRIXLAB_VERSION}"
+SANDBOX_NODE="${MATRIXLAB_NAMESPACE}/matrix-lab-sandbox-node:${MATRIXLAB_VERSION}"
+SANDBOX_UTILS="${MATRIXLAB_NAMESPACE}/matrix-lab-sandbox-utils:${MATRIXLAB_VERSION}"
+
+echo
+printf "${BOLD}📦 Installing MatrixLab addon (legacy package)${RESET}\n"
+echo "   Version:    ${MATRIXLAB_VERSION}"
+echo "   Namespace:  ${MATRIXLAB_NAMESPACE}"
+echo "   Host port:  ${MATRIXLAB_PORT}"
+echo "   Jobs dir:   ${MATRIXLAB_JOBS_DIR}"
+echo "   Container:  ${MATRIXLAB_CONTAINER}"
+echo
+
+# ---- 1. Preflight --------------------------------------------------------
+step "Preflight"
+
+# In ``MATRIXLAB_OPTIONAL=1`` mode (chained from ``make install``), a
+# missing docker / dead daemon / held port should warn and skip — not
+# break the parent installer.  The standalone ``make install-matrixlab``
+# leaves this var unset and gets the strict fatal behavior.
+__optional() { [ -n "${MATRIXLAB_OPTIONAL:-}" ]; }
+__skip_or_die() {
+  local reason="$1"; shift
+  if __optional; then
+    warn "MatrixLab install skipped — ${reason}"
+    [ "$#" -gt 0 ] && for line in "$@"; do hint "$line"; done
+    warn "Re-run with:  make install-matrixlab     # once the prerequisite is in place"
+    exit 0
+  fi
+  fail "${reason}"
+  [ "$#" -gt 0 ] && for line in "$@"; do hint "$line"; done
+  exit 2
+}
+
+if ! command -v docker >/dev/null 2>&1; then
+  __skip_or_die "docker not on PATH" \
+    "Install Docker: https://docs.docker.com/get-docker/"
+fi
+if ! docker info >/dev/null 2>&1; then
+  __skip_or_die "docker daemon not reachable" \
+    "Start Docker Desktop, or:  sudo systemctl start docker"
+fi
+ok "docker reachable"
+
+# Port check — accept "held by our own container" as fine.
+#
+# Robust detection: ``lsof`` can be missing on slim WSL distros (where
+# this script frequently runs) and even when present may not see ports
+# bound by the docker daemon (running as root) if invoked as a non-root
+# user.  We try every available tool and *also* ask docker directly
+# whether any container publishes the port — that catches the very
+# common case where a stale matrixlab container from a previous
+# install attempt is sitting in state ``created`` with the port
+# reserved.
+__port_in_use_by_proc() {
+  if command -v lsof >/dev/null 2>&1; then
+    lsof -nP -iTCP:"${MATRIXLAB_PORT}" -sTCP:LISTEN >/dev/null 2>&1 && return 0
+  fi
+  if command -v ss >/dev/null 2>&1; then
+    ss -ltnH "( sport = :${MATRIXLAB_PORT} )" 2>/dev/null | grep -q . && return 0
+  fi
+  if command -v netstat >/dev/null 2>&1; then
+    netstat -ltn 2>/dev/null | awk '{print $4}' | grep -E "[:.]${MATRIXLAB_PORT}\$" >/dev/null && return 0
+  fi
+  return 1
+}
+# Return the name of any docker container publishing MATRIXLAB_PORT,
+# else empty.  Format: container_name ("" when none).
+__port_in_use_by_docker() {
+  docker ps --format '{{.Names}}\t{{.Ports}}' 2>/dev/null \
+    | awk -F'\t' -v p=":${MATRIXLAB_PORT}->" '$2 ~ p { print $1; exit }'
+}
+
+if __port_in_use_by_proc || [ -n "$(__port_in_use_by_docker)" ]; then
+  holder="$(__port_in_use_by_docker)"
+  if [ "${holder}" = "${MATRIXLAB_CONTAINER}" ]; then
+    ok "port ${MATRIXLAB_PORT} already held by ${MATRIXLAB_CONTAINER} (will reuse)"
+  elif [ -n "${holder}" ]; then
+    __skip_or_die "port ${MATRIXLAB_PORT} held by another docker container: ${holder}" \
+      "Stop it:  docker stop ${holder}" \
+      "or set:  MATRIXLAB_PORT=<other> make install-matrixlab"
+  else
+    __skip_or_die "port ${MATRIXLAB_PORT} held by another process" \
+      "Find the process:  sudo lsof -nP -iTCP:${MATRIXLAB_PORT} -sTCP:LISTEN" \
+      "or set:  MATRIXLAB_PORT=<other> make install-matrixlab"
+  fi
+else
+  ok "port ${MATRIXLAB_PORT} free"
+fi
+
+# ---- 2. Pull images ------------------------------------------------------
+step "Pulling images from Docker Hub"
+
+pull_one() {
+  local img="$1"
+  if docker image inspect "${img}" >/dev/null 2>&1; then
+    ok "${img} already present (skip pull)"
+    return 0
+  fi
+  if docker pull "${img}" >/dev/null 2>&1; then
+    ok "${img} pulled"
+    return 0
+  fi
+  fail "could not pull ${img}"
+  hint "check registry credentials, or run 'docker pull ${img}' manually for the full error"
+  return 4
+}
+
+pull_one "${RUNNER_IMAGE}"
+# Sandbox images pull lazily on first /code/run, but pre-pulling them
+# avoids a multi-second stall on the first execution attempt.
+pull_one "${SANDBOX_PYTHON}"
+pull_one "${SANDBOX_NODE}"
+pull_one "${SANDBOX_UTILS}"
+
+# ---- 3. Workspace directory ---------------------------------------------
+step "Preparing workspace directory"
+
+mkdir -p "${MATRIXLAB_JOBS_DIR}"
+# 0777 because the runner writes as root and sandbox containers may
+# run as non-root users with different uids — same recipe the
+# docker-compose recipe uses.
+chmod 0777 "${MATRIXLAB_JOBS_DIR}" || true
+ok "${MATRIXLAB_JOBS_DIR} ready"
+
+# ---- 4. Start the runner -------------------------------------------------
+step "Starting MatrixLab runner"
+
+# Bring the runner up.  Wrapped in a function so the OPTIONAL mode
+# (chained from ``make install``) can intercept any failure with a
+# friendly skip-or-die instead of a raw docker stack trace.  The
+# function returns 0 on success and a non-zero code on failure.
+__run_runner_container() {
+  docker run -d --name "${MATRIXLAB_CONTAINER}" \
+    --restart unless-stopped \
+    -p "${MATRIXLAB_PORT}:8000" \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    -v "${MATRIXLAB_JOBS_DIR}:${MATRIXLAB_JOBS_DIR}" \
+    -e "MATRIXLAB_LOCAL_JOBS_DIR=${MATRIXLAB_JOBS_DIR}" \
+    -e "MATRIXLAB_HOST_JOBS_DIR=${MATRIXLAB_JOBS_DIR}" \
+    -e "MATRIXLAB_IMAGE_NAMESPACE=${MATRIXLAB_NAMESPACE}" \
+    "${RUNNER_IMAGE}" >/dev/null 2>&1
+}
+
+existing_status=$(docker inspect --format '{{.State.Status}}' "${MATRIXLAB_CONTAINER}" 2>/dev/null || true)
+
+if [ "${existing_status}" = "running" ]; then
+  ok "container ${MATRIXLAB_CONTAINER} already running"
+elif [ -n "${existing_status}" ]; then
+  ok "container ${MATRIXLAB_CONTAINER} exists (status=${existing_status}) — starting"
+  start_err=$(docker start "${MATRIXLAB_CONTAINER}" 2>&1 >/dev/null || true)
+  if [ -n "${start_err}" ]; then
+    warn "docker start failed: ${start_err}"
+    # A container in state=created/exited that won't start usually
+    # means the published port slipped to another container after the
+    # previous attempt died.  The container has no state worth
+    # preserving — recreate it cleanly.  This is the WSL/Docker
+    # Desktop failure mode the user hit; auto-recovery beats a
+    # confusing make-failure for an empty container.
+    case "${existing_status}" in
+      created|exited|dead)
+        hint "auto-recovery: removing the stale container and recreating it"
+        docker rm -f "${MATRIXLAB_CONTAINER}" >/dev/null 2>&1 || true
+        if __run_runner_container; then
+          ok "container ${MATRIXLAB_CONTAINER} recreated"
+        else
+          # The port is genuinely held by someone else — surface
+          # who, then bail through the friendly path.
+          holder="$(docker ps --format '{{.Names}}\t{{.Ports}}' 2>/dev/null \
+                     | awk -F'\t' -v p=":${MATRIXLAB_PORT}->" '$2 ~ p { print $1; exit }')"
+          if [ -n "${holder}" ] && [ "${holder}" != "${MATRIXLAB_CONTAINER}" ]; then
+            __skip_or_die "port ${MATRIXLAB_PORT} held by container ${holder}" \
+              "Stop it:  docker stop ${holder}" \
+              "or set:  MATRIXLAB_PORT=<other> make install-matrixlab"
+          else
+            __skip_or_die "could not start MatrixLab runner after auto-recovery" \
+              "Inspect with:  docker logs ${MATRIXLAB_CONTAINER} --tail 50" \
+              "or set:  MATRIXLAB_PORT=<other> make install-matrixlab"
+          fi
+        fi
+        ;;
+      *)
+        __skip_or_die "container ${MATRIXLAB_CONTAINER} (status=${existing_status}) refused to start" \
+          "Inspect with:  docker logs ${MATRIXLAB_CONTAINER} --tail 50"
+        ;;
+    esac
+  fi
+else
+  if __run_runner_container; then
+    ok "container ${MATRIXLAB_CONTAINER} created"
+  else
+    # Fresh-install failure path — surface the same port-collision
+    # diagnosis the recovery path uses so the operator gets the
+    # same actionable hint regardless of which branch tripped.
+    holder="$(docker ps --format '{{.Names}}\t{{.Ports}}' 2>/dev/null \
+               | awk -F'\t' -v p=":${MATRIXLAB_PORT}->" '$2 ~ p { print $1; exit }')"
+    if [ -n "${holder}" ]; then
+      __skip_or_die "port ${MATRIXLAB_PORT} held by container ${holder}" \
+        "Stop it:  docker stop ${holder}" \
+        "or set:  MATRIXLAB_PORT=<other> make install-matrixlab"
+    else
+      __skip_or_die "docker run failed for ${RUNNER_IMAGE}" \
+        "Reproduce manually to see the full error:" \
+        "  docker run --rm -p ${MATRIXLAB_PORT}:8000 ${RUNNER_IMAGE}"
+    fi
+  fi
+fi
+
+# ---- 5. Probe /health ----------------------------------------------------
+step "Waiting for runner /health"
+
+RUNNER_URL="http://localhost:${MATRIXLAB_PORT}"
+for i in $(seq 1 60); do
+  if curl -fsS -m 2 "${RUNNER_URL}/health" >/dev/null 2>&1; then
+    ok "${RUNNER_URL}/health responding after ${i}s"
+    break
+  fi
+  if [ "${i}" -eq 60 ]; then
+    fail "runner did not answer /health within 60s"
+    hint "docker logs ${MATRIXLAB_CONTAINER} --tail 50"
+    exit 5
+  fi
+  sleep 1
+done
+
+# Pull the version + capabilities to print a friendly summary.
+caps=$(curl -fsS -m 5 "${RUNNER_URL}/capabilities" 2>/dev/null || true)
+if [ -n "${caps}" ]; then
+  version=$(echo "${caps}" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('version','?'))" 2>/dev/null || echo "?")
+  images=$(echo "${caps}" | python3 -c "import sys,json; d=json.load(sys.stdin); print(', '.join(d.get('images', [])))" 2>/dev/null || echo "?")
+  echo
+  echo "   Runner version:  ${version}"
+  echo "   Sandbox langs:   ${images}"
+fi
+
+# ---- 6. Next-step hint ---------------------------------------------------
+echo
+ok "MatrixLab addon installed and reachable."
+echo
+echo "Next steps:"
+echo "  • Smoke-test:   curl ${RUNNER_URL}/code/run -H 'Content-Type: application/json' \\"
+echo "                       -d '{\"language\":\"python\",\"code\":\"print(2+2)\",\"timeout\":30}'"
+echo "  • Activate in GitPilot:  open Admin → Sandbox → toggle backend to MatrixLab"
+echo "  • Stop the runner:  docker stop ${MATRIXLAB_CONTAINER}"
+echo
diff --git a/scripts/rotate-mcp-token.sh b/scripts/rotate-mcp-token.sh
new file mode 100755
index 0000000..6bd91d8
--- /dev/null
+++ b/scripts/rotate-mcp-token.sh
@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# scripts/rotate-mcp-token.sh
+#
+# Full reset of the MCP auth token.  Used when ``make run-mcp``'s
+# auto-recovery couldn't fix a 401 — typically because Forge
+# persisted an older token in Postgres on its first boot, and just
+# force-recreating the Forge container with the new env doesn't
+# clear that persisted state.
+#
+# Three steps:
+#   1. Generate a fresh MCP_AUTH_TOKEN and write it into .mcp.env.
+#   2. Stop the Forge container AND wipe its volumes so the persisted
+#      credential cache is gone.  Postgres data (a separate volume)
+#      is preserved — gitpilot's MCP registry stays intact.
+#   3. Bring Forge back up with the new token, wait for /health, run
+#      the registration sweep.
+#
+# Idempotent.  Safe to run any number of times.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+cd "${REPO_ROOT}"
+
+# Colours, degrading to plain when not a TTY.
+if [ -t 1 ]; then
+  GREEN=$(printf '\033[32m'); RED=$(printf '\033[31m'); YELLOW=$(printf '\033[33m'); BOLD=$(printf '\033[1m'); RESET=$(printf '\033[0m')
+else
+  GREEN=""; RED=""; YELLOW=""; BOLD=""; RESET=""
+fi
+ok()    { printf "${GREEN}✓${RESET} %s\n" "$*"; }
+warn()  { printf "${YELLOW}⚠${RESET} %s\n" "$*"; }
+fail()  { printf "${RED}✗${RESET} %s\n" "$*" 1>&2; }
+step()  { printf "${BOLD}🔹${RESET} %s\n" "$*"; }
+
+ENV_FILE="${REPO_ROOT}/.mcp.env"
+COMPOSE_FILE="${REPO_ROOT}/docker-compose.mcp.yml"
+
+if [ ! -f "${ENV_FILE}" ]; then
+  fail ".mcp.env not found at ${ENV_FILE}"
+  fail "Run 'make install-mcp' first to bootstrap the MCP env."
+  exit 2
+fi
+if [ ! -f "${COMPOSE_FILE}" ]; then
+  fail "docker-compose.mcp.yml not found at ${COMPOSE_FILE}"
+  exit 2
+fi
+
+# -----------------------------------------------------------------------
+# 1. Generate fresh token + update .mcp.env
+# -----------------------------------------------------------------------
+step "Rotating MCP_AUTH_TOKEN in .mcp.env"
+
+if command -v openssl >/dev/null 2>&1; then
+  NEW_TOKEN=$(openssl rand -hex 32)
+elif command -v python3 >/dev/null 2>&1; then
+  NEW_TOKEN=$(python3 -c 'import secrets; print(secrets.token_hex(32))')
+else
+  fail "Need openssl or python3 to generate a secure token."
+  exit 2
+fi
+
+# Portable sed -i (BSD/GNU). Try GNU form first; fall back to BSD.
+if sed -i.bak "s|^MCP_AUTH_TOKEN=.*|MCP_AUTH_TOKEN=${NEW_TOKEN}|" "${ENV_FILE}" 2>/dev/null; then
+  rm -f "${ENV_FILE}.bak"
+else
+  sed -i '' "s|^MCP_AUTH_TOKEN=.*|MCP_AUTH_TOKEN=${NEW_TOKEN}|" "${ENV_FILE}"
+fi
+ok "Wrote fresh MCP_AUTH_TOKEN to .mcp.env (32 bytes, hex-encoded)."
+
+# -----------------------------------------------------------------------
+# 2. Stop Forge + wipe its volumes
+# -----------------------------------------------------------------------
+step "Stopping mcp-context-forge and wiping its volumes"
+
+# ``rm -fsv`` stops the container AND deletes its named volumes.
+# Postgres uses different named volumes so its data is preserved.
+docker compose --env-file "${ENV_FILE}" -f "${COMPOSE_FILE}" --profile mcp \
+  rm -fsv mcp-context-forge >/dev/null 2>&1 || true
+
+# Belt-and-suspenders: hunt for any Forge-specific anonymous volumes
+# that survived (rare, but seen on older compose versions).
+docker volume ls --format '{{.Name}}' 2>/dev/null \
+  | grep -E 'gitpilot-mcp.*forge' \
+  | xargs -r docker volume rm 2>/dev/null \
+  || true
+ok "Forge stopped, volumes removed."
+
+# -----------------------------------------------------------------------
+# 3. Re-up Forge with the new token + register
+# -----------------------------------------------------------------------
+step "Starting mcp-context-forge with the rotated token"
+
+docker compose --env-file "${ENV_FILE}" -f "${COMPOSE_FILE}" --profile mcp \
+  up -d --force-recreate --no-deps mcp-context-forge >/dev/null
+
+# Wait for /health to answer through the published host port.
+FORGE_PORT="${MCP_FORGE_PORT:-4444}"
+HOST_PROBE="http://localhost:${FORGE_PORT}/health"
+printf "  waiting for ${HOST_PROBE}"
+for i in $(seq 1 60); do
+  if curl -fsS -m 2 -o /dev/null "${HOST_PROBE}" 2>/dev/null; then
+    echo " (${i}s)"
+    break
+  fi
+  printf "."
+  sleep 1
+  if [ "${i}" -eq 60 ]; then
+    echo
+    fail "Forge did not return to healthy within 60s."
+    fail "Inspect:  docker logs gitpilot-mcp-context-forge --tail 80"
+    exit 5
+  fi
+done
+ok "Forge healthy at ${HOST_PROBE}."
+
+# Re-run registration with the rotated token.
+step "Re-registering MCP servers with the new token"
+if ! bash "${SCRIPT_DIR}/register-mcp-servers.sh"; then
+  fail "Registration still failed after token rotation."
+  fail "Last resort:  make stop-mcp && make uninstall-mcp && make run-mcp"
+  exit 6
+fi
+
+echo
+ok "MCP token rotation complete."
+echo
+echo "Next:"
+echo "  make run           # start GitPilot with the rotated token"
+echo "  curl -sf -H 'Authorization: Bearer ${NEW_TOKEN:0:12}…' \\"
+echo "       http://localhost:${FORGE_PORT}/gateways   # verify the new token works"
diff --git a/scripts/start-gitpilot-stack.sh b/scripts/start-gitpilot-stack.sh
new file mode 100755
index 0000000..6805b2e
--- /dev/null
+++ b/scripts/start-gitpilot-stack.sh
@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# scripts/start-gitpilot-stack.sh
+#
+# Full production startup that wraps the existing 'make run' flow
+# and adds the MatrixLab addon on top.  Purely additive — does NOT
+# modify the original Makefile recipes or any scripts on the canonical
+# startup path.  Used by:
+#
+#   make startup            # one command, full stack
+#   bash scripts/start-gitpilot-stack.sh
+#
+# What it does, in order:
+#
+#   1. Sanity check (docker + ports + .env populated).
+#   2. Install/start the MatrixLab addon (idempotent, reuses container).
+#   3. Start GitPilot (delegates to 'make run' — original recipe).
+#   4. Wait for GitPilot's /api/ping.
+#   5. Auto-fix the persisted matrixlab_url so the Install Addon
+#      modal points at the actually-listening port (the bug behind
+#      the "Runner URL: http://localhost:8000 / Needs attention"
+#      screenshot — caused by stale settings.json from before the
+#      port-shift to 8765).
+#   6. Print a green summary with the URLs and the next-step hints.
+#
+# Verbose by default — every step is logged with elapsed time so an
+# operator filing a bug report can paste the log and we can see
+# exactly where things diverged.  Set GITPILOT_QUIET=1 to suppress.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+cd "${REPO_ROOT}"
+
+GITPILOT_PORT="${GITPILOT_PORT:-8000}"
+GITPILOT_URL="http://127.0.0.1:${GITPILOT_PORT}"
+
+# ---- Logging -------------------------------------------------------------
+if [ -t 1 ] && [ -z "${GITPILOT_QUIET:-}" ]; then
+  GREEN=$(printf '\033[32m'); RED=$(printf '\033[31m'); YELLOW=$(printf '\033[33m')
+  BLUE=$(printf '\033[34m'); BOLD=$(printf '\033[1m'); DIM=$(printf '\033[2m'); RESET=$(printf '\033[0m')
+else
+  GREEN=""; RED=""; YELLOW=""; BLUE=""; BOLD=""; DIM=""; RESET=""
+fi
+__t0=$(date +%s)
+ts()    { printf "${DIM}[+%3ds]${RESET}" $(($(date +%s) - __t0)); }
+ok()    { printf "%s ${GREEN}✓${RESET} %s\n" "$(ts)" "$*"; }
+warn()  { printf "%s ${YELLOW}⚠${RESET} %s\n" "$(ts)" "$*"; }
+fail()  { printf "%s ${RED}✗${RESET} %s\n" "$(ts)" "$*" 1>&2; }
+step()  { printf "\n%s ${BOLD}${BLUE}━━ %s ━━${RESET}\n" "$(ts)" "$*"; }
+debug() { [ -n "${GITPILOT_DEBUG:-}" ] && printf "%s ${DIM}· %s${RESET}\n" "$(ts)" "$*" || true; }
+
+# ---- 1. Preflight -------------------------------------------------------
+step "1/5 · Preflight"
+
+if ! command -v docker >/dev/null 2>&1; then
+  fail "docker not on PATH — install Docker (https://docs.docker.com/get-docker/)"
+  exit 1
+fi
+if ! docker info >/dev/null 2>&1; then
+  fail "docker daemon not running — start Docker Desktop or 'sudo systemctl start docker'"
+  exit 1
+fi
+ok "docker reachable"
+
+if [ ! -f .env ]; then
+  warn ".env not found — GitPilot will boot with template defaults"
+  warn "   Get OAuth credentials at:  https://github.com/settings/applications/new"
+  warn "   cp .env.template .env  and fill in GITHUB_CLIENT_ID + GITHUB_CLIENT_SECRET"
+else
+  ok ".env present"
+fi
+
+# Port check — accept "held by our own container" as fine.
+port_busy() {
+  local port="$1"
+  local our_match="$2"
+  if command -v lsof >/dev/null 2>&1; then
+    local who
+    who=$(lsof -nP -iTCP:"${port}" -sTCP:LISTEN 2>/dev/null | awk 'NR>1 {print $1}' | head -1)
+    [ -z "${who}" ] && return 1
+    docker ps --format '{{.Names}}' 2>/dev/null | grep -q "${our_match}" && return 1
+    echo "${who}"
+    return 0
+  fi
+  return 1
+}
+for entry in "8000:gitpilot" "4444:gitpilot-mcp-context-forge" "8765:gitpilot-matrixlab"; do
+  port="${entry%%:*}"
+  pattern="${entry##*:}"
+  who=$(port_busy "${port}" "${pattern}" || true)
+  if [ -n "${who}" ]; then
+    warn "port ${port} held by ${who} (not one of our containers — may conflict)"
+  else
+    debug "port ${port} free or held by our own container"
+  fi
+done
+
+# ---- 2. Install / start MatrixLab addon ---------------------------------
+step "2/5 · MatrixLab addon (idempotent install + start)"
+
+# Force-disable interactive prompts in install-matrixlab.sh.  The
+# script is already idempotent (re-running reuses the existing
+# container).
+MATRIXLAB_PORT="${MATRIXLAB_PORT:-8765}"
+MATRIXLAB_NAMESPACE="${MATRIXLAB_NAMESPACE:-ruslanmv}"
+export MATRIXLAB_PORT MATRIXLAB_NAMESPACE
+
+if [ -x "${SCRIPT_DIR}/install-matrixlab.sh" ]; then
+  if bash "${SCRIPT_DIR}/install-matrixlab.sh"; then
+    ok "MatrixLab addon ready on :${MATRIXLAB_PORT}"
+  else
+    warn "MatrixLab install returned non-zero — continuing without it"
+    warn "   Inspect with:  bash scripts/install-matrixlab.sh"
+  fi
+else
+  warn "scripts/install-matrixlab.sh not present — skipping addon install"
+fi
+
+# ---- 3. Start GitPilot via the existing `make run` ----------------------
+step "3/5 · GitPilot backend + frontend (delegating to 'make run')"
+
+# If GitPilot is already up we don't need to start it.
+if curl -fsS -m 2 -o /dev/null "${GITPILOT_URL}/api/ping" 2>/dev/null; then
+  ok "GitPilot already running on ${GITPILOT_URL}"
+else
+  # Launch in the background so we can probe + fix the URL afterwards.
+  # The user can still Ctrl-C the trailing process when they're done.
+  ok "Starting 'make run' in the background — logs streamed below"
+  echo
+  # Foreground would block; we run it in a way the operator can see.
+  make run &
+  MAKE_PID=$!
+  trap 'kill $MAKE_PID 2>/dev/null || true' INT TERM
+
+  # Wait for /api/ping.  Bounded by GITPILOT_START_TIMEOUT (default 120s).
+  __wait_start=$(date +%s)
+  __wait_limit=$((${GITPILOT_START_TIMEOUT:-120}))
+  while ! curl -fsS -m 2 -o /dev/null "${GITPILOT_URL}/api/ping" 2>/dev/null; do
+    if [ $(($(date +%s) - __wait_start)) -gt "${__wait_limit}" ]; then
+      fail "GitPilot did not answer /api/ping within ${__wait_limit}s"
+      exit 5
+    fi
+    sleep 2
+  done
+  echo
+  ok "GitPilot /api/ping responding after $(($(date +%s) - __wait_start))s"
+fi
+
+# ---- 4. Auto-fix the persisted matrixlab_url ----------------------------
+step "4/5 · Auto-detect and fix the matrixlab_url in settings.json"
+
+if [ -x "${SCRIPT_DIR}/fix-matrixlab-url.sh" ]; then
+  GITPILOT_URL="${GITPILOT_URL}" bash "${SCRIPT_DIR}/fix-matrixlab-url.sh" || \
+    warn "URL auto-fix returned non-zero — open Settings → Sandbox → Advanced to set it manually"
+else
+  warn "scripts/fix-matrixlab-url.sh missing — skipping URL auto-fix"
+fi
+
+# ---- 5. Summary ---------------------------------------------------------
+step "5/5 · Stack ready"
+
+cat <<SUMMARY
+
+  ${BOLD}GitPilot      ${RESET}${GITPILOT_URL}
+  ${BOLD}MCP Forge     ${RESET}http://localhost:4444         (if MCP stack started)
+  ${BOLD}MatrixLab     ${RESET}http://localhost:${MATRIXLAB_PORT}/health
+  ${BOLD}Frontend (dev)${RESET}http://localhost:5173
+
+  ${BOLD}Diagnose anything that didn't come up clean:${RESET}
+    make doctor                                # ports / images / token check
+    make diagnose-matrixlab                    # full matrixlab-side probe
+    docker logs gitpilot-matrixlab --tail 80   # runner logs
+
+  ${BOLD}Stop everything:${RESET}
+    make stop                                  # GitPilot + MCP
+    docker stop gitpilot-matrixlab             # MatrixLab addon
+
+SUMMARY
+
+# Keep the trailing make-run in the foreground for the operator (so
+# Ctrl-C still tears down the dev servers cleanly).  Bail when the
+# subprocess exits.
+if [ -n "${MAKE_PID:-}" ]; then
+  wait "${MAKE_PID}" 2>/dev/null || true
+fi
diff --git a/tests/test_docs_links.py b/tests/test_docs_links.py
index d2b7c15..7f87c4d 100644
--- a/tests/test_docs_links.py
+++ b/tests/test_docs_links.py
@@ -27,7 +27,12 @@
 # (.venv, node_modules, build artefacts) and the legacy mcp-stack
 # clone that the install workflow may drop into the repo.
 _SKIP_PARTS = {".venv", "node_modules", "build", "dist", "htmlcov",
-               ".git", "__pycache__", "mcp-stack"}
+               ".git", "__pycache__", "mcp-stack",
+               # uv's project cache (transient — pulled archives, sdists,
+               # extracted wheels — none of it is repo source).
+               ".uv-cache",
+               # MatrixLab addon's job workspace bind-mount.
+               ".matrixlab-jobs"}
 
 
 def _iter_markdown() -> Iterable[Path]:
diff --git a/tests/test_execute_short_circuit.py b/tests/test_execute_short_circuit.py
new file mode 100644
index 0000000..7044bf0
--- /dev/null
+++ b/tests/test_execute_short_circuit.py
@@ -0,0 +1,107 @@
+"""Tests for the deterministic EXECUTE short-circuit.
+
+The short-circuit replaces the LLM planner for unambiguous "run this
+file" requests.  Two failure classes it has to prevent:
+
+1. The small-LLM CrewAI planner treating ``EXECUTE`` as a tool name,
+   failing, retrying, then downgrading the action to ``READ`` (the bug
+   that motivated this code path).
+2. The latency overhead of an LLM round-trip when the answer is
+   deterministic from the routing decision + repo file list.
+
+So the tests assert:
+* Unambiguous requests produce an EXECUTE plan with the right path.
+* Ambiguous, off-intent, or unrunnable requests fall through to the
+  caller (return ``None``), so the LLM planner can disambiguate.
+"""
+from __future__ import annotations
+
+import pytest
+
+from gitpilot.agentic import (
+    PlanResult,
+    _is_runnable_path,
+    _looks_like_matplotlib,
+    try_execute_short_circuit,
+)
+
+
+@pytest.mark.parametrize(
+    "goal,intent,targets,repo,expected_path",
+    [
+        # Named target — most common case ("execute demo.py")
+        ("execute demo.py", "execute", ["demo.py"], ["demo.py", "README.md"], "demo.py"),
+        # Unnamed but exactly one runnable file in the repo
+        ("run the script",  "execute", [],          ["README.md", "tool.py"], "tool.py"),
+        # Bash script
+        ("run the shell",   "execute", ["build.sh"], ["build.sh"],            "build.sh"),
+        # Node script
+        ("execute main",    "execute", ["main.js"],  ["main.js"],             "main.js"),
+    ],
+)
+def test_short_circuit_produces_execute_plan(goal, intent, targets, repo, expected_path) -> None:
+    plan = try_execute_short_circuit(
+        goal=goal, intent=intent, target_files=targets, repo_files=repo,
+    )
+    assert isinstance(plan, PlanResult)
+    assert len(plan.steps) == 1
+    step = plan.steps[0]
+    assert len(step.files) == 1
+    assert step.files[0].path == expected_path
+    assert step.files[0].action == "EXECUTE"
+
+
+@pytest.mark.parametrize(
+    "intent,targets,repo,reason",
+    [
+        # Wrong intent — planner has to handle it
+        ("find",    ["demo.py"],          ["demo.py"],            "intent != execute"),
+        ("modify",  ["demo.py"],          ["demo.py"],            "intent != execute"),
+        ("unknown", ["demo.py"],          ["demo.py"],            "intent != execute"),
+        # Unrunnable target — planner has to ask or refuse
+        ("execute", ["README.md"],        ["README.md"],          "not a runnable extension"),
+        # Multiple runnable files but none named — operator must pick
+        ("execute", [],                   ["a.py", "b.py"],       "ambiguous repo"),
+        # No targets, empty repo — planner has to ask
+        ("execute", [],                   [],                     "nothing to run"),
+        # Multiple named targets — operator has to pick
+        ("execute", ["a.py", "b.py"],     ["a.py", "b.py"],       "multiple targets"),
+    ],
+)
+def test_short_circuit_falls_through(intent, targets, repo, reason) -> None:
+    plan = try_execute_short_circuit(
+        goal="...", intent=intent, target_files=targets, repo_files=repo,
+    )
+    assert plan is None, f"expected fallthrough ({reason}), got plan with {plan}"
+
+
+def test_is_runnable_path_covers_expected_extensions() -> None:
+    for runnable in ("foo.py", "bar.js", "baz.mjs", "x.cjs", "build.sh", "go.bash"):
+        assert _is_runnable_path(runnable), runnable
+    for non_runnable in ("README.md", "data.json", "image.png", "Dockerfile", "Makefile"):
+        assert not _is_runnable_path(non_runnable), non_runnable
+
+
+def test_matplotlib_detector_hits_common_idioms() -> None:
+    # The actual matplotlib-using code patterns we want to catch.
+    assert _looks_like_matplotlib("import matplotlib.pyplot as plt\nplt.show()")
+    assert _looks_like_matplotlib("from matplotlib import pyplot")
+    assert _looks_like_matplotlib("import matplotlib\nmatplotlib.use('Agg')")
+    # Should NOT trip on unrelated code (false positives waste time but
+    # are otherwise harmless; we still verify the common case).
+    assert not _looks_like_matplotlib("print('hello world')")
+    assert not _looks_like_matplotlib("import numpy as np\nx = np.zeros(10)")
+
+
+def test_short_circuit_summary_mentions_target_and_outcome_contract() -> None:
+    """UX contract: the plan summary the modal renders must name the
+    file *and* signal that stdout/stderr/exit-code will come back —
+    otherwise users don't understand what just got planned."""
+    plan = try_execute_short_circuit(
+        goal="execute demo.py", intent="execute",
+        target_files=["demo.py"], repo_files=["demo.py"],
+    )
+    assert plan is not None
+    assert "demo.py" in plan.summary
+    assert "stdout" in plan.summary
+    assert "exit code" in plan.summary
diff --git a/tests/test_execute_short_circuit_plan.py b/tests/test_execute_short_circuit_plan.py
new file mode 100644
index 0000000..6dc39b3
--- /dev/null
+++ b/tests/test_execute_short_circuit_plan.py
@@ -0,0 +1,122 @@
+"""Tests for the executor short-circuit attaching an ExecutionPlan.
+
+When the router detects an unambiguous RUN_FILE intent, the short
+circuit returns a PlanResult whose ``execution_plan`` field carries
+the approval-card data the chat UI renders.
+"""
+
+from __future__ import annotations
+
+from gitpilot.agentic import try_execute_short_circuit
+
+
+def test_short_circuit_attaches_execution_plan() -> None:
+    plan = try_execute_short_circuit(
+        goal="please run demo.py",
+        intent="execute",
+        target_files=["demo.py"],
+        repo_files=["demo.py", "README.md"],
+    )
+    assert plan is not None
+    assert plan.execution_plan is not None
+    ep = plan.execution_plan
+    assert ep["file"] == "demo.py"
+    assert ep["command"] == ["python", "demo.py"]
+    assert ep["requires_approval"] is True
+    assert "safety" in ep and "checks" in ep["safety"]
+
+
+def test_short_circuit_no_target_no_plan() -> None:
+    plan = try_execute_short_circuit(
+        goal="run something",
+        intent="execute",
+        target_files=[],
+        repo_files=["README.md"],  # no runnable file
+    )
+    assert plan is None
+
+
+def test_short_circuit_picks_unique_runnable() -> None:
+    plan = try_execute_short_circuit(
+        goal="run the script",
+        intent="execute",
+        target_files=[],
+        repo_files=["main.py", "README.md"],
+    )
+    assert plan is not None
+    assert plan.execution_plan is not None
+    assert plan.execution_plan["file"] == "main.py"
+
+
+def test_short_circuit_not_execute_intent() -> None:
+    plan = try_execute_short_circuit(
+        goal="explain demo.py",
+        intent="info",
+        target_files=["demo.py"],
+        repo_files=["demo.py"],
+    )
+    assert plan is None
+
+
+def test_short_circuit_extracts_unverified_path_from_goal() -> None:
+    """The most common 'empty plan' failure: user just created demo.py
+    on the branch; the router's tree fetch raced or was cached without
+    it, so target_files is empty. We must still produce a plan from the
+    explicit goal text instead of falling through to the LLM."""
+    plan = try_execute_short_circuit(
+        goal="run demo.py",
+        intent="execute",
+        target_files=[],
+        repo_files=["README.md", "src/main.py", "src/helpers.py"],
+    )
+    assert plan is not None
+    assert plan.execution_plan is not None
+    assert plan.execution_plan["file"] == "demo.py"
+    # The unverified-file warning must be present so the user sees
+    # honest context, but approval is still possible.
+    warnings = plan.execution_plan["safety"]["warnings"]
+    assert any("not in cached repo tree" in w["label"].lower() for w in warnings)
+    # And the "File exists" check is marked unverified, not falsely green.
+    checks = plan.execution_plan["safety"]["checks"]
+    file_check = next((c for c in checks if "demo.py" in c["label"]), None)
+    assert file_check is not None
+    assert file_check["ok"] is False
+
+
+def test_short_circuit_extracts_path_from_natural_phrasing() -> None:
+    """The exact phrasing from the user's bug report — 'please execute
+    this demo.py code in the sandbox' — must short-circuit, not return
+    an empty plan."""
+    plan = try_execute_short_circuit(
+        goal="please execute this demo.py code in the sandbox",
+        intent="execute",
+        target_files=[],
+        repo_files=["README.md"],
+    )
+    assert plan is not None
+    assert plan.execution_plan is not None
+    assert plan.execution_plan["file"] == "demo.py"
+
+
+def test_short_circuit_extracts_first_when_multiple_mentioned() -> None:
+    """Bareword extractor preserves goal order; the short-circuit
+    requires exactly one candidate, so multiple distinct filenames
+    fall through to the LLM (which can disambiguate)."""
+    plan = try_execute_short_circuit(
+        goal="run a.py and then b.py",
+        intent="execute",
+        target_files=[],
+        repo_files=[],
+    )
+    assert plan is None  # ambiguous — let the LLM ask
+
+
+def test_extract_runnable_paths_dedup_and_extensions() -> None:
+    from gitpilot.agentic import _extract_runnable_paths_from_goal
+
+    out = _extract_runnable_paths_from_goal("run demo.py and demo.py again")
+    assert out == ["demo.py"]
+    out = _extract_runnable_paths_from_goal("execute scripts/build.sh please")
+    assert out == ["scripts/build.sh"]
+    # Non-runnable extensions are not extracted.
+    assert _extract_runnable_paths_from_goal("explain README.md") == []
diff --git a/tests/test_local_tools.py b/tests/test_local_tools.py
index 9f4c93c..c0b4be6 100644
--- a/tests/test_local_tools.py
+++ b/tests/test_local_tools.py
@@ -220,6 +220,12 @@ def test_blocked_command(self, tmp_path):
         assert "Permission denied" in result
 
     def test_successful_command(self, tmp_path):
+        """``run_command`` now prefers ``_run_via_sandbox`` (which talks
+        to the configured backend through ``/api/sandbox/run``); the
+        legacy ``_executor.execute`` path is only the import-error
+        fallback.  Force the sandbox path to raise ``_SandboxFallback``
+        so the test exercises the same TerminalExecutor mock contract
+        it always did, then mock the executor as before."""
         ws = _make_ws(tmp_path)
         lt._current_workspace = ws
 
@@ -230,7 +236,8 @@ def test_successful_command(self, tmp_path):
         mock_result.timed_out = False
         mock_result.truncated = False
 
-        with patch.object(lt._executor, "execute", new_callable=AsyncMock) as mock_exec:
+        with patch.object(lt, "_run_via_sandbox", side_effect=lt._SandboxFallback("forced")), \
+             patch.object(lt._executor, "execute", new_callable=AsyncMock) as mock_exec:
             mock_exec.return_value = mock_result
             result = lt.run_command.func("echo hello")
 
diff --git a/tests/test_matrixlab_admin_api.py b/tests/test_matrixlab_admin_api.py
new file mode 100644
index 0000000..43c201d
--- /dev/null
+++ b/tests/test_matrixlab_admin_api.py
@@ -0,0 +1,611 @@
+"""Tests for the enterprise MatrixLab install/admin surface.
+
+Two layers:
+
+1. Pure helpers (`classify_error`, `derive_status`) — verified
+   without spinning up FastAPI or httpx. These are the smarts that
+   keep raw Docker / HTTP errors out of the install modal.
+2. HTTP endpoints — driven through ``TestClient`` with the docker /
+   httpx layer monkeypatched so the tests stay hermetic. No real
+   Docker, no real MatrixLab runner.
+
+The contract under test is: every endpoint returns the same
+:class:`MatrixLabStatus` shape; ``status`` is one of the documented
+literals; raw errors land in ``technicalDetails.rawError`` only.
+"""
+from __future__ import annotations
+
+from typing import Iterator, List
+
+import httpx
+import pytest
+from fastapi.testclient import TestClient
+
+from gitpilot import matrixlab_admin_api as mla
+from gitpilot.matrixlab_admin_api import (
+    MatrixLabStatus,
+    classify_error,
+    derive_status,
+)
+from gitpilot.sandbox_api import MatrixLabLifecycleResponse, _StepResult
+from gitpilot.settings import reload_settings
+
+
+# ---------------------------------------------------------------------
+# Pure helper tests — no FastAPI, no httpx, no Docker
+# ---------------------------------------------------------------------
+
+@pytest.mark.parametrize(
+    "raw, expected_code",
+    [
+        ("Expecting value: line 1 column 1 (char 0)", "INVALID_HEALTH_RESPONSE"),
+        ("Invalid JSON: foo", "INVALID_HEALTH_RESPONSE"),
+        ("[Errno 111] Connection refused", "CONNECTION_REFUSED"),
+        ("the connection was refused by peer", "CONNECTION_REFUSED"),
+        ("timed out waiting for response", "TIMEOUT"),
+        ("Read timeout reached", "TIMEOUT"),
+        ("Name or service not known", "DNS_ERROR"),
+        ("Cannot connect to the Docker daemon at unix:///var/run/docker.sock", "DOCKER_NOT_RUNNING"),
+        ("Error response from docker daemon: ...", "DOCKER_NOT_RUNNING"),
+        ("driver failed: port is already allocated", "PORT_IN_USE"),
+        ("listen tcp 0.0.0.0:8000: bind: address already in use", "PORT_IN_USE"),
+        ("permission denied while connecting to socket", "PERMISSION_DENIED"),
+        ("No such image: matrixlab-runner:latest", "IMAGE_MISSING"),
+        ("docker not on PATH", "DOCKER_NOT_INSTALLED"),
+    ],
+)
+def test_classify_error_maps_known_traces(raw: str, expected_code: str) -> None:
+    code, msg = classify_error(raw)
+    assert code == expected_code
+    assert msg  # always non-empty for non-empty inputs
+
+
+def test_classify_error_empty_returns_empty() -> None:
+    """Truthy guard so callers can branch on ``if code``."""
+    assert classify_error("") == ("", "")
+    assert classify_error(None) == ("", "")
+
+
+def test_classify_error_unknown_is_documented_unknown_code() -> None:
+    """Anything the table doesn't cover gets a stable ``UNKNOWN`` code
+    so the UI can still drive a copy lookup table off it."""
+    code, msg = classify_error("something completely novel and unparseable")
+    assert code == "UNKNOWN"
+    assert "unexpected" in msg.lower()
+
+
+# ---------------------------------------------------------------------
+# derive_status — the state machine that drives the modal
+# ---------------------------------------------------------------------
+
+def _lifecycle(**overrides) -> MatrixLabLifecycleResponse:
+    base = dict(
+        docker_available=True,
+        installed=False,
+        running=False,
+        lifecycle_enabled=True,
+        runner_image="ruslanmv/matrixlab-runner:latest",
+        sandbox_images=["matrix-lab-sandbox-python:latest"],
+        container_name="gitpilot-matrixlab",
+        matrixlab_url="http://localhost:8000",
+        steps=[],
+    )
+    base.update(overrides)
+    return MatrixLabLifecycleResponse(**base)
+
+
+def test_derive_status_not_installed_when_no_image_and_no_container() -> None:
+    s = derive_status(
+        lifecycle=_lifecycle(installed=False, running=False),
+        reachable=False,
+        health_error=None,
+        active_sandbox="subprocess",
+    )
+    assert s.status == "not_installed"
+    assert s.installed is False
+    assert s.running is False
+    assert s.errorCode is None
+    assert "not installed" in s.message.lower()
+
+
+def test_derive_status_ready_when_running_and_reachable() -> None:
+    s = derive_status(
+        lifecycle=_lifecycle(installed=True, running=True),
+        reachable=True,
+        health_error=None,
+        active_sandbox="matrixlab",
+    )
+    assert s.status == "ready"
+    assert s.installed is True
+    assert s.running is True
+    assert s.reachable is True
+    assert s.errorCode is None
+
+
+def test_derive_status_needs_attention_when_running_but_unreachable() -> None:
+    """The bug from the original screenshot — runner is up but /health
+    returned an empty body. The modal must NOT show contradictory
+    badges."""
+    s = derive_status(
+        lifecycle=_lifecycle(installed=True, running=True),
+        reachable=False,
+        health_error="Expecting value: line 1 column 1 (char 0)",
+        active_sandbox="local",
+    )
+    assert s.status == "needs_attention"
+    # Single coherent state — running stays true but reachable=false
+    # and we flag an error code rather than contradict ourselves.
+    assert s.running is True
+    assert s.reachable is False
+    assert s.errorCode == "INVALID_HEALTH_RESPONSE"
+    # User-facing message must NOT contain the raw stack-trace-like phrase
+    assert "Expecting value" not in s.message
+    assert "cannot connect" in s.message.lower()
+    # Raw error preserved for the disclosure
+    assert s.technicalDetails is not None
+    assert s.technicalDetails.rawError == "Expecting value: line 1 column 1 (char 0)"
+
+
+def test_derive_status_needs_attention_when_installed_but_stopped() -> None:
+    s = derive_status(
+        lifecycle=_lifecycle(installed=True, running=False),
+        reachable=False,
+        health_error=None,
+        active_sandbox="subprocess",
+    )
+    assert s.status == "needs_attention"
+    assert s.errorCode == "STOPPED"
+
+
+def test_derive_status_needs_attention_when_docker_missing() -> None:
+    s = derive_status(
+        lifecycle=_lifecycle(docker_available=False),
+        reachable=False,
+        health_error=None,
+        active_sandbox="subprocess",
+    )
+    assert s.status == "needs_attention"
+    assert s.dockerAvailable is False
+    # Docker-missing maps to a clear code, not just UNKNOWN
+    assert s.errorCode in ("DOCKER_NOT_INSTALLED", "DOCKER_NOT_RUNNING")
+
+
+@pytest.mark.parametrize("in_flight", ["installing", "starting", "stopping", "checking"])
+def test_derive_status_in_flight_overrides_terminal_state(in_flight: str) -> None:
+    """While a long-running install/start is mid-flight the modal must
+    show the progress state, not the stale terminal state."""
+    s = derive_status(
+        lifecycle=_lifecycle(installed=False, running=False),
+        reachable=False,
+        health_error=None,
+        active_sandbox="subprocess",
+        in_flight=in_flight,  # type: ignore[arg-type]
+    )
+    assert s.status == in_flight
+    # Progress messages are friendly, not jargon
+    assert s.message and "…" in s.message
+
+
+def test_status_response_excludes_secrets_and_tracebacks() -> None:
+    """Critical UX invariant: the public ``message`` never leaks
+    a raw exception trace. Operators see it only under
+    ``technicalDetails.rawError``."""
+    s = derive_status(
+        lifecycle=_lifecycle(installed=True, running=True),
+        reachable=False,
+        health_error="Traceback (most recent call last): json.decoder.JSONDecodeError",
+        active_sandbox="local",
+    )
+    assert "Traceback" not in s.message
+    assert "JSONDecodeError" not in s.message
+    assert s.technicalDetails is not None
+    assert "Traceback" in (s.technicalDetails.rawError or "")
+
+
+# ---------------------------------------------------------------------
+# Endpoint tests — mocked docker + mocked httpx
+# ---------------------------------------------------------------------
+
+@pytest.fixture()
+def client(tmp_path, monkeypatch) -> Iterator[TestClient]:
+    """Hermetic TestClient with docker + httpx stubbed so the tests
+    never touch the real host."""
+    from gitpilot import settings as settings_module
+
+    cfg_dir = tmp_path / "cfg"
+    cfg_dir.mkdir(parents=True, exist_ok=True)
+    monkeypatch.setattr(settings_module, "CONFIG_DIR", cfg_dir)
+    monkeypatch.setattr(settings_module, "CONFIG_FILE", cfg_dir / "settings.json")
+    monkeypatch.setenv("GITPILOT_CONFIG_DIR", str(cfg_dir))
+    for name in (
+        "GITPILOT_SANDBOX",
+        "GITPILOT_MATRIXLAB_URL",
+        "GITPILOT_MATRIXLAB_TOKEN",
+        "GITPILOT_MATRIXLAB_IMAGE",
+        "GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE",
+    ):
+        monkeypatch.delenv(name, raising=False)
+    reload_settings()
+
+    from gitpilot.api import app
+
+    with TestClient(app) as c:
+        yield c
+    reload_settings()
+
+
+def _stub_docker(monkeypatch, *, available: bool, installed: bool, running: bool) -> None:
+    """Pretend docker is/isn't on PATH and that the runner image / URL
+    are present without invoking any subprocesses or sockets."""
+
+    async def fake_image_present(name: str) -> bool:
+        return installed
+
+    async def fake_running() -> bool:
+        return running
+
+    monkeypatch.setattr(
+        "gitpilot.sandbox_api._docker_available", lambda: available,
+    )
+    # matrixlab_admin_api imported the same symbol by name; patch its
+    # bound reference too so the install path sees our stub.
+    monkeypatch.setattr(
+        "gitpilot.matrixlab_admin_api._docker_available", lambda: available,
+    )
+    monkeypatch.setattr(
+        "gitpilot.sandbox_api._docker_image_present", fake_image_present,
+    )
+    monkeypatch.setattr(
+        "gitpilot.sandbox_api._matrixlab_running", fake_running,
+    )
+
+
+def _stub_health(monkeypatch, *, reachable: bool, raw_error: str | None = None,
+                 version: str | None = None) -> None:
+    async def fake_probe() -> tuple[bool, str | None, str | None]:
+        return (reachable, raw_error, version)
+
+    monkeypatch.setattr(
+        "gitpilot.matrixlab_admin_api._probe_health", fake_probe,
+    )
+
+
+def test_status_endpoint_returns_not_installed_on_fresh_host(client, monkeypatch) -> None:
+    _stub_docker(monkeypatch, available=True, installed=False, running=False)
+    _stub_health(monkeypatch, reachable=False)
+
+    r = client.get("/api/matrixlab/status")
+    assert r.status_code == 200
+    data = r.json()
+    assert data["status"] == "not_installed"
+    assert data["installed"] is False
+    assert data["running"] is False
+    assert data["reachable"] is False
+    # Stable shape — every key in MatrixLabStatus is present
+    for key in ("status", "installed", "running", "reachable", "lifecycleEnabled",
+                "dockerAvailable", "activeSandbox", "runnerUrl", "message"):
+        assert key in data
+
+
+def test_status_endpoint_ready_when_runner_healthy(client, monkeypatch) -> None:
+    _stub_docker(monkeypatch, available=True, installed=True, running=True)
+    _stub_health(monkeypatch, reachable=True, version="1.2.3")
+
+    r = client.get("/api/matrixlab/status")
+    data = r.json()
+    assert data["status"] == "ready"
+    assert data["version"] == "1.2.3"
+    assert data["errorCode"] is None
+
+
+def test_status_endpoint_translates_invalid_health_response(client, monkeypatch) -> None:
+    """The exact failure mode from the user's screenshot: running but
+    the health endpoint returned empty/non-JSON. UI must get a clean
+    classified error, never the raw 'Expecting value' string."""
+    _stub_docker(monkeypatch, available=True, installed=True, running=True)
+    _stub_health(
+        monkeypatch,
+        reachable=False,
+        raw_error="Expecting value: line 1 column 1 (char 0)",
+    )
+
+    r = client.get("/api/matrixlab/status")
+    data = r.json()
+    assert data["status"] == "needs_attention"
+    assert data["errorCode"] == "INVALID_HEALTH_RESPONSE"
+    # User-facing message is friendly
+    assert "Expecting value" not in data["message"]
+    # Raw error preserved for the disclosure
+    assert data["technicalDetails"]["rawError"] == "Expecting value: line 1 column 1 (char 0)"
+
+
+def test_install_returns_failed_status_when_lifecycle_disabled(client, monkeypatch) -> None:
+    """Lifecycle off (typical default) — install must NOT raise HTTP
+    403. It must return a normalised failed-status JSON so the modal
+    can render the right copy + recovery action."""
+    _stub_docker(monkeypatch, available=True, installed=False, running=False)
+    _stub_health(monkeypatch, reachable=False)
+    monkeypatch.setenv("GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE", "0")
+
+    r = client.post("/api/matrixlab/install")
+    assert r.status_code == 200
+    data = r.json()
+    assert data["status"] == "failed"
+    assert data["errorCode"] == "LIFECYCLE_DISABLED"
+    # Friendly copy
+    assert "automatic" in data["message"].lower() or "disabled" in data["message"].lower()
+    # Admin hint in technical details
+    assert data["technicalDetails"] is not None
+
+
+def test_install_returns_failed_status_when_docker_missing(client, monkeypatch) -> None:
+    monkeypatch.setenv("GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE", "1")
+    _stub_docker(monkeypatch, available=False, installed=False, running=False)
+    _stub_health(monkeypatch, reachable=False)
+
+    r = client.post("/api/matrixlab/install")
+    data = r.json()
+    assert data["status"] == "failed"
+    assert data["errorCode"] == "DOCKER_NOT_INSTALLED"
+
+
+def test_test_endpoint_reprobes_and_returns_status(client, monkeypatch) -> None:
+    """The modal's 'Retry connection' button calls /test — must return
+    a fresh status without performing any docker operations."""
+    _stub_docker(monkeypatch, available=True, installed=True, running=True)
+    _stub_health(monkeypatch, reachable=True, version="0.1.7")
+
+    r = client.post("/api/matrixlab/test")
+    data = r.json()
+    assert data["status"] == "ready"
+    assert data["version"] == "0.1.7"
+
+
+def test_activate_refuses_when_not_ready(client, monkeypatch) -> None:
+    """Don't let the user point the Run button at a dead backend by
+    clicking Activate before MatrixLab is healthy."""
+    _stub_docker(monkeypatch, available=True, installed=False, running=False)
+    _stub_health(monkeypatch, reachable=False)
+
+    # Snapshot the current backend before activation attempt
+    before = client.get("/api/sandbox/status").json()["backend"]
+
+    r = client.post("/api/matrixlab/activate")
+    data = r.json()
+    assert data["status"] != "ready"
+    assert "not ready" in data["message"].lower()
+
+    # And the backend wasn't flipped
+    after = client.get("/api/sandbox/status").json()["backend"]
+    assert after == before
+
+
+def test_activate_sets_backend_when_ready(client, monkeypatch) -> None:
+    """Successful flow: install + start + health-ok → activate flips
+    the sandbox backend so the Run button uses MatrixLab from now on."""
+    _stub_docker(monkeypatch, available=True, installed=True, running=True)
+    _stub_health(monkeypatch, reachable=True, version="1.0.0")
+
+    # Pre-condition — default is subprocess
+    assert client.get("/api/sandbox/status").json()["backend"] == "subprocess"
+
+    r = client.post("/api/matrixlab/activate")
+    data = r.json()
+    assert data["status"] == "ready"
+    assert data["activeSandbox"] == "matrixlab"
+
+    # /api/sandbox/status now reflects the flip
+    assert client.get("/api/sandbox/status").json()["backend"] == "matrixlab"
+
+
+def test_repair_returns_failed_status_when_lifecycle_disabled(client, monkeypatch) -> None:
+    """The Repair button must NOT raise HTTP 403 when lifecycle is off —
+    it has to return a normalised failed status so the modal can render
+    a recovery action and copy."""
+    monkeypatch.setenv("GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE", "0")
+
+    r = client.post("/api/matrixlab/repair")
+    assert r.status_code == 200
+    data = r.json()
+    assert data["status"] == "failed"
+    assert data["errorCode"] == "LIFECYCLE_DISABLED"
+
+
+def test_repair_message_does_not_use_running_but_unreachable_phrasing(monkeypatch) -> None:
+    """UX invariant: the headline status message must use the cleaner
+    'installed, but GitPilot cannot connect to the runner' phrasing —
+    NOT the older 'running, but GitPilot cannot connect to it at
+    http://… contradictory copy."""
+    from gitpilot.matrixlab_admin_api import derive_status
+    from gitpilot.sandbox_api import MatrixLabLifecycleResponse
+
+    lifecycle = MatrixLabLifecycleResponse(
+        docker_available=True, installed=True, running=True,
+        lifecycle_enabled=True,
+        runner_image="ruslanmv/matrixlab-runner:latest",
+        sandbox_images=[], container_name="x",
+        matrixlab_url="http://localhost:8765",
+        steps=[],
+    )
+    s = derive_status(
+        lifecycle=lifecycle, reachable=False,
+        health_error="connection refused",
+        active_sandbox="local",
+    )
+    assert "installed" in s.message.lower()
+    assert "cannot connect" in s.message.lower()
+    # Older buggy copy must not survive a regression.
+    assert "running, but" not in s.message.lower()
+
+
+def test_reinstall_returns_failed_status_when_lifecycle_disabled(client, monkeypatch) -> None:
+    monkeypatch.setenv("GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE", "0")
+
+    r = client.post("/api/matrixlab/reinstall", json={"remove_data": False})
+    data = r.json()
+    assert data["status"] == "failed"
+    assert data["errorCode"] == "LIFECYCLE_DISABLED"
+
+
+def test_reinstall_accepts_remove_data_flag(client, monkeypatch) -> None:
+    """Wiping cached data is opt-in; reinstall must still parse the
+    request body even when set to True."""
+    monkeypatch.delenv("GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE", raising=False)
+
+    # Even with remove_data=True the request shape must be accepted
+    # (lifecycle gate fires first; the test is about request schema).
+    r = client.post("/api/matrixlab/reinstall", json={"remove_data": True})
+    assert r.status_code == 200
+    data = r.json()
+    assert "status" in data
+    assert "errorCode" in data
+
+
+def test_reinstall_empty_body_uses_default(client, monkeypatch) -> None:
+    """Posting with no body should not 422 — remove_data defaults to False."""
+    monkeypatch.delenv("GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE", raising=False)
+
+    r = client.post("/api/matrixlab/reinstall")
+    assert r.status_code == 200, r.text
+
+
+def test_logs_endpoint_reports_docker_missing(client, monkeypatch) -> None:
+    monkeypatch.setattr("gitpilot.matrixlab_admin_api._docker_available", lambda: False)
+
+    r = client.get("/api/matrixlab/logs")
+    data = r.json()
+    assert data["ok"] is False
+    assert data["errorCode"] == "DOCKER_NOT_INSTALLED"
+
+
+# ---------------------------------------------------------------------
+# Cross-state invariants — properties every status must satisfy
+# ---------------------------------------------------------------------
+
+def test_no_response_can_be_both_running_and_unreachable_without_error_code() -> None:
+    """The 'Unreachable + Running' contradiction shown in the original
+    UI is exactly what derive_status must prevent: whenever
+    running=True AND reachable=False, there has to be an errorCode."""
+    s = derive_status(
+        lifecycle=_lifecycle(installed=True, running=True),
+        reachable=False,
+        health_error="connection refused",
+        active_sandbox="local",
+    )
+    assert s.running is True
+    assert s.reachable is False
+    assert s.errorCode is not None and s.errorCode != ""
+
+
+def test_status_field_only_takes_documented_values() -> None:
+    """Guards the state-machine contract the frontend depends on."""
+    allowed = {
+        "not_installed", "installing", "starting", "stopping",
+        "checking", "ready", "needs_attention", "failed",
+    }
+    for lc, reach, err in [
+        (_lifecycle(installed=False, running=False), False, None),
+        (_lifecycle(installed=True, running=True), True, None),
+        (_lifecycle(installed=True, running=True), False, "boom"),
+        (_lifecycle(installed=True, running=False), False, None),
+        (_lifecycle(docker_available=False), False, None),
+    ]:
+        s = derive_status(
+            lifecycle=lc, reachable=reach,
+            health_error=err, active_sandbox="subprocess",
+        )
+        assert s.status in allowed, f"unexpected status {s.status!r}"
+
+
+def test_default_sandbox_images_use_dockerhub_namespace() -> None:
+    """Regression: ``docker pull matrix-lab-sandbox-python:latest`` would
+    404 because the image is published as ``ruslanmv/matrix-lab-sandbox-python``.
+    Every default image must carry the namespace prefix that matches
+    the matrixlab Makefile (and the docker-publish workflow that pushes
+    them)."""
+    from gitpilot.sandbox_api import DEFAULT_SANDBOX_IMAGES
+
+    assert DEFAULT_SANDBOX_IMAGES, "expected at least one sandbox image"
+    for ref in DEFAULT_SANDBOX_IMAGES:
+        assert "/" in ref, f"image {ref!r} lacks a registry namespace"
+        # Tag present
+        assert ":" in ref.split("/", 1)[1], f"image {ref!r} lacks a tag"
+
+
+# ---------------------------------------------------------------------
+# Native install path (Advanced) — pidfile + status synthesis
+# ---------------------------------------------------------------------
+
+async def test_native_status_reports_not_installed_for_empty_dir(tmp_path, monkeypatch) -> None:
+    """Fresh host, nothing cloned: native status reports installed=False.
+
+    Native async test (pytest-asyncio's auto mode runs it on a clean
+    event loop).  ``asyncio.get_event_loop().run_until_complete(...)``
+    breaks when a previous async test mutated the global loop state —
+    proper ``async def`` avoids that whole class of flakes.
+    """
+    monkeypatch.setattr(mla, "MATRIXLAB_LOCAL_DIR", tmp_path / "ml")
+    monkeypatch.setattr(mla, "MATRIXLAB_PID_FILE", tmp_path / "ml" / ".pid")
+
+    info = await mla._native_status()
+    assert info["installed"] is False
+    assert info["running"] is False
+    assert info["repo_present"] is False
+    assert info["venv_present"] is False
+
+
+async def test_native_status_detects_full_layout(tmp_path, monkeypatch) -> None:
+    """Cloned repo + venv + runner/app/main.py present → installed=True."""
+    ml = tmp_path / "ml"
+    (ml / ".git").mkdir(parents=True)
+    (ml / ".venv").mkdir()
+    (ml / "runner" / "app").mkdir(parents=True)
+    (ml / "runner" / "app" / "main.py").write_text("# stub")
+    monkeypatch.setattr(mla, "MATRIXLAB_LOCAL_DIR", ml)
+    monkeypatch.setattr(mla, "MATRIXLAB_PID_FILE", ml / ".pid")
+
+    info = await mla._native_status()
+    assert info["installed"] is True
+    # No pid yet so still considered not running.
+    assert info["running"] is False
+
+
+def test_install_local_returns_failed_when_lifecycle_disabled(client, monkeypatch) -> None:
+    monkeypatch.setenv("GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE", "0")
+    r = client.post("/api/matrixlab/install_local")
+    assert r.status_code == 200
+    data = r.json()
+    assert data["status"] == "failed"
+    assert data["errorCode"] == "LIFECYCLE_DISABLED"
+
+
+def test_install_local_returns_failed_when_git_missing(client, monkeypatch) -> None:
+    monkeypatch.setenv("GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE", "1")
+    # Pretend git is not on PATH.
+    import shutil as _shutil
+    real_which = _shutil.which
+    monkeypatch.setattr("shutil.which", lambda name: None if name == "git" else real_which(name))
+
+    r = client.post("/api/matrixlab/install_local")
+    data = r.json()
+    assert data["status"] == "failed"
+    assert data["errorCode"] == "GIT_NOT_INSTALLED"
+
+
+def test_message_never_contains_python_traceback_markers() -> None:
+    """User-facing copy hygiene: nothing that looks like a stack trace
+    should ever bleed through to the headline message."""
+    for hostile in (
+        "Traceback (most recent call last)",
+        "json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)",
+        "<class 'httpx.ConnectError'>",
+        "ConnectionError(MaxRetryError(...))",
+    ):
+        s = derive_status(
+            lifecycle=_lifecycle(installed=True, running=True),
+            reachable=False,
+            health_error=hostile,
+            active_sandbox="local",
+        )
+        for marker in ("Traceback", "JSONDecodeError", "<class", "MaxRetryError"):
+            assert marker not in s.message
diff --git a/tests/test_matrixlab_url_recovery.py b/tests/test_matrixlab_url_recovery.py
new file mode 100644
index 0000000..8e80407
--- /dev/null
+++ b/tests/test_matrixlab_url_recovery.py
@@ -0,0 +1,209 @@
+"""Backend tests for the stale-URL auto-detect + diagnostic logs.
+
+These cover the two production bugs the install modal exposed:
+
+* "Runner URL: http://localhost:8000 — Needs attention" after the
+  :8000 → :8765 port migration.  /repair and /url/auto-detect now
+  probe candidate ports and adopt the first live one.
+
+* "Could not read MatrixLab logs."  The /logs endpoint now returns
+  an actionable error + a list of matrixlab-shaped containers when
+  the expected one is missing.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import pytest
+
+from gitpilot import matrixlab_admin_api as adm
+
+
+# ---------------------------------------------------------------------------
+# _discover_live_url
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_discover_picks_first_responder(monkeypatch) -> None:
+    async def fake_probe(url):
+        return (url == "http://localhost:8765", None, None)
+
+    monkeypatch.setattr(adm, "_probe_url", fake_probe)
+    discovered = await adm._discover_live_url("http://localhost:8000")
+    assert discovered == "http://localhost:8765"
+
+
+@pytest.mark.asyncio
+async def test_discover_skips_current_url(monkeypatch) -> None:
+    """The current URL is already known-bad — don't waste a probe on it."""
+    probed = []
+
+    async def fake_probe(url):
+        probed.append(url)
+        return (False, "boom", None)
+
+    monkeypatch.setattr(adm, "_probe_url", fake_probe)
+    out = await adm._discover_live_url("http://localhost:8765")
+    assert out is None
+    # The current URL must not appear in the probe list.
+    assert "http://localhost:8765" not in probed
+    # And we did probe the other candidates.
+    assert "http://localhost:8000" in probed
+
+
+@pytest.mark.asyncio
+async def test_discover_none_when_all_dead(monkeypatch) -> None:
+    async def fake_probe(_url):
+        return (False, "down", None)
+
+    monkeypatch.setattr(adm, "_probe_url", fake_probe)
+    assert await adm._discover_live_url("http://localhost:8000") is None
+
+
+# ---------------------------------------------------------------------------
+# discoveredUrl bubbles through _current_status
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_status_populates_discovered_url(monkeypatch) -> None:
+    """When the configured URL is down and another responds, the
+    /status payload exposes discoveredUrl so the modal can offer
+    the one-click switch."""
+    async def fake_probe_health():
+        return (False, "connection refused", None)
+
+    async def fake_discover(_current):
+        return "http://localhost:8765"
+
+    async def fake_gather():
+        # Minimal lifecycle shape derive_status can consume.
+        from gitpilot.sandbox_api import MatrixLabLifecycleResponse
+        return MatrixLabLifecycleResponse(
+            docker_available=True,
+            installed=True,
+            running=True,
+            lifecycle_enabled=True,
+            runner_image="ruslanmv/matrixlab-runner:latest",
+            sandbox_images=[],
+            container_name="gitpilot-matrixlab",
+            matrixlab_url="http://localhost:8765",
+            steps=[],
+        )
+
+    monkeypatch.setattr(adm, "_probe_health", fake_probe_health)
+    monkeypatch.setattr(adm, "_discover_live_url", fake_discover)
+    monkeypatch.setattr(adm, "_gather_lifecycle_status", fake_gather)
+
+    status = await adm._current_status()
+    assert status.discoveredUrl == "http://localhost:8765"
+
+
+@pytest.mark.asyncio
+async def test_status_no_discovered_when_already_healthy(monkeypatch) -> None:
+    async def fake_probe_health():
+        return (True, None, "1.2.3")
+
+    calls = []
+
+    async def fake_discover(_current):
+        calls.append(1)
+        return "http://localhost:9999"
+
+    async def fake_gather():
+        from gitpilot.sandbox_api import MatrixLabLifecycleResponse
+        return MatrixLabLifecycleResponse(
+            docker_available=True,
+            installed=True,
+            running=True,
+            lifecycle_enabled=True,
+            runner_image="ruslanmv/matrixlab-runner:latest",
+            sandbox_images=[],
+            container_name="gitpilot-matrixlab",
+            matrixlab_url="http://localhost:8765",
+            steps=[],
+        )
+
+    monkeypatch.setattr(adm, "_probe_health", fake_probe_health)
+    monkeypatch.setattr(adm, "_discover_live_url", fake_discover)
+    monkeypatch.setattr(adm, "_gather_lifecycle_status", fake_gather)
+
+    status = await adm._current_status()
+    assert status.discoveredUrl is None
+    # Don't waste a probe when we're already healthy.
+    assert calls == []
+
+
+# ---------------------------------------------------------------------------
+# /logs — diagnostic mode for "container not found"
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_logs_reports_missing_container_with_hint(monkeypatch) -> None:
+    from gitpilot.sandbox_api import _StepResult
+
+    monkeypatch.setattr(adm, "_docker_available", lambda: True)
+
+    async def fake_run_shell(cmd, *, timeout=15):
+        if "logs" in cmd:
+            return _StepResult(
+                cmd=" ".join(cmd), exit_code=1, duration_ms=10,
+                stdout="", stderr='Error: No such container: gitpilot-matrixlab',
+            )
+        if cmd[:3] == ["docker", "ps", "-a"]:
+            # Two other matrixlab-shaped containers from older installs.
+            return _StepResult(
+                cmd=" ".join(cmd), exit_code=0, duration_ms=5,
+                stdout=(
+                    "matrixlab-runner\tUp 3 minutes\n"
+                    "old-matrixlab\tExited (137) 2 days ago\n"
+                    "unrelated-container\tUp 5 minutes\n"
+                ),
+                stderr="",
+            )
+        return _StepResult(cmd=" ".join(cmd), exit_code=0, duration_ms=0, stdout="", stderr="")
+
+    monkeypatch.setattr(adm, "_run_shell", fake_run_shell)
+
+    payload = await adm.matrixlab_logs(tail=50)
+    assert payload["ok"] is False
+    assert payload["errorCode"] == "CONTAINER_NOT_FOUND"
+    assert "make install-matrixlab" in payload["hint"]
+    # We surfaced exactly the matrixlab-shaped candidates, not the
+    # unrelated container.
+    names = " ".join(payload["candidates"])
+    assert "matrixlab-runner" in names
+    assert "old-matrixlab" in names
+    assert "unrelated-container" not in names
+
+
+@pytest.mark.asyncio
+async def test_logs_happy_path(monkeypatch) -> None:
+    from gitpilot.sandbox_api import _StepResult
+
+    monkeypatch.setattr(adm, "_docker_available", lambda: True)
+
+    async def fake_run_shell(cmd, *, timeout=15):
+        return _StepResult(
+            cmd=" ".join(cmd), exit_code=0, duration_ms=12,
+            stdout="line one\nline two\n", stderr="",
+        )
+
+    monkeypatch.setattr(adm, "_run_shell", fake_run_shell)
+
+    payload = await adm.matrixlab_logs(tail=10)
+    assert payload["ok"] is True
+    assert payload["lines"] == ["line one", "line two"]
+    assert payload["container"]  # surfaced for the UI badge
+
+
+@pytest.mark.asyncio
+async def test_logs_no_docker(monkeypatch) -> None:
+    monkeypatch.setattr(adm, "_docker_available", lambda: False)
+    payload = await adm.matrixlab_logs(tail=50)
+    assert payload["ok"] is False
+    assert payload["errorCode"] == "DOCKER_NOT_INSTALLED"
+    assert "make install-matrixlab" in payload["hint"]
diff --git a/tests/test_post_create_next_actions.py b/tests/test_post_create_next_actions.py
new file mode 100644
index 0000000..11d2012
--- /dev/null
+++ b/tests/test_post_create_next_actions.py
@@ -0,0 +1,105 @@
+"""After a plan creates/modifies runnable files, the executor should
+surface deterministic next_actions so the chat UI can offer one-click
+follow-ups ("Run demo.py", "Open in Canvas") without LLM round-tripping.
+
+These tests cover the helper logic that builds the next_actions list.
+The end-to-end executor is exercised in the wider integration suite;
+here we lock the contract so a refactor can't quietly drop the
+suggestions.
+"""
+
+from __future__ import annotations
+
+from gitpilot.agentic import _is_runnable_path
+
+
+def _build_next_actions(plan_steps):
+    """Mirror the inline logic in execute_plan() so we can test it in
+    isolation. Kept in sync with the function — any change there must
+    be reflected here and vice versa."""
+    next_actions = []
+    seen = set()
+    for step in plan_steps:
+        for pf in step.get("files", []) or []:
+            action = (pf.get("action") or "").upper()
+            path = pf.get("path")
+            if not path or path in seen:
+                continue
+            if action in {"CREATE", "MODIFY"} and _is_runnable_path(path):
+                seen.add(path)
+                next_actions.append({
+                    "kind": "run_file",
+                    "label": f"Prepare Run {path}",
+                    "payload": {"file": path},
+                })
+                next_actions.append({
+                    "kind": "open_workspace",
+                    "label": "Open Workspace",
+                    "payload": {"file": path},
+                })
+    return next_actions
+
+
+def test_create_runnable_python_emits_run_and_workspace() -> None:
+    actions = _build_next_actions([
+        {"files": [{"path": "demo.py", "action": "CREATE"}]},
+    ])
+    kinds = [a["kind"] for a in actions]
+    # Enterprise vocabulary: "Prepare Run" + "Open Workspace".
+    # "Canvas" is reserved for the runnable split-editor and lives in
+    # the overflow menu of the file preview.
+    assert kinds == ["run_file", "open_workspace"]
+    assert actions[0]["payload"]["file"] == "demo.py"
+    assert actions[0]["label"] == "Prepare Run demo.py"
+    assert actions[1]["label"] == "Open Workspace"
+
+
+def test_modify_runnable_also_emits_actions() -> None:
+    actions = _build_next_actions([
+        {"files": [{"path": "main.js", "action": "MODIFY"}]},
+    ])
+    assert any(a["kind"] == "run_file" for a in actions)
+
+
+def test_create_markdown_emits_no_actions() -> None:
+    actions = _build_next_actions([
+        {"files": [{"path": "README.md", "action": "CREATE"}]},
+    ])
+    assert actions == []
+
+
+def test_delete_runnable_emits_no_actions() -> None:
+    actions = _build_next_actions([
+        {"files": [{"path": "demo.py", "action": "DELETE"}]},
+    ])
+    assert actions == []
+
+
+def test_read_only_emits_no_actions() -> None:
+    actions = _build_next_actions([
+        {"files": [{"path": "demo.py", "action": "READ"}]},
+    ])
+    assert actions == []
+
+
+def test_dedup_across_steps() -> None:
+    """If the same file appears in two steps (e.g. CREATE then MODIFY in
+    a multi-pass plan), we only suggest the next_actions once."""
+    actions = _build_next_actions([
+        {"files": [{"path": "demo.py", "action": "CREATE"}]},
+        {"files": [{"path": "demo.py", "action": "MODIFY"}]},
+    ])
+    paths = [a["payload"]["file"] for a in actions]
+    assert paths.count("demo.py") == 2  # one run_file + one open_in_canvas
+    assert len(actions) == 2
+
+
+def test_multiple_runnable_files() -> None:
+    actions = _build_next_actions([
+        {"files": [
+            {"path": "a.py", "action": "CREATE"},
+            {"path": "b.sh", "action": "CREATE"},
+        ]},
+    ])
+    files = {a["payload"]["file"] for a in actions}
+    assert files == {"a.py", "b.sh"}
diff --git a/tests/test_sandbox_api.py b/tests/test_sandbox_api.py
index 4dae2be..7c2bee5 100644
--- a/tests/test_sandbox_api.py
+++ b/tests/test_sandbox_api.py
@@ -205,24 +205,38 @@ def _patched(*args, **kwargs):
     assert captured["body"]["code"] == "print('hi')"
 
 
-def test_lifecycle_mutating_endpoints_gated(client: TestClient) -> None:
-    """Without GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE, install/start/stop
-    must 403 — never silently execute docker on behalf of a browser
-    POST."""
+def test_lifecycle_mutating_endpoints_gated_when_explicitly_disabled(
+    client: TestClient, monkeypatch,
+) -> None:
+    """When GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE=0 is set, install/start/
+    stop must 403 — never silently execute docker on behalf of a browser
+    POST.  (Default is enabled; the env var is now an opt-OUT.)"""
+    monkeypatch.setenv("GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE", "0")
     for path in ("/api/sandbox/matrixlab/install",
                  "/api/sandbox/matrixlab/start",
                  "/api/sandbox/matrixlab/stop"):
         r = client.post(path)
-        assert r.status_code == 403, f"{path} must require the env flag"
+        assert r.status_code == 403, f"{path} must reject when explicitly disabled"
         assert "GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE" in r.json()["detail"]
 
 
 def test_lifecycle_status_always_safe(client: TestClient) -> None:
-    """GET /lifecycle is read-only; safe to call even when the env
-    flag is off.  Reports lifecycle_enabled=False so the UI can render
-    the right hint."""
+    """GET /lifecycle is read-only; safe to call regardless of the env
+    flag.  After the polarity flip the default is enabled, so a fresh
+    install should report lifecycle_enabled=True."""
     r = client.get("/api/sandbox/matrixlab/lifecycle")
     assert r.status_code == 200
     data = r.json()
-    assert data["lifecycle_enabled"] is False
-    assert "instructions" in data
+    assert data["lifecycle_enabled"] is True
+    assert "matrixlab_url" in data
+
+
+def test_lifecycle_status_reports_disabled_when_env_overrides(
+    client: TestClient, monkeypatch,
+) -> None:
+    """Operators who explicitly opt OUT via env still see the disabled
+    state in /lifecycle so the UI can render the right hint."""
+    monkeypatch.setenv("GITPILOT_ENABLE_MATRIXLAB_LIFECYCLE", "0")
+    r = client.get("/api/sandbox/matrixlab/lifecycle")
+    assert r.status_code == 200
+    assert r.json()["lifecycle_enabled"] is False
diff --git a/tests/test_sandbox_plan.py b/tests/test_sandbox_plan.py
new file mode 100644
index 0000000..9b5f6dd
--- /dev/null
+++ b/tests/test_sandbox_plan.py
@@ -0,0 +1,283 @@
+"""Tests for the deterministic ExecutionPlan builder.
+
+The contract: build_execution_plan_* must be pure (no I/O), return
+``None`` rather than raise on invalid input, and surface safety
+warnings that are stable across calls.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from gitpilot.sandbox_plan import (
+    ExecutionPlan,
+    SafetyWarning,
+    analyze_safety,
+    build_execution_plan_for_file,
+    build_execution_plan_for_inline,
+)
+
+
+# ---------------------------------------------------------------------------
+# Safety analyzer
+# ---------------------------------------------------------------------------
+
+
+def test_analyze_safety_flags_os_system() -> None:
+    warns = analyze_safety("import os\nos.system('rm -rf /')\n", "python")
+    labels = [w.label for w in warns]
+    assert any("os.system" in label or "exec" in label for label in labels)
+
+
+def test_analyze_safety_flags_network() -> None:
+    warns = analyze_safety("import requests\nrequests.get('https://x')\n", "python")
+    assert any("network" in w.label.lower() for w in warns)
+
+
+def test_analyze_safety_flags_plt_show() -> None:
+    warns = analyze_safety("import matplotlib.pyplot as plt\nplt.show()\n", "python")
+    assert any("plt.show" in w.label for w in warns)
+
+
+def test_analyze_safety_clean_code_returns_empty() -> None:
+    assert analyze_safety("print(2 + 2)", "python") == []
+
+
+def test_analyze_safety_orders_high_severity_first() -> None:
+    code = (
+        "import os\n"
+        "import requests\n"            # medium
+        "os.system('echo hi')\n"       # high
+        "open('/tmp/x','w').write('hi')\n"  # low
+    )
+    warns = analyze_safety(code, "python")
+    severities = [w.severity for w in warns]
+    assert severities[0] == "high"
+    # No "high" can appear after a "low"/"medium".
+    rank = {"high": 0, "medium": 1, "low": 2}
+    assert severities == sorted(severities, key=lambda s: rank[s])
+
+
+def test_analyze_safety_empty_input() -> None:
+    assert analyze_safety("", "python") == []
+    assert analyze_safety(None, "python") == []  # type: ignore[arg-type]
+
+
+# ---------------------------------------------------------------------------
+# File-run plan
+# ---------------------------------------------------------------------------
+
+
+def test_file_plan_happy_path() -> None:
+    plan = build_execution_plan_for_file(
+        file="demo.py",
+        repo_files=["demo.py", "README.md"],
+    )
+    assert plan is not None
+    assert plan.file == "demo.py"
+    assert plan.language == "python"
+    assert plan.command == ["python", "demo.py"]
+    assert plan.requires_approval is True
+    assert any("Network" in c.label for c in plan.safety_checks)
+    assert plan.inline_code is None
+
+
+def test_file_plan_rejects_missing_file() -> None:
+    assert build_execution_plan_for_file(
+        file="ghost.py", repo_files=["demo.py"]
+    ) is None
+
+
+def test_file_plan_rejects_non_runnable_extension() -> None:
+    assert build_execution_plan_for_file(
+        file="README.md", repo_files=["README.md"]
+    ) is None
+
+
+def test_file_plan_with_reader_attaches_warnings() -> None:
+    plan = build_execution_plan_for_file(
+        file="risky.py",
+        repo_files=["risky.py"],
+        file_reader=lambda _: "import requests\nrequests.get('https://x')\n",
+    )
+    assert plan is not None
+    assert any("network" in w.label.lower() for w in plan.safety_warnings)
+
+
+def test_file_plan_handles_reader_exception_gracefully() -> None:
+    def boom(_: str) -> str:
+        raise OSError("disk on fire")
+
+    plan = build_execution_plan_for_file(
+        file="demo.py",
+        repo_files=["demo.py"],
+        file_reader=boom,
+    )
+    assert plan is not None
+    assert plan.safety_warnings == []  # graceful degradation
+
+
+def test_file_plan_resolves_bash_and_node() -> None:
+    py = build_execution_plan_for_file(file="a.py", repo_files=["a.py"])
+    js = build_execution_plan_for_file(file="a.js", repo_files=["a.js"])
+    sh = build_execution_plan_for_file(file="a.sh", repo_files=["a.sh"])
+    assert py and py.command[0] == "python"
+    assert js and js.command[0] == "node"
+    assert sh and sh.command[0] == "bash"
+
+
+def test_file_plan_unique_plan_ids() -> None:
+    a = build_execution_plan_for_file(file="x.py", repo_files=["x.py"])
+    b = build_execution_plan_for_file(file="x.py", repo_files=["x.py"])
+    assert a is not None and b is not None
+    assert a.plan_id != b.plan_id
+
+
+# ---------------------------------------------------------------------------
+# Inline plan
+# ---------------------------------------------------------------------------
+
+
+def test_inline_plan_happy_path() -> None:
+    plan = build_execution_plan_for_inline(
+        code="print('hi')", language="python",
+    )
+    assert plan is not None
+    assert plan.file is None
+    assert plan.inline_code == "print('hi')"
+    assert plan.language == "python"
+    assert plan.command == ["python", "inline.py"]
+
+
+def test_inline_plan_normalizes_language_aliases() -> None:
+    for alias in ("py", "Python", "PYTHON3"):
+        plan = build_execution_plan_for_inline(code="x=1", language=alias)
+        assert plan is not None
+        assert plan.language == "python"
+
+
+def test_inline_plan_rejects_empty_code() -> None:
+    assert build_execution_plan_for_inline(code="", language="python") is None
+    assert build_execution_plan_for_inline(code="   \n\t  ", language="python") is None
+
+
+def test_inline_plan_rejects_unknown_language() -> None:
+    assert build_execution_plan_for_inline(code="puts 1", language="ruby") is None
+
+
+def test_inline_plan_carries_parent_run_id() -> None:
+    plan = build_execution_plan_for_inline(
+        code="print(1)", language="py", parent_run_id="run_abc",
+    )
+    assert plan is not None
+    assert plan.parent_run_id == "run_abc"
+
+
+def test_inline_plan_display_filename_overrides_inline_name() -> None:
+    """File-aware Canvas: when a real repo file is opened for editing,
+    the plan's displayed command should read ``python demo.py`` instead
+    of ``python inline.py``.  Pure cosmetic: execution itself still
+    runs the buffer bytes via the inline path."""
+    plan = build_execution_plan_for_inline(
+        code="print('hi')",
+        language="python",
+        display_filename="src/demo.py",
+    )
+    assert plan is not None
+    assert plan.command == ["python", "src/demo.py"]
+    # Safety check copy should also reflect the file context.
+    labels = " ".join(c.label for c in plan.safety_checks)
+    assert "src/demo.py" in labels
+
+
+def test_inline_plan_no_display_filename_falls_back_to_inline() -> None:
+    plan = build_execution_plan_for_inline(code="print(1)", language="python")
+    assert plan is not None
+    assert plan.command == ["python", "inline.py"]
+
+
+def test_inline_plan_empty_display_filename_falls_back_to_inline() -> None:
+    plan = build_execution_plan_for_inline(
+        code="print(1)", language="python", display_filename="  ",
+    )
+    assert plan is not None
+    assert plan.command == ["python", "inline.py"]
+
+
+def test_endpoint_inline_plan_uses_display_filename(client) -> None:
+    res = client.post(
+        "/api/sandbox/plan",
+        json={
+            "code": "print(1)", "language": "python",
+            "source": "canvas",
+            "display_filename": "demo.py",
+        },
+    )
+    assert res.status_code == 200, res.text
+    plan = res.json()["plan"]
+    assert plan["command"] == ["python", "demo.py"]
+
+
+def test_inline_plan_serializes_cleanly() -> None:
+    plan = build_execution_plan_for_inline(
+        code="import requests\nrequests.get('x')", language="python",
+    )
+    assert plan is not None
+    d = plan.to_dict()
+    assert isinstance(d["safety"]["warnings"], list)
+    assert d["requires_approval"] is True
+    assert d["command"] == ["python", "inline.py"]
+    assert d["inline_code"].startswith("import requests")
+
+
+# ---------------------------------------------------------------------------
+# Endpoint
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def client():
+    from fastapi import FastAPI
+    from fastapi.testclient import TestClient
+
+    from gitpilot.sandbox_api import router as sandbox_router
+
+    app = FastAPI()
+    app.include_router(sandbox_router)
+    return TestClient(app)
+
+
+def test_endpoint_file_plan(client) -> None:
+    res = client.post(
+        "/api/sandbox/plan",
+        json={"file": "demo.py", "repo_files": ["demo.py"], "source": "chat"},
+    )
+    assert res.status_code == 200, res.text
+    plan = res.json()["plan"]
+    assert plan["file"] == "demo.py"
+    assert plan["command"] == ["python", "demo.py"]
+    assert plan["requires_approval"] is True
+
+
+def test_endpoint_inline_plan(client) -> None:
+    res = client.post(
+        "/api/sandbox/plan",
+        json={"code": "print(1)", "language": "python", "source": "code_block"},
+    )
+    assert res.status_code == 200, res.text
+    plan = res.json()["plan"]
+    assert plan["inline_code"] == "print(1)"
+    assert plan["source"] == "code_block"
+
+
+def test_endpoint_rejects_missing_file(client) -> None:
+    res = client.post(
+        "/api/sandbox/plan",
+        json={"file": "ghost.py", "repo_files": ["demo.py"]},
+    )
+    assert res.status_code == 400
+
+
+def test_endpoint_rejects_empty_request(client) -> None:
+    res = client.post("/api/sandbox/plan", json={})
+    assert res.status_code == 400