diff --git a/.codex b/.codex
new file mode 100644
index 000000000..e69de29bb
diff --git a/.github/workflows/build-native.yml b/.github/workflows/build-native.yml
index 57efa21a2..2fd7d5563 100644
--- a/.github/workflows/build-native.yml
+++ b/.github/workflows/build-native.yml
@@ -77,8 +77,8 @@ jobs:
         if: runner.os != 'Windows'
         run: |
           mkdir -p artifacts
-          cp native/target/${{ matrix.target }}/release/libgsd_engine.dylib artifacts/gsd_engine.node 2>/dev/null || \
-          cp native/target/${{ matrix.target }}/release/libgsd_engine.so artifacts/gsd_engine.node 2>/dev/null || \
+          cp native/target/${{ matrix.target }}/release/libforge_engine.dylib artifacts/forge_engine.node 2>/dev/null || \
+          cp native/target/${{ matrix.target }}/release/libforge_engine.so artifacts/forge_engine.node 2>/dev/null || \
           { echo "::error::No library found for ${{ matrix.platform }}"; exit 1; }
           ls -la artifacts/
 
@@ -86,13 +86,13 @@ jobs:
         if: runner.os == 'Windows'
         run: |
           mkdir artifacts
-          copy native\target\${{ matrix.target }}\release\gsd_engine.dll artifacts\gsd_engine.node
+          copy native\target\${{ matrix.target }}\release\forge_engine.dll artifacts\forge_engine.node
 
       - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:
           name: native-${{ matrix.platform }}
-          path: artifacts/gsd_engine.node
+          path: artifacts/forge_engine.node
           if-no-files-found: error
 
   publish:
@@ -118,7 +118,7 @@ jobs:
       - name: Copy binaries to platform packages
         run: |
           for platform in darwin-arm64 darwin-x64 linux-x64-gnu linux-arm64-gnu win32-x64-msvc; do
-            cp "artifacts/native-${platform}/gsd_engine.node" "native/npm/${platform}/gsd_engine.node"
+            cp "artifacts/native-${platform}/forge_engine.node" "native/npm/${platform}/forge_engine.node"
             echo "Copied binary for ${platform}"
             ls -la "native/npm/${platform}/"
           done
diff --git a/flake.lock b/flake.lock
new file mode 100644
index 000000000..8da6f7b09
--- /dev/null
+++ b/flake.lock
@@ -0,0 +1,61 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1776067740,
+        "narHash": "sha256-B35lpsqnSZwn1Lmz06BpwF7atPgFmUgw1l8KAV3zpVQ=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "7e495b747b51f95ae15e74377c5ce1fe69c1765f",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-25.11",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}
diff --git a/flake.nix b/flake.nix
index ad5e05c52..66536d804 100644
--- a/flake.nix
+++ b/flake.nix
@@ -18,8 +18,13 @@
           packages = with pkgs; [
             bash
             bun
+            cargo
+            clippy
             git
             nodejs_24
+            rust-analyzer
+            rustc
+            rustfmt
           ];
 
           shellHook = ''
@@ -28,7 +33,9 @@
 
             echo "gsd-2 runtime shell"
             echo "  bun : $(command -v bun)"
+            echo "  cargo: $(command -v cargo)"
             echo "  node: $(command -v node)"
+            echo "  rustc: $(command -v rustc)"
           '';
         };
       });
diff --git a/native/crates/ast/Cargo.toml b/native/crates/ast/Cargo.toml
index 91647fb32..d0fc47d7a 100644
--- a/native/crates/ast/Cargo.toml
+++ b/native/crates/ast/Cargo.toml
@@ -1,5 +1,5 @@
 [package]
-name = "gsd-ast"
+name = "forge-ast"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
diff --git a/native/crates/ast/src/ast.rs b/native/crates/ast/src/ast.rs
index 8559af9f3..a648294cc 100644
--- a/native/crates/ast/src/ast.rs
+++ b/native/crates/ast/src/ast.rs
@@ -383,7 +383,7 @@ mod tests {
 	impl Drop for TempTree { fn drop(&mut self) { let _ = fs::remove_dir_all(&self.root); } }
 	fn make_temp_tree() -> TempTree {
 		let unique = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_nanos();
-		let root = std::env::temp_dir().join(format!("gsd-ast-test-{unique}"));
+		let root = std::env::temp_dir().join(format!("forge-ast-test-{unique}"));
 		fs::create_dir_all(root.join("nested")).unwrap();
 		fs::write(root.join("a.ts"), "const a = 1;\n").unwrap();
 		fs::write(root.join("nested").join("b.ts"), "const b = 2;\n").unwrap();
@@ -421,7 +421,7 @@ mod tests {
 	#[test]
 	fn rejects_mixed_replace_lang() {
 		let unique = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_nanos();
-		let root = std::env::temp_dir().join(format!("gsd-ast-mixed-{unique}"));
+		let root = std::env::temp_dir().join(format!("forge-ast-mixed-{unique}"));
 		fs::create_dir_all(&root).unwrap();
 		fs::write(root.join("a.ts"), "const a = 1;\n").unwrap();
 		fs::write(root.join("b.rs"), "fn main() {}\n").unwrap();
diff --git a/native/crates/engine/Cargo.toml b/native/crates/engine/Cargo.toml
index 20b39e349..6038b9e12 100644
--- a/native/crates/engine/Cargo.toml
+++ b/native/crates/engine/Cargo.toml
@@ -1,5 +1,5 @@
 [package]
-name = "gsd-engine"
+name = "forge-engine"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
@@ -13,8 +13,8 @@ test = false
 doctest = false
 
 [dependencies]
-gsd-ast = { path = "../ast" }
-gsd-grep = { path = "../grep" }
+forge-ast = { path = "../ast" }
+forge-grep = { path = "../grep" }
 arboard = "3"
 dashmap = "6"
 globset = "0.4"
diff --git a/native/crates/engine/src/ast.rs b/native/crates/engine/src/ast.rs
index 78570d939..e711cff59 100644
--- a/native/crates/engine/src/ast.rs
+++ b/native/crates/engine/src/ast.rs
@@ -1,2 +1,2 @@
-//! Forces the linker to include gsd_ast napi registrations.
-use gsd_ast as _;
+//! Forces the linker to include forge_ast napi registrations.
+use forge_ast as _;
diff --git a/native/crates/engine/src/grep.rs b/native/crates/engine/src/grep.rs
index cb4713c90..7cb28e290 100644
--- a/native/crates/engine/src/grep.rs
+++ b/native/crates/engine/src/grep.rs
@@ -1,13 +1,13 @@
 //! N-API bindings for the grep module.
 //!
-//! Wraps `gsd_grep` functions and exposes them as JS-callable N-API exports.
+//! Wraps `forge_grep` functions and exposes them as JS-callable N-API exports.
 
 use napi::bindgen_prelude::*;
 use napi_derive::napi;
 
 use crate::task;
 
-// ── N-API types (mirroring gsd_grep types for the JS boundary) ────────
+// ── N-API types (mirroring forge_grep types for the JS boundary) ────────
 
 #[napi(object)]
 pub struct NapiContextLine {
@@ -105,14 +105,14 @@ fn clamp_u32(value: u64) -> u32 {
     value.min(u32::MAX as u64) as u32
 }
 
-fn convert_context_line(cl: gsd_grep::ContextLine) -> NapiContextLine {
+fn convert_context_line(cl: forge_grep::ContextLine) -> NapiContextLine {
     NapiContextLine {
         line_number: clamp_u32(cl.line_number),
         line: cl.line,
     }
 }
 
-fn convert_search_match(m: gsd_grep::SearchMatch) -> NapiSearchMatch {
+fn convert_search_match(m: forge_grep::SearchMatch) -> NapiSearchMatch {
     NapiSearchMatch {
         line_number: clamp_u32(m.line_number),
         line: m.line,
@@ -130,7 +130,7 @@ fn convert_search_match(m: gsd_grep::SearchMatch) -> NapiSearchMatch {
     }
 }
 
-fn convert_file_match(m: gsd_grep::FileMatch) -> NapiGrepMatch {
+fn convert_file_match(m: forge_grep::FileMatch) -> NapiGrepMatch {
     NapiGrepMatch {
         path: m.path,
         line_number: clamp_u32(m.line_number),
@@ -157,7 +157,7 @@ fn convert_file_match(m: gsd_grep::FileMatch) -> NapiGrepMatch {
 /// and optional context lines.
 #[napi(js_name = "search")]
 pub fn search(content: Buffer, options: NapiSearchOptions) -> Result<NapiSearchResult> {
-    let opts = gsd_grep::SearchOptions {
+    let opts = forge_grep::SearchOptions {
         pattern: options.pattern,
         ignore_case: options.ignore_case.unwrap_or(false),
         multiline: options.multiline.unwrap_or(false),
@@ -167,7 +167,7 @@ pub fn search(content: Buffer, options: NapiSearchOptions) -> Result<NapiSearchR
         max_columns: options.max_columns.map(|v| v as usize),
     };
 
-    match gsd_grep::search_content(content.as_ref(), &opts) {
+    match forge_grep::search_content(content.as_ref(), &opts) {
         Ok(result) => Ok(NapiSearchResult {
             matches: result
                 .matches
@@ -188,7 +188,7 @@ pub fn search(content: Buffer, options: NapiSearchOptions) -> Result<NapiSearchR
 #[napi(js_name = "grep")]
 pub fn grep(options: NapiGrepOptions) -> task::Async<NapiGrepResult> {
     task::blocking("grep", (), move |_ct| {
-        let opts = gsd_grep::GrepOptions {
+        let opts = forge_grep::GrepOptions {
             pattern: options.pattern,
             path: options.path,
             glob: options.glob,
@@ -202,7 +202,7 @@ pub fn grep(options: NapiGrepOptions) -> task::Async<NapiGrepResult> {
             max_columns: options.max_columns.map(|v| v as usize),
         };
 
-        match gsd_grep::search_path(&opts) {
+        match forge_grep::search_path(&opts) {
             Ok(result) => Ok(NapiGrepResult {
                 matches: result.matches.into_iter().map(convert_file_match).collect(),
                 total_matches: clamp_u32(result.total_matches),
diff --git a/native/crates/grep/Cargo.toml b/native/crates/grep/Cargo.toml
index d77fb6faf..f7c422a2a 100644
--- a/native/crates/grep/Cargo.toml
+++ b/native/crates/grep/Cargo.toml
@@ -1,5 +1,5 @@
 [package]
-name = "gsd-grep"
+name = "forge-grep"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
diff --git a/native/npm/darwin-arm64/package.json b/native/npm/darwin-arm64/package.json
index 7d77c1d5d..f45d588fc 100644
--- a/native/npm/darwin-arm64/package.json
+++ b/native/npm/darwin-arm64/package.json
@@ -8,9 +8,9 @@
   "cpu": [
     "arm64"
   ],
-  "main": "gsd_engine.node",
+  "main": "forge_engine.node",
   "files": [
-    "gsd_engine.node"
+    "forge_engine.node"
   ],
   "license": "MIT",
   "repository": {
diff --git a/native/npm/darwin-x64/package.json b/native/npm/darwin-x64/package.json
index c0223f376..35c57d060 100644
--- a/native/npm/darwin-x64/package.json
+++ b/native/npm/darwin-x64/package.json
@@ -8,9 +8,9 @@
   "cpu": [
     "x64"
   ],
-  "main": "gsd_engine.node",
+  "main": "forge_engine.node",
   "files": [
-    "gsd_engine.node"
+    "forge_engine.node"
   ],
   "license": "MIT",
   "repository": {
diff --git a/native/npm/linux-arm64-gnu/package.json b/native/npm/linux-arm64-gnu/package.json
index 88cb0d0f2..bb5ba5131 100644
--- a/native/npm/linux-arm64-gnu/package.json
+++ b/native/npm/linux-arm64-gnu/package.json
@@ -8,9 +8,9 @@
   "cpu": [
     "arm64"
   ],
-  "main": "gsd_engine.node",
+  "main": "forge_engine.node",
   "files": [
-    "gsd_engine.node"
+    "forge_engine.node"
   ],
   "license": "MIT",
   "repository": {
diff --git a/native/npm/linux-x64-gnu/package.json b/native/npm/linux-x64-gnu/package.json
index 7f988b372..0d3d11d48 100644
--- a/native/npm/linux-x64-gnu/package.json
+++ b/native/npm/linux-x64-gnu/package.json
@@ -8,9 +8,9 @@
   "cpu": [
     "x64"
   ],
-  "main": "gsd_engine.node",
+  "main": "forge_engine.node",
   "files": [
-    "gsd_engine.node"
+    "forge_engine.node"
   ],
   "license": "MIT",
   "repository": {
diff --git a/native/npm/win32-x64-msvc/package.json b/native/npm/win32-x64-msvc/package.json
index 6954da721..fe4387e66 100644
--- a/native/npm/win32-x64-msvc/package.json
+++ b/native/npm/win32-x64-msvc/package.json
@@ -8,9 +8,9 @@
   "cpu": [
     "x64"
   ],
-  "main": "gsd_engine.node",
+  "main": "forge_engine.node",
   "files": [
-    "gsd_engine.node"
+    "forge_engine.node"
   ],
   "license": "MIT",
   "repository": {
diff --git a/native/scripts/build.js b/native/scripts/build.js
index 65d270a94..b6697fff2 100644
--- a/native/scripts/build.js
+++ b/native/scripts/build.js
@@ -27,7 +27,7 @@ const profile = isDev ? "debug" : "release";
 const cargoArgs = ["build"];
 if (!isDev) cargoArgs.push("--release");
 
-console.log(`Building gsd-engine (${profile})...`);
+console.log(`Building forge-engine (${profile})...`);
 
 try {
   execSync(`cargo ${cargoArgs.join(" ")}`, {
@@ -52,9 +52,9 @@ const targetDir = path.join(cargoTargetRoot, profile);
 const platformTag = `${process.platform}-${process.arch}`;
 
 const libraryNames = {
-  darwin: "libgsd_engine.dylib",
-  linux: "libgsd_engine.so",
-  win32: "gsd_engine.dll",
+  darwin: "libforge_engine.dylib",
+  linux: "libforge_engine.so",
+  win32: "forge_engine.dll",
 };
 
 const libName = libraryNames[process.platform];
@@ -72,8 +72,8 @@ if (!fs.existsSync(sourcePath)) {
 fs.mkdirSync(addonDir, { recursive: true });
 
 const destFilename = isDev
-  ? "gsd_engine.dev.node"
-  : `gsd_engine.${platformTag}.node`;
+  ? "forge_engine.dev.node"
+  : `forge_engine.${platformTag}.node`;
 const destPath = path.join(addonDir, destFilename);
 
 fs.copyFileSync(sourcePath, destPath);
diff --git a/packages/native/src/__tests__/clipboard.test.mjs b/packages/native/src/__tests__/clipboard.test.mjs
index 407b6bdc9..08b1154de 100644
--- a/packages/native/src/__tests__/clipboard.test.mjs
+++ b/packages/native/src/__tests__/clipboard.test.mjs
@@ -10,8 +10,8 @@ const require = createRequire(import.meta.url);
 const addonDir = path.resolve(__dirname, "..", "..", "..", "..", "native", "addon");
 const platformTag = `${process.platform}-${process.arch}`;
 const candidates = [
-  path.join(addonDir, `gsd_engine.${platformTag}.node`),
-  path.join(addonDir, "gsd_engine.dev.node"),
+  path.join(addonDir, `forge_engine.${platformTag}.node`),
+  path.join(addonDir, "forge_engine.dev.node"),
 ];
 
 let native;
diff --git a/packages/native/src/__tests__/diff.test.mjs b/packages/native/src/__tests__/diff.test.mjs
index a590f467f..3b20391b7 100644
--- a/packages/native/src/__tests__/diff.test.mjs
+++ b/packages/native/src/__tests__/diff.test.mjs
@@ -19,8 +19,8 @@ const addonDir = path.resolve(
 );
 const platformTag = `${process.platform}-${process.arch}`;
 const candidates = [
-  path.join(addonDir, `gsd_engine.${platformTag}.node`),
-  path.join(addonDir, "gsd_engine.dev.node"),
+  path.join(addonDir, `forge_engine.${platformTag}.node`),
+  path.join(addonDir, "forge_engine.dev.node"),
 ];
 
 let native;
diff --git a/packages/native/src/__tests__/fd.test.mjs b/packages/native/src/__tests__/fd.test.mjs
index a2ed59e17..b91af2a14 100644
--- a/packages/native/src/__tests__/fd.test.mjs
+++ b/packages/native/src/__tests__/fd.test.mjs
@@ -13,8 +13,8 @@ const require = createRequire(import.meta.url);
 const addonDir = path.resolve(__dirname, "..", "..", "..", "..", "native", "addon");
 const platformTag = `${process.platform}-${process.arch}`;
 const candidates = [
-  path.join(addonDir, `gsd_engine.${platformTag}.node`),
-  path.join(addonDir, "gsd_engine.dev.node"),
+  path.join(addonDir, `forge_engine.${platformTag}.node`),
+  path.join(addonDir, "forge_engine.dev.node"),
 ];
 
 let native;
diff --git a/packages/native/src/__tests__/glob.test.mjs b/packages/native/src/__tests__/glob.test.mjs
index a9784cf60..64719a225 100644
--- a/packages/native/src/__tests__/glob.test.mjs
+++ b/packages/native/src/__tests__/glob.test.mjs
@@ -21,8 +21,8 @@ const addonDir = path.resolve(
 );
 const platformTag = `${process.platform}-${process.arch}`;
 const candidates = [
-  path.join(addonDir, `gsd_engine.${platformTag}.node`),
-  path.join(addonDir, "gsd_engine.dev.node"),
+  path.join(addonDir, `forge_engine.${platformTag}.node`),
+  path.join(addonDir, "forge_engine.dev.node"),
 ];
 
 let native;
diff --git a/packages/native/src/__tests__/grep.test.mjs b/packages/native/src/__tests__/grep.test.mjs
index 0f3c200f7..ff8a2a828 100644
--- a/packages/native/src/__tests__/grep.test.mjs
+++ b/packages/native/src/__tests__/grep.test.mjs
@@ -13,8 +13,8 @@ const require = createRequire(import.meta.url);
 const addonDir = path.resolve(__dirname, "..", "..", "..", "..", "native", "addon");
 const platformTag = `${process.platform}-${process.arch}`;
 const candidates = [
-  path.join(addonDir, `gsd_engine.${platformTag}.node`),
-  path.join(addonDir, "gsd_engine.dev.node"),
+  path.join(addonDir, `forge_engine.${platformTag}.node`),
+  path.join(addonDir, "forge_engine.dev.node"),
 ];
 
 let native;
diff --git a/packages/native/src/__tests__/highlight.test.mjs b/packages/native/src/__tests__/highlight.test.mjs
index 286821b22..f6cda9c28 100644
--- a/packages/native/src/__tests__/highlight.test.mjs
+++ b/packages/native/src/__tests__/highlight.test.mjs
@@ -11,8 +11,8 @@ const require = createRequire(import.meta.url);
 const addonDir = path.resolve(__dirname, "..", "..", "..", "..", "native", "addon");
 const platformTag = `${process.platform}-${process.arch}`;
 const candidates = [
-  path.join(addonDir, `gsd_engine.${platformTag}.node`),
-  path.join(addonDir, "gsd_engine.dev.node"),
+  path.join(addonDir, `forge_engine.${platformTag}.node`),
+  path.join(addonDir, "forge_engine.dev.node"),
 ];
 
 let native;
diff --git a/packages/native/src/__tests__/html.test.mjs b/packages/native/src/__tests__/html.test.mjs
index 7a9424a79..4f1d70330 100644
--- a/packages/native/src/__tests__/html.test.mjs
+++ b/packages/native/src/__tests__/html.test.mjs
@@ -10,8 +10,8 @@ const require = createRequire(import.meta.url);
 const addonDir = path.resolve(__dirname, "..", "..", "..", "..", "native", "addon");
 const platformTag = `${process.platform}-${process.arch}`;
 const candidates = [
-  path.join(addonDir, `gsd_engine.${platformTag}.node`),
-  path.join(addonDir, "gsd_engine.dev.node"),
+  path.join(addonDir, `forge_engine.${platformTag}.node`),
+  path.join(addonDir, "forge_engine.dev.node"),
 ];
 
 let native;
diff --git a/packages/native/src/__tests__/image.test.mjs b/packages/native/src/__tests__/image.test.mjs
index b560507b4..45da73403 100644
--- a/packages/native/src/__tests__/image.test.mjs
+++ b/packages/native/src/__tests__/image.test.mjs
@@ -11,8 +11,8 @@ const require = createRequire(import.meta.url);
 const addonDir = path.resolve(__dirname, "..", "..", "..", "..", "native", "addon");
 const platformTag = `${process.platform}-${process.arch}`;
 const candidates = [
-  path.join(addonDir, `gsd_engine.${platformTag}.node`),
-  path.join(addonDir, "gsd_engine.dev.node"),
+  path.join(addonDir, `forge_engine.${platformTag}.node`),
+  path.join(addonDir, "forge_engine.dev.node"),
 ];
 
 let native;
diff --git a/packages/native/src/__tests__/json-parse.test.mjs b/packages/native/src/__tests__/json-parse.test.mjs
index 19c16e75f..ed05ef8de 100644
--- a/packages/native/src/__tests__/json-parse.test.mjs
+++ b/packages/native/src/__tests__/json-parse.test.mjs
@@ -10,8 +10,8 @@ const require = createRequire(import.meta.url);
 const addonDir = path.resolve(__dirname, "..", "..", "..", "..", "native", "addon");
 const platformTag = `${process.platform}-${process.arch}`;
 const candidates = [
-  path.join(addonDir, `gsd_engine.${platformTag}.node`),
-  path.join(addonDir, "gsd_engine.dev.node"),
+  path.join(addonDir, `forge_engine.${platformTag}.node`),
+  path.join(addonDir, "forge_engine.dev.node"),
 ];
 
 let native;
diff --git a/packages/native/src/__tests__/ps.test.mjs b/packages/native/src/__tests__/ps.test.mjs
index 0730f8d00..4ab57e237 100644
--- a/packages/native/src/__tests__/ps.test.mjs
+++ b/packages/native/src/__tests__/ps.test.mjs
@@ -12,8 +12,8 @@ const require = createRequire(import.meta.url);
 const addonDir = path.resolve(__dirname, "..", "..", "..", "..", "native", "addon");
 const platformTag = `${process.platform}-${process.arch}`;
 const candidates = [
-  path.join(addonDir, `gsd_engine.${platformTag}.node`),
-  path.join(addonDir, "gsd_engine.dev.node"),
+  path.join(addonDir, `forge_engine.${platformTag}.node`),
+  path.join(addonDir, "forge_engine.dev.node"),
 ];
 
 let native;
diff --git a/packages/native/src/__tests__/text.test.mjs b/packages/native/src/__tests__/text.test.mjs
index c9f635bc0..130d094bc 100644
--- a/packages/native/src/__tests__/text.test.mjs
+++ b/packages/native/src/__tests__/text.test.mjs
@@ -19,8 +19,8 @@ const addonDir = path.resolve(
 );
 const platformTag = `${process.platform}-${process.arch}`;
 const candidates = [
-  path.join(addonDir, `gsd_engine.${platformTag}.node`),
-  path.join(addonDir, "gsd_engine.dev.node"),
+  path.join(addonDir, `forge_engine.${platformTag}.node`),
+  path.join(addonDir, "forge_engine.dev.node"),
 ];
 
 let native;
diff --git a/packages/native/src/__tests__/truncate.test.mjs b/packages/native/src/__tests__/truncate.test.mjs
index 07a79463e..e33c16d71 100644
--- a/packages/native/src/__tests__/truncate.test.mjs
+++ b/packages/native/src/__tests__/truncate.test.mjs
@@ -10,8 +10,8 @@ const require = createRequire(import.meta.url);
 const addonDir = path.resolve(__dirname, "..", "..", "..", "..", "native", "addon");
 const platformTag = `${process.platform}-${process.arch}`;
 const candidates = [
-  path.join(addonDir, `gsd_engine.${platformTag}.node`),
-  path.join(addonDir, "gsd_engine.dev.node"),
+  path.join(addonDir, `forge_engine.${platformTag}.node`),
+  path.join(addonDir, "forge_engine.dev.node"),
 ];
 
 let native;
diff --git a/packages/native/src/__tests__/ttsr.test.mjs b/packages/native/src/__tests__/ttsr.test.mjs
index 7a1e29085..912ee442c 100644
--- a/packages/native/src/__tests__/ttsr.test.mjs
+++ b/packages/native/src/__tests__/ttsr.test.mjs
@@ -11,8 +11,8 @@ const require = createRequire(import.meta.url);
 const addonDir = path.resolve(__dirname, "..", "..", "..", "..", "native", "addon");
 const platformTag = `${process.platform}-${process.arch}`;
 const candidates = [
-  path.join(addonDir, `gsd_engine.${platformTag}.node`),
-  path.join(addonDir, "gsd_engine.dev.node"),
+  path.join(addonDir, `forge_engine.${platformTag}.node`),
+  path.join(addonDir, "forge_engine.dev.node"),
 ];
 
 let native;
diff --git a/packages/native/src/native.ts b/packages/native/src/native.ts
index b22a17a3f..a2b0083f9 100644
--- a/packages/native/src/native.ts
+++ b/packages/native/src/native.ts
@@ -4,8 +4,8 @@
  * Locates and loads the compiled Rust N-API addon (`.node` file).
  * Resolution order:
  *   1. @singularity-forge/engine-{platform} npm optional dependency (production install)
- *   2. native/addon/gsd_engine.{platform}.node (local release build)
- *   3. native/addon/gsd_engine.dev.node (local debug build)
+ *   2. native/addon/forge_engine.{platform}.node (local release build)
+ *   3. native/addon/forge_engine.dev.node (local debug build)
  */
 
 import * as path from "node:path";
@@ -44,8 +44,8 @@ function loadNative(): Record<string, unknown> {
     }
   }
 
-  // 2. Try local release build (native/addon/gsd_engine.{platform}.node)
-  const releasePath = path.join(addonDir, `gsd_engine.${platformTag}.node`);
+  // 2. Try local release build (native/addon/forge_engine.{platform}.node)
+  const releasePath = path.join(addonDir, `forge_engine.${platformTag}.node`);
   try {
     _loadedSuccessfully = true; return _require(releasePath) as Record<string, unknown>;
   } catch (err) {
@@ -53,8 +53,8 @@ function loadNative(): Record<string, unknown> {
     errors.push(`${releasePath}: ${message}`);
   }
 
-  // 3. Try local dev build (native/addon/gsd_engine.dev.node)
-  const devPath = path.join(addonDir, "gsd_engine.dev.node");
+  // 3. Try local dev build (native/addon/forge_engine.dev.node)
+  const devPath = path.join(addonDir, "forge_engine.dev.node");
   try {
     _loadedSuccessfully = true; return _require(devPath) as Record<string, unknown>;
   } catch (err) {
@@ -70,7 +70,7 @@ function loadNative(): Record<string, unknown> {
   // entire import chain at startup (#1223). Consumers with JS fallbacks
   // (parseRoadmap, parsePlan, fuzzyFind, etc.) catch these and degrade gracefully.
   process.stderr.write(
-    `[gsd] Native addon not available for ${platformTag}. Falling back to JS implementations (slower).\n` +
+    `[forge] Native addon not available for ${platformTag}. Falling back to JS implementations (slower).\n` +
       `  Supported native platforms: ${supportedPlatforms.join(", ")}\n`,
   );
   return new Proxy({} as Record<string, unknown>, {
diff --git a/scripts/build-web-if-stale.cjs b/scripts/build-web-if-stale.cjs
index bd9e828d4..10bf5fa4e 100644
--- a/scripts/build-web-if-stale.cjs
+++ b/scripts/build-web-if-stale.cjs
@@ -19,7 +19,7 @@ const { join, resolve } = require('node:path')
 
 // Skip on Windows — Next.js webpack build hits EPERM scanning system dirs
 if (process.platform === 'win32') {
-  console.log('[gsd] Web build skipped on Windows.')
+  console.log('[forge] Web build skipped on Windows.')
   process.exit(0)
 }
 
@@ -83,7 +83,7 @@ function ensureWebBuildDependencies() {
     return
   }
 
-  console.log('[gsd] Web build dependencies are missing or incomplete — running npm --prefix web ci...')
+  console.log('[forge] Web build dependencies are missing or incomplete — running npm --prefix web ci...')
   execSync('npm --prefix web ci', { cwd: root, stdio: 'inherit' })
 }
 
@@ -91,20 +91,20 @@ const sourceMtime = Math.max(newestMtime(webRoot), newestMtime(srcRoot))
 const builtMtime = sentinelMtime()
 
 if (builtMtime > 0 && builtMtime >= sourceMtime) {
-  console.log('[gsd] Web build is up-to-date, skipping rebuild.')
+  console.log('[forge] Web build is up-to-date, skipping rebuild.')
   process.exit(0)
 }
 
 if (builtMtime === 0) {
-  console.log('[gsd] No staged web build found — building now...')
+  console.log('[forge] No staged web build found — building now...')
 } else {
-  console.log('[gsd] Web/src source has changed since last build — rebuilding...')
+  console.log('[forge] Web/src source has changed since last build — rebuilding...')
 }
 
 try {
   ensureWebBuildDependencies()
   execSync('npm run build:web-host', { cwd: root, stdio: 'inherit' })
 } catch (err) {
-  console.error('[gsd] Web build failed:', err.message)
+  console.error('[forge] Web build failed:', err.message)
   process.exit(1)
 }
diff --git a/scripts/dev-cli.js b/scripts/dev-cli.js
index fd4ec0a0c..fdeb26791 100644
--- a/scripts/dev-cli.js
+++ b/scripts/dev-cli.js
@@ -20,7 +20,7 @@ const child = spawn(
 )
 
 child.on('error', (error) => {
-  console.error(`[gsd] Failed to launch local dev CLI: ${error instanceof Error ? error.message : String(error)}`)
+  console.error(`[forge] Failed to launch local dev CLI: ${error instanceof Error ? error.message : String(error)}`)
   process.exit(1)
 })
 
diff --git a/scripts/postinstall.js b/scripts/postinstall.js
index 2e4b39776..95a0336e6 100644
--- a/scripts/postinstall.js
+++ b/scripts/postinstall.js
@@ -36,7 +36,7 @@ function run(cmd) {
 }
 
 function logWarn(message) {
-  process.stderr.write(`[gsd] postinstall: ${message}\n`)
+  process.stderr.write(`[forge] postinstall: ${message}\n`)
 }
 
 function resolveAssetName() {
diff --git a/scripts/stage-web-standalone.cjs b/scripts/stage-web-standalone.cjs
index 85800473b..8f87799ae 100644
--- a/scripts/stage-web-standalone.cjs
+++ b/scripts/stage-web-standalone.cjs
@@ -43,7 +43,7 @@ function overlayNodePty(targetRoot) {
 }
 
 if (!existsSync(standaloneAppRoot)) {
-  console.error('[gsd] Web standalone build not found at web/.next/standalone/web. Run `npm --prefix web run build` first.')
+  console.error('[forge] Web standalone build not found at web/.next/standalone/web. Run `npm --prefix web run build` first.')
   process.exit(1)
 }
 
@@ -67,7 +67,7 @@ if (existsSync(publicRoot)) {
 
 const hydratedTargets = overlayNodePty(distStandaloneRoot)
 
-console.log(`[gsd] Staged web standalone host at ${distStandaloneRoot}`)
+console.log(`[forge] Staged web standalone host at ${distStandaloneRoot}`)
 if (hydratedTargets.length > 0) {
-  console.log(`[gsd] Hydrated node-pty native assets in ${hydratedTargets.length} location(s).`)
+  console.log(`[forge] Hydrated node-pty native assets in ${hydratedTargets.length} location(s).`)
 }
diff --git a/src/cli-web-branch.ts b/src/cli-web-branch.ts
index a4afe765b..ab950f187 100644
--- a/src/cli-web-branch.ts
+++ b/src/cli-web-branch.ts
@@ -122,7 +122,7 @@ export function migrateLegacyFlatSessions(baseSessionsDir: string, projectSessio
 
 function emitWebModeFailure(stderr: WritableLike, status: WebModeLaunchStatus): void {
   if (status.ok) return
-  stderr.write(`[gsd] Web mode launch failed: ${status.failureReason}\n`)
+  stderr.write(`[forge] Web mode launch failed: ${status.failureReason}\n`)
 }
 
 /**
@@ -249,7 +249,7 @@ export async function runWebCliBranch(
     currentCwd = resolve(defaultCwd, webPath)
     const checkExists = existsSync
     if (!checkExists(currentCwd)) {
-      stderr.write(`[gsd] Project path does not exist: ${currentCwd}\n`)
+      stderr.write(`[forge] Project path does not exist: ${currentCwd}\n`)
       return {
         handled: true,
         exitCode: 1,
@@ -270,7 +270,7 @@ export async function runWebCliBranch(
         launchInputs: { cwd: currentCwd, projectSessionsDir: '', agentDir: deps.agentDir ?? defaultAgentDir },
       }
     }
-    stderr.write(`[gsd] Using project path: ${currentCwd}\n`)
+    stderr.write(`[forge] Using project path: ${currentCwd}\n`)
   } else {
     currentCwd = defaultCwd
   }
diff --git a/src/cli.ts b/src/cli.ts
index 846280a07..4d34274d3 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -681,7 +681,7 @@ if (!cliFlags.worktree && !isPrintMode) {
 // which handles non-interactive output gracefully.
 // ---------------------------------------------------------------------------
 if (cliFlags.messages[0] === 'auto' && !process.stdout.isTTY) {
-  process.stderr.write('[gsd] stdout is not a terminal — running auto-mode in headless mode.\n')
+  process.stderr.write('[forge] stdout is not a terminal — running auto-mode in headless mode.\n')
   await runHeadlessFromAuto(cliFlags.messages.slice(1))
 }
 
diff --git a/src/headless-ui.ts b/src/headless-ui.ts
index 16a904d77..0e25cd4e8 100644
--- a/src/headless-ui.ts
+++ b/src/headless-ui.ts
@@ -303,8 +303,8 @@ export function formatProgress(event: Record<string, unknown>, ctx: ProgressCont
         // Bold important notifications
         const isImportant = /^(committed:|verification gate:|milestone|blocked:)/i.test(msg)
         return isImportant
-          ? `${c.bold}[gsd]     ${msg}${c.reset}`
-          : `[gsd]     ${msg}`
+          ? `${c.bold}[forge]     ${msg}${c.reset}`
+          : `[forge]     ${msg}`
       }
 
       if (method === 'setStatus') {
diff --git a/src/mcp-server.ts b/src/mcp-server.ts
index ee24b547e..1dbfd8b10 100644
--- a/src/mcp-server.ts
+++ b/src/mcp-server.ts
@@ -134,5 +134,5 @@ export async function startMcpServer(options: {
   // Connect to stdin/stdout transport
   const transport = new StdioServerTransport()
   await server.connect(transport)
-  process.stderr.write(`[gsd] MCP server started (v${version})\n`)
+  process.stderr.write(`[forge] MCP server started (v${version})\n`)
 }
diff --git a/src/onboarding.ts b/src/onboarding.ts
index 7e4086b26..262cd0546 100644
--- a/src/onboarding.ts
+++ b/src/onboarding.ts
@@ -107,7 +107,7 @@ async function loadClack(): Promise<ClackModule> {
   try {
     return await import('@clack/prompts')
   } catch {
-    throw new Error('[gsd] @clack/prompts not found — onboarding wizard requires this dependency')
+    throw new Error('[forge] @clack/prompts not found — onboarding wizard requires this dependency')
   }
 }
 
@@ -220,7 +220,7 @@ export async function runOnboarding(authStorage: AuthStorage): Promise<void> {
     ;[p, pc] = await Promise.all([loadClack(), loadPico()])
   } catch (err) {
     // If clack isn't available, fall back silently — don't block boot
-    process.stderr.write(`[gsd] Onboarding wizard unavailable: ${err instanceof Error ? err.message : String(err)}\n`)
+    process.stderr.write(`[forge] Onboarding wizard unavailable: ${err instanceof Error ? err.message : String(err)}\n`)
     return
   }
 
diff --git a/src/pi-migration.ts b/src/pi-migration.ts
index 704fd69b5..d5571783d 100644
--- a/src/pi-migration.ts
+++ b/src/pi-migration.ts
@@ -50,7 +50,7 @@ export function migratePiCredentials(authStorage: AuthStorage): boolean {
       authStorage.set(providerId, credential)
       const isLlm = LLM_PROVIDER_IDS.includes(providerId)
       if (isLlm) migratedLlm = true
-      process.stderr.write(`[gsd] Migrated ${isLlm ? 'LLM provider' : 'credential'}: ${providerId} (from Pi)\n`)
+      process.stderr.write(`[forge] Migrated ${isLlm ? 'LLM provider' : 'credential'}: ${providerId} (from Pi)\n`)
     }
 
     return migratedLlm
diff --git a/src/resource-loader.ts b/src/resource-loader.ts
index b36c18c72..870d1cf20 100644
--- a/src/resource-loader.ts
+++ b/src/resource-loader.ts
@@ -352,7 +352,7 @@ function reconcileSymlink(link: string, target: string): void {
   try {
     symlinkSync(target, link, 'junction')
   } catch (err) {
-    console.error(`[gsd] WARN: Failed to symlink ${link} → ${target}: ${err instanceof Error ? err.message : err}`)
+    console.error(`[forge] WARN: Failed to symlink ${link} → ${target}: ${err instanceof Error ? err.message : err}`)
   }
 }
 
@@ -397,7 +397,7 @@ function reconcileMergedNodeModules(
       try { symlinkSync(join(hoisted, entry.name), join(agentNodeModules, entry.name), 'junction'); linkedCount++ } catch { /* skip individual */ }
     }
   } catch (err) {
-    console.error(`[gsd] WARN: Failed to read hoisted node_modules at ${hoisted}: ${err instanceof Error ? err.message : err}`)
+    console.error(`[forge] WARN: Failed to read hoisted node_modules at ${hoisted}: ${err instanceof Error ? err.message : err}`)
   }
 
   // Overlay internal node_modules entries that weren't hoisted.
@@ -412,7 +412,7 @@ function reconcileMergedNodeModules(
       try { symlinkSync(join(internal, entry.name), link, 'junction'); linkedCount++ } catch { /* skip individual */ }
     }
   } catch (err) {
-    console.error(`[gsd] WARN: Failed to read internal node_modules at ${internal}: ${err instanceof Error ? err.message : err}`)
+    console.error(`[forge] WARN: Failed to read internal node_modules at ${internal}: ${err instanceof Error ? err.message : err}`)
   }
 
   // Only stamp marker if we actually linked something — avoids caching a broken state
diff --git a/src/resources/extensions/gsd/activity-log.ts b/src/resources/extensions/gsd/activity-log.ts
index f9155d967..889b92758 100644
--- a/src/resources/extensions/gsd/activity-log.ts
+++ b/src/resources/extensions/gsd/activity-log.ts
@@ -17,7 +17,7 @@ const SEQ_PREFIX_RE = /^(\d+)-/;
 import type { ExtensionContext } from "@sf-run/pi-coding-agent";
 import { gsdRoot } from "./paths.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
-import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
+import { isAuditEnvelopeEnabled } from "./uok/audit-toggle.js";
 
 interface ActivityLogState {
   nextSeq: number;
@@ -135,7 +135,7 @@ export function saveActivityLog(
     state.nextSeq += 1;
     state.lastSnapshotKeyByUnit.set(unitKey, key);
 
-    if (isUnifiedAuditEnabled()) {
+    if (isAuditEnvelopeEnabled()) {
       emitUokAuditEvent(
         basePath,
         buildAuditEnvelope({
diff --git a/src/resources/extensions/gsd/auto-start.ts b/src/resources/extensions/gsd/auto-start.ts
index 696709359..4ec3b3932 100644
--- a/src/resources/extensions/gsd/auto-start.ts
+++ b/src/resources/extensions/gsd/auto-start.ts
@@ -489,8 +489,8 @@ export async function bootstrapAutoSession(
     // Route to the interactive discussion handler instead of falling through to
     // auto-mode, which would immediately stop with "needs discussion".
     if (hasSurvivorBranch && state.phase === "needs-discussion") {
-      const { showSmartEntry } = await import("./guided-flow.js");
-      await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
+      const { showWorkflowEntry } = await import("./guided-flow.js");
+      await showWorkflowEntry(ctx, pi, base, { step: requestedStepMode });
 
       invalidateAllCaches();
       const postState = await deriveState(base);
@@ -547,8 +547,8 @@ export async function bootstrapAutoSession(
           return releaseLockAndReturn();
         }
 
-        const { showSmartEntry } = await import("./guided-flow.js");
-        await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
+        const { showWorkflowEntry } = await import("./guided-flow.js");
+        await showWorkflowEntry(ctx, pi, base, { step: requestedStepMode });
 
         invalidateAllCaches();
         const postState = await deriveState(base);
@@ -589,8 +589,8 @@ export async function bootstrapAutoSession(
         const contextFile = resolveMilestoneFile(base, mid, "CONTEXT");
         const hasContext = !!(contextFile && (await loadFile(contextFile)));
         if (!hasContext) {
-          const { showSmartEntry } = await import("./guided-flow.js");
-          await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
+          const { showWorkflowEntry } = await import("./guided-flow.js");
+          await showWorkflowEntry(ctx, pi, base, { step: requestedStepMode });
 
           invalidateAllCaches();
           const postState = await deriveState(base);
@@ -608,8 +608,8 @@ export async function bootstrapAutoSession(
 
       // Active milestone has CONTEXT-DRAFT but no full context — needs discussion
       if (state.phase === "needs-discussion") {
-        const { showSmartEntry } = await import("./guided-flow.js");
-        await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
+        const { showWorkflowEntry } = await import("./guided-flow.js");
+        await showWorkflowEntry(ctx, pi, base, { step: requestedStepMode });
 
         invalidateAllCaches();
         const postState = await deriveState(base);
@@ -630,8 +630,8 @@ export async function bootstrapAutoSession(
 
     // Unreachable safety check
     if (!state.activeMilestone) {
-      const { showSmartEntry } = await import("./guided-flow.js");
-      await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
+      const { showWorkflowEntry } = await import("./guided-flow.js");
+      await showWorkflowEntry(ctx, pi, base, { step: requestedStepMode });
       return releaseLockAndReturn();
     }
 
diff --git a/src/resources/extensions/gsd/auto/phases.ts b/src/resources/extensions/gsd/auto/phases.ts
index d093edd10..5dafb1293 100644
--- a/src/resources/extensions/gsd/auto/phases.ts
+++ b/src/resources/extensions/gsd/auto/phases.ts
@@ -48,7 +48,7 @@ import { withTimeout, FINALIZE_PRE_TIMEOUT_MS, FINALIZE_POST_TIMEOUT_MS } from "
 import { getEligibleSlices } from "../slice-parallel-eligibility.js";
 import { startSliceParallel } from "../slice-parallel-orchestrator.js";
 import { isDbAvailable, getMilestoneSlices } from "../gsd-db.js";
-import { ensurePlanV2Graph } from "../uok/plan-v2.js";
+import { ensurePlanV2Graph as ensurePlanningFlowGraph } from "../uok/plan-v2.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { UokGateRunner } from "../uok/gate-runner.js";
 import { resetEvidence } from "../safety/evidence-collector.js";
@@ -84,15 +84,15 @@ export function _resolveDispatchGuardBasePath(
   return s.originalBasePath || s.basePath;
 }
 
-const PLAN_V2_GATE_PHASES: ReadonlySet<Phase> = new Set([
+const PLANNING_FLOW_GATE_PHASES: ReadonlySet<Phase> = new Set([
   "executing",
   "summarizing",
   "validating-milestone",
   "completing-milestone",
 ]);
 
-function shouldRunPlanV2Gate(phase: Phase): boolean {
-  return PLAN_V2_GATE_PHASES.has(phase);
+function shouldRunPlanningFlowGate(phase: Phase): boolean {
+  return PLANNING_FLOW_GATE_PHASES.has(phase);
 }
 
 function shouldSkipArtifactVerification(unitType: string): boolean {
@@ -404,29 +404,30 @@ export async function runPreDispatch(
 
   // Derive state
   let state = await deps.deriveState(s.basePath);
-  if (prefs?.uok?.plan_v2?.enabled && shouldRunPlanV2Gate(state.phase)) {
-    const compiled = ensurePlanV2Graph(s.basePath, state);
+  const planningFlowEnabled = prefs?.uok?.planning_flow?.enabled === true || prefs?.uok?.plan_v2?.enabled === true;
+  if (planningFlowEnabled && shouldRunPlanningFlowGate(state.phase)) {
+    const compiled = ensurePlanningFlowGraph(s.basePath, state);
     if (!compiled.ok) {
-      const reason = compiled.reason ?? "Plan v2 compilation failed";
+      const reason = compiled.reason ?? "Planning flow compilation failed";
       await runPreDispatchGate({
-        gateId: "plan-v2-gate",
+        gateId: "planning-flow-gate",
         gateType: "policy",
         outcome: "manual-attention",
         failureClass: "manual-attention",
-        rationale: "plan v2 compile gate failed",
+        rationale: "planning flow compile gate failed",
         findings: reason,
         milestoneId: state.activeMilestone?.id ?? undefined,
       });
       ctx.ui.notify(`Plan gate failed-closed: ${reason}`, "error");
       await deps.pauseAuto(ctx, pi);
-      return { action: "break", reason: "plan-v2-gate-failed" };
+      return { action: "break", reason: "planning-flow-gate-failed" };
     }
     await runPreDispatchGate({
-      gateId: "plan-v2-gate",
+      gateId: "planning-flow-gate",
       gateType: "policy",
       outcome: "pass",
       failureClass: "none",
-      rationale: "plan v2 compile gate passed",
+      rationale: "planning flow compile gate passed",
       milestoneId: state.activeMilestone?.id ?? undefined,
     });
   }
diff --git a/src/resources/extensions/gsd/bootstrap/crash-log.ts b/src/resources/extensions/gsd/bootstrap/crash-log.ts
index 61278f173..da87c3b61 100644
--- a/src/resources/extensions/gsd/bootstrap/crash-log.ts
+++ b/src/resources/extensions/gsd/bootstrap/crash-log.ts
@@ -21,7 +21,7 @@ export function writeCrashLog(err: Error, source: string): void {
     const ts = new Date().toISOString().replace(/[:.]/g, "-");
     const logPath = join(crashDir, `${ts}.log`);
     const lines = [
-      `[gsd] ${source}: ${err.message}`,
+      `[forge] ${source}: ${err.message}`,
       `timestamp: ${new Date().toISOString()}`,
       `pid: ${process.pid}`,
       err.stack ?? "(no stack trace available)",
diff --git a/src/resources/extensions/gsd/bootstrap/register-extension.ts b/src/resources/extensions/gsd/bootstrap/register-extension.ts
index fad1dfc15..4108f7b20 100644
--- a/src/resources/extensions/gsd/bootstrap/register-extension.ts
+++ b/src/resources/extensions/gsd/bootstrap/register-extension.ts
@@ -22,11 +22,11 @@ export function handleRecoverableExtensionProcessError(err: Error): boolean {
   if ((err as NodeJS.ErrnoException).code === "ENOENT") {
     const syscall = (err as NodeJS.ErrnoException).syscall;
     if (syscall?.startsWith("spawn")) {
-      process.stderr.write(`[gsd] spawn ENOENT: ${(err as any).path ?? "unknown"} — command not found\n`);
+      process.stderr.write(`[forge] spawn ENOENT: ${(err as any).path ?? "unknown"} — command not found\n`);
       return true;
     }
     if (syscall === "uv_cwd") {
-      process.stderr.write(`[gsd] ENOENT (${syscall}): ${err.message}\n`);
+      process.stderr.write(`[forge] ENOENT (${syscall}): ${err.message}\n`);
       return true;
     }
   }
diff --git a/src/resources/extensions/gsd/bootstrap/register-hooks.ts b/src/resources/extensions/gsd/bootstrap/register-hooks.ts
index 2284bc2d9..d3c00923a 100644
--- a/src/resources/extensions/gsd/bootstrap/register-hooks.ts
+++ b/src/resources/extensions/gsd/bootstrap/register-hooks.ts
@@ -44,7 +44,7 @@ export function registerHooks(pi: ExtensionAPI): void {
       const sid = ctx.sessionManager?.getSessionId?.() ?? "";
       const sfile = ctx.sessionManager?.getSessionFile?.() ?? "";
       if (sid) {
-        process.stderr.write(`[gsd] session ${sid.slice(0, 8)} · ${sfile}\n`);
+        process.stderr.write(`[forge] session ${sid.slice(0, 8)} · ${sfile}\n`);
       }
     } catch {
       /* non-fatal */
diff --git a/src/resources/extensions/gsd/cache.ts b/src/resources/extensions/gsd/cache.ts
index 93eb05215..456a66ad9 100644
--- a/src/resources/extensions/gsd/cache.ts
+++ b/src/resources/extensions/gsd/cache.ts
@@ -1,4 +1,4 @@
-// GSD Extension — Unified Cache Invalidation
+// GSD Extension — Cache Invalidation
 //
 // Three module-scoped caches exist across the GSD extension:
 //   1. State cache (state.ts)  — memoized deriveState() result
diff --git a/src/resources/extensions/gsd/commands/handlers/workflow.ts b/src/resources/extensions/gsd/commands/handlers/workflow.ts
index 595dcf8a6..fd603d08d 100644
--- a/src/resources/extensions/gsd/commands/handlers/workflow.ts
+++ b/src/resources/extensions/gsd/commands/handlers/workflow.ts
@@ -267,8 +267,8 @@ export async function handleWorkflowCommand(trimmed: string, ctx: ExtensionComma
       try { unlinkSync(headlessContextPath); } catch { /* non-fatal */ }
       await showHeadlessMilestoneCreation(ctx, pi, basePath, seedContext);
     } else {
-      const { showSmartEntry } = await import("../../guided-flow.js");
-      await showSmartEntry(ctx, pi, basePath);
+      const { showWorkflowEntry } = await import("../../guided-flow.js");
+      await showWorkflowEntry(ctx, pi, basePath);
     }
     return true;
   }
diff --git a/src/resources/extensions/gsd/docs/preferences-reference.md b/src/resources/extensions/gsd/docs/preferences-reference.md
index da2897669..d8e142a79 100644
--- a/src/resources/extensions/gsd/docs/preferences-reference.md
+++ b/src/resources/extensions/gsd/docs/preferences-reference.md
@@ -193,7 +193,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `hooks`: boolean — enable routing hooks. Default: `true`.
   - `capability_routing`: boolean — enable capability-profile scoring for model selection within a tier. Requires `enabled: true`. Default: `false`.
 
-- `uok`: Unified Orchestration Kernel controls. Keys:
+- `uok`: orchestration kernel controls. Keys:
   - `enabled`: boolean — enable kernel wrappers and contract observers. Default: `true`.
   - `legacy_fallback.enabled`: boolean — emergency release fallback that forces legacy orchestration behavior even when `uok.enabled` is `true`. Default: `false`.
     - Runtime override: set `GSD_UOK_FORCE_LEGACY=1` (or `GSD_UOK_LEGACY_FALLBACK=1`) to force legacy behavior for the current process.
@@ -203,8 +203,8 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `gitops.enabled`: boolean — persist turn-level git transaction records.
   - `gitops.turn_action`: `"commit"` | `"snapshot"` | `"status-only"` — turn transaction mode.
   - `gitops.turn_push`: boolean — whether turn transactions should include push intent metadata.
-  - `audit_unified.enabled`: boolean — dual-write unified audit envelope events.
-  - `plan_v2.enabled`: boolean — enable bounded clarify/research/draft/compile planning flow.
+  - `audit_envelope.enabled`: boolean — dual-write audit envelope events.
+  - `planning_flow.enabled`: boolean — enable bounded clarify/research/draft/compile planning flow.
 
 - `context_management`: configures context hygiene for auto-mode sessions. Keys:
   - `observation_masking`: boolean — mask old tool results to reduce context bloat. Default: `true`.
diff --git a/src/resources/extensions/gsd/error-classifier.ts b/src/resources/extensions/gsd/error-classifier.ts
index f302418ea..33fad43eb 100644
--- a/src/resources/extensions/gsd/error-classifier.ts
+++ b/src/resources/extensions/gsd/error-classifier.ts
@@ -1,5 +1,5 @@
 /**
- * Unified error classifier for provider/network/server errors.
+ * Error classifier for provider/network/server failures.
  *
  * Consolidates patterns from:
  *  - isTransientNetworkError()  in preferences-models.ts
diff --git a/src/resources/extensions/gsd/guided-flow.ts b/src/resources/extensions/gsd/guided-flow.ts
index 1da70b65d..4fc4495cd 100644
--- a/src/resources/extensions/gsd/guided-flow.ts
+++ b/src/resources/extensions/gsd/guided-flow.ts
@@ -1,8 +1,9 @@
 /**
- * GSD Guided Flow — Smart Entry Wizard
+ * GSD Guided Flow — Workflow Entry Wizard
  *
- * One function: showSmartEntry(). Reads state from disk, shows a contextual
- * wizard via showNextAction(), and dispatches through GSD-WORKFLOW.md.
+ * Primary entrypoints: `showWorkflowEntry()` and the legacy `showSmartEntry()`
+ * export. Reads state from disk, shows a contextual wizard via
+ * `showNextAction()`, and dispatches through GSD-WORKFLOW.md.
  * No execution state, no hooks, no tools — the LLM does the rest.
  */
 
@@ -38,7 +39,7 @@ import { isInheritedRepo } from "./repo-identity.js";
 import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitignore.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { resolveUokFlags } from "./uok/flags.js";
-import { ensurePlanV2Graph } from "./uok/plan-v2.js";
+import { ensurePlanV2Graph as ensurePlanningFlowGraph } from "./uok/plan-v2.js";
 import { detectProjectState } from "./detection.js";
 import { showProjectInit, offerMigration } from "./init-wizard.js";
 import { validateDirectory } from "./validate-directory.js";
@@ -86,24 +87,24 @@ function nextMilestoneIdReserved(existingIds: string[], uniqueEnabled: boolean):
   return id;
 }
 
-function needsPlanV2Gate(state: GSDState): boolean {
+function needsPlanningFlowGate(state: GSDState): boolean {
   return state.phase === "executing"
     || state.phase === "summarizing"
     || state.phase === "validating-milestone"
     || state.phase === "completing-milestone";
 }
 
-function runPlanV2Gate(
+function runPlanningFlowGate(
   ctx: ExtensionContext,
   basePath: string,
   state: GSDState,
 ): boolean {
   const prefs = loadEffectiveGSDPreferences()?.preferences;
   const uokFlags = resolveUokFlags(prefs);
-  if (!uokFlags.planV2 || !needsPlanV2Gate(state)) return true;
-  const compiled = ensurePlanV2Graph(basePath, state);
+  if (!uokFlags.planningFlow || !needsPlanningFlowGate(state)) return true;
+  const compiled = ensurePlanningFlowGraph(basePath, state);
   if (!compiled.ok) {
-    const reason = compiled.reason ?? "plan-v2 compilation failed";
+    const reason = compiled.reason ?? "planning-flow compilation failed";
     ctx.ui.notify(
       `Plan gate failed-closed: ${reason}. Complete plan/discuss artifacts before execution.`,
       "error",
@@ -1079,16 +1080,16 @@ async function dispatchDiscussForMilestone(
   await dispatchWorkflow(pi, prompt, "gsd-discuss", ctx, "discuss-milestone");
 }
 
-// ─── Smart Entry Point ────────────────────────────────────────────────────────
+// ─── Workflow Entry Point ─────────────────────────────────────────────────────
 
 /**
- * The one wizard. Reads state, shows contextual options, dispatches into the workflow doc.
+ * The workflow entry wizard. Reads state, shows contextual options, and dispatches into the workflow doc.
  */
 /**
  * Self-heal: scan runtime records and clear stale ones left behind when
  * auto-mode crashed mid-unit. auto.ts has its own selfHealRuntimeRecords()
  * but guided-flow (manual /gsd mode) never called it — meaning stale records
- * persisted until the next /gsd auto run.  This ensures the wizard always
+ * persisted until the next /gsd auto run. This ensures the workflow entry
  * starts from a clean state regardless of how the previous session ended.
  */
 function selfHealRuntimeRecords(basePath: string, ctx: ExtensionContext): { cleared: number } {
@@ -1224,7 +1225,7 @@ async function handleMilestoneActions(
   return false;
 }
 
-export async function showSmartEntry(
+export async function showWorkflowEntry(
   ctx: ExtensionCommandContext,
   pi: ExtensionAPI,
   basePath: string,
@@ -1350,7 +1351,7 @@ export async function showSmartEntry(
     logWarning("guided", `STATE.md rebuild failed: ${(err as Error).message}`);
   }
 
-  if (!runPlanV2Gate(ctx, basePath, state)) return;
+  if (!runPlanningFlowGate(ctx, basePath, state)) return;
 
   if (!state.activeMilestone?.id) {
     // Guard: if a discuss session is already in flight, don't re-inject the prompt.
@@ -1642,7 +1643,7 @@ export async function showSmartEntry(
         });
         if (confirmed) {
           discardMilestone(basePath, milestoneId);
-          return showSmartEntry(ctx, pi, basePath, options);
+          return showWorkflowEntry(ctx, pi, basePath, options);
         }
       }
     } else {
@@ -1680,7 +1681,7 @@ export async function showSmartEntry(
         await fireStatusViaCommand(ctx);
       } else if (choice === "milestone_actions") {
         const acted = await handleMilestoneActions(ctx, pi, basePath, milestoneId, milestoneTitle, options);
-        if (acted) return showSmartEntry(ctx, pi, basePath, options);
+        if (acted) return showWorkflowEntry(ctx, pi, basePath, options);
       }
     }
     return;
@@ -1780,7 +1781,7 @@ export async function showSmartEntry(
       await fireStatusViaCommand(ctx);
     } else if (choice === "milestone_actions") {
       const acted = await handleMilestoneActions(ctx, pi, basePath, milestoneId, milestoneTitle, options);
-      if (acted) return showSmartEntry(ctx, pi, basePath, options);
+      if (acted) return showWorkflowEntry(ctx, pi, basePath, options);
     }
     return;
   }
@@ -1835,7 +1836,7 @@ export async function showSmartEntry(
       await fireStatusViaCommand(ctx);
     } else if (choice === "milestone_actions") {
       const acted = await handleMilestoneActions(ctx, pi, basePath, milestoneId, milestoneTitle, options);
-      if (acted) return showSmartEntry(ctx, pi, basePath, options);
+      if (acted) return showWorkflowEntry(ctx, pi, basePath, options);
     }
     return;
   }
@@ -1926,7 +1927,7 @@ export async function showSmartEntry(
       await fireStatusViaCommand(ctx);
     } else if (choice === "milestone_actions") {
       const acted = await handleMilestoneActions(ctx, pi, basePath, milestoneId, milestoneTitle, options);
-      if (acted) return showSmartEntry(ctx, pi, basePath, options);
+      if (acted) return showWorkflowEntry(ctx, pi, basePath, options);
     }
     return;
   }
@@ -1935,3 +1936,5 @@ export async function showSmartEntry(
   const { fireStatusViaCommand } = await import("./commands.js");
   await fireStatusViaCommand(ctx);
 }
+
+export const showSmartEntry = showWorkflowEntry;
diff --git a/src/resources/extensions/gsd/init-wizard.ts b/src/resources/extensions/gsd/init-wizard.ts
index feafb2d86..66c2091cf 100644
--- a/src/resources/extensions/gsd/init-wizard.ts
+++ b/src/resources/extensions/gsd/init-wizard.ts
@@ -261,7 +261,7 @@ export async function showProjectInit(
   }
 
   // Write initial STATE.md so it exists before the first /gsd invocation.
-  // The explicit /gsd init path (ops.ts) returns without entering showSmartEntry(),
+  // The explicit /gsd init path (ops.ts) returns without entering showWorkflowEntry(),
   // which would otherwise generate STATE.md at guided-flow.ts:1358.
   try {
     const { deriveState } = await import("./state.js");
diff --git a/src/resources/extensions/gsd/journal.ts b/src/resources/extensions/gsd/journal.ts
index 3d635b5ce..3a334e015 100644
--- a/src/resources/extensions/gsd/journal.ts
+++ b/src/resources/extensions/gsd/journal.ts
@@ -16,7 +16,7 @@ import { appendFileSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
-import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
+import { isAuditEnvelopeEnabled } from "./uok/audit-toggle.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -93,7 +93,7 @@ export function emitJournalEvent(basePath: string, entry: JournalEntry): void {
     // Silent failure — journal must never break auto-mode
   }
 
-  if (!isUnifiedAuditEnabled()) return;
+  if (!isAuditEnvelopeEnabled()) return;
   try {
     const causedBy = entry.causedBy
       ? `${entry.causedBy.flowId}:${entry.causedBy.seq}`
diff --git a/src/resources/extensions/gsd/metrics.ts b/src/resources/extensions/gsd/metrics.ts
index 42edda37a..1320ebbff 100644
--- a/src/resources/extensions/gsd/metrics.ts
+++ b/src/resources/extensions/gsd/metrics.ts
@@ -20,7 +20,7 @@ import { getAndClearSkills } from "./skill-telemetry.js";
 import { loadJsonFile, loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
 import { parseUnitId } from "./unit-id.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
-import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
+import { isAuditEnvelopeEnabled } from "./uok/audit-toggle.js";
 import { getDatabase } from "./gsd-db.js";
 
 // Re-export from shared — import directly from format-utils to avoid pulling
@@ -296,7 +296,7 @@ export function snapshotUnitMetrics(
   // Background outcome recording for Bayesian learning
   recordUnitOutcome(unit).catch(() => { /* fire-and-forget */ });
 
-  if (isUnifiedAuditEnabled()) {
+  if (isAuditEnvelopeEnabled()) {
     emitUokAuditEvent(
       basePath,
       buildAuditEnvelope({
diff --git a/src/resources/extensions/gsd/preferences-types.ts b/src/resources/extensions/gsd/preferences-types.ts
index a9802def2..bd6ea25e9 100644
--- a/src/resources/extensions/gsd/preferences-types.ts
+++ b/src/resources/extensions/gsd/preferences-types.ts
@@ -231,9 +231,17 @@ export interface UokPreferences {
     turn_action?: UokTurnActionMode;
     turn_push?: boolean;
   };
+  audit_envelope?: {
+    enabled?: boolean;
+  };
+  /** @deprecated Use `audit_envelope` instead. */
   audit_unified?: {
     enabled?: boolean;
   };
+  planning_flow?: {
+    enabled?: boolean;
+  };
+  /** @deprecated Use `planning_flow` instead. */
   plan_v2?: {
     enabled?: boolean;
   };
@@ -289,7 +297,7 @@ export interface GSDPreferences {
   post_unit_hooks?: PostUnitHookConfig[];
   pre_dispatch_hooks?: PreDispatchHookConfig[];
   dynamic_routing?: DynamicRoutingConfig;
-  /** Unified Orchestration Kernel controls (all flags default off). */
+  /** Orchestration kernel controls (all flags default off). */
   uok?: UokPreferences;
   /** Per-model capability overrides. Deep-merged with built-in profiles for capability-aware routing (ADR-004). */
   modelOverrides?: Record<string, { capabilities?: Partial<ModelCapabilities> }>;
diff --git a/src/resources/extensions/gsd/preferences-validation.ts b/src/resources/extensions/gsd/preferences-validation.ts
index 619b54bf1..09b39859b 100644
--- a/src/resources/extensions/gsd/preferences-validation.ts
+++ b/src/resources/extensions/gsd/preferences-validation.ts
@@ -186,8 +186,10 @@ export function validatePreferences(preferences: GSDPreferences): {
       }
 
       const parseEnabledBlock = (
-        key: "legacy_fallback" | "gates" | "model_policy" | "execution_graph" | "audit_unified" | "plan_v2",
+        key: "legacy_fallback" | "gates" | "model_policy" | "execution_graph" | "audit_envelope" | "audit_unified" | "planning_flow" | "plan_v2",
+        targetKey?: "legacy_fallback" | "gates" | "model_policy" | "execution_graph" | "audit_envelope" | "planning_flow",
       ): void => {
+        const normalizedTargetKey = targetKey ?? (key === "plan_v2" ? "planning_flow" : key);
         const value = raw[key];
         if (value === undefined) return;
         if (typeof value !== "object" || value === null) {
@@ -205,7 +207,7 @@ export function validatePreferences(preferences: GSDPreferences): {
           warnings.push(`unknown uok.${key} key "${unk}" — ignored`);
         }
         if (Object.keys(parsed).length > 0) {
-          valid[key] = parsed;
+          valid[normalizedTargetKey] = parsed;
         }
       };
 
@@ -213,8 +215,16 @@ export function validatePreferences(preferences: GSDPreferences): {
       parseEnabledBlock("gates");
       parseEnabledBlock("model_policy");
       parseEnabledBlock("execution_graph");
-      parseEnabledBlock("audit_unified");
-      parseEnabledBlock("plan_v2");
+      parseEnabledBlock("audit_envelope");
+      if (raw.audit_unified !== undefined && raw.audit_envelope === undefined) {
+        warnings.push("uok.audit_unified is deprecated; use uok.audit_envelope");
+        parseEnabledBlock("audit_unified", "audit_envelope");
+      }
+      parseEnabledBlock("planning_flow");
+      if (raw.plan_v2 !== undefined && raw.planning_flow === undefined) {
+        warnings.push("uok.plan_v2 is deprecated; use uok.planning_flow");
+        parseEnabledBlock("plan_v2", "planning_flow");
+      }
 
       if (raw.gitops !== undefined) {
         if (typeof raw.gitops !== "object" || raw.gitops === null) {
@@ -257,7 +267,9 @@ export function validatePreferences(preferences: GSDPreferences): {
         "model_policy",
         "execution_graph",
         "gitops",
+        "audit_envelope",
         "audit_unified",
+        "planning_flow",
         "plan_v2",
       ]);
       for (const key of Object.keys(raw)) {
diff --git a/src/resources/extensions/gsd/preferences.ts b/src/resources/extensions/gsd/preferences.ts
index b5dd6e840..0a0443bbf 100644
--- a/src/resources/extensions/gsd/preferences.ts
+++ b/src/resources/extensions/gsd/preferences.ts
@@ -400,11 +400,27 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
           gitops: (base.uok?.gitops || override.uok?.gitops)
             ? { ...(base.uok?.gitops ?? {}), ...(override.uok?.gitops ?? {}) }
             : undefined,
-          audit_unified: (base.uok?.audit_unified || override.uok?.audit_unified)
-            ? { ...(base.uok?.audit_unified ?? {}), ...(override.uok?.audit_unified ?? {}) }
+          audit_envelope: (
+            base.uok?.audit_envelope
+            || base.uok?.audit_unified
+            || override.uok?.audit_envelope
+            || override.uok?.audit_unified
+          )
+            ? {
+                ...(base.uok?.audit_envelope ?? base.uok?.audit_unified ?? {}),
+                ...(override.uok?.audit_envelope ?? override.uok?.audit_unified ?? {}),
+              }
             : undefined,
-          plan_v2: (base.uok?.plan_v2 || override.uok?.plan_v2)
-            ? { ...(base.uok?.plan_v2 ?? {}), ...(override.uok?.plan_v2 ?? {}) }
+          planning_flow: (
+            base.uok?.planning_flow
+            || base.uok?.plan_v2
+            || override.uok?.planning_flow
+            || override.uok?.plan_v2
+          )
+            ? {
+                ...(base.uok?.planning_flow ?? base.uok?.plan_v2 ?? {}),
+                ...(override.uok?.planning_flow ?? override.uok?.plan_v2 ?? {}),
+              }
             : undefined,
         }
       : undefined,
diff --git a/src/resources/extensions/gsd/rule-registry.ts b/src/resources/extensions/gsd/rule-registry.ts
index 7a697257a..446d578d9 100644
--- a/src/resources/extensions/gsd/rule-registry.ts
+++ b/src/resources/extensions/gsd/rule-registry.ts
@@ -1,13 +1,13 @@
-// GSD Extension — Unified Rule Registry
+// GSD Extension — Rule Registry
 //
-// Holds all dispatch rules and hooks as a flat list of UnifiedRule objects.
+// Holds all dispatch rules and hooks as a flat list of RegistryRule objects.
 // Provides evaluation methods for each phase (dispatch, post-unit, pre-dispatch)
 // and encapsulates mutable hook state as instance fields.
 //
 // A module-level singleton accessor allows existing code to migrate incrementally.
 
 import { logWarning } from "./workflow-logger.js";
-import type { UnifiedRule, RulePhase } from "./rule-types.js";
+import type { RegistryRule, RulePhase } from "./rule-types.js";
 import type { DispatchAction, DispatchContext, DispatchRule } from "./auto-dispatch.js";
 import type {
   PostUnitHookConfig,
@@ -39,10 +39,10 @@ export function resolveHookArtifactPath(basePath: string, unitId: string, artifa
 // ─── Dispatch Rule Conversion ──────────────────────────────────────────────
 
 /**
- * Convert an array of DispatchRule objects to UnifiedRule[] format.
+ * Convert an array of DispatchRule objects to RegistryRule[] format.
  * Preserves exact array order — dispatch is order-dependent (first-match-wins).
  */
-export function convertDispatchRules(rules: DispatchRule[]): UnifiedRule[] {
+export function convertDispatchRules(rules: DispatchRule[]): RegistryRule[] {
   return rules.map((rule) => ({
     name: rule.name,
     when: "dispatch" as const,
@@ -59,7 +59,7 @@ const HOOK_STATE_FILE = "hook-state.json";
 
 export class RuleRegistry {
   /** Static dispatch rules provided at construction time. */
-  private readonly dispatchRules: UnifiedRule[];
+  private readonly dispatchRules: RegistryRule[];
 
   // ── Mutable hook state (encapsulated, not module-level) ──────────────
 
@@ -73,7 +73,7 @@ export class RuleRegistry {
   retryPending: boolean = false;
   retryTrigger: { unitType: string; unitId: string; retryArtifact: string } | null = null;
 
-  constructor(dispatchRules: UnifiedRule[]) {
+  constructor(dispatchRules: RegistryRule[]) {
     this.dispatchRules = dispatchRules;
   }
 
@@ -83,8 +83,8 @@ export class RuleRegistry {
    * Returns all rules: static dispatch rules + dynamically loaded hook rules.
    * Hook rules are loaded fresh from preferences on each call (not cached).
    */
-  listRules(): UnifiedRule[] {
-    const rules: UnifiedRule[] = [...this.dispatchRules];
+  listRules(): RegistryRule[] {
+    const rules: RegistryRule[] = [...this.dispatchRules];
 
     // Convert post-unit hooks to unified rules
     const postHooks = resolvePostUnitHooks();
@@ -575,7 +575,7 @@ export function setRegistry(r: RuleRegistry): void {
 }
 
 /** Create and set the singleton registry with the given dispatch rules. */
-export function initRegistry(dispatchRules: UnifiedRule[]): RuleRegistry {
+export function initRegistry(dispatchRules: RegistryRule[]): RuleRegistry {
   const registry = new RuleRegistry(dispatchRules);
   setRegistry(registry);
   return registry;
diff --git a/src/resources/extensions/gsd/rule-types.ts b/src/resources/extensions/gsd/rule-types.ts
index 37478053c..d5a961998 100644
--- a/src/resources/extensions/gsd/rule-types.ts
+++ b/src/resources/extensions/gsd/rule-types.ts
@@ -1,6 +1,6 @@
-// GSD Extension — Unified Rule Type Definitions
+// GSD Extension — Rule Type Definitions
 //
-// Every dispatch rule and hook is expressed as a `UnifiedRule` with a
+// Every dispatch rule and hook is expressed as a `RegistryRule` with a
 // consistent when/where/then shape. This file defines the type system;
 // the `RuleRegistry` class in rule-registry.ts holds instances at runtime.
 
@@ -36,13 +36,13 @@ export interface RuleLifecycle {
   idempotency_key?: string;
 }
 
-// ─── Unified Rule ───────────────────────────────────────────────────────────
+// ─── Registry Rule ───────────────────────────────────────────────────────────
 
 /**
  * A single entry in the rule registry. Dispatch rules, post-unit hooks,
  * and pre-dispatch hooks all share this shape.
  */
-export interface UnifiedRule {
+export interface RegistryRule {
   /** Stable human-readable identifier (existing names preserved per D005). */
   name: string;
   /** Which phase/event this rule responds to. */
diff --git a/src/resources/extensions/gsd/session-lock.ts b/src/resources/extensions/gsd/session-lock.ts
index 3fe5b73d1..701f6c3d2 100644
--- a/src/resources/extensions/gsd/session-lock.ts
+++ b/src/resources/extensions/gsd/session-lock.ts
@@ -222,14 +222,14 @@ function createLockCompromisedHandler(lockFilePath: string): () => void {
     const elapsed = Date.now() - _lockAcquiredAt;
     if (elapsed < 1_800_000) {
       process.stderr.write(
-        `[gsd] Lock heartbeat caught up after ${Math.round(elapsed / 1000)}s — long LLM call, no action needed.\n`,
+        `[forge] Lock heartbeat caught up after ${Math.round(elapsed / 1000)}s — long LLM call, no action needed.\n`,
       );
       return;
     }
     const existing = readExistingLockDataWithRetry(lockFilePath);
     if (existing && existing.pid === process.pid) {
       process.stderr.write(
-        `[gsd] Lock heartbeat mismatch after ${Math.round(elapsed / 1000)}s — lock file still owned by PID ${process.pid}, treating as false positive.\n`,
+        `[forge] Lock heartbeat mismatch after ${Math.round(elapsed / 1000)}s — lock file still owned by PID ${process.pid}, treating as false positive.\n`,
       );
       return;
     }
@@ -463,7 +463,7 @@ export function getSessionLockStatus(basePath: string): SessionLockStatus {
         const result = acquireSessionLock(basePath);
         if (result.acquired) {
           process.stderr.write(
-            `[gsd] Lock recovered after onCompromised — lock file PID matched, re-acquired.\n`,
+            `[forge] Lock recovered after onCompromised — lock file PID matched, re-acquired.\n`,
           );
           return { valid: true, recovered: true };
         }
diff --git a/src/resources/extensions/gsd/templates/PREFERENCES.md b/src/resources/extensions/gsd/templates/PREFERENCES.md
index 9117bf24a..adf1fd0d0 100644
--- a/src/resources/extensions/gsd/templates/PREFERENCES.md
+++ b/src/resources/extensions/gsd/templates/PREFERENCES.md
@@ -53,9 +53,9 @@ uok:
     enabled: false
     turn_action: status-only
     turn_push: false
-  audit_unified:
+  audit_envelope:
     enabled: false
-  plan_v2:
+  planning_flow:
     enabled: false
 auto_visualize:
 auto_report:
diff --git a/src/resources/extensions/gsd/tests/auto-start-model-capture.test.ts b/src/resources/extensions/gsd/tests/auto-start-model-capture.test.ts
index db312680f..28224bc9b 100644
--- a/src/resources/extensions/gsd/tests/auto-start-model-capture.test.ts
+++ b/src/resources/extensions/gsd/tests/auto-start-model-capture.test.ts
@@ -11,8 +11,8 @@ test("bootstrapAutoSession snapshots ctx.model before guided-flow entry (#2829)"
   const snapshotIdx = source.indexOf("const startModelSnapshot = manualSessionOverride");
   assert.ok(snapshotIdx > -1, "auto-start.ts should snapshot model at bootstrap start");
 
-  const firstDiscussIdx = source.indexOf('await showSmartEntry(ctx, pi, base, { step: requestedStepMode });');
-  assert.ok(firstDiscussIdx > -1, "auto-start.ts should route through showSmartEntry during guided flow");
+  const firstDiscussIdx = source.indexOf('await showWorkflowEntry(ctx, pi, base, { step: requestedStepMode });');
+  assert.ok(firstDiscussIdx > -1, "auto-start.ts should route through showWorkflowEntry during guided flow");
 
   assert.ok(
     snapshotIdx < firstDiscussIdx,
diff --git a/src/resources/extensions/gsd/tests/auto-start-needs-discussion.test.ts b/src/resources/extensions/gsd/tests/auto-start-needs-discussion.test.ts
index a14c5a539..7535b3c16 100644
--- a/src/resources/extensions/gsd/tests/auto-start-needs-discussion.test.ts
+++ b/src/resources/extensions/gsd/tests/auto-start-needs-discussion.test.ts
@@ -6,7 +6,7 @@
  *
  *   1. The survivor branch check included needs-discussion, so a branch
  *      created by a prior failed bootstrap caused hasSurvivorBranch = true,
- *      skipping all showSmartEntry calls.
+ *      skipping all showWorkflowEntry calls.
  *
  *   2. No needs-discussion handler existed in the !hasSurvivorBranch block,
  *      so the phase fell through to auto-mode which immediately stopped
@@ -118,12 +118,12 @@ describe("auto-start-needs-discussion (#1726)", () => {
     const source = readAutoStartSource();
 
     // After the pre-planning handler, there should be a needs-discussion handler
-    // that calls showSmartEntry
+    // that calls showWorkflowEntry
     const needsDiscussionHandler = source.match(
-      /if\s*\(state\.phase\s*===\s*"needs-discussion"\)\s*\{[^}]*showSmartEntry/s,
+      /if\s*\(state\.phase\s*===\s*"needs-discussion"\)\s*\{[^}]*showWorkflowEntry/s,
     );
     assert.ok(!!needsDiscussionHandler,
-      "needs-discussion handler calling showSmartEntry must exist in !hasSurvivorBranch block");
+      "needs-discussion handler calling showWorkflowEntry must exist in !hasSurvivorBranch block");
   });
 
   test("4. needs-discussion handler has abort path", () => {
@@ -133,7 +133,7 @@ describe("auto-start-needs-discussion (#1726)", () => {
     // if discussion didn't promote the draft
     assert.ok(
       source.includes('postState.phase !== "needs-discussion"'),
-      "needs-discussion handler must check if phase advanced after showSmartEntry",
+      "needs-discussion handler must check if phase advanced after showWorkflowEntry",
     );
     assert.ok(
       source.includes("milestone draft was not promoted"),
@@ -157,12 +157,12 @@ describe("auto-start-needs-discussion (#1726)", () => {
     }
   });
 
-  test("6. No infinite loop: needs-discussion always routes to showSmartEntry", () => {
+  test("6. No infinite loop: needs-discussion always routes to showWorkflowEntry", () => {
     const source = readAutoStartSource();
 
     // Verify needs-discussion does NOT appear in auto-dispatch trigger conditions
     // within auto-start.ts. The only place needs-discussion should appear is in
-    // the showSmartEntry routing block.
+    // the showWorkflowEntry routing block.
     const survivorSection = source.match(
       /\/\/ Milestone branch recovery.*?let hasSurvivorBranch = false;[\s\S]*?if\s*\([^)]*state\.phase[^)]*\)\s*\{/,
     );
@@ -187,16 +187,16 @@ describe("auto-start-needs-discussion (#1726)", () => {
     }
   });
 
-  test("7. Survivor branch + needs-discussion routes to showSmartEntry", () => {
+  test("7. Survivor branch + needs-discussion routes to showWorkflowEntry", () => {
     const source = readAutoStartSource();
 
     // When hasSurvivorBranch is true AND phase is needs-discussion, the code
-    // must route to showSmartEntry instead of falling through to auto-mode.
+    // must route to showWorkflowEntry instead of falling through to auto-mode.
     const survivorNeedsDiscussion = source.match(
-      /if\s*\(hasSurvivorBranch\s*&&\s*state\.phase\s*===\s*"needs-discussion"\)\s*\{[^}]*showSmartEntry/s,
+      /if\s*\(hasSurvivorBranch\s*&&\s*state\.phase\s*===\s*"needs-discussion"\)\s*\{[^}]*showWorkflowEntry/s,
     );
     assert.ok(!!survivorNeedsDiscussion,
-      "hasSurvivorBranch && needs-discussion must route to showSmartEntry");
+      "hasSurvivorBranch && needs-discussion must route to showWorkflowEntry");
 
     // Verify the handler checks if the discussion succeeded
     const handlerBlock = source.match(
diff --git a/src/resources/extensions/gsd/tests/crash-handler-secondary.test.ts b/src/resources/extensions/gsd/tests/crash-handler-secondary.test.ts
index bb981f16f..a5f58c14b 100644
--- a/src/resources/extensions/gsd/tests/crash-handler-secondary.test.ts
+++ b/src/resources/extensions/gsd/tests/crash-handler-secondary.test.ts
@@ -76,7 +76,7 @@ describe('register-extension crash handler secondary fixes (#3348)', () => {
     // The original #3696 fix replaced "throw err" with a log-and-continue.
     // The secondary fix replaces that with writeCrashLog + process.exit(1).
     assert.ok(
-      !registerExtSrc.includes('process.stderr.write(`[gsd] uncaught extension error (non-fatal)'),
+      !registerExtSrc.includes('process.stderr.write(`[forge] uncaught extension error (non-fatal)'),
       '_gsdEpipeGuard should NOT log errors as non-fatal and continue',
     );
     assert.match(
diff --git a/src/resources/extensions/gsd/tests/rule-registry.test.ts b/src/resources/extensions/gsd/tests/rule-registry.test.ts
index b10455d5c..26892b3c0 100644
--- a/src/resources/extensions/gsd/tests/rule-registry.test.ts
+++ b/src/resources/extensions/gsd/tests/rule-registry.test.ts
@@ -1,6 +1,6 @@
 // GSD Extension — Rule Registry Tests
 //
-// Tests the RuleRegistry class, UnifiedRule types, singleton accessors,
+// Tests the RuleRegistry class, RegistryRule types, singleton accessors,
 // and evaluation methods using mock rules.
 
 import assert from 'node:assert/strict';
@@ -14,14 +14,14 @@ import {
   convertDispatchRules,
   getOrCreateRegistry,
 } from "../rule-registry.ts";
-import type { UnifiedRule } from "../rule-types.ts";
+import type { RegistryRule } from "../rule-types.ts";
 import type { DispatchAction, DispatchContext } from "../auto-dispatch.ts";
 import { DISPATCH_RULES, getDispatchRuleNames } from "../auto-dispatch.ts";
 import type { GSDState } from "../types.ts";
 
 // ─── Mock Rule Factories ──────────────────────────────────────────────────
 
-function mockDispatchRule(name: string, matchPhase: string): UnifiedRule {
+function mockDispatchRule(name: string, matchPhase: string): RegistryRule {
   return {
     name,
     when: "dispatch",
@@ -69,7 +69,7 @@ describe("RuleRegistry", () => {
   });
 
   test("construct with dispatch rules, listRules returns them", () => {
-    const rules: UnifiedRule[] = [
+    const rules: RegistryRule[] = [
       mockDispatchRule("rule-a", "planning"),
       mockDispatchRule("rule-b", "executing"),
       mockDispatchRule("rule-c", "complete"),
@@ -86,7 +86,7 @@ describe("RuleRegistry", () => {
   });
 
   test("listRules returns correct fields on each rule", () => {
-    const rules: UnifiedRule[] = [
+    const rules: RegistryRule[] = [
       mockDispatchRule("check-fields", "planning"),
     ];
     const registry = new RuleRegistry(rules);
@@ -102,7 +102,7 @@ describe("RuleRegistry", () => {
   });
 
   test("evaluateDispatch returns first matching rule", async () => {
-    const rules: UnifiedRule[] = [
+    const rules: RegistryRule[] = [
       mockDispatchRule("rule-planning", "planning"),
       mockDispatchRule("rule-executing", "executing"),
       mockDispatchRule("rule-complete", "complete"),
@@ -119,7 +119,7 @@ describe("RuleRegistry", () => {
   });
 
   test("evaluateDispatch returns stop when no rule matches", async () => {
-    const rules: UnifiedRule[] = [
+    const rules: RegistryRule[] = [
       mockDispatchRule("only-planning", "planning"),
     ];
     const registry = new RuleRegistry(rules);
@@ -133,7 +133,7 @@ describe("RuleRegistry", () => {
   });
 
   test("evaluateDispatch works with async where predicate", async () => {
-    const asyncRule: UnifiedRule = {
+    const asyncRule: RegistryRule = {
       name: "async-rule",
       when: "dispatch",
       evaluation: "first-match",
@@ -227,7 +227,7 @@ describe("RuleRegistry", () => {
 
   test("evaluateDispatch respects rule order (first match wins)", async () => {
     // Both rules match "planning" but rule-first should win
-    const ruleFirst: UnifiedRule = {
+    const ruleFirst: RegistryRule = {
       name: "rule-first",
       when: "dispatch",
       evaluation: "first-match",
@@ -239,7 +239,7 @@ describe("RuleRegistry", () => {
       },
       then: () => {},
     };
-    const ruleSecond: UnifiedRule = {
+    const ruleSecond: RegistryRule = {
       name: "rule-second",
       when: "dispatch",
       evaluation: "first-match",
@@ -264,7 +264,7 @@ describe("RuleRegistry", () => {
 
   // ── Dispatch rule conversion tests ─────────────────────────────────
 
-  test("convertDispatchRules produces correct count of UnifiedRule objects", () => {
+  test("convertDispatchRules produces correct count of RegistryRule objects", () => {
     const converted = convertDispatchRules(DISPATCH_RULES);
     assert.deepStrictEqual(converted.length, DISPATCH_RULES.length, `convertDispatchRules produces ${DISPATCH_RULES.length} rules`);
   });
@@ -386,7 +386,7 @@ describe("RuleRegistry", () => {
   // ── matchedRule provenance (S02 journal support) ───────────────────
 
   test("evaluateDispatch result includes matchedRule on dispatch match", async () => {
-    const rules: UnifiedRule[] = [
+    const rules: RegistryRule[] = [
       mockDispatchRule("my-planning-rule", "planning"),
     ];
     const registry = new RuleRegistry(rules);
@@ -398,7 +398,7 @@ describe("RuleRegistry", () => {
   });
 
   test("evaluateDispatch result includes matchedRule '<no-match>' on fallback stop", async () => {
-    const rules: UnifiedRule[] = [
+    const rules: RegistryRule[] = [
       mockDispatchRule("only-planning", "planning"),
     ];
     const registry = new RuleRegistry(rules);
diff --git a/src/resources/extensions/gsd/tests/smart-entry-draft.test.ts b/src/resources/extensions/gsd/tests/smart-entry-draft.test.ts
index 978dba4a2..2a0e9565f 100644
--- a/src/resources/extensions/gsd/tests/smart-entry-draft.test.ts
+++ b/src/resources/extensions/gsd/tests/smart-entry-draft.test.ts
@@ -76,7 +76,7 @@ const guidedFlowSource = readFileSync(
 
 assert(
   guidedFlowSource.includes('state.phase === "needs-discussion"'),
-  "guided-flow.ts should have 'needs-discussion' phase check in showSmartEntry",
+  "guided-flow.ts should have 'needs-discussion' phase check in showWorkflowEntry",
 );
 
 // Check the branch has draft-aware menu options
diff --git a/src/resources/extensions/gsd/tests/survivor-branch-complete.test.ts b/src/resources/extensions/gsd/tests/survivor-branch-complete.test.ts
index 0d6fe66a4..833451f25 100644
--- a/src/resources/extensions/gsd/tests/survivor-branch-complete.test.ts
+++ b/src/resources/extensions/gsd/tests/survivor-branch-complete.test.ts
@@ -76,13 +76,13 @@ const { assertTrue, assertEq, report } = createTestContext();
   // Simulate the decision logic after the fix:
   // if (hasSurvivorBranch && state.phase === "complete") -> finalize
   // if (hasSurvivorBranch && state.phase === "needs-discussion") -> discuss
-  // if (!hasSurvivorBranch && state.phase === "complete") -> showSmartEntry
+  // if (!hasSurvivorBranch && state.phase === "complete") -> showWorkflowEntry
 
   const scenarios = [
     { hasSurvivorBranch: true, phase: "complete", expected: "finalize" },
     { hasSurvivorBranch: true, phase: "needs-discussion", expected: "discuss" },
     { hasSurvivorBranch: true, phase: "pre-planning", expected: "continue" },
-    { hasSurvivorBranch: false, phase: "complete", expected: "showSmartEntry" },
+    { hasSurvivorBranch: false, phase: "complete", expected: "showWorkflowEntry" },
   ];
 
   for (const { hasSurvivorBranch, phase, expected } of scenarios) {
@@ -92,7 +92,7 @@ const { assertTrue, assertEq, report } = createTestContext();
     } else if (hasSurvivorBranch && phase === "needs-discussion") {
       result = "discuss";
     } else if (!hasSurvivorBranch && (!phase || phase === "complete")) {
-      result = "showSmartEntry";
+      result = "showWorkflowEntry";
     } else {
       result = "continue";
     }
diff --git a/src/resources/extensions/gsd/tests/uok-audit-unified.test.ts b/src/resources/extensions/gsd/tests/uok-audit-unified.test.ts
index 884b88115..417b56c1c 100644
--- a/src/resources/extensions/gsd/tests/uok-audit-unified.test.ts
+++ b/src/resources/extensions/gsd/tests/uok-audit-unified.test.ts
@@ -7,7 +7,7 @@ import { emitJournalEvent } from "../journal.ts";
 import { saveActivityLog } from "../activity-log.ts";
 import { initMetrics, resetMetrics, snapshotUnitMetrics } from "../metrics.ts";
 import { setLogBasePath, logWarning } from "../workflow-logger.ts";
-import { setUnifiedAuditEnabled } from "../uok/audit-toggle.ts";
+import { setAuditEnvelopeEnabled } from "../uok/audit-toggle.ts";
 
 function readAuditEvents(basePath: string): Array<Record<string, unknown>> {
   const file = join(basePath, ".gsd", "audit", "events.jsonl");
@@ -27,9 +27,9 @@ function makeMockContext(entries: unknown[]): any {
   };
 }
 
-test("unified audit plane bridges journal/activity/metrics/workflow logger into audit envelope log", () => {
+test("audit envelope bridges journal/activity/metrics/workflow logger into audit event log", () => {
   const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-audit-"));
-  setUnifiedAuditEnabled(true);
+  setAuditEnvelopeEnabled(true);
   try {
     emitJournalEvent(basePath, {
       ts: new Date().toISOString(),
@@ -77,15 +77,15 @@ test("unified audit plane bridges journal/activity/metrics/workflow logger into
     assert.ok(types.has("unit-metrics-snapshot"));
     assert.ok(types.has("workflow-log-warn"));
   } finally {
-    setUnifiedAuditEnabled(false);
+    setAuditEnvelopeEnabled(false);
     resetMetrics();
     rmSync(basePath, { recursive: true, force: true });
   }
 });
 
-test("unified audit bridge is disabled when toggle is off", () => {
+test("audit envelope bridge is disabled when toggle is off", () => {
   const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-audit-off-"));
-  setUnifiedAuditEnabled(false);
+  setAuditEnvelopeEnabled(false);
   try {
     emitJournalEvent(basePath, {
       ts: new Date().toISOString(),
diff --git a/src/resources/extensions/gsd/tests/uok-plan-v2-wiring.test.ts b/src/resources/extensions/gsd/tests/uok-plan-v2-wiring.test.ts
index 34b2ba213..c0c4522ee 100644
--- a/src/resources/extensions/gsd/tests/uok-plan-v2-wiring.test.ts
+++ b/src/resources/extensions/gsd/tests/uok-plan-v2-wiring.test.ts
@@ -88,17 +88,17 @@ test.afterEach(() => {
   tempDirs.clear();
 });
 
-test("guided flow enforces plan-v2 gate before execution-oriented dispatch", () => {
+test("guided flow enforces planning-flow gate before execution-oriented dispatch", () => {
   const source = readFileSync(join(gsdDir, "guided-flow.ts"), "utf-8");
   assert.ok(
-    source.includes("needsPlanV2Gate") &&
-    source.includes("ensurePlanV2Graph") &&
+    source.includes("needsPlanningFlowGate") &&
+    source.includes("ensurePlanningFlowGraph") &&
     source.includes("Plan gate failed-closed"),
-    "guided flow should fail-closed when plan-v2 graph compilation fails",
+    "guided flow should fail-closed when planning-flow graph compilation fails",
   );
 });
 
-test("plan-v2 gate fails closed for execution phase when finalized context is missing", () => {
+test("planning-flow gate fails closed for execution phase when finalized context is missing", () => {
   const basePath = createBasePath();
   seedGraphRows();
 
@@ -109,7 +109,7 @@ test("plan-v2 gate fails closed for execution phase when finalized context is mi
   assert.match(compiled.reason ?? "", /CONTEXT\.md/i);
 });
 
-test("plan-v2 compiler writes pipeline metadata for clarify/research/draft stages", () => {
+test("planning-flow compiler writes pipeline metadata for clarify/research/draft stages", () => {
   const basePath = createBasePath();
   seedGraphRows();
 
diff --git a/src/resources/extensions/gsd/tests/uok-preferences.test.ts b/src/resources/extensions/gsd/tests/uok-preferences.test.ts
index 31b141d46..e0f7fed8d 100644
--- a/src/resources/extensions/gsd/tests/uok-preferences.test.ts
+++ b/src/resources/extensions/gsd/tests/uok-preferences.test.ts
@@ -16,8 +16,8 @@ test("uok preferences validate nested flags and turn_action", () => {
         turn_action: "status-only",
         turn_push: false,
       },
-      audit_unified: { enabled: true },
-      plan_v2: { enabled: true },
+      audit_envelope: { enabled: true },
+      planning_flow: { enabled: true },
     },
   };
 
@@ -26,7 +26,7 @@ test("uok preferences validate nested flags and turn_action", () => {
   assert.equal(result.preferences.uok?.enabled, true);
   assert.equal(result.preferences.uok?.legacy_fallback?.enabled, false);
   assert.equal(result.preferences.uok?.gitops?.turn_action, "status-only");
-  assert.equal(result.preferences.uok?.plan_v2?.enabled, true);
+  assert.equal(result.preferences.uok?.planning_flow?.enabled, true);
 });
 
 test("uok preferences reject invalid turn_action", () => {
@@ -40,3 +40,27 @@ test("uok preferences reject invalid turn_action", () => {
 
   assert.ok(result.errors.some((e) => e.includes("uok.gitops.turn_action")));
 });
+
+test("uok preferences accept deprecated plan_v2 alias", () => {
+  const result = validatePreferences({
+    uok: {
+      plan_v2: {
+        enabled: true,
+      },
+    },
+  } as never);
+
+  assert.equal(result.preferences.uok?.planning_flow?.enabled, true);
+});
+
+test("uok preferences accept deprecated audit_unified alias", () => {
+  const result = validatePreferences({
+    uok: {
+      audit_unified: {
+        enabled: true,
+      },
+    },
+  } as never);
+
+  assert.equal(result.preferences.uok?.audit_envelope?.enabled, true);
+});
diff --git a/src/resources/extensions/gsd/tests/zombie-gsd-state.test.ts b/src/resources/extensions/gsd/tests/zombie-gsd-state.test.ts
index d18a7fcf8..7f3dc8710 100644
--- a/src/resources/extensions/gsd/tests/zombie-gsd-state.test.ts
+++ b/src/resources/extensions/gsd/tests/zombie-gsd-state.test.ts
@@ -8,7 +8,7 @@ const { assertTrue, assertMatch, assertNoMatch, report } = createTestContext();
 // ─── #2942: Zombie .gsd state skips init wizard ─────────────────────────────
 //
 // A partially initialized .gsd/ (symlink exists but no PREFERENCES.md or
-// milestones/) causes the init wizard gate in showSmartEntry to be skipped,
+// milestones/) causes the init wizard gate in showWorkflowEntry to be skipped,
 // resulting in an uninitialized project session.
 
 console.log("\n=== #2942: zombie .gsd state must not skip init wizard ===");
@@ -20,11 +20,11 @@ const guidedFlowSrc = readFileSync(
   "utf-8",
 );
 
-// Find the showSmartEntry function
-const smartEntryIdx = guidedFlowSrc.indexOf("export async function showSmartEntry(");
-assertTrue(smartEntryIdx >= 0, "guided-flow.ts defines showSmartEntry");
+// Find the showWorkflowEntry function
+const smartEntryIdx = guidedFlowSrc.indexOf("export async function showWorkflowEntry(");
+assertTrue(smartEntryIdx >= 0, "guided-flow.ts defines showWorkflowEntry");
 
-// Extract the region between showSmartEntry and the first showProjectInit call
+// Extract the region between showWorkflowEntry and the first showProjectInit call
 // This is where the init wizard gate lives.
 const afterSmartEntry = smartEntryIdx >= 0 ? guidedFlowSrc.slice(smartEntryIdx, smartEntryIdx + 3000) : "";
 
diff --git a/src/resources/extensions/gsd/uok/audit-toggle.ts b/src/resources/extensions/gsd/uok/audit-toggle.ts
index 688c5c53e..a9240c574 100644
--- a/src/resources/extensions/gsd/uok/audit-toggle.ts
+++ b/src/resources/extensions/gsd/uok/audit-toggle.ts
@@ -1,9 +1,11 @@
-const AUDIT_ENV_KEY = "GSD_UOK_AUDIT_UNIFIED";
+const AUDIT_ENV_KEY = "GSD_UOK_AUDIT_ENVELOPE";
+const LEGACY_AUDIT_ENV_KEY = "GSD_UOK_AUDIT_UNIFIED";
 
-export function setUnifiedAuditEnabled(enabled: boolean): void {
+export function setAuditEnvelopeEnabled(enabled: boolean): void {
   process.env[AUDIT_ENV_KEY] = enabled ? "1" : "0";
+  process.env[LEGACY_AUDIT_ENV_KEY] = enabled ? "1" : "0";
 }
 
-export function isUnifiedAuditEnabled(): boolean {
-  return process.env[AUDIT_ENV_KEY] === "1";
+export function isAuditEnvelopeEnabled(): boolean {
+  return process.env[AUDIT_ENV_KEY] === "1" || process.env[LEGACY_AUDIT_ENV_KEY] === "1";
 }
diff --git a/src/resources/extensions/gsd/uok/flags.ts b/src/resources/extensions/gsd/uok/flags.ts
index 8eacf1dd7..73395d9e3 100644
--- a/src/resources/extensions/gsd/uok/flags.ts
+++ b/src/resources/extensions/gsd/uok/flags.ts
@@ -10,8 +10,8 @@ export interface UokFlags {
   gitops: boolean;
   gitopsTurnAction: "commit" | "snapshot" | "status-only";
   gitopsTurnPush: boolean;
-  auditUnified: boolean;
-  planV2: boolean;
+  auditEnvelope: boolean;
+  planningFlow: boolean;
 }
 
 function envForcesLegacyFallback(): boolean {
@@ -34,8 +34,8 @@ export function resolveUokFlags(prefs: GSDPreferences | undefined): UokFlags {
     gitops: uok?.gitops?.enabled === true,
     gitopsTurnAction: uok?.gitops?.turn_action ?? "status-only",
     gitopsTurnPush: uok?.gitops?.turn_push === true,
-    auditUnified: uok?.audit_unified?.enabled === true,
-    planV2: uok?.plan_v2?.enabled === true,
+    auditEnvelope: uok?.audit_envelope?.enabled === true || uok?.audit_unified?.enabled === true,
+    planningFlow: uok?.planning_flow?.enabled === true || uok?.plan_v2?.enabled === true,
   };
 }
 
diff --git a/src/resources/extensions/gsd/uok/kernel.ts b/src/resources/extensions/gsd/uok/kernel.ts
index fbd39903f..cb318a986 100644
--- a/src/resources/extensions/gsd/uok/kernel.ts
+++ b/src/resources/extensions/gsd/uok/kernel.ts
@@ -6,7 +6,7 @@ import type { AutoSession } from "../auto/session.js";
 import type { LoopDeps } from "../auto/loop-deps.js";
 import { gsdRoot } from "../paths.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
-import { setUnifiedAuditEnabled } from "./audit-toggle.js";
+import { setAuditEnvelopeEnabled } from "./audit-toggle.js";
 import { resolveUokFlags } from "./flags.js";
 import { createTurnObserver } from "./loop-adapter.js";
 
@@ -45,7 +45,7 @@ export async function runAutoLoopWithUok(args: RunAutoLoopWithUokArgs): Promise<
   const { ctx, pi, s, deps, runLegacyLoop } = args;
   const prefs = deps.loadEffectiveGSDPreferences()?.preferences;
   const flags = resolveUokFlags(prefs);
-  setUnifiedAuditEnabled(flags.auditUnified);
+  setAuditEnvelopeEnabled(flags.auditEnvelope);
 
   writeParityEvent(s.basePath, {
     ts: new Date().toISOString(),
@@ -54,7 +54,7 @@ export async function runAutoLoopWithUok(args: RunAutoLoopWithUokArgs): Promise<
     phase: "enter",
   });
 
-  if (flags.auditUnified) {
+  if (flags.auditEnvelope) {
     emitUokAuditEvent(
       s.basePath,
       buildAuditEnvelope({
@@ -76,7 +76,7 @@ export async function runAutoLoopWithUok(args: RunAutoLoopWithUokArgs): Promise<
           basePath: s.basePath,
           gitAction: flags.gitopsTurnAction,
           gitPush: flags.gitopsTurnPush,
-          enableAudit: flags.auditUnified,
+          enableAudit: flags.auditEnvelope,
           enableGitops: flags.gitops,
         }),
       }
diff --git a/src/resources/extensions/gsd/workflow-logger.ts b/src/resources/extensions/gsd/workflow-logger.ts
index ec9fb55bb..0a58f3e22 100644
--- a/src/resources/extensions/gsd/workflow-logger.ts
+++ b/src/resources/extensions/gsd/workflow-logger.ts
@@ -21,7 +21,7 @@ import { join } from "node:path";
 
 import { appendNotification } from "./notification-store.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
-import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
+import { isAuditEnvelopeEnabled } from "./uok/audit-toggle.js";
 
 // ─── Types ──────────────────────────────────────────────────────────────
 
@@ -277,7 +277,7 @@ function _push(
     _buffer.shift();
   }
 
-  if (_auditBasePath && isUnifiedAuditEnabled()) {
+  if (_auditBasePath && isAuditEnvelopeEnabled()) {
     try {
       emitUokAuditEvent(
         _auditBasePath,
diff --git a/src/resources/extensions/gsd/workflow-reconcile.ts b/src/resources/extensions/gsd/workflow-reconcile.ts
index 1887c9860..07902e591 100644
--- a/src/resources/extensions/gsd/workflow-reconcile.ts
+++ b/src/resources/extensions/gsd/workflow-reconcile.ts
@@ -48,7 +48,7 @@ export function replaySliceComplete(milestoneId: string, sliceId: string, ts: st
     const incompleteTasks = tasks.filter(t => !isClosedStatus(t.status));
     if (incompleteTasks.length > 0) {
       process.stderr.write(
-        `[gsd] reconcile: skipping complete_slice replay for ${sliceId} — ` +
+        `[forge] reconcile: skipping complete_slice replay for ${sliceId} — ` +
         `${incompleteTasks.length} task(s) still pending\n`,
       );
       return;
diff --git a/src/web-mode.ts b/src/web-mode.ts
index 3d917431c..622152025 100644
--- a/src/web-mode.ts
+++ b/src/web-mode.ts
@@ -210,13 +210,13 @@ export function stopWebMode(deps: Pick<WebModeDeps, 'pidFilePath' | 'readPidFile
     for (const [cwd, entry] of entries) {
       const result = killPid(entry.pid)
       if (result === 'killed') {
-        stderr.write(`[gsd] Stopped web server for ${cwd} (pid=${entry.pid})\n`)
+        stderr.write(`[forge] Stopped web server for ${cwd} (pid=${entry.pid})\n`)
         stopped++
       } else if (result === 'already-dead') {
-        stderr.write(`[gsd] Web server for ${cwd} was already stopped (pid=${entry.pid})\n`)
+        stderr.write(`[forge] Web server for ${cwd} was already stopped (pid=${entry.pid})\n`)
         stopped++
       } else {
-        stderr.write(`[gsd] Failed to stop web server for ${cwd}: ${result.error}\n`)
+        stderr.write(`[forge] Failed to stop web server for ${cwd}: ${result.error}\n`)
       }
       unregisterInstance(cwd)
     }
@@ -224,7 +224,7 @@ export function stopWebMode(deps: Pick<WebModeDeps, 'pidFilePath' | 'readPidFile
     const deletePid = deps.deletePidFile ?? deletePidFile
     const pidFilePath = deps.pidFilePath ?? defaultWebPidFilePath
     deletePid(pidFilePath)
-    stderr.write(`[gsd] Stopped ${stopped} instance${stopped === 1 ? '' : 's'}.\n`)
+    stderr.write(`[forge] Stopped ${stopped} instance${stopped === 1 ? '' : 's'}.\n`)
     return { ok: true, stoppedCount: stopped }
   }
 
@@ -234,19 +234,19 @@ export function stopWebMode(deps: Pick<WebModeDeps, 'pidFilePath' | 'readPidFile
     const registry = readInstanceRegistry()
     const entry = registry[resolvedCwd]
     if (!entry) {
-      stderr.write(`[gsd] No web server running for ${resolvedCwd}\n`)
+      stderr.write(`[forge] No web server running for ${resolvedCwd}\n`)
       return { ok: false, reason: 'not-found' }
     }
     const result = killPid(entry.pid)
     unregisterInstance(resolvedCwd)
     if (result === 'killed') {
-      stderr.write(`[gsd] Stopped web server for ${resolvedCwd} (pid=${entry.pid})\n`)
+      stderr.write(`[forge] Stopped web server for ${resolvedCwd} (pid=${entry.pid})\n`)
       return { ok: true, stoppedCount: 1 }
     } else if (result === 'already-dead') {
-      stderr.write(`[gsd] Web server for ${resolvedCwd} was already stopped — cleared stale entry.\n`)
+      stderr.write(`[forge] Web server for ${resolvedCwd} was already stopped — cleared stale entry.\n`)
       return { ok: true, stoppedCount: 1 }
     } else {
-      stderr.write(`[gsd] Failed to stop web server for ${resolvedCwd}: ${result.error}\n`)
+      stderr.write(`[forge] Failed to stop web server for ${resolvedCwd}: ${result.error}\n`)
       return { ok: false, reason: result.error }
     }
   }
@@ -263,22 +263,22 @@ function stopLegacyPidFile(deps: Pick<WebModeDeps, 'pidFilePath' | 'readPidFile'
 
   const pid = readPid(pidFilePath)
   if (pid === null) {
-    stderr.write(`[gsd] Web server is not running (no PID file found)\n`)
+    stderr.write(`[forge] Web server is not running (no PID file found)\n`)
     return { ok: false, reason: 'no-pid-file' }
   }
 
-  stderr.write(`[gsd] Stopping web server (pid=${pid})…\n`)
+  stderr.write(`[forge] Stopping web server (pid=${pid})…\n`)
 
   const result = killPid(pid)
   deletePid(pidFilePath)
   if (result === 'killed') {
-    stderr.write(`[gsd] Web server stopped.\n`)
+    stderr.write(`[forge] Web server stopped.\n`)
     return { ok: true }
   } else if (result === 'already-dead') {
-    stderr.write(`[gsd] Web server was already stopped — cleared stale PID file.\n`)
+    stderr.write(`[forge] Web server was already stopped — cleared stale PID file.\n`)
     return { ok: true }
   } else {
-    stderr.write(`[gsd] Failed to stop web server: ${result.error}\n`)
+    stderr.write(`[forge] Failed to stop web server: ${result.error}\n`)
     return { ok: false, reason: result.error }
   }
 }
@@ -359,10 +359,10 @@ function needsWindowsShell(command: string, platform: NodeJS.Platform): boolean
 
 function formatLaunchStatus(status: WebModeLaunchStatus): string {
   if (status.ok) {
-    return `[gsd] Web mode startup: status=started cwd=${status.cwd} port=${status.port} host=${status.hostPath} kind=${status.hostKind} url=${status.url}\n`
+    return `[forge] Web mode startup: status=started cwd=${status.cwd} port=${status.port} host=${status.hostPath} kind=${status.hostKind} url=${status.url}\n`
   }
 
-  return `[gsd] Web mode startup: status=failed cwd=${status.cwd} port=${status.port ?? 'n/a'} host=${status.hostPath ?? 'unresolved'} kind=${status.hostKind} reason=${status.failureReason}\n`
+  return `[forge] Web mode startup: status=failed cwd=${status.cwd} port=${status.port ?? 'n/a'} host=${status.hostPath ?? 'unresolved'} kind=${status.hostKind} reason=${status.failureReason}\n`
 }
 
 function emitLaunchStatus(stderr: WritableLike, status: WebModeLaunchStatus): void {
@@ -475,7 +475,7 @@ async function waitForBootReady(url: string, timeoutMs = 180_000, stderr?: Writa
       if (response.statusCode >= 200 && response.statusCode < 300) {
         if (!hostUp) {
           hostUp = true
-          stderr?.write(`[gsd] Web host ready.\n`)
+          stderr?.write(`[forge] Web host ready.\n`)
         }
         consecutive5xx = 0
         // Host responded successfully — it's ready for the browser
@@ -508,9 +508,9 @@ async function waitForBootReady(url: string, timeoutMs = 180_000, stderr?: Writa
     if (now - lastTickAt >= TICKER_INTERVAL_MS) {
       lastTickAt = now
       if (hostUp) {
-        stderr?.write(`[gsd] Still waiting… (${elapsed()})\n`)
+        stderr?.write(`[forge] Still waiting… (${elapsed()})\n`)
       } else {
-        stderr?.write(`[gsd] Waiting for web host… (${elapsed()})\n`)
+        stderr?.write(`[forge] Waiting for web host… (${elapsed()})\n`)
       }
     }
 
@@ -532,14 +532,14 @@ function cleanupStaleInstance(cwd: string, stderr: WritableLike, registryPath?:
   const stale = registry[key]
   if (!stale) return
 
-  stderr.write(`[gsd] Cleaning up stale web server for ${key} (pid=${stale.pid}, port=${stale.port})…\n`)
+  stderr.write(`[forge] Cleaning up stale web server for ${key} (pid=${stale.pid}, port=${stale.port})…\n`)
   const result = killPid(stale.pid)
   if (result === 'killed') {
-    stderr.write(`[gsd] Killed stale web server (pid=${stale.pid}).\n`)
+    stderr.write(`[forge] Killed stale web server (pid=${stale.pid}).\n`)
   } else if (result === 'already-dead') {
-    stderr.write(`[gsd] Stale web server was already stopped (pid=${stale.pid}) — clearing entry.\n`)
+    stderr.write(`[forge] Stale web server was already stopped (pid=${stale.pid}) — clearing entry.\n`)
   } else {
-    stderr.write(`[gsd] Could not kill stale web server (pid=${stale.pid}): ${result.error}\n`)
+    stderr.write(`[forge] Could not kill stale web server (pid=${stale.pid}): ${result.error}\n`)
   }
   unregisterInstance(cwd, registryPath)
 }
@@ -574,7 +574,7 @@ export async function launchWebMode(
     return failure
   }
 
-  stderr.write(`[gsd] Starting web mode…\n`)
+  stderr.write(`[forge] Starting web mode…\n`)
 
   // Kill any stale server instance for this project before reserving a port.
   // This prevents EADDRINUSE when the previous `gsd --web` was terminated
@@ -600,7 +600,7 @@ export async function launchWebMode(
   }
 
   try {
-    stderr.write(`[gsd] Initialising resources…\n`)
+    stderr.write(`[forge] Initialising resources…\n`)
     const bootstrap = deps.initResources ? { initResources: deps.initResources } : await loadResourceBootstrap()
     bootstrap.initResources(options.agentDir)
   } catch (error) {
@@ -629,7 +629,7 @@ export async function launchWebMode(
     deps.execPath ?? process.execPath,
   )
 
-  stderr.write(`[gsd] Launching web host on port ${port}…\n`)
+  stderr.write(`[forge] Launching web host on port ${port}…\n`)
 
   const spawnResult = await spawnDetachedProcess(
     deps.spawn ?? ((command, args, spawnOptions) => spawn(command, args, spawnOptions)),
@@ -697,7 +697,7 @@ export async function launchWebMode(
     try {
       ;(deps.openBrowser ?? openBrowser)(authenticatedUrl)
     } catch (browserError) {
-      stderr.write(`[gsd] Could not open browser: ${browserError instanceof Error ? browserError.message : String(browserError)}\n`)
+      stderr.write(`[forge] Could not open browser: ${browserError instanceof Error ? browserError.message : String(browserError)}\n`)
     }
   } catch (error) {
     const failure: WebModeLaunchFailure = {
@@ -730,7 +730,7 @@ export async function launchWebMode(
     hostPath: resolution.entryPath,
     hostRoot: resolution.hostRoot,
   }
-  stderr.write(`[gsd] Ready → ${authenticatedUrl}\n`)
+  stderr.write(`[forge] Ready → ${authenticatedUrl}\n`)
   emitLaunchStatus(stderr, success)
   return success
 }
diff --git a/src/worktree-cli.ts b/src/worktree-cli.ts
index 70abba856..23e87c8df 100644
--- a/src/worktree-cli.ts
+++ b/src/worktree-cli.ts
@@ -302,10 +302,10 @@ async function handleStatusBanner(basePath: string): Promise<void> {
 
   const names = withChanges.map(w => chalk.cyan(w.name)).join(', ')
   process.stderr.write(
-    chalk.dim('[gsd] ') +
+    chalk.dim('[forge] ') +
     chalk.yellow(`${withChanges.length} worktree${withChanges.length === 1 ? '' : 's'} with unmerged changes: `) +
     names + '\n' +
-    chalk.dim('[gsd] ') +
+    chalk.dim('[forge] ') +
     chalk.dim('Resume: gsd -w <name>  |  Merge: gsd worktree merge <name>  |  List: gsd worktree list\n\n'),
   )
 }
@@ -378,7 +378,7 @@ async function createAndEnter(ext: ExtensionModules, basePath: string, name: str
 
     const hookError = ext.runWorktreePostCreateHook(basePath, info.path)
     if (hookError) {
-      process.stderr.write(chalk.yellow(`[gsd] ${hookError}\n`))
+      process.stderr.write(chalk.yellow(`[forge] ${hookError}\n`))
     }
 
     process.chdir(info.path)
@@ -389,7 +389,7 @@ async function createAndEnter(ext: ExtensionModules, basePath: string, name: str
     process.stderr.write(chalk.dim(`  branch ${info.branch}\n\n`))
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err)
-    process.stderr.write(chalk.red(`[gsd] Failed to create worktree: ${msg}\n`))
+    process.stderr.write(chalk.red(`[forge] Failed to create worktree: ${msg}\n`))
     process.exit(1)
   }
 }
diff --git a/web/components/sf/activity-view.tsx b/web/components/sf/activity-view.tsx
new file mode 100644
index 000000000..b0eacb014
--- /dev/null
+++ b/web/components/sf/activity-view.tsx
@@ -0,0 +1,78 @@
+"use client"
+
+import { CheckCircle2, Play, Clock, Terminal, AlertCircle } from "lucide-react"
+import { cn } from "@/lib/utils"
+import { useGSDWorkspaceState, type TerminalLineType } from "@/lib/sf-workspace-store"
+
+function EventIcon({ type }: { type: TerminalLineType }) {
+  const baseClass = "h-4 w-4"
+  switch (type) {
+    case "system":
+      return <Clock className={cn(baseClass, "text-info")} />
+    case "success":
+      return <CheckCircle2 className={cn(baseClass, "text-success")} />
+    case "error":
+      return <AlertCircle className={cn(baseClass, "text-destructive")} />
+    case "output":
+      return <Terminal className={cn(baseClass, "text-foreground")} />
+    case "input":
+      return <Play className={cn(baseClass, "text-warning")} />
+    default:
+      return <Clock className={cn(baseClass, "text-muted-foreground")} />
+  }
+}
+
+export function ActivityView() {
+  const workspace = useGSDWorkspaceState()
+  const terminalLines = workspace.terminalLines ?? []
+
+  // Show most recent events first
+  const reversedLines = [...terminalLines].reverse()
+
+  return (
+    <div className="flex h-full flex-col overflow-hidden">
+      <div className="border-b border-border px-6 py-3">
+        <h1 className="text-lg font-semibold">Activity Log</h1>
+        <p className="text-sm text-muted-foreground">
+          Execution history and git operations
+        </p>
+      </div>
+
+      <div className="flex-1 overflow-y-auto">
+        {reversedLines.length === 0 ? (
+          <div className="py-8 text-center text-sm text-muted-foreground">
+            No activity yet. Events will appear here once the workspace is active.
+          </div>
+        ) : (
+          <div className="relative px-6 py-4">
+            {/* Timeline line */}
+            <div className="absolute left-10 top-6 bottom-6 w-px bg-border" />
+
+            <div className="space-y-4">
+              {reversedLines.map((line) => (
+                <div key={line.id} className="relative flex gap-4">
+                  {/* Timeline dot */}
+                  <div className="relative z-10 flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-full border border-border bg-card">
+                    <EventIcon type={line.type} />
+                  </div>
+
+                  {/* Content */}
+                  <div className="flex-1 pt-0.5">
+                    <div className="flex items-start justify-between gap-4">
+                      <div>
+                        <p className="text-sm font-medium">{line.content}</p>
+                      </div>
+                      <span className="flex-shrink-0 font-mono text-xs text-muted-foreground">
+                        {line.timestamp}
+                      </span>
+                    </div>
+                  </div>
+                </div>
+              ))}
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
diff --git a/web/components/sf/app-shell.tsx b/web/components/sf/app-shell.tsx
new file mode 100644
index 000000000..df37b3ed9
--- /dev/null
+++ b/web/components/sf/app-shell.tsx
@@ -0,0 +1,605 @@
+"use client"
+
+import Image from "next/image"
+import { useState, useEffect, useCallback, useRef, useSyncExternalStore } from "react"
+import { Menu, X } from "lucide-react"
+import { Sidebar, MilestoneExplorer, CollapsedMilestoneSidebar } from "@/components/sf/sidebar"
+import { ShellTerminal } from "@/components/sf/shell-terminal"
+import { Dashboard } from "@/components/sf/dashboard"
+import { Roadmap } from "@/components/sf/roadmap"
+import { FilesView } from "@/components/sf/files-view"
+import { ActivityView } from "@/components/sf/activity-view"
+import { VisualizerView } from "@/components/sf/visualizer-view"
+import { StatusBar } from "@/components/sf/status-bar"
+import { DualTerminal } from "@/components/sf/dual-terminal"
+import { FocusedPanel } from "@/components/sf/focused-panel"
+import { OnboardingGate } from "@/components/sf/onboarding-gate"
+import { CommandSurface } from "@/components/sf/command-surface"
+import { DevOverridesProvider } from "@/lib/dev-overrides"
+import { ProjectStoreManagerProvider, useProjectStoreManager } from "@/lib/project-store-manager"
+import { Skeleton } from "@/components/ui/skeleton"
+import { cn } from "@/lib/utils"
+import { toast } from "sonner"
+import {
+  GSDWorkspaceProvider,
+  getCurrentScopeLabel,
+  getProjectDisplayName,
+  getStatusPresentation,
+  getVisibleWorkspaceError,
+  useGSDWorkspaceState,
+  useGSDWorkspaceActions,
+} from "@/lib/sf-workspace-store"
+import { ChatMode } from "@/components/sf/chat-mode"
+import { ScopeBadge } from "@/components/sf/scope-badge"
+import { Badge } from "@/components/ui/badge"
+import { ProjectsPanel, ProjectSelectionGate } from "@/components/sf/projects-view"
+import { UpdateBanner } from "@/components/sf/update-banner"
+import { getAuthToken } from "@/lib/auth"
+
+const KNOWN_VIEWS = new Set(["dashboard", "power", "chat", "roadmap", "files", "activity", "visualize"])
+
+function viewStorageKey(projectCwd: string): string {
+  return `gsd-active-view:${projectCwd}`
+}
+
+function WorkspaceChrome() {
+  const [activeView, setActiveView] = useState("dashboard")
+  const [isTerminalExpanded, setIsTerminalExpanded] = useState(false)
+  const [terminalHeight, setTerminalHeight] = useState(300)
+  const [terminalDragActive, setTerminalDragActive] = useState(false)
+  const isDraggingTerminal = useRef(false)
+  const didDragTerminal = useRef(false)
+  const dragStartY = useRef(0)
+  const dragStartHeight = useRef(0)
+  const [sidebarWidth, setSidebarWidth] = useState(256)
+  const isDraggingSidebar = useRef(false)
+  const dragStartX = useRef(0)
+  const dragStartWidth = useRef(0)
+  const [sidebarCollapsed, setSidebarCollapsed] = useState(false)
+  const [viewRestored, setViewRestored] = useState(false)
+  const [projectsPanelOpen, setProjectsPanelOpen] = useState(false)
+  const [mobileNavOpen, setMobileNavOpen] = useState(false)
+  const [mobileMilestoneOpen, setMobileMilestoneOpen] = useState(false)
+  const workspace = useGSDWorkspaceState()
+  const { refreshBoot } = useGSDWorkspaceActions()
+
+  const status = getStatusPresentation(workspace)
+  const projectPath = workspace.boot?.project.cwd
+  const projectLabel = getProjectDisplayName(projectPath)
+  const titleOverride = workspace.titleOverride?.trim() || null
+  const scopeLabel = getCurrentScopeLabel(workspace.boot?.workspace)
+  const visibleError = getVisibleWorkspaceError(workspace)
+
+  // Restore persisted view once boot provides projectCwd
+  useEffect(() => {
+    if (viewRestored || !projectPath) return
+    const restoreTimer = window.setTimeout(() => {
+      try {
+        const stored = sessionStorage.getItem(viewStorageKey(projectPath))
+        if (stored && KNOWN_VIEWS.has(stored)) {
+          setActiveView(stored)
+        }
+      } catch {
+        // sessionStorage may be unavailable (e.g. SSR, iframe sandbox)
+      }
+      setViewRestored(true)
+    }, 0)
+    return () => window.clearTimeout(restoreTimer)
+  }, [projectPath, viewRestored])
+
+  // Reset viewRestored when projectPath changes so the restore effect can
+  // fire for the newly-selected project (fixes #2711: tab reset on switch).
+  const prevProjectPath = useRef(projectPath)
+  useEffect(() => {
+    if (prevProjectPath.current !== projectPath) {
+      prevProjectPath.current = projectPath
+      setViewRestored(false)
+    }
+  }, [projectPath])
+
+  // Persist view changes to sessionStorage
+  useEffect(() => {
+    if (!projectPath) return
+    try {
+      sessionStorage.setItem(viewStorageKey(projectPath), activeView)
+    } catch {
+      // sessionStorage may be unavailable
+    }
+  }, [activeView, projectPath])
+
+  // Restore sidebar collapsed state from localStorage
+  useEffect(() => {
+    const restoreTimer = window.setTimeout(() => {
+      try {
+        const stored = localStorage.getItem("gsd-sidebar-collapsed")
+        if (stored === "true") setSidebarCollapsed(true)
+      } catch {
+        // localStorage may be unavailable
+      }
+    }, 0)
+    return () => window.clearTimeout(restoreTimer)
+  }, [])
+
+  // Persist sidebar collapsed state
+  useEffect(() => {
+    try {
+      localStorage.setItem("gsd-sidebar-collapsed", String(sidebarCollapsed))
+    } catch {
+      // localStorage may be unavailable
+    }
+  }, [sidebarCollapsed])
+
+  useEffect(() => {
+    if (typeof document === "undefined") return
+    const base = projectLabel ? `GSD - ${projectLabel}` : "GSD"
+    document.title = titleOverride ? `${titleOverride} · ${base}` : base
+  }, [titleOverride, projectLabel])
+
+  // Close mobile nav on view change
+  const handleViewChange = useCallback((view: string) => {
+    setActiveView(view)
+    setMobileNavOpen(false)
+  }, [])
+
+  // Listen for cross-component file navigation events (e.g. sidebar task clicks)
+  useEffect(() => {
+    const handler = () => {
+      setActiveView("files")
+    }
+    window.addEventListener("gsd:open-file", handler)
+    return () => window.removeEventListener("gsd:open-file", handler)
+  }, [])
+
+  // Listen for cross-component view navigation events (e.g. /gsd visualize dispatch)
+  useEffect(() => {
+    const handler = (e: CustomEvent<{ view: string }>) => {
+      if (KNOWN_VIEWS.has(e.detail.view)) {
+        handleViewChange(e.detail.view)
+      }
+    }
+    window.addEventListener("gsd:navigate-view", handler as EventListener)
+    return () => window.removeEventListener("gsd:navigate-view", handler as EventListener)
+  }, [handleViewChange])
+
+  // Listen for projects panel toggle (sidebar icon, or programmatic)
+  useEffect(() => {
+    const handler = () => setProjectsPanelOpen(true)
+    window.addEventListener("gsd:open-projects", handler)
+    return () => window.removeEventListener("gsd:open-projects", handler)
+  }, [])
+
+  // Terminal + sidebar panel drag-to-resize
+  useEffect(() => {
+    const handleMouseMove = (e: MouseEvent) => {
+      if (isDraggingTerminal.current) {
+        didDragTerminal.current = true
+        const delta = dragStartY.current - e.clientY
+        const newHeight = Math.max(150, Math.min(600, dragStartHeight.current + delta))
+        setTerminalHeight(newHeight)
+      }
+      if (isDraggingSidebar.current) {
+        const delta = dragStartX.current - e.clientX
+        const newWidth = Math.max(180, Math.min(480, dragStartWidth.current + delta))
+        setSidebarWidth(newWidth)
+      }
+    }
+    const handleMouseUp = () => {
+      isDraggingTerminal.current = false
+      isDraggingSidebar.current = false
+      setTerminalDragActive(false)
+      document.body.style.cursor = ""
+      document.body.style.userSelect = ""
+    }
+    document.addEventListener("mousemove", handleMouseMove)
+    document.addEventListener("mouseup", handleMouseUp)
+    return () => {
+      document.removeEventListener("mousemove", handleMouseMove)
+      document.removeEventListener("mouseup", handleMouseUp)
+    }
+  }, [])
+
+  const handleTerminalDragStart = useCallback(
+    (e: React.MouseEvent) => {
+      isDraggingTerminal.current = true
+      setTerminalDragActive(true)
+      dragStartY.current = e.clientY
+      dragStartHeight.current = terminalHeight
+      document.body.style.cursor = "row-resize"
+      document.body.style.userSelect = "none"
+    },
+    [terminalHeight],
+  )
+
+  const handleSidebarDragStart = useCallback(
+    (e: React.MouseEvent) => {
+      isDraggingSidebar.current = true
+      dragStartX.current = e.clientX
+      dragStartWidth.current = sidebarWidth
+      document.body.style.cursor = "col-resize"
+      document.body.style.userSelect = "none"
+    },
+    [sidebarWidth],
+  )
+
+  const retryDisabled = !!workspace.commandInFlight || workspace.onboardingRequestState !== "idle"
+  const isConnecting = workspace.bootStatus === "idle" || workspace.bootStatus === "loading"
+
+  // Persistent loading toast — dismissed the moment boot completes
+  useEffect(() => {
+    if (!isConnecting) return
+    const id = toast.loading("Connecting to workspace…", {
+      description: "Establishing the live bridge session",
+      duration: Infinity,
+    })
+    return () => {
+      toast.dismiss(id)
+    }
+  }, [isConnecting])
+
+  // Detect project welcome state — hide chrome for v1-legacy, brownfield, blank projects
+  const detection = workspace.boot?.projectDetection
+  const isWelcomeState =
+    !isConnecting &&
+    activeView === "dashboard" &&
+    detection != null &&
+    detection.kind !== "active-gsd" &&
+    detection.kind !== "empty-gsd"
+
+  // --- Unauthenticated gate ---
+  // Render a clear recovery screen before any workspace chrome is mounted so
+  // users who open a manually-typed URL (no #token= fragment) get actionable
+  // guidance instead of a cascade of 401 errors.
+  if (workspace.bootStatus === "unauthenticated") {
+    return (
+      <div className="flex h-dvh flex-col items-center justify-center gap-6 bg-background p-8 text-center">
+        <Image
+          src="/logo-black.svg"
+          alt="GSD"
+          width={57}
+          height={16}
+          className="shrink-0 h-4 w-auto dark:hidden"
+        />
+        <Image
+          src="/logo-white.svg"
+          alt="GSD"
+          width={57}
+          height={16}
+          className="shrink-0 h-4 w-auto hidden dark:block"
+        />
+        <div className="flex flex-col items-center gap-2">
+          <h1 className="text-lg font-semibold text-foreground">Authentication Required</h1>
+          <p className="max-w-sm text-sm text-muted-foreground">
+            This workspace requires an auth token. Copy the full URL from your terminal
+            (including the{" "}
+            <code className="rounded bg-muted px-1 py-0.5 font-mono text-xs">#token=…</code>{" "}
+            part) or restart with{" "}
+            <code className="rounded bg-muted px-1 py-0.5 font-mono text-xs">gsd --web</code>.
+          </p>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="relative flex h-screen flex-col overflow-hidden bg-background text-foreground">
+      <header className="flex h-12 flex-shrink-0 items-center justify-between border-b border-border bg-card px-2 md:px-4">
+        <div className="flex items-center gap-2 md:gap-3 min-w-0">
+          {/* Mobile hamburger menu */}
+          <button
+            className="flex md:hidden h-10 w-10 items-center justify-center rounded-md text-muted-foreground hover:bg-accent/50 hover:text-foreground transition-colors"
+            onClick={() => setMobileNavOpen(!mobileNavOpen)}
+            aria-label={mobileNavOpen ? "Close navigation" : "Open navigation"}
+            data-testid="mobile-nav-toggle"
+          >
+            {mobileNavOpen ? <X className="h-5 w-5" /> : <Menu className="h-5 w-5" />}
+          </button>
+          <div className="flex items-center gap-2">
+            <Image
+              src="/logo-black.svg"
+              alt="GSD"
+              width={57}
+              height={16}
+              className="shrink-0 h-4 w-auto dark:hidden"
+            />
+            <Image
+              src="/logo-white.svg"
+              alt="GSD"
+              width={57}
+              height={16}
+              className="shrink-0 h-4 w-auto hidden dark:block"
+            />
+            <Badge variant="outline" className="hidden sm:inline-flex text-[10px] rounded-full border-foreground/15 bg-accent/40 text-muted-foreground font-normal">
+              beta
+            </Badge>
+          </div>
+          <span className="hidden sm:inline text-2xl font-thin text-muted-foreground leading-none select-none">/</span>
+          <span className="hidden sm:inline text-sm text-muted-foreground truncate" data-testid="workspace-project-cwd" title={projectPath ?? undefined}>
+            {isConnecting ? (
+              <Skeleton className="inline-block h-4 w-28 align-middle" />
+            ) : (
+              <>
+                {projectLabel}
+                {titleOverride && (
+                  <span
+                    className="ml-2 inline-flex items-center rounded-full border border-foreground/15 bg-accent/60 px-2 py-0.5 text-[10px] font-medium text-foreground"
+                    data-testid="workspace-title-override"
+                    title={titleOverride}
+                  >
+                    {titleOverride}
+                  </span>
+                )}
+              </>
+            )}
+          </span>
+        </div>
+
+        <div className="flex items-center gap-2 md:gap-3">
+          {/* Hidden status marker for test instrumentation */}
+          <span className="sr-only" data-testid="workspace-connection-status">{status.label}</span>
+          <span
+            className="hidden sm:inline text-xs text-muted-foreground"
+            data-testid="workspace-scope-label"
+          >
+            {isConnecting ? <Skeleton className="inline-block h-3.5 w-40 align-middle" /> : <ScopeBadge label={scopeLabel} size="sm" />}
+          </span>
+        </div>
+      </header>
+
+      <UpdateBanner />
+
+      {!isConnecting && visibleError && (
+        <div
+          className="flex items-center gap-3 border-b border-destructive/20 bg-destructive/10 px-4 py-2 text-xs text-destructive"
+          data-testid="workspace-error-banner"
+        >
+          <span className="flex-1">{visibleError}</span>
+          <button
+            onClick={() => void refreshBoot()}
+            disabled={retryDisabled}
+            className={cn(
+              "flex-shrink-0 rounded border border-destructive/30 bg-background px-2 py-0.5 text-xs font-medium text-destructive transition-colors hover:bg-destructive/10",
+              retryDisabled && "cursor-not-allowed opacity-50",
+            )}
+          >
+            Retry
+          </button>
+        </div>
+      )}
+
+      {/* Mobile navigation drawer */}
+      {mobileNavOpen && (
+        <div
+          className="fixed inset-0 z-40 bg-black/50 md:hidden"
+          onClick={() => setMobileNavOpen(false)}
+          data-testid="mobile-nav-overlay"
+        />
+      )}
+      <div
+        className={cn(
+          "fixed inset-y-0 left-0 z-50 w-64 transform bg-sidebar border-r border-border transition-transform duration-200 ease-out md:hidden",
+          mobileNavOpen ? "translate-x-0" : "-translate-x-full",
+        )}
+        data-testid="mobile-nav-drawer"
+      >
+        <Sidebar activeView={activeView} onViewChange={isConnecting ? () => {} : handleViewChange} isConnecting={isConnecting} mobile />
+      </div>
+
+      {/* Mobile milestone drawer */}
+      {mobileMilestoneOpen && (
+        <div
+          className="fixed inset-0 z-40 bg-black/50 md:hidden"
+          onClick={() => setMobileMilestoneOpen(false)}
+          data-testid="mobile-milestone-overlay"
+        />
+      )}
+      {!isWelcomeState && (
+        <div
+          className={cn(
+            "fixed inset-y-0 right-0 z-50 w-72 transform bg-sidebar border-l border-border transition-transform duration-200 ease-out md:hidden",
+            mobileMilestoneOpen ? "translate-x-0" : "translate-x-full",
+          )}
+          data-testid="mobile-milestone-drawer"
+        >
+          <MilestoneExplorer
+            isConnecting={isConnecting}
+            width={288}
+            onCollapse={() => setMobileMilestoneOpen(false)}
+          />
+        </div>
+      )}
+
+      <div className="flex flex-1 overflow-hidden">
+        {/* Desktop sidebar — hidden on mobile */}
+        <div className="hidden md:flex">
+          <Sidebar activeView={activeView} onViewChange={isConnecting ? () => {} : handleViewChange} isConnecting={isConnecting} />
+        </div>
+
+        <div className="flex flex-1 flex-col overflow-hidden">
+          <div
+            className={cn(
+              "flex-1 overflow-hidden transition-all",
+              isTerminalExpanded && "h-1/3",
+            )}
+          >
+            {isConnecting ? (
+              <Dashboard />
+            ) : (
+              <>
+                {activeView === "dashboard" && (
+                  <Dashboard
+                    onSwitchView={handleViewChange}
+                    onExpandTerminal={() => setIsTerminalExpanded(true)}
+                  />
+                )}
+                {activeView === "power" && <DualTerminal />}
+                {activeView === "roadmap" && <Roadmap />}
+                {activeView === "files" && <FilesView />}
+                {activeView === "activity" && <ActivityView />}
+                {activeView === "visualize" && <VisualizerView />}
+                {activeView === "chat" && <ChatMode />}
+              </>
+            )}
+          </div>
+
+          {activeView !== "power" && activeView !== "chat" && (
+            <div className="border-t border-border flex flex-col" style={{ flexShrink: 0 }}>
+              {/* Drag handle + toggle header — entire bar is clickable */}
+              <div
+                role="button"
+                tabIndex={0}
+                onClick={() => {
+                  if (didDragTerminal.current) {
+                    didDragTerminal.current = false
+                    return
+                  }
+                  if (!isConnecting) setIsTerminalExpanded(!isTerminalExpanded)
+                }}
+                onKeyDown={(e) => {
+                  if (e.key === "Enter" || e.key === " ") {
+                    e.preventDefault()
+                    if (!isConnecting) setIsTerminalExpanded(!isTerminalExpanded)
+                  }
+                }}
+                className={cn(
+                  "flex h-8 w-full items-center justify-between bg-card px-3 text-xs select-none transition-colors",
+                  isTerminalExpanded && "cursor-row-resize",
+                  !isTerminalExpanded && !isConnecting && "cursor-pointer hover:bg-muted/50",
+                  isConnecting && "cursor-default",
+                )}
+                onMouseDown={(e) => {
+                  if (isTerminalExpanded) handleTerminalDragStart(e)
+                }}
+              >
+                <div className="flex items-center gap-2 text-muted-foreground">
+                  <span className="font-medium text-foreground">Terminal</span>
+                  <span className="text-[10px] text-muted-foreground">
+                    {isTerminalExpanded ? "▼" : "▲"}
+                  </span>
+                </div>
+              </div>
+              {/* Terminal content */}
+              <div
+                className="overflow-hidden"
+                style={{ height: isTerminalExpanded ? terminalHeight : 0, transition: terminalDragActive ? "none" : "height 200ms" }}
+              >
+                <ShellTerminal className="h-full" projectCwd={workspace.boot?.project.cwd} />
+              </div>
+            </div>
+          )}
+        </div>
+
+        {/* Resizable milestone sidebar — hidden on mobile, hidden during project welcome */}
+        {!isWelcomeState && !sidebarCollapsed && (
+          <div
+            className="relative hidden md:flex h-full items-stretch"
+            style={{ flexShrink: 0 }}
+          >
+            {/* Thin visible border */}
+            <div className="w-px bg-border" />
+            {/* Wide invisible grab area overlapping the border */}
+            <div
+              className="absolute left-[-3px] top-0 bottom-0 w-[7px] cursor-col-resize z-10 hover:bg-muted-foreground/20 transition-colors"
+              onMouseDown={handleSidebarDragStart}
+            />
+          </div>
+        )}
+        <div className="hidden md:flex">
+          {!isWelcomeState && (sidebarCollapsed ? (
+            <CollapsedMilestoneSidebar onExpand={() => setSidebarCollapsed(false)} />
+          ) : (
+            <MilestoneExplorer
+              isConnecting={isConnecting}
+              width={sidebarWidth}
+              onCollapse={() => setSidebarCollapsed(true)}
+            />
+          ))}
+        </div>
+      </div>
+
+      {/* Desktop status bar — hidden on mobile */}
+      <div className="hidden md:block">
+        <StatusBar />
+      </div>
+
+      {/* Mobile bottom bar — quick access to milestones + status */}
+      {!isWelcomeState && (
+        <div className="flex md:hidden h-12 items-center justify-between border-t border-border bg-card px-3" data-testid="mobile-bottom-bar">
+          <div className="flex items-center gap-2 text-xs text-muted-foreground truncate">
+            <span className="sr-only" data-testid="workspace-connection-status-mobile">{status.label}</span>
+            <span className={cn("h-2 w-2 rounded-full shrink-0", status.tone === "success" ? "bg-success" : status.tone === "warning" ? "bg-warning" : status.tone === "danger" ? "bg-destructive" : "bg-muted-foreground")} />
+            <span className="truncate">{scopeLabel}</span>
+          </div>
+          <button
+            onClick={() => setMobileMilestoneOpen(!mobileMilestoneOpen)}
+            className="flex h-10 items-center gap-2 rounded-md px-3 text-xs font-medium text-muted-foreground hover:bg-accent/50 hover:text-foreground transition-colors"
+            data-testid="mobile-milestone-toggle"
+          >
+            Milestones
+          </button>
+        </div>
+      )}
+
+      <ProjectsPanel open={projectsPanelOpen} onOpenChange={setProjectsPanelOpen} />
+      <CommandSurface />
+      <FocusedPanel />
+      <OnboardingGate />
+    </div>
+  )
+}
+
+export function GSDAppShell() {
+  // Extract the auth token from the URL fragment on first render.
+  // Must happen before any API calls fire.
+  getAuthToken()
+
+  return (
+    <ProjectStoreManagerProvider>
+      <ProjectAwareWorkspace />
+    </ProjectStoreManagerProvider>
+  )
+}
+
+function ProjectAwareWorkspace() {
+  const manager = useProjectStoreManager()
+  const activeProjectCwd = useSyncExternalStore(manager.subscribe, manager.getSnapshot, manager.getSnapshot)
+  const activeStore = activeProjectCwd ? manager.getActiveStore() : null
+
+  // Shut down all projects when the tab actually closes.
+  // IMPORTANT: pagehide fires both on real page unload AND on mobile/Safari
+  // tab switches (bfcache entry).  When event.persisted is true the page is
+  // being cached for later reuse — the server must stay alive.  Only send
+  // the shutdown beacon when the page is truly being discarded.
+  useEffect(() => {
+    const handlePageHide = (event: PageTransitionEvent) => {
+      if (event.persisted) {
+        // Page is entering bfcache (tab switch, app backgrounding) — keep
+        // the server alive so PTY sessions survive.
+        return
+      }
+      // sendBeacon cannot set custom headers, so pass the auth token as a
+      // query parameter instead (the proxy accepts `_token` as a fallback).
+      const token = getAuthToken()
+      const url = token ? `/api/shutdown?_token=${token}` : "/api/shutdown"
+      navigator.sendBeacon(url, "")
+    }
+
+    window.addEventListener("pagehide", handlePageHide)
+
+    return () => {
+      window.removeEventListener("pagehide", handlePageHide)
+    }
+  }, [])
+
+  // No project selected yet — show project selection gate
+  if (!activeProjectCwd || !activeStore) {
+    return <ProjectSelectionGate />
+  }
+
+  return (
+    <GSDWorkspaceProvider store={activeStore}>
+      <DevOverridesProvider>
+        <WorkspaceChrome />
+      </DevOverridesProvider>
+    </GSDWorkspaceProvider>
+  )
+}
diff --git a/web/components/sf/chat-mode.tsx b/web/components/sf/chat-mode.tsx
new file mode 100644
index 000000000..68a37cbad
--- /dev/null
+++ b/web/components/sf/chat-mode.tsx
@@ -0,0 +1,2346 @@
+"use client"
+
+import Image from "next/image"
+import { useEffect, useRef, useCallback, useState, useMemo, KeyboardEvent, DragEvent, ClipboardEvent } from "react"
+import { MessagesSquare, SendHorizonal, Check, Eye, EyeOff, Play, Loader2, Milestone, X, MessageCircle, FileEdit, FilePlus, Terminal, ChevronDown, ChevronRight, MoreHorizontal, Zap, Square, Pause, BarChart3, LayoutGrid, ListOrdered, History, Compass, PenLine, Inbox, SkipForward, Undo2, BookOpen, Settings, SlidersHorizontal, Stethoscope, FileOutput, Trash2, Globe, type LucideIcon } from "lucide-react"
+import { cn } from "@/lib/utils"
+import { Input } from "@/components/ui/input"
+import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@/components/ui/tooltip"
+import { Popover, PopoverTrigger, PopoverContent } from "@/components/ui/popover"
+import { ChatMessage, TuiPrompt } from "@/lib/pty-chat-parser"
+import { PendingImage, processImageFile, generateImageId, MAX_PENDING_IMAGES } from "@/lib/image-utils"
+import {
+  useGSDWorkspaceState,
+  useGSDWorkspaceActions,
+  buildPromptCommand,
+  type CompletedToolExecution,
+  type ActiveToolExecution,
+  type PendingUiRequest,
+  type TurnSegment,
+} from "@/lib/sf-workspace-store"
+import { deriveWorkflowAction } from "@/lib/workflow-actions"
+import { useTerminalFontSize } from "@/lib/use-terminal-font-size"
+
+/* ─── ActionPanel types ─── */
+
+// ActionPanelConfig removed — all commands now route through the main bridge.
+
+/* ─── GSD Action Definitions ─── */
+
+/**
+ * Defines every /gsd subcommand available in the chat input bar.
+ * Top 3 are shown as standalone buttons; the rest live in the overflow menu.
+ * All commands dispatch through the main bridge session.
+ */
+interface GSDActionDef {
+  label: string
+  command: string
+  icon: LucideIcon
+  description: string
+  category: "workflow" | "visibility" | "correction" | "knowledge" | "config" | "maintenance"
+  /** When true, this command is disabled while auto-mode is active (injects competing LLM prompt) */
+  disabledDuringAuto?: boolean
+}
+
+const GSD_ACTIONS: GSDActionDef[] = [
+  // ── Top 3 (standalone buttons) ──
+  { label: "Discuss",   command: "/gsd discuss",   icon: MessageCircle,     description: "Start guided milestone/slice discussion",                    category: "workflow",    disabledDuringAuto: true },
+  { label: "Next",      command: "/gsd next",      icon: Play,              description: "Execute next task, then pause",                              category: "workflow" },
+  { label: "Auto",      command: "/gsd auto",      icon: Zap,               description: "Run all queued units continuously",                         category: "workflow" },
+  // ── Overflow: Workflow ──
+  { label: "Stop",      command: "/gsd stop",      icon: Square,            description: "Stop auto-mode gracefully",                                  category: "workflow" },
+  { label: "Pause",     command: "/gsd pause",     icon: Pause,             description: "Pause auto-mode (preserves state)",                          category: "workflow" },
+  // ── Overflow: Visibility ──
+  { label: "Status",    command: "/gsd status",    icon: BarChart3,         description: "Show progress dashboard",                                    category: "visibility" },
+  { label: "Visualize", command: "/gsd visualize", icon: LayoutGrid,        description: "Interactive TUI (progress, deps, metrics, timeline)",        category: "visibility" },
+  { label: "Queue",     command: "/gsd queue",     icon: ListOrdered,       description: "Show queued/dispatched units and execution order",            category: "visibility" },
+  { label: "History",   command: "/gsd history",   icon: History,           description: "View execution history with cost/phase/model details",        category: "visibility" },
+  // ── Overflow: Course correction ──
+  { label: "Steer",     command: "/gsd steer",     icon: Compass,           description: "Apply user override to active work",                         category: "correction" },
+  { label: "Capture",   command: "/gsd capture",   icon: PenLine,           description: "Quick-capture a thought to CAPTURES.md",                     category: "correction" },
+  { label: "Triage",    command: "/gsd triage",    icon: Inbox,             description: "Classify and route pending captures",                        category: "correction",  disabledDuringAuto: true },
+  { label: "Skip",      command: "/gsd skip",      icon: SkipForward,       description: "Prevent a unit from auto-mode dispatch",                     category: "correction" },
+  { label: "Undo",      command: "/gsd undo",      icon: Undo2,             description: "Revert last completed unit",                                 category: "correction" },
+  // ── Overflow: Knowledge ──
+  { label: "Knowledge", command: "/gsd knowledge", icon: BookOpen,          description: "Add rule, pattern, or lesson to KNOWLEDGE.md",               category: "knowledge" },
+  // ── Overflow: Configuration ──
+  { label: "Mode",      command: "/gsd mode",      icon: SlidersHorizontal, description: "Set workflow mode (solo/team)",                               category: "config" },
+  { label: "Prefs",     command: "/gsd prefs",     icon: Settings,          description: "Manage preferences (global/project)",                        category: "config" },
+  // ── Overflow: Maintenance ──
+  { label: "Doctor",    command: "/gsd doctor",    icon: Stethoscope,       description: "Diagnose and repair .gsd/ state",                            category: "maintenance" },
+  { label: "Export",    command: "/gsd export",    icon: FileOutput,        description: "Export milestone/slice results (JSON or Markdown)",           category: "maintenance" },
+  { label: "Cleanup",   command: "/gsd cleanup",   icon: Trash2,            description: "Remove merged branches or snapshots",                        category: "maintenance" },
+  { label: "Remote",    command: "/gsd remote",    icon: Globe,             description: "Control remote auto-mode (Slack/Discord)",                    category: "maintenance" },
+]
+
+/** Top 3 shown as standalone buttons next to chat input */
+const TOP_ACTIONS = GSD_ACTIONS.slice(0, 3)
+/** Remaining actions in the overflow menu */
+const OVERFLOW_ACTIONS = GSD_ACTIONS.slice(3)
+
+const CATEGORY_LABELS: Record<GSDActionDef["category"], string> = {
+  workflow: "Workflow",
+  visibility: "Visibility",
+  correction: "Course Correction",
+  knowledge: "Knowledge",
+  config: "Configuration",
+  maintenance: "Maintenance",
+}
+
+function groupByCategory(actions: GSDActionDef[]): Array<{ category: GSDActionDef["category"]; label: string; items: GSDActionDef[] }> {
+  const seen = new Map<GSDActionDef["category"], GSDActionDef[]>()
+  for (const a of actions) {
+    let group = seen.get(a.category)
+    if (!group) {
+      group = []
+      seen.set(a.category, group)
+    }
+    group.push(a)
+  }
+  return Array.from(seen.entries()).map(([cat, items]) => ({ category: cat, label: CATEGORY_LABELS[cat], items }))
+}
+
+/**
+ * ChatMode — main view for the Chat tab.
+ *
+ * All /gsd commands dispatch through the main bridge session.
+ * Commands that inject competing LLM prompts (discuss, triage)
+ * are disabled while auto-mode is active.
+ *
+ * Observability:
+ *   - This component mounts only when activeView === "chat" (no hidden pre-init).
+ *   - sessionStorage key "gsd-active-view:<cwd>" equals "chat" when this view is active.
+ *   - Header toolbar: data-testid="chat-mode-action-bar" confirms toolbar rendered.
+ *   - Primary button: data-testid="chat-primary-action" reflects current workflowAction label.
+ *   - Secondary buttons: data-testid="chat-secondary-action-{command}".
+ */
+export function ChatMode({ className }: { className?: string }) {
+  const state = useGSDWorkspaceState()
+  const { sendCommand } = useGSDWorkspaceActions()
+
+  const bridge = state.boot?.bridge ?? null
+
+  const handleAction = useCallback(
+    (command: string) => {
+      void sendCommand(buildPromptCommand(command, bridge))
+    },
+    [sendCommand, bridge],
+  )
+
+  return (
+    <div className={cn("flex h-full flex-col overflow-hidden bg-background", className)}>
+      {/* ── Header bar ── */}
+      <ChatModeHeader
+        onPrimaryAction={handleAction}
+        onSecondaryAction={handleAction}
+      />
+
+      {/* ── Main chat pane ── */}
+      <ChatPane
+        sessionId="gsd-main"
+        command="gsd"
+        className="flex-1"
+        onOpenAction={(action) => handleAction(action.command)}
+      />
+    </div>
+  )
+}
+
+/* ─── Header ─── */
+
+interface ChatModeHeaderProps {
+  onPrimaryAction: (command: string) => void
+  onSecondaryAction: (command: string) => void
+}
+
+/**
+ * ChatModeHeader — action toolbar for Chat Mode.
+ *
+ * Single-row layout matching the Power User Mode header: title + badge left-aligned,
+ * workflow action buttons immediately to the right (no second row).
+ *
+ * Observability:
+ *   - data-testid="chat-mode-action-bar" on the workflow button row
+ *   - data-testid="chat-primary-action" on the primary button
+ *   - data-testid="chat-secondary-action-{command}" on each secondary button
+ */
+function ChatModeHeader({ onPrimaryAction, onSecondaryAction }: ChatModeHeaderProps) {
+  const state = useGSDWorkspaceState()
+
+  const boot = state.boot
+  const workspace = boot?.workspace ?? null
+  const auto = boot?.auto ?? null
+
+  const workflowAction = deriveWorkflowAction({
+    phase: workspace?.active.phase ?? "pre-planning",
+    autoActive: auto?.active ?? false,
+    autoPaused: auto?.paused ?? false,
+    onboardingLocked: boot?.onboarding.locked ?? false,
+    commandInFlight: state.commandInFlight,
+    bootStatus: state.bootStatus,
+    hasMilestones: (workspace?.milestones.length ?? 0) > 0,
+    projectDetectionKind: boot?.projectDetection?.kind ?? null,
+  })
+
+  const handlePrimary = () => {
+    if (!workflowAction.primary) return
+    onPrimaryAction(workflowAction.primary.command)
+  }
+
+  // Derive a short GSD state badge label
+  const stateBadge = (() => {
+    if (state.bootStatus !== "ready") return state.bootStatus
+    const phase = workspace?.active.phase
+    if (!phase) return "idle"
+    if (auto?.active && !auto?.paused) return "auto"
+    if (auto?.paused) return "paused"
+    return phase
+  })()
+
+  return (
+    <div className="flex items-center justify-between border-b border-border bg-card px-4 py-2">
+      {/* Left: title + state badge */}
+      <div className="flex items-center gap-2">
+        <MessagesSquare className="h-4 w-4 text-muted-foreground" />
+        <span className="font-medium">Chat Mode</span>
+        <span className="rounded-full border border-border bg-muted px-2 py-0.5 text-[10px] font-medium text-muted-foreground uppercase tracking-wide">
+          {stateBadge}
+        </span>
+      </div>
+
+      {/* Right: workflow action buttons */}
+      <div className="flex items-center gap-2" data-testid="chat-mode-action-bar">
+          {workflowAction.primary && (
+            <button
+              data-testid="chat-primary-action"
+              onClick={handlePrimary}
+              disabled={workflowAction.disabled}
+              className={cn(
+                "inline-flex items-center gap-1.5 rounded-md px-3 py-1 text-xs font-medium transition-colors",
+                workflowAction.primary.variant === "destructive"
+                  ? "bg-destructive text-destructive-foreground hover:bg-destructive/90"
+                  : "bg-primary text-primary-foreground hover:bg-primary/90",
+                workflowAction.disabled && "cursor-not-allowed opacity-50",
+              )}
+              title={workflowAction.disabledReason}
+            >
+              {state.commandInFlight ? (
+                <Loader2 className="h-3 w-3 animate-spin" />
+              ) : workflowAction.isNewMilestone ? (
+                <Milestone className="h-3 w-3" />
+              ) : (
+                <Play className="h-3 w-3" />
+              )}
+              {workflowAction.primary.label}
+            </button>
+          )}
+          {workflowAction.secondaries.map((action) => (
+            <button
+              key={action.command}
+              data-testid={`chat-secondary-action-${action.command}`}
+              onClick={() => onSecondaryAction(action.command)}
+              disabled={workflowAction.disabled}
+              className={cn(
+                "inline-flex items-center gap-1 rounded-md border border-border bg-background px-2 py-1 text-xs font-medium transition-colors hover:bg-accent",
+                workflowAction.disabled && "cursor-not-allowed opacity-50",
+              )}
+              title={workflowAction.disabledReason}
+            >
+              {action.label}
+            </button>
+          ))}
+          {state.commandInFlight && (
+            <span className="flex items-center gap-1 text-xs text-muted-foreground">
+              <Loader2 className="h-3 w-3 animate-spin" />
+            </span>
+          )}
+        </div>
+    </div>
+  )
+}
+
+
+type ShikiHighlighter = {
+  codeToHtml: (code: string, options: { lang: string; theme: string }) => string
+}
+
+let chatHighlighterPromise: Promise<ShikiHighlighter> | null = null
+
+function getChatHighlighter(): Promise<ShikiHighlighter> {
+  if (!chatHighlighterPromise) {
+    chatHighlighterPromise = import("shiki")
+      .then((mod) =>
+        mod.createHighlighter({
+          themes: ["github-dark-default", "github-light-default"],
+          langs: [
+            "typescript", "tsx", "javascript", "jsx",
+            "json", "jsonc", "markdown", "mdx",
+            "css", "scss", "less", "html", "xml",
+            "yaml", "toml", "bash", "python", "ruby",
+            "rust", "go", "java", "kotlin", "swift",
+            "c", "cpp", "csharp", "php", "sql",
+            "graphql", "dockerfile", "makefile",
+            "lua", "diff", "ini", "dotenv",
+          ],
+        }),
+      )
+      .catch((err) => {
+        chatHighlighterPromise = null
+        throw err
+      })
+  }
+  return chatHighlighterPromise
+}
+
+/* ─── Markdown renderer for assistant bubbles ─── */
+
+/**
+ * Renders markdown content using react-markdown + remark-gfm + shiki code blocks.
+ * Dynamic imports keep the main bundle lean.
+ * Falls back to plain text if modules fail to load.
+ *
+ * Observability:
+ *   - console.debug("[ChatBubble] markdown modules loaded") fires once on first render
+ */
+function MarkdownContent({ content }: { content: string }) {
+  const [rendered, setRendered] = useState<React.ReactNode | null>(null)
+  const [ready, setReady] = useState(false)
+  const isDark = useIsDark()
+
+  useEffect(() => {
+    let cancelled = false
+
+    Promise.all([
+      import("react-markdown"),
+      import("remark-gfm"),
+      getChatHighlighter(),
+    ])
+      .then(([ReactMarkdownMod, remarkGfmMod, highlighter]) => {
+        if (cancelled) return
+        console.debug("[ChatBubble] markdown modules loaded")
+
+        const ReactMarkdown = ReactMarkdownMod.default
+        const remarkGfm = remarkGfmMod.default
+
+        const shikiTheme = isDark ? "github-dark-default" : "github-light-default"
+
+        const buildComponents = (h: typeof highlighter) => ({
+          code({ className, children, ...props }: React.HTMLAttributes<HTMLElement> & { children?: React.ReactNode }) {
+            const match = /language-(\w+)/.exec(className || "")
+            const codeStr = String(children).replace(/\n$/, "")
+
+            if (match) {
+              try {
+                const highlighted = h.codeToHtml(codeStr, {
+                  lang: match[1],
+                  theme: shikiTheme,
+                })
+                return (
+                  <div
+                    className="chat-code-block my-3 rounded-xl overflow-x-auto text-sm shadow-sm border border-border/50"
+                    dangerouslySetInnerHTML={{ __html: highlighted }}
+                  />
+                )
+              } catch { /* unsupported language — fall through */ }
+            }
+
+            const isInline = !className && !String(children).includes("\n")
+            if (isInline) {
+              return (
+                <code
+                  className="rounded-md bg-muted px-1.5 py-0.5 text-[0.85em] font-mono text-foreground"
+                  {...props}
+                >
+                  {children}
+                </code>
+              )
+            }
+
+            return (
+              <pre className={cn("my-3 overflow-x-auto rounded-xl p-4 text-sm border border-border/50", isDark ? "bg-[#0d1117]" : "bg-[#f6f8fa]")}>
+                <code className="font-mono">{children}</code>
+              </pre>
+            )
+          },
+          pre({ children }: { children?: React.ReactNode }) {
+            return <>{children}</>
+          },
+          table({ children }: { children?: React.ReactNode }) {
+            return (
+              <div className="my-4 overflow-x-auto rounded-lg border border-border">
+                <table className="min-w-full border-collapse text-sm">{children}</table>
+              </div>
+            )
+          },
+          th({ children }: { children?: React.ReactNode }) {
+            return (
+              <th className="border-b border-border bg-muted/50 px-3 py-2 text-left text-xs font-semibold text-muted-foreground uppercase tracking-wide">
+                {children}
+              </th>
+            )
+          },
+          td({ children }: { children?: React.ReactNode }) {
+            return (
+              <td className="border-b border-border/50 px-3 py-2 text-sm last:border-0">
+                {children}
+              </td>
+            )
+          },
+          a({ href, children }: { href?: string; children?: React.ReactNode }) {
+            return (
+              <a
+                href={href}
+                className="text-info underline underline-offset-2 hover:text-info transition-colors"
+                target="_blank"
+                rel="noopener noreferrer"
+              >
+                {children}
+              </a>
+            )
+          },
+          h1({ children }: { children?: React.ReactNode }) {
+            return <h1 className="mt-4 mb-2 text-base font-semibold text-foreground first:mt-0">{children}</h1>
+          },
+          h2({ children }: { children?: React.ReactNode }) {
+            return <h2 className="mt-3 mb-1.5 text-sm font-semibold text-foreground first:mt-0">{children}</h2>
+          },
+          h3({ children }: { children?: React.ReactNode }) {
+            return <h3 className="mt-2 mb-1 text-sm font-medium text-foreground first:mt-0">{children}</h3>
+          },
+          ul({ children }: { children?: React.ReactNode }) {
+            return <ul className="my-2 ml-4 list-disc space-y-0.5 text-sm [&>li]:text-foreground">{children}</ul>
+          },
+          ol({ children }: { children?: React.ReactNode }) {
+            return <ol className="my-2 ml-4 list-decimal space-y-0.5 text-sm [&>li]:text-foreground">{children}</ol>
+          },
+          blockquote({ children }: { children?: React.ReactNode }) {
+            return <blockquote className="my-3 border-l-2 border-primary/40 pl-3 text-sm text-muted-foreground italic">{children}</blockquote>
+          },
+          hr() {
+            return <hr className="my-4 border-border/50" />
+          },
+          p({ children }: { children?: React.ReactNode }) {
+            return <p className="mb-2 text-sm leading-relaxed last:mb-0 text-foreground">{children}</p>
+          },
+          img({ alt, src }: { alt?: string; src?: string }) {
+            return (
+              <span className="my-2 block rounded-lg border border-border bg-muted/50 px-3 py-2 text-xs text-muted-foreground italic">
+                🖼 {alt || src || "image"}
+              </span>
+            )
+          },
+        })
+
+        setRendered(
+          <ReactMarkdown remarkPlugins={[remarkGfm]} components={buildComponents(highlighter) as import("react-markdown").Components}>
+            {content}
+          </ReactMarkdown>,
+        )
+        setReady(true)
+      })
+      .catch(() => {
+        if (!cancelled) setReady(true)
+      })
+
+    return () => { cancelled = true }
+   
+  }, [content, isDark]) // re-render when content changes (streaming) or theme toggles
+
+  if (!ready) {
+    // Plain text fallback while modules load
+    return (
+      <span className="whitespace-pre-wrap text-sm leading-relaxed text-foreground">
+        {content}
+      </span>
+    )
+  }
+
+  if (!rendered) {
+    return (
+      <span className="whitespace-pre-wrap text-sm leading-relaxed text-foreground">
+        {content}
+      </span>
+    )
+  }
+
+  return <div className="chat-markdown min-w-0">{rendered}</div>
+}
+
+/* ─── TuiSelectPrompt ─── */
+
+/**
+ * Renders a GSD arrow-key select prompt as a native clickable list.
+ *
+ * Clicking an option calculates the arrow-key delta from the current
+ * PTY-tracked selection, sends that many \x1b[A/\x1b[B + \r to the PTY,
+ * and transitions to a static post-submission state.
+ *
+ * Observability:
+ *   - Logs "[TuiSelectPrompt] mounted kind=select label=%s" on mount
+ *   - Logs "[TuiSelectPrompt] submit delta=%d keystrokes=%j" on submit
+ *   - data-testid="tui-select-prompt" on container
+ *   - data-testid="tui-select-option-{i}" on each option button
+ *   - data-testid="tui-prompt-submitted" on post-submission element
+ */
+function TuiSelectPrompt({
+  prompt,
+  onSubmit,
+}: {
+  prompt: TuiPrompt
+  onSubmit: (data: string) => void
+}) {
+  const [localIndex, setLocalIndex] = useState(prompt.selectedIndex ?? 0)
+  const [submitted, setSubmitted] = useState(false)
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    console.log("[TuiSelectPrompt] mounted kind=select label=%s", prompt.label)
+    // Auto-focus the container so keyboard events are captured immediately
+    containerRef.current?.focus()
+  }, [prompt.label])
+
+  const submitIndex = useCallback(
+    (clickedIndex: number) => {
+      const delta = clickedIndex - localIndex
+      let keystrokes = ""
+      if (delta > 0) {
+        keystrokes = "\x1b[B".repeat(delta)
+      } else if (delta < 0) {
+        keystrokes = "\x1b[A".repeat(Math.abs(delta))
+      }
+      keystrokes += "\r"
+
+      console.log(
+        "[TuiSelectPrompt] submit delta=%d keystrokes=%j",
+        delta,
+        keystrokes,
+      )
+
+      setLocalIndex(clickedIndex)
+      setSubmitted(true)
+      onSubmit(keystrokes)
+    },
+    [localIndex, onSubmit],
+  )
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLDivElement>) => {
+      if (submitted) return
+      if (e.key === "ArrowUp") {
+        e.preventDefault()
+        setLocalIndex((i) => Math.max(0, i - 1))
+      } else if (e.key === "ArrowDown") {
+        e.preventDefault()
+        setLocalIndex((i) => Math.min(prompt.options.length - 1, i + 1))
+      } else if (e.key === "Enter") {
+        e.preventDefault()
+        submitIndex(localIndex)
+      }
+    },
+    [submitted, localIndex, prompt.options.length, submitIndex],
+  )
+
+  if (submitted) {
+    const selectedLabel = prompt.options[localIndex] ?? ""
+    return (
+      <div
+        data-testid="tui-prompt-submitted"
+        className="mt-2 flex items-center gap-1.5 rounded-lg bg-primary/10 px-3 py-2 text-sm text-primary"
+      >
+        <Check className="h-3.5 w-3.5 flex-shrink-0" />
+        <span className="font-medium">{selectedLabel}</span>
+      </div>
+    )
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      data-testid="tui-select-prompt"
+      tabIndex={0}
+      onKeyDown={handleKeyDown}
+      className="mt-2 rounded-xl border border-border bg-background p-1.5 shadow-sm outline-none focus-visible:ring-1 focus-visible:ring-border"
+      aria-label={`Select: ${prompt.label}`}
+      role="listbox"
+      aria-activedescendant={`tui-select-option-${localIndex}`}
+    >
+      {prompt.label && (
+        <p className="mb-1.5 px-2 text-[11px] font-medium text-muted-foreground uppercase tracking-wide">
+          {prompt.label}
+        </p>
+      )}
+      {prompt.options.map((option, i) => {
+        const isSelected = i === localIndex
+        const description = prompt.descriptions?.[i]
+        return (
+          <button
+            key={i}
+            id={`tui-select-option-${i}`}
+            data-testid={`tui-select-option-${i}`}
+            role="option"
+            aria-selected={isSelected}
+            onClick={() => submitIndex(i)}
+            className={cn(
+              "flex w-full items-start gap-2 rounded-lg px-3 py-1.5 text-left text-sm transition-colors",
+              isSelected
+                ? "bg-primary/15 text-primary font-medium"
+                : "text-foreground hover:bg-muted",
+            )}
+          >
+            <span className="mt-0.5 flex h-4 w-4 flex-shrink-0 items-center justify-center">
+              {isSelected ? (
+                <Check className="h-3 w-3 text-primary" />
+              ) : (
+                <span className="h-1.5 w-1.5 rounded-full bg-muted-foreground/30" />
+              )}
+            </span>
+            <span className="min-w-0">
+              <span className="block">{option}</span>
+              {description && (
+                <span className="mt-0.5 block text-xs font-normal text-muted-foreground">
+                  {description}
+                </span>
+              )}
+            </span>
+          </button>
+        )
+      })}
+    </div>
+  )
+}
+
+/* ─── TuiTextPrompt ─── */
+
+/**
+ * Renders a GSD text prompt as a native labeled input field.
+ *
+ * Submitting sends the typed value + "\r" to the PTY (carriage return = Enter).
+ * After submission shows a static "✓ Submitted" confirmation (value not echoed).
+ *
+ * Observability:
+ *   - Logs "[TuiTextPrompt] mounted kind=text label=%s" on mount
+ *   - Logs "[TuiTextPrompt] submitted label=%s" on submit
+ *   - data-testid="tui-text-prompt" on container
+ *   - data-testid="tui-prompt-submitted" on post-submission element
+ */
+function TuiTextPrompt({
+  prompt,
+  onSubmit,
+}: {
+  prompt: TuiPrompt
+  onSubmit: (data: string) => void
+}) {
+  const [value, setValue] = useState("")
+  const [submitted, setSubmitted] = useState(false)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  useEffect(() => {
+    console.log("[TuiTextPrompt] mounted kind=text label=%s", prompt.label)
+    inputRef.current?.focus()
+  }, [prompt.label])
+
+  const handleSubmit = useCallback(() => {
+    if (submitted) return
+    console.log("[TuiTextPrompt] submitted label=%s", prompt.label)
+    setSubmitted(true)
+    onSubmit(value + "\r")
+  }, [submitted, value, prompt.label, onSubmit])
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLInputElement>) => {
+      if (e.key === "Enter") {
+        e.preventDefault()
+        handleSubmit()
+      }
+    },
+    [handleSubmit],
+  )
+
+  if (submitted) {
+    return (
+      <div
+        data-testid="tui-prompt-submitted"
+        className="mt-2 flex items-center gap-1.5 rounded-lg bg-primary/10 px-3 py-2 text-sm text-primary"
+      >
+        <Check className="h-3.5 w-3.5 flex-shrink-0" />
+        <span className="font-medium">✓ Submitted</span>
+      </div>
+    )
+  }
+
+  return (
+    <div
+      data-testid="tui-text-prompt"
+      className="mt-2 rounded-xl border border-border bg-background p-3 shadow-sm"
+    >
+      {prompt.label && (
+        <p className="mb-2 text-[11px] font-medium text-muted-foreground uppercase tracking-wide">
+          {prompt.label}
+        </p>
+      )}
+      <div className="flex gap-2">
+        <Input
+          ref={inputRef}
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          onKeyDown={handleKeyDown}
+          placeholder="Type your answer…"
+          className="flex-1 h-8 text-sm"
+          aria-label={prompt.label || "Text input"}
+        />
+        <button
+          onClick={handleSubmit}
+          disabled={!value.trim()}
+          className={cn(
+            "flex h-8 items-center justify-center rounded-lg px-3 text-xs font-medium transition-all",
+            value.trim()
+              ? "bg-primary text-primary-foreground hover:bg-primary/90 active:scale-95 shadow-sm"
+              : "bg-muted text-muted-foreground cursor-not-allowed",
+          )}
+        >
+          Submit
+        </button>
+      </div>
+    </div>
+  )
+}
+
+/* ─── TuiPasswordPrompt ─── */
+
+/**
+ * Renders a GSD password/API-key prompt as a native masked input field.
+ *
+ * Submitting sends the typed value + "\r" to the PTY.
+ * The entered value is NEVER shown in the DOM, logs, or post-submission text.
+ * After submission shows "{label} — entered ✓" with no value echo.
+ *
+ * Observability:
+ *   - Logs "[TuiPasswordPrompt] mounted kind=password label=%s" on mount
+ *   - Logs "[TuiPasswordPrompt] submitted label=%s" on submit (value not logged)
+ *   - data-testid="tui-password-prompt" on container
+ *   - data-testid="tui-prompt-submitted" on post-submission element
+ */
+function TuiPasswordPrompt({
+  prompt,
+  onSubmit,
+}: {
+  prompt: TuiPrompt
+  onSubmit: (data: string) => void
+}) {
+  const [value, setValue] = useState("")
+  const [submitted, setSubmitted] = useState(false)
+  const [showPassword, setShowPassword] = useState(false)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  useEffect(() => {
+    console.log("[TuiPasswordPrompt] mounted kind=password label=%s", prompt.label)
+    inputRef.current?.focus()
+  }, [prompt.label])
+
+  const handleSubmit = useCallback(() => {
+    if (submitted) return
+    // Value intentionally not logged — redaction constraint
+    console.log("[TuiPasswordPrompt] submitted label=%s", prompt.label)
+    setSubmitted(true)
+    onSubmit(value + "\r")
+  }, [submitted, value, prompt.label, onSubmit])
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLInputElement>) => {
+      if (e.key === "Enter") {
+        e.preventDefault()
+        handleSubmit()
+      }
+    },
+    [handleSubmit],
+  )
+
+  if (submitted) {
+    const displayLabel = prompt.label || "Value"
+    return (
+      <div
+        data-testid="tui-prompt-submitted"
+        className="mt-2 flex items-center gap-1.5 rounded-lg bg-primary/10 px-3 py-2 text-sm text-primary"
+      >
+        <Check className="h-3.5 w-3.5 flex-shrink-0" />
+        <span className="font-medium">{displayLabel} — entered ✓</span>
+      </div>
+    )
+  }
+
+  return (
+    <div
+      data-testid="tui-password-prompt"
+      className="mt-2 rounded-xl border border-border bg-background p-3 shadow-sm"
+    >
+      {prompt.label && (
+        <p className="mb-2 text-[11px] font-medium text-muted-foreground uppercase tracking-wide">
+          {prompt.label}
+        </p>
+      )}
+      <div className="flex gap-2">
+        <div className="relative flex-1">
+          <Input
+            ref={inputRef}
+            type={showPassword ? "text" : "password"}
+            value={value}
+            onChange={(e) => setValue(e.target.value)}
+            onKeyDown={handleKeyDown}
+            placeholder="Enter value…"
+            className="h-8 pr-9 text-sm"
+            aria-label={prompt.label || "Password input"}
+            autoComplete="off"
+          />
+          <button
+            type="button"
+            onClick={() => setShowPassword((s) => !s)}
+            tabIndex={-1}
+            aria-label={showPassword ? "Hide input" : "Show input"}
+            className="absolute right-2.5 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-muted-foreground transition-colors"
+          >
+            {showPassword ? (
+              <EyeOff className="h-3.5 w-3.5" />
+            ) : (
+              <Eye className="h-3.5 w-3.5" />
+            )}
+          </button>
+        </div>
+        <button
+          onClick={handleSubmit}
+          disabled={!value}
+          className={cn(
+            "flex h-8 items-center justify-center rounded-lg px-3 text-xs font-medium transition-all",
+            value
+              ? "bg-primary text-primary-foreground hover:bg-primary/90 active:scale-95 shadow-sm"
+              : "bg-muted text-muted-foreground cursor-not-allowed",
+          )}
+        >
+          Submit
+        </button>
+      </div>
+      <p className="mt-1.5 text-[10px] text-muted-foreground">
+        Value is transmitted securely and not stored in chat history.
+      </p>
+    </div>
+  )
+}
+
+/* ─── StreamingCursor ─── */
+
+function StreamingCursor() {
+  return (
+    <span
+      aria-hidden="true"
+      className="ml-0.5 inline-block h-3.5 w-0.5 translate-y-0.5 rounded-full bg-current opacity-70"
+      style={{ animation: "chat-cursor 1s ease-in-out infinite" }}
+    />
+  )
+}
+
+
+function createLocalMessageId(): string {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID()
+  }
+  return `msg-${Date.now()}-${Math.random().toString(16).slice(2)}`
+}
+
+/* ─── Theme detection hook ─── */
+
+function useIsDark(): boolean {
+  const [isDark, setIsDark] = useState(() =>
+    typeof document !== "undefined" && document.documentElement.classList.contains("dark"),
+  )
+  useEffect(() => {
+    if (typeof document === "undefined") return
+    const el = document.documentElement
+    const observer = new MutationObserver(() => {
+      setIsDark(el.classList.contains("dark"))
+    })
+    observer.observe(el, { attributes: true, attributeFilter: ["class"] })
+    return () => observer.disconnect()
+  }, [])
+  return isDark
+}
+
+/* ─── PlatformLogoIcon ─── */
+
+/**
+ * Renders the platform logo icon, dynamically switching between
+ * light and dark variants based on the current theme.
+ */
+function PlatformLogoIcon({ className }: { className?: string }) {
+  const isDark = useIsDark()
+  return (
+    <Image
+      src={isDark ? "/logo-icon-white.svg" : "/logo-icon-black.svg"}
+      alt=""
+      width={24}
+      height={32}
+      unoptimized
+      className={cn("h-4 w-auto", className)}
+    />
+  )
+}
+
+/* ─── InlineThinking ─── */
+
+/**
+ * Thinking indicator rendered inline inside an assistant bubble.
+ * Shows a collapsible preview of the LLM's reasoning with a visible,
+ * well-styled block that shows more context lines.
+ */
+function InlineThinking({ content, isStreaming }: { content: string; isStreaming: boolean }) {
+  const [expanded, setExpanded] = useState(false)
+  const scrollRef = useRef<HTMLDivElement>(null)
+  const lines = content.split("\n").filter((l) => l.trim())
+  const previewLines = lines.slice(-5)
+  const hasMore = lines.length > 5
+
+  // Auto-scroll the expanded view to the bottom when streaming
+  useEffect(() => {
+    if (expanded && isStreaming && scrollRef.current) {
+      scrollRef.current.scrollTop = scrollRef.current.scrollHeight
+    }
+  }, [expanded, isStreaming, content])
+
+  return (
+    <div className="mb-3">
+      <button
+        onClick={() => setExpanded((e) => !e)}
+        className={cn(
+          "group w-full rounded-xl border px-3.5 py-2.5 text-left transition-all",
+          "border-border/50 bg-muted/50 hover:bg-muted/50",
+        )}
+      >
+        {/* Header row */}
+        <div className="flex items-center gap-2">
+          {isStreaming ? (
+            <span className="relative flex h-2 w-2 flex-shrink-0">
+              <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-muted-foreground/30" />
+              <span className="relative inline-flex h-2 w-2 rounded-full bg-muted-foreground/50" />
+            </span>
+          ) : (
+            <span className="flex h-4 w-4 flex-shrink-0 items-center justify-center rounded bg-muted-foreground/10">
+              <span className="text-[9px] text-muted-foreground">💭</span>
+            </span>
+          )}
+          <span className="text-[11px] font-medium uppercase tracking-wider text-muted-foreground">
+            {isStreaming ? "Thinking…" : "Thought process"}
+          </span>
+          {hasMore && !expanded && (
+            <span className="ml-1 rounded-full bg-muted px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground">
+              {lines.length} lines
+            </span>
+          )}
+          <span className="ml-auto flex-shrink-0">
+            {expanded
+              ? <ChevronDown className="h-3 w-3 text-muted-foreground transition-transform" />
+              : <ChevronRight className="h-3 w-3 text-muted-foreground transition-transform group-hover:text-muted-foreground" />
+            }
+          </span>
+        </div>
+
+        {/* Collapsed preview — show 5 lines */}
+        {!expanded && (
+          <div className="mt-2 space-y-0.5 border-l-2 border-muted-foreground/10 pl-3">
+            {previewLines.map((line, i) => (
+              <p key={i} className="text-[12px] leading-relaxed text-muted-foreground line-clamp-1">
+                {line}
+              </p>
+            ))}
+            {isStreaming && <StreamingCursor />}
+          </div>
+        )}
+
+        {/* Expanded view — scrollable with more space */}
+        {expanded && (
+          <div
+            ref={scrollRef}
+            className="mt-2 max-h-[400px] overflow-y-auto overscroll-contain rounded-lg border border-border/50 bg-background/50 p-3 text-[12px] leading-[1.7] text-muted-foreground whitespace-pre-wrap scrollbar-thin scrollbar-thumb-border scrollbar-track-transparent"
+          >
+            {content}
+            {isStreaming && <StreamingCursor />}
+          </div>
+        )}
+      </button>
+    </div>
+  )
+}
+
+/* ─── ChatBubble ─── */
+
+/**
+ * Renders a single ChatMessage as a styled bubble.
+ *
+ * - assistant: left-aligned bubble with full markdown rendering + syntax-highlighted code blocks
+ * - user: right-aligned outgoing bubble with plain text
+ * - system: small centered muted line (no bubble chrome)
+ * - incomplete messages show an animated streaming cursor
+ * - when message.prompt.kind === 'select', TuiSelectPrompt renders below content
+ */
+function ChatBubble({
+  message,
+  onSubmitPrompt,
+  isThinking,
+}: {
+  message: ChatMessage
+  onSubmitPrompt?: (data: string) => void
+  isThinking?: boolean
+}) {
+  if (message.role === "system") {
+    return (
+      <div className="flex items-center justify-center py-1">
+        <span className="text-[11px] text-muted-foreground italic px-3">
+          {message.content}
+        </span>
+      </div>
+    )
+  }
+
+  if (message.role === "user") {
+    return (
+      <div className="flex justify-end">
+        <div className="max-w-[72%] rounded-2xl rounded-br-md bg-primary px-4 py-2.5 text-sm text-primary-foreground shadow-sm">
+          {message.images && message.images.length > 0 && (
+            <div className="flex gap-1.5 mb-2 flex-wrap">
+              {message.images.map((img, idx) => (
+                <Image
+                  key={idx}
+                  src={`data:${img.mimeType};base64,${img.data}`}
+                  alt={`Attached image ${idx + 1}`}
+                  width={32}
+                  height={32}
+                  unoptimized
+                  className="h-8 w-8 rounded object-cover border border-primary-foreground/20"
+                />
+              ))}
+            </div>
+          )}
+          <span className="whitespace-pre-wrap leading-relaxed">{message.content}</span>
+          {!message.complete && <StreamingCursor />}
+        </div>
+      </div>
+    )
+  }
+
+  // assistant
+  const hasSelectPrompt =
+    message.prompt?.kind === "select" &&
+    !message.complete &&
+    onSubmitPrompt != null
+
+  const hasTextPrompt =
+    message.prompt?.kind === "text" &&
+    !message.complete &&
+    onSubmitPrompt != null
+
+  const hasPasswordPrompt =
+    message.prompt?.kind === "password" &&
+    !message.complete &&
+    onSubmitPrompt != null
+
+  const hasAnyPrompt = hasSelectPrompt || hasTextPrompt || hasPasswordPrompt
+
+  return (
+    <div className="flex justify-start gap-3">
+      <div className="mt-1 flex-shrink-0 flex h-7 w-7 items-center justify-center rounded-full bg-card border border-border">
+        <PlatformLogoIcon className="h-3.5 w-auto" />
+      </div>
+      <div className="max-w-[82%] min-w-0 rounded-2xl rounded-tl-md border border-border bg-card px-4 py-3 shadow-sm">
+        {/* Minimal waiting indicator — shown when streaming starts but no content yet */}
+        {isThinking && !message.content && (
+          <div className="flex items-center gap-2 py-1">
+            <span className="relative flex h-2 w-2">
+              <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-muted-foreground/30" />
+              <span className="relative inline-flex h-2 w-2 rounded-full bg-muted-foreground/50" />
+            </span>
+            <span className="text-[10px] font-medium text-muted-foreground uppercase tracking-wider">
+              Thinking…
+            </span>
+          </div>
+        )}
+        {message.content && <MarkdownContent content={message.content} />}
+        {!message.complete && !hasAnyPrompt && <StreamingCursor />}
+        {hasSelectPrompt && (
+          <TuiSelectPrompt
+            prompt={message.prompt!}
+            onSubmit={onSubmitPrompt!}
+          />
+        )}
+        {hasTextPrompt && (
+          <TuiTextPrompt
+            prompt={message.prompt!}
+            onSubmit={onSubmitPrompt!}
+          />
+        )}
+        {hasPasswordPrompt && (
+          <TuiPasswordPrompt
+            prompt={message.prompt!}
+            onSubmit={onSubmitPrompt!}
+          />
+        )}
+      </div>
+    </div>
+  )
+}
+
+/* ─── ChatMessageList ─── */
+
+/**
+ * Renders ChatMessage[] as a scrollable list of ChatBubble components.
+ *
+ * Scroll behavior:
+ *   - Auto-scrolls to bottom on new messages ONLY when the user is within 100px of bottom
+ *   - If the user has scrolled up to read history, auto-scroll is suppressed
+ */
+function ChatMessageList({
+  messages,
+  onSubmitPrompt,
+  fontSize,
+}: {
+  messages: ChatMessage[]
+  onSubmitPrompt: (data: string) => void
+  fontSize?: number
+}) {
+  const scrollRef = useRef<HTMLDivElement>(null)
+  const isNearBottomRef = useRef(true)
+  const prevMessageCountRef = useRef(messages.length)
+
+  const handleScroll = useCallback(() => {
+    const el = scrollRef.current
+    if (!el) return
+    const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight
+    isNearBottomRef.current = distanceFromBottom < 100
+  }, [])
+
+  // Scroll to bottom on new messages (if user is near bottom)
+  useEffect(() => {
+    const el = scrollRef.current
+    if (!el) return
+
+    const isNewMessage = messages.length !== prevMessageCountRef.current
+    prevMessageCountRef.current = messages.length
+
+    if (isNearBottomRef.current) {
+      el.scrollTop = el.scrollHeight
+    }
+
+    // If a new message arrives while scrolled up, still update the count but don't scroll
+    void isNewMessage
+  }, [messages])
+
+  return (
+    <div
+      ref={scrollRef}
+      onScroll={handleScroll}
+      className="flex-1 overflow-y-auto px-4 py-4 space-y-4"
+      style={fontSize ? { fontSize: `${fontSize}px` } : undefined}
+    >
+      {messages.map((msg) => (
+        <ChatBubble key={msg.id} message={msg} onSubmitPrompt={onSubmitPrompt} />
+      ))}
+      {/* Bottom spacer for scroll anchor */}
+      <div className="h-2" />
+    </div>
+  )
+}
+
+/* ─── ChatInputBar ─── */
+
+/**
+ * Text input bar at the bottom of ChatPane.
+ *
+ * - Enter: send input + "\r" and clear
+ * - Shift+Enter: insert newline (multiline)
+ * - Disabled when disconnected; shows "Disconnected" badge
+ * - Send button visible when input has content and connected
+ * - Top 3 action buttons (Discuss, Next, Auto) shown standalone
+ * - Overflow menu (⋯) contains all remaining /gsd subcommands grouped by category
+ * - Every action has a tooltip with description on hover
+ */
+function ChatInputBar({
+  onSendInput,
+  connected,
+  onOpenAction,
+}: {
+  onSendInput: (data: string, images?: PendingImage[]) => void
+  connected: boolean
+  onOpenAction?: (action: GSDActionDef) => void
+}) {
+  const autoActive = useGSDWorkspaceState().boot?.auto?.active ?? false
+  const [value, setValue] = useState("")
+  const [overflowOpen, setOverflowOpen] = useState(false)
+  const [pendingImages, setPendingImages] = useState<PendingImage[]>([])
+  const [isDragging, setIsDragging] = useState(false)
+  const [imageNotice, setImageNotice] = useState<string | null>(null)
+  const textareaRef = useRef<HTMLTextAreaElement>(null)
+  const dragCounterRef = useRef(0)
+
+  // Cleanup blob URLs on unmount
+  useEffect(() => {
+    return () => {
+      pendingImages.forEach((img) => URL.revokeObjectURL(img.previewUrl))
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const addImages = useCallback(async (files: File[]) => {
+    setImageNotice(null)
+
+    const imageFiles = files.filter((f) => f.type.startsWith("image/"))
+    if (imageFiles.length === 0) return
+
+    setPendingImages((prev) => {
+      const remaining = MAX_PENDING_IMAGES - prev.length
+      if (remaining <= 0) {
+        setImageNotice(`Maximum ${MAX_PENDING_IMAGES} images per message`)
+        return prev
+      }
+      return prev // return current, processing happens below
+    })
+
+    // Process files outside setState to handle async
+    const currentCount = pendingImages.length
+    const toProcess = imageFiles.slice(0, MAX_PENDING_IMAGES - currentCount)
+
+    if (toProcess.length < imageFiles.length) {
+      setImageNotice(`Maximum ${MAX_PENDING_IMAGES} images per message`)
+    }
+
+    const newImages: PendingImage[] = []
+    for (const file of toProcess) {
+      try {
+        const result = await processImageFile(file)
+        const previewUrl = URL.createObjectURL(file)
+        newImages.push({
+          id: generateImageId(),
+          data: result.data,
+          mimeType: result.mimeType,
+          previewUrl,
+        })
+      } catch (err) {
+        console.warn("[chat-input] image processing failed:", err instanceof Error ? err.message : err)
+        setImageNotice(err instanceof Error ? err.message : "Failed to process image")
+      }
+    }
+
+    if (newImages.length > 0) {
+      setPendingImages((prev) => {
+        const combined = [...prev, ...newImages]
+        if (combined.length > MAX_PENDING_IMAGES) {
+          // Revoke excess
+          combined.slice(MAX_PENDING_IMAGES).forEach((img) => URL.revokeObjectURL(img.previewUrl))
+          setImageNotice(`Maximum ${MAX_PENDING_IMAGES} images per message`)
+          return combined.slice(0, MAX_PENDING_IMAGES)
+        }
+        return combined
+      })
+    }
+  }, [pendingImages.length])
+
+  const removeImage = useCallback((id: string) => {
+    setPendingImages((prev) => {
+      const removed = prev.find((img) => img.id === id)
+      if (removed) URL.revokeObjectURL(removed.previewUrl)
+      return prev.filter((img) => img.id !== id)
+    })
+    setImageNotice(null)
+  }, [])
+
+  const handleDrop = useCallback((e: DragEvent<HTMLDivElement>) => {
+    e.preventDefault()
+    e.stopPropagation()
+    setIsDragging(false)
+    dragCounterRef.current = 0
+    const files = Array.from(e.dataTransfer.files)
+    void addImages(files)
+  }, [addImages])
+
+  const handleDragOver = useCallback((e: DragEvent<HTMLDivElement>) => {
+    e.preventDefault()
+    e.stopPropagation()
+  }, [])
+
+  const handleDragEnter = useCallback((e: DragEvent<HTMLDivElement>) => {
+    e.preventDefault()
+    e.stopPropagation()
+    dragCounterRef.current += 1
+    setIsDragging(true)
+  }, [])
+
+  const handleDragLeave = useCallback((e: DragEvent<HTMLDivElement>) => {
+    e.preventDefault()
+    e.stopPropagation()
+    dragCounterRef.current -= 1
+    if (dragCounterRef.current <= 0) {
+      dragCounterRef.current = 0
+      setIsDragging(false)
+    }
+  }, [])
+
+  const handlePaste = useCallback((e: ClipboardEvent<HTMLTextAreaElement>) => {
+    const items = e.clipboardData?.files
+    if (items && items.length > 0) {
+      const imageFiles = Array.from(items).filter((f) => f.type.startsWith("image/"))
+      if (imageFiles.length > 0) {
+        e.preventDefault()
+        void addImages(imageFiles)
+      }
+      // If no image files in clipboard, let normal text paste proceed (no-regression)
+    }
+  }, [addImages])
+
+  const handleSend = useCallback(() => {
+    const trimmed = value.trim()
+    if (!trimmed && pendingImages.length === 0) return
+    if (!connected) return
+    onSendInput(value + "\r", pendingImages.length > 0 ? pendingImages : undefined)
+    setValue("")
+    // Don't revoke URLs here — they'll be used in the chat bubble for the sent message
+    setPendingImages([])
+    setImageNotice(null)
+    if (textareaRef.current) {
+      textareaRef.current.style.height = "auto"
+    }
+  }, [value, connected, onSendInput, pendingImages])
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLTextAreaElement>) => {
+      if (e.key === "Enter" && !e.shiftKey) {
+        e.preventDefault()
+        handleSend()
+      }
+    },
+    [handleSend],
+  )
+
+  const handleInput = useCallback((e: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(e.target.value)
+    const el = e.target
+    el.style.height = "auto"
+    el.style.height = `${Math.min(el.scrollHeight, 160)}px`
+  }, [])
+
+  const hasContent = value.trim().length > 0 || pendingImages.length > 0
+  const overflowGroups = useMemo(() => groupByCategory(OVERFLOW_ACTIONS), [])
+
+  return (
+    <div className="flex-shrink-0 border-t border-border bg-card px-4 py-3 backdrop-blur-sm">
+      <div
+        className="flex items-end gap-2"
+        onDrop={handleDrop}
+        onDragOver={handleDragOver}
+        onDragEnter={handleDragEnter}
+        onDragLeave={handleDragLeave}
+      >
+        {/* Input + send button */}
+        <div
+          className={cn(
+            "flex flex-1 flex-col rounded-xl border bg-background transition-colors",
+            connected
+              ? "border-border focus-within:ring-1 focus-within:ring-border/30"
+              : "border-border/50 opacity-80",
+            isDragging && connected && "border-primary/60 ring-2 ring-primary/20 bg-primary/5",
+          )}
+        >
+          {/* Thumbnail preview row */}
+          {pendingImages.length > 0 && (
+            <div className="flex items-center gap-2 px-3 pt-2.5 pb-1 flex-wrap">
+              {pendingImages.map((img) => (
+                <div key={img.id} className="relative group flex-shrink-0">
+                  <Image
+                    src={img.previewUrl}
+                    alt="Pending image"
+                    width={48}
+                    height={48}
+                    unoptimized
+                    className="h-12 w-12 rounded-lg object-cover border border-border/50"
+                  />
+                  <button
+                    onClick={() => removeImage(img.id)}
+                    aria-label="Remove image"
+                    className="absolute -top-1.5 -right-1.5 flex h-4 w-4 items-center justify-center rounded-full bg-destructive text-destructive-foreground text-[10px] opacity-0 group-hover:opacity-100 transition-opacity shadow-sm"
+                  >
+                    <X className="h-2.5 w-2.5" />
+                  </button>
+                </div>
+              ))}
+              {imageNotice && (
+                <span className="text-[10px] text-muted-foreground italic">{imageNotice}</span>
+              )}
+            </div>
+          )}
+          <div className="flex items-end gap-2">
+          <textarea
+            ref={textareaRef}
+            value={value}
+            onChange={handleInput}
+            onKeyDown={handleKeyDown}
+            onPaste={handlePaste}
+            disabled={!connected}
+            rows={1}
+            aria-label="Send message"
+            placeholder={
+              connected
+                ? "Message…"
+                : "Connecting…"
+            }
+            className="min-h-[40px] flex-1 resize-none bg-transparent px-3 py-2.5 text-sm text-foreground placeholder:text-muted-foreground focus:outline-none disabled:cursor-not-allowed disabled:text-muted-foreground"
+            style={{ height: "40px", maxHeight: "160px", overflowY: "auto" }}
+          />
+          <div className="flex flex-shrink-0 items-end pb-1.5 pr-1.5 gap-1">
+            {!connected && (
+              <span className="px-2 py-1 text-[10px] font-medium text-muted-foreground uppercase tracking-wide">
+                Disconnected
+              </span>
+            )}
+            <button
+              onClick={handleSend}
+              disabled={!connected || !hasContent}
+              aria-label="Send"
+              className={cn(
+                "flex h-7 w-7 items-center justify-center rounded-lg transition-all",
+                hasContent && connected
+                  ? "bg-primary text-primary-foreground shadow-sm hover:bg-primary/90 active:scale-95"
+                  : "bg-muted text-muted-foreground cursor-not-allowed",
+              )}
+            >
+              <SendHorizonal className="h-3.5 w-3.5" />
+            </button>
+          </div>
+        </div>
+        </div>
+
+        {/* ── Top 3 action buttons with tooltips ── */}
+        {onOpenAction && (
+          <TooltipProvider delayDuration={300}>
+            {TOP_ACTIONS.map((action) => {
+              const Icon = action.icon
+              const isDisabled = action.disabledDuringAuto && autoActive
+              return (
+                <Tooltip key={action.command}>
+                  <TooltipTrigger asChild>
+                    <button
+                      onClick={() => onOpenAction(action)}
+                      disabled={isDisabled}
+                      aria-label={action.description}
+                      className={cn(
+                        "flex flex-shrink-0 items-center justify-center gap-1.5 rounded-xl border border-border bg-background px-3 py-2.5 text-xs font-medium text-foreground transition-colors hover:bg-accent",
+                        isDisabled && "cursor-not-allowed opacity-40",
+                      )}
+                    >
+                      <Icon className="h-3.5 w-3.5 text-muted-foreground" />
+                      {action.label}
+                    </button>
+                  </TooltipTrigger>
+                  <TooltipContent side="top" sideOffset={6}>
+                    <p className="font-medium">{action.label}</p>
+                    <p className="text-[10px] opacity-80">
+                      {isDisabled ? "Disabled while auto-mode is running" : action.description}
+                    </p>
+                  </TooltipContent>
+                </Tooltip>
+              )
+            })}
+
+            {/* ── Overflow menu ── */}
+            <Popover open={overflowOpen} onOpenChange={setOverflowOpen}>
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <PopoverTrigger asChild>
+                    <button
+                      aria-label="More GSD commands"
+                      className={cn(
+                        "flex flex-shrink-0 items-center justify-center rounded-xl border border-border bg-background p-2.5 text-foreground transition-colors hover:bg-accent",
+                        overflowOpen && "bg-accent",
+                      )}
+                    >
+                      <MoreHorizontal className="h-4 w-4 text-muted-foreground" />
+                    </button>
+                  </PopoverTrigger>
+                </TooltipTrigger>
+                {!overflowOpen && (
+                  <TooltipContent side="top" sideOffset={6}>
+                    More commands
+                  </TooltipContent>
+                )}
+              </Tooltip>
+
+              <PopoverContent
+                side="top"
+                align="end"
+                sideOffset={8}
+                className="w-64 max-h-[420px] overflow-y-auto rounded-xl border border-border bg-popover p-2 shadow-lg"
+              >
+                {overflowGroups.map((group, gi) => (
+                  <div key={group.category}>
+                    {gi > 0 && <div className="my-1.5 border-t border-border/50" />}
+                    <p className="px-2 py-1 text-[10px] font-semibold text-muted-foreground uppercase tracking-wider">
+                      {group.label}
+                    </p>
+                    {group.items.map((action) => {
+                      const Icon = action.icon
+                      const isDisabled = action.disabledDuringAuto && autoActive
+                      return (
+                        <Tooltip key={action.command}>
+                          <TooltipTrigger asChild>
+                            <button
+                              onClick={() => {
+                                if (isDisabled) return
+                                setOverflowOpen(false)
+                                onOpenAction(action)
+                              }}
+                              disabled={isDisabled}
+                              className={cn(
+                                "flex w-full items-center gap-2.5 rounded-lg px-2 py-1.5 text-left text-sm text-foreground transition-colors hover:bg-accent",
+                                isDisabled && "cursor-not-allowed opacity-40",
+                              )}
+                            >
+                              <Icon className="h-3.5 w-3.5 flex-shrink-0 text-muted-foreground" />
+                              <span className="flex-1 truncate">{action.label}</span>
+                            </button>
+                          </TooltipTrigger>
+                          <TooltipContent side="left" sideOffset={8}>
+                            <p className="font-medium">{action.label}</p>
+                            <p className="text-[10px] opacity-80">
+                              {isDisabled ? "Disabled while auto-mode is running" : action.description}
+                            </p>
+                          </TooltipContent>
+                        </Tooltip>
+                      )
+                    })}
+                  </div>
+                ))}
+              </PopoverContent>
+            </Popover>
+          </TooltipProvider>
+        )}
+      </div>
+    </div>
+  )
+}
+
+/* ─── Placeholder state ─── */
+
+function PlaceholderState({
+  connected,
+  runningLabel,
+  notice,
+  primaryAction,
+  onPrimaryAction,
+}: {
+  connected: boolean
+  runningLabel?: string
+  notice?: string | null
+  primaryAction?: { label: string; icon: LucideIcon } | null
+  onPrimaryAction?: () => void
+}) {
+  const showSpinner = connected && Boolean(runningLabel)
+
+  return (
+    <div className="flex flex-1 flex-col items-center justify-center text-center py-16">
+      <div className="flex h-12 w-12 items-center justify-center rounded-full border border-border bg-card">
+        {showSpinner ? (
+          <Loader2 className="h-5 w-5 animate-spin text-muted-foreground" />
+        ) : (
+          <MessagesSquare className="h-6 w-6 text-muted-foreground" />
+        )}
+      </div>
+      <div className="mt-3 space-y-1">
+        <p className="text-sm font-medium text-foreground">Chat Mode</p>
+        {showSpinner ? (
+          <p className="max-w-xs text-xs text-muted-foreground">
+            Running {runningLabel}…
+          </p>
+        ) : notice ? (
+          <p className="max-w-xs text-xs text-muted-foreground">{notice}</p>
+        ) : !connected ? (
+          <p className="max-w-xs text-xs text-muted-foreground">
+            Connecting to GSD session…
+          </p>
+        ) : primaryAction && onPrimaryAction ? (
+          <div className="mt-4">
+            <button
+              onClick={onPrimaryAction}
+              className="inline-flex items-center gap-2 rounded-xl border border-border bg-background px-5 py-2.5 text-sm font-medium text-foreground transition-colors hover:bg-accent active:scale-[0.98]"
+            >
+              <primaryAction.icon className="h-4 w-4 text-muted-foreground" />
+              {primaryAction.label}
+            </button>
+          </div>
+        ) : (
+          <p className="max-w-xs text-xs text-muted-foreground">
+            Connected — waiting for GSD output…
+          </p>
+        )}
+      </div>
+    </div>
+  )
+}
+
+
+/* ─── InlineUiRequest ─── */
+
+/**
+ * Renders a bridge-level PendingUiRequest inline in the chat message flow.
+ * Supports select (single + multi), confirm, input, and editor requests.
+ * After submission, transitions to a static confirmation state.
+ *
+ * The FocusedPanel (Sheet overlay in app-shell) is the fallback surface for
+ * these same requests in non-chat views. Whichever the user interacts with
+ * first resolves the request — the store deduplicates.
+ */
+function InlineUiRequest({ request }: { request: PendingUiRequest }) {
+  const { respondToUiRequest, dismissUiRequest } = useGSDWorkspaceActions()
+  const isSubmitting = useGSDWorkspaceState().commandInFlight === "extension_ui_response"
+
+  const handleSubmit = useCallback((value: Record<string, unknown>) => {
+    void respondToUiRequest(request.id, value)
+  }, [respondToUiRequest, request.id])
+
+  const handleDismiss = useCallback(() => {
+    void dismissUiRequest(request.id)
+  }, [dismissUiRequest, request.id])
+
+  return (
+    <div className="flex justify-start gap-3" data-testid="inline-ui-request" data-request-id={request.id}>
+      <div className="mt-1 flex-shrink-0 flex h-7 w-7 items-center justify-center rounded-full bg-card border border-border">
+        <PlatformLogoIcon className="h-3.5 w-auto" />
+      </div>
+      <div className="max-w-[82%] min-w-0 rounded-2xl rounded-tl-md border border-border bg-card px-4 py-3 shadow-sm">
+        {request.title && (
+          <p className="mb-2.5 text-sm font-medium text-foreground">{request.title}</p>
+        )}
+        {request.method === "select" && (
+          <InlineSelect request={request} onSubmit={handleSubmit} disabled={isSubmitting} />
+        )}
+        {request.method === "confirm" && (
+          <InlineConfirm request={request} onSubmit={handleSubmit} onDismiss={handleDismiss} disabled={isSubmitting} />
+        )}
+        {request.method === "input" && (
+          <InlineInput request={request} onSubmit={handleSubmit} disabled={isSubmitting} />
+        )}
+        {request.method === "editor" && (
+          <InlineEditor request={request} onSubmit={handleSubmit} disabled={isSubmitting} />
+        )}
+      </div>
+    </div>
+  )
+}
+
+function InlineSelect({
+  request,
+  onSubmit,
+  disabled,
+}: {
+  request: Extract<PendingUiRequest, { method: "select" }>
+  onSubmit: (value: Record<string, unknown>) => void
+  disabled: boolean
+}) {
+  const isMulti = Boolean(request.allowMultiple)
+  const [singleValue, setSingleValue] = useState("")
+  const [multiValues, setMultiValues] = useState<Set<string>>(new Set())
+  const [submitted, setSubmitted] = useState(false)
+
+  const handleSubmit = useCallback(() => {
+    setSubmitted(true)
+    onSubmit({ value: isMulti ? Array.from(multiValues) : singleValue })
+  }, [isMulti, singleValue, multiValues, onSubmit])
+
+  if (submitted) {
+    return (
+      <div className="flex items-center gap-1.5 rounded-lg bg-primary/10 px-3 py-2 text-sm text-primary">
+        <Check className="h-3.5 w-3.5 flex-shrink-0" />
+        <span className="font-medium">{isMulti ? `${multiValues.size} selected` : singleValue}</span>
+      </div>
+    )
+  }
+
+  const canSubmit = isMulti ? multiValues.size > 0 : singleValue !== ""
+
+  return (
+    <div className="space-y-1.5">
+      {request.options.map((option, i) => {
+        if (isMulti) {
+          const checked = multiValues.has(option)
+          return (
+            <button
+              key={i}
+              onClick={() => {
+                const next = new Set(multiValues)
+                if (checked) next.delete(option); else next.add(option)
+                setMultiValues(next)
+              }}
+              disabled={disabled}
+              className={cn(
+                "flex w-full items-center gap-2.5 rounded-lg px-3 py-2 text-left text-sm transition-colors",
+                checked ? "bg-primary/15 text-primary font-medium" : "text-foreground hover:bg-muted",
+              )}
+            >
+              <span className="flex h-4 w-4 flex-shrink-0 items-center justify-center rounded border border-border">
+                {checked && <Check className="h-2.5 w-2.5 text-primary" />}
+              </span>
+              <span>{option}</span>
+            </button>
+          )
+        }
+        const selected = singleValue === option
+        return (
+          <button
+            key={i}
+            onClick={() => setSingleValue(option)}
+            disabled={disabled}
+            className={cn(
+              "flex w-full items-center gap-2.5 rounded-lg px-3 py-2 text-left text-sm transition-colors",
+              selected ? "bg-primary/15 text-primary font-medium" : "text-foreground hover:bg-muted",
+            )}
+          >
+            <span className="flex h-4 w-4 flex-shrink-0 items-center justify-center">
+              {selected ? (
+                <Check className="h-3 w-3 text-primary" />
+              ) : (
+                <span className="h-1.5 w-1.5 rounded-full bg-muted-foreground/30" />
+              )}
+            </span>
+            <span>{option}</span>
+          </button>
+        )
+      })}
+      <button
+        onClick={handleSubmit}
+        disabled={disabled || !canSubmit}
+        className={cn(
+          "mt-2 flex w-full items-center justify-center rounded-lg px-3 py-2 text-xs font-medium transition-all",
+          canSubmit && !disabled
+            ? "bg-primary text-primary-foreground hover:bg-primary/90 active:scale-[0.98] shadow-sm"
+            : "bg-muted text-muted-foreground cursor-not-allowed",
+        )}
+      >
+        {isMulti ? `Submit (${multiValues.size})` : "Submit"}
+      </button>
+    </div>
+  )
+}
+
+function InlineConfirm({
+  request,
+  onSubmit,
+  onDismiss,
+  disabled,
+}: {
+  request: Extract<PendingUiRequest, { method: "confirm" }>
+  onSubmit: (value: Record<string, unknown>) => void
+  onDismiss: () => void
+  disabled: boolean
+}) {
+  const [resolved, setResolved] = useState<boolean | null>(null)
+
+  if (resolved !== null) {
+    return (
+      <div className="flex items-center gap-1.5 rounded-lg bg-primary/10 px-3 py-2 text-sm text-primary">
+        <Check className="h-3.5 w-3.5 flex-shrink-0" />
+        <span className="font-medium">{resolved ? "Confirmed" : "Cancelled"}</span>
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-2.5">
+      <p className="text-sm text-foreground leading-relaxed">{request.message}</p>
+      <div className="flex gap-2">
+        <button
+          onClick={() => { setResolved(true); onSubmit({ value: true }) }}
+          disabled={disabled}
+          className="flex-1 rounded-lg bg-primary px-3 py-2 text-xs font-medium text-primary-foreground hover:bg-primary/90 active:scale-[0.98] shadow-sm transition-all"
+        >
+          Confirm
+        </button>
+        <button
+          onClick={() => { setResolved(false); onDismiss() }}
+          disabled={disabled}
+          className="flex-1 rounded-lg border border-border bg-background px-3 py-2 text-xs font-medium text-foreground hover:bg-accent transition-colors"
+        >
+          Cancel
+        </button>
+      </div>
+    </div>
+  )
+}
+
+function InlineInput({
+  request,
+  onSubmit,
+  disabled,
+}: {
+  request: Extract<PendingUiRequest, { method: "input" }>
+  onSubmit: (value: Record<string, unknown>) => void
+  disabled: boolean
+}) {
+  const [value, setValue] = useState("")
+  const [submitted, setSubmitted] = useState(false)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  useEffect(() => { inputRef.current?.focus() }, [])
+
+  if (submitted) {
+    return (
+      <div className="flex items-center gap-1.5 rounded-lg bg-primary/10 px-3 py-2 text-sm text-primary">
+        <Check className="h-3.5 w-3.5 flex-shrink-0" />
+        <span className="font-medium">Submitted</span>
+      </div>
+    )
+  }
+
+  const handleSubmit = () => {
+    if (!value.trim() || disabled) return
+    setSubmitted(true)
+    onSubmit({ value })
+  }
+
+  return (
+    <div className="flex gap-2">
+      <Input
+        ref={inputRef}
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        onKeyDown={(e) => { if (e.key === "Enter") { e.preventDefault(); handleSubmit() } }}
+        placeholder={request.placeholder || "Type your answer…"}
+        disabled={disabled}
+        className="flex-1 h-8 text-sm"
+      />
+      <button
+        onClick={handleSubmit}
+        disabled={disabled || !value.trim()}
+        className={cn(
+          "flex h-8 items-center justify-center rounded-lg px-3 text-xs font-medium transition-all",
+          value.trim() && !disabled
+            ? "bg-primary text-primary-foreground hover:bg-primary/90 active:scale-95 shadow-sm"
+            : "bg-muted text-muted-foreground cursor-not-allowed",
+        )}
+      >
+        Submit
+      </button>
+    </div>
+  )
+}
+
+function InlineEditor({
+  request,
+  onSubmit,
+  disabled,
+}: {
+  request: Extract<PendingUiRequest, { method: "editor" }>
+  onSubmit: (value: Record<string, unknown>) => void
+  disabled: boolean
+}) {
+  const [value, setValue] = useState(request.prefill || "")
+  const [submitted, setSubmitted] = useState(false)
+
+  if (submitted) {
+    return (
+      <div className="flex items-center gap-1.5 rounded-lg bg-primary/10 px-3 py-2 text-sm text-primary">
+        <Check className="h-3.5 w-3.5 flex-shrink-0" />
+        <span className="font-medium">Submitted</span>
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-2">
+      <textarea
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        disabled={disabled}
+        className="w-full min-h-[120px] rounded-lg border border-border bg-background px-3 py-2 text-sm font-mono focus:outline-none focus:ring-1 focus:ring-border/30 resize-y"
+        autoFocus
+      />
+      <button
+        onClick={() => { setSubmitted(true); onSubmit({ value }) }}
+        disabled={disabled}
+        className="flex w-full items-center justify-center rounded-lg bg-primary px-3 py-2 text-xs font-medium text-primary-foreground hover:bg-primary/90 active:scale-[0.98] shadow-sm transition-all"
+      >
+        Submit
+      </button>
+    </div>
+  )
+}
+
+/* ─── Chat Pane ─── */
+
+interface ChatPaneProps {
+  sessionId?: string
+  command?: string
+  commandArgs?: string[]
+  className?: string
+  initialCommand?: string
+  onCompletionSignal?: () => void
+  onOpenAction?: (action: GSDActionDef) => void
+  activityLabel?: string
+  suppressTerminalChrome?: boolean
+  suppressInitialEcho?: boolean
+}
+
+/* ─── ToolExecutionBlock ─── */
+
+/**
+ * Renders a completed tool execution as a collapsible block.
+ * Edit tool shows a syntax-highlighted unified diff.
+ * Write tool shows the file path and a preview.
+ * Bash tool shows the command and output.
+ * Other tools show a compact summary.
+ */
+function ToolExecutionBlock({ tool }: { tool: CompletedToolExecution }) {
+  const [expanded, setExpanded] = useState(false)
+  const autoExpandedRef = useRef(false)
+  const normalizedToolName = typeof tool.name === "string" ? tool.name.toLowerCase() : ""
+
+  const path = typeof tool.args?.path === "string" ? tool.args.path : typeof tool.args?.file_path === "string" ? tool.args.file_path : null
+  const shortPath = path ? (path.startsWith(process.env.HOME ?? "/Users") ? "~" + path.slice((process.env.HOME ?? "").length) : path) : null
+  const isError = tool.result?.isError ?? false
+  const diff = tool.result?.details?.diff as string | undefined
+
+  // Choose icon and label
+  const icon = normalizedToolName === "edit" ? <FileEdit className="h-3.5 w-3.5" />
+    : normalizedToolName === "write" ? <FilePlus className="h-3.5 w-3.5" />
+    : <Terminal className="h-3.5 w-3.5" />
+
+  const label = normalizedToolName === "edit" ? "Edit"
+    : normalizedToolName === "write" ? "Write"
+    : normalizedToolName === "bash" ? "$"
+    : tool.name
+
+  // For bash, show the command
+  const bashCommand = normalizedToolName === "bash" && typeof tool.args?.command === "string" ? tool.args.command : null
+
+  // Result text (for bash output, read result, etc.)
+  const resultText = tool.result?.content
+    ?.filter((c) => c.type === "text" && c.text)
+    .map((c) => c.text)
+    .join("\n") ?? ""
+
+  useEffect(() => {
+    if (autoExpandedRef.current) return
+    const hasVisibleResult = Boolean(diff || resultText.trim() || isError)
+    if (!hasVisibleResult) return
+    autoExpandedRef.current = true
+    setExpanded(true)
+  }, [diff, resultText, isError])
+
+  return (
+    <div className="flex justify-start gap-3">
+      <div className="w-7 flex-shrink-0" />
+      <div className="max-w-[82%] min-w-0 w-full">
+        <button
+          onClick={() => setExpanded((e) => !e)}
+          className={cn(
+            "w-full rounded-lg border px-3 py-2 text-left text-xs transition-colors",
+            isError
+              ? "border-destructive/30 bg-destructive/5 hover:bg-destructive/10"
+              : "border-border/50 bg-muted/50 hover:bg-muted/50",
+          )}
+        >
+          {/* Header */}
+          <div className="flex items-center gap-2">
+            <span className={cn("flex-shrink-0", isError ? "text-destructive" : "text-muted-foreground")}>
+              {icon}
+            </span>
+            <span className={cn("font-mono font-medium", isError ? "text-destructive" : "text-muted-foreground")}>
+              {label}
+            </span>
+            {shortPath && (
+              <span className="truncate font-mono text-info/80">{shortPath}</span>
+            )}
+            {bashCommand && !shortPath && (
+              <span className="truncate font-mono text-muted-foreground">{bashCommand.length > 60 ? bashCommand.slice(0, 60) + "…" : bashCommand}</span>
+            )}
+            <span className="ml-auto flex-shrink-0 text-muted-foreground">
+              {expanded ? <ChevronDown className="h-3 w-3" /> : <ChevronRight className="h-3 w-3" />}
+            </span>
+          </div>
+
+          {/* Expanded content */}
+          {expanded && diff && (
+            <div className="mt-2 overflow-x-auto rounded-md border border-border/50 bg-background p-2 font-mono text-[11px] leading-relaxed">
+              {diff.split("\n").map((line, i) => {
+                const isAdd = line.startsWith("+")
+                const isRemove = line.startsWith("-")
+                const isContext = line.startsWith(" ")
+                return (
+                  <div
+                    key={i}
+                    className={cn(
+                      "whitespace-pre",
+                      isAdd && "bg-success/10 text-success",
+                      isRemove && "bg-destructive/10 text-destructive",
+                      isContext && "text-muted-foreground",
+                      !isAdd && !isRemove && !isContext && "text-muted-foreground",
+                    )}
+                  >
+                    {line}
+                  </div>
+                )
+              })}
+            </div>
+          )}
+
+          {/* Expanded: bash output or other result */}
+          {expanded && !diff && resultText && (
+            <div className="mt-2 max-h-[200px] overflow-y-auto rounded-md border border-border/50 bg-background p-2 font-mono text-[11px] leading-relaxed text-muted-foreground whitespace-pre-wrap">
+              {resultText.length > 2000 ? resultText.slice(0, 2000) + "\n…" : resultText}
+            </div>
+          )}
+
+          {/* Error message */}
+          {expanded && isError && resultText && (
+            <div className="mt-2 rounded-md border border-destructive/20 bg-destructive/5 p-2 text-[11px] text-destructive whitespace-pre-wrap">
+              {resultText}
+            </div>
+          )}
+        </button>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * ChatPane — bridge event-driven chat rendering.
+ *
+ * Consumes structured agent events from the workspace store:
+ * - streamingAssistantText: live text deltas from the LLM
+ * - streamingThinkingText: live thinking/reasoning deltas
+ * - liveTranscript: completed text blocks from previous turns
+ * - activeToolExecution: currently running tool call
+ *
+ * User messages are tracked locally and sent via submitInput().
+ * No terminal buffer parsing — all data comes from the bridge event stream.
+ *
+ * Observability:
+ *   - data-testid="chat-pane-store-driven" on the root element
+ *   - ChatInputBar shows "Disconnected" badge when bridge is not connected
+ */
+export function ChatPane({ className, onOpenAction }: ChatPaneProps) {
+  const state = useGSDWorkspaceState()
+  const { submitInput, sendCommand, pushChatUserMessage } = useGSDWorkspaceActions()
+  const [terminalFontSize] = useTerminalFontSize()
+
+  const connected = state.connectionState === "connected"
+  const isStreaming = state.boot?.bridge.sessionState?.isStreaming ?? false
+  const bridge = state.boot?.bridge ?? null
+
+  // ── Derive smart CTA for the placeholder state ──
+  const workflowAction = deriveWorkflowAction({
+    phase: state.boot?.workspace?.active.phase ?? "pre-planning",
+    autoActive: state.boot?.auto?.active ?? false,
+    autoPaused: state.boot?.auto?.paused ?? false,
+    onboardingLocked: state.boot?.onboarding.locked ?? false,
+    commandInFlight: state.commandInFlight,
+    bootStatus: state.bootStatus,
+    hasMilestones: (state.boot?.workspace?.milestones.length ?? 0) > 0,
+    projectDetectionKind: state.boot?.projectDetection?.kind ?? null,
+  })
+
+  const placeholderCTA = useMemo((): { label: string; icon: LucideIcon } | null => {
+    if (!workflowAction.primary || workflowAction.disabled) return null
+    const phase = state.boot?.workspace?.active.phase ?? "pre-planning"
+    const autoActive = state.boot?.auto?.active ?? false
+    const autoPaused = state.boot?.auto?.paused ?? false
+
+    if (autoActive && !autoPaused) {
+      return { label: "Stop Auto", icon: Square }
+    }
+    if (autoPaused) {
+      return { label: "Resume Auto", icon: Play }
+    }
+    if (phase === "complete") {
+      return { label: "New Milestone", icon: Milestone }
+    }
+    if (phase === "planning") {
+      return { label: "Plan", icon: Play }
+    }
+    if (phase === "executing" || phase === "summarizing") {
+      return { label: "Start Auto", icon: Zap }
+    }
+    if (phase === "pre-planning") {
+      return { label: "Initialize Project", icon: Play }
+    }
+    return { label: "Continue", icon: Play }
+  }, [workflowAction, state.boot?.workspace?.active.phase, state.boot?.auto?.active, state.boot?.auto?.paused])
+
+  const handlePlaceholderCTA = useCallback(() => {
+    if (!workflowAction.primary) return
+    void sendCommand(buildPromptCommand(workflowAction.primary.command, bridge))
+  }, [workflowAction, sendCommand, bridge])
+
+  /** Send user text — adds a user bubble and dispatches via the store */
+  const handleUserInput = useCallback((data: string, images?: PendingImage[]) => {
+    const text = data.replace(/\r$/, "").trim()
+    if (!text && (!images || images.length === 0)) return
+
+    const userMsg: ChatMessage = {
+      id: createLocalMessageId(),
+      role: "user",
+      content: text,
+      complete: true,
+      timestamp: Date.now(),
+      images: images?.map((i) => ({ data: i.data, mimeType: i.mimeType })),
+    }
+    pushChatUserMessage(userMsg)
+    void submitInput(text, images)
+  }, [submitInput, pushChatUserMessage])
+
+  // Build unified timeline from store state.
+  // Uses the segment-ordered data to render thinking/text/tool blocks
+  // in their actual chronological order within each turn.
+  type TimelineItem =
+    | { kind: "thinking"; content: string; id: string }
+    | { kind: "message"; message: ChatMessage }
+    | { kind: "tool"; tool: CompletedToolExecution }
+    | { kind: "active-tool"; tool: ActiveToolExecution }
+    | { kind: "streaming-thinking"; content: string }
+    | { kind: "streaming-message"; content: string; isThinking: boolean }
+    | { kind: "ui-request"; request: PendingUiRequest }
+
+  const timeline = useMemo((): TimelineItem[] => {
+    const items: TimelineItem[] = []
+    const transcriptBlocks = state.liveTranscript
+    const segmentBlocks = state.completedTurnSegments
+    const userMsgs = state.chatUserMessages
+
+    // Interleave: user messages alternate with assistant turns.
+    // For completed turns, render from segments to preserve chronological order.
+    for (let i = 0; i < Math.max(userMsgs.length, transcriptBlocks.length); i++) {
+      if (i < userMsgs.length) {
+        items.push({ kind: "message", message: userMsgs[i] })
+      }
+      if (i < segmentBlocks.length && segmentBlocks[i].length > 0) {
+        // Render each segment in order
+        for (const seg of segmentBlocks[i]) {
+          if (seg.kind === "thinking") {
+            items.push({ kind: "thinking", content: seg.content, id: `turn-${i}-thinking-${items.length}` })
+          } else if (seg.kind === "text") {
+            items.push({
+              kind: "message",
+              message: {
+                id: `turn-${i}-text-${items.length}`,
+                role: "assistant",
+                content: seg.content,
+                complete: true,
+                timestamp: i + 1,
+              },
+            })
+          } else if (seg.kind === "tool") {
+            items.push({ kind: "tool", tool: seg.tool })
+          }
+        }
+      } else if (i < transcriptBlocks.length && transcriptBlocks[i].trim()) {
+        // Fallback: no segments stored yet (shouldn't happen for new turns, but safe)
+        items.push({
+          kind: "message",
+          message: {
+            id: `transcript-${i}`,
+            role: "assistant",
+            content: transcriptBlocks[i],
+            complete: true,
+            timestamp: i + 1,
+          },
+        })
+      }
+    }
+
+    // Current turn: render finalized segments, then any in-flight content
+    for (const seg of state.currentTurnSegments) {
+      if (seg.kind === "thinking") {
+        items.push({ kind: "thinking", content: seg.content, id: `current-thinking-${items.length}` })
+      } else if (seg.kind === "text") {
+        items.push({
+          kind: "message",
+          message: {
+            id: `current-text-${items.length}`,
+            role: "assistant",
+            content: seg.content,
+            complete: true,
+            timestamp: Date.now(),
+          },
+        })
+      } else if (seg.kind === "tool") {
+        items.push({ kind: "tool", tool: seg.tool })
+      }
+    }
+
+    // Active tool execution indicator
+    if (state.activeToolExecution) {
+      items.push({ kind: "active-tool", tool: state.activeToolExecution })
+    }
+
+    // Currently streaming thinking (live, not yet finalized into a segment)
+    if (state.streamingThinkingText.length > 0) {
+      items.push({ kind: "streaming-thinking", content: state.streamingThinkingText })
+    }
+
+    // Currently streaming text (live)
+    if (state.streamingAssistantText.length > 0) {
+      items.push({
+        kind: "streaming-message",
+        content: state.streamingAssistantText,
+        isThinking: false,
+      })
+    }
+
+    // If only thinking is happening (no text yet, no tool), show a minimal indicator
+    if (
+      state.streamingThinkingText.length === 0 &&
+      state.streamingAssistantText.length === 0 &&
+      !state.activeToolExecution &&
+      isStreaming &&
+      state.currentTurnSegments.length === 0
+    ) {
+      // Pure waiting state — streaming started but nothing produced yet
+      items.push({ kind: "streaming-message", content: "", isThinking: true })
+    }
+
+    // Pending UI requests — at the end
+    for (const req of state.pendingUiRequests) {
+      items.push({ kind: "ui-request", request: req })
+    }
+
+    return items
+  }, [state.liveTranscript, state.completedTurnSegments, state.currentTurnSegments, state.streamingAssistantText, state.streamingThinkingText, state.activeToolExecution, state.pendingUiRequests, state.chatUserMessages, isStreaming])
+
+  // Prompt submit handler for TUI prompts (select/text/password)
+  const handlePromptSubmit = useCallback((data: string) => {
+    void submitInput(data.replace(/\r$/, ""))
+  }, [submitInput])
+
+  const showPlaceholder = timeline.length === 0 && !isStreaming
+
+  // Show an "awaiting input" indicator when the session is idle (connected,
+  // not streaming, has timeline content) so the UI does not appear stuck (#2707).
+  const showAwaitingInput = connected && !isStreaming && timeline.length > 0
+    && !state.activeToolExecution
+    && state.pendingUiRequests.length === 0
+
+  // Auto-scroll ref
+  const scrollRef = useRef<HTMLDivElement>(null)
+  const isNearBottomRef = useRef(true)
+
+  const handleScroll = useCallback(() => {
+    const el = scrollRef.current
+    if (!el) return
+    isNearBottomRef.current = el.scrollHeight - el.scrollTop - el.clientHeight < 100
+  }, [])
+
+  useEffect(() => {
+    const el = scrollRef.current
+    if (!el) return
+    if (isNearBottomRef.current) {
+      el.scrollTop = el.scrollHeight
+    }
+  }, [timeline])
+
+  return (
+    <div
+      data-testid="chat-pane-store-driven"
+      className={cn("flex flex-col overflow-hidden", className)}
+    >
+      <div className="flex flex-1 flex-col overflow-hidden">
+        {showPlaceholder ? (
+          <PlaceholderState
+            connected={connected}
+            runningLabel={isStreaming ? "responding" : undefined}
+            primaryAction={placeholderCTA}
+            onPrimaryAction={handlePlaceholderCTA}
+          />
+        ) : (
+          <div
+            ref={scrollRef}
+            onScroll={handleScroll}
+            className="flex-1 overflow-y-auto px-4 py-4 space-y-4"
+            style={terminalFontSize !== 13 ? { fontSize: `${terminalFontSize}px` } : undefined}
+          >
+            {timeline.map((item, idx) => {
+              switch (item.kind) {
+                case "message":
+                  return (
+                    <ChatBubble
+                      key={item.message.id}
+                      message={item.message}
+                      onSubmitPrompt={handlePromptSubmit}
+                    />
+                  )
+                case "thinking":
+                  return (
+                    <div key={item.id} className="flex justify-start gap-3">
+                      <div className="w-7 flex-shrink-0" />
+                      <div className="max-w-[82%] min-w-0">
+                        <InlineThinking content={item.content} isStreaming={false} />
+                      </div>
+                    </div>
+                  )
+                case "streaming-thinking":
+                  return (
+                    <div key="streaming-thinking" className="flex justify-start gap-3">
+                      <div className="w-7 flex-shrink-0" />
+                      <div className="max-w-[82%] min-w-0">
+                        <InlineThinking content={item.content} isStreaming={true} />
+                      </div>
+                    </div>
+                  )
+                case "streaming-message":
+                  return (
+                    <ChatBubble
+                      key="streaming-message"
+                      message={{
+                        id: "streaming-current",
+                        role: "assistant",
+                        content: item.content,
+                        complete: false,
+                        timestamp: Date.now(),
+                      }}
+                      isThinking={item.isThinking}
+                    />
+                  )
+                case "tool":
+                  return <ToolExecutionBlock key={item.tool.id} tool={item.tool} />
+                case "active-tool":
+                  return (
+                    <div key={`active-${item.tool.id}`} className="flex justify-start gap-3">
+                      <div className="w-7 flex-shrink-0" />
+                      <div className="max-w-[82%] min-w-0">
+                        <div className="flex items-center gap-2 rounded-lg border border-border/50 bg-muted/50 px-3.5 py-2">
+                          <Loader2 className="h-3 w-3 animate-spin text-muted-foreground" />
+                          <span className="font-mono text-xs text-muted-foreground">
+                            {item.tool.name}
+                          </span>
+                          {Boolean(item.tool.args?.path) && (
+                            <span className="font-mono text-xs text-info/80 truncate">
+                              {String(item.tool.args?.path)}
+                            </span>
+                          )}
+                        </div>
+                      </div>
+                    </div>
+                  )
+                case "ui-request":
+                  return <InlineUiRequest key={item.request.id} request={item.request} />
+              }
+            })}
+            {showAwaitingInput && (
+              <div className="flex items-center gap-2 px-1 py-1 text-xs text-muted-foreground animate-in fade-in duration-500">
+                <span className="inline-block h-2 w-2 rounded-full bg-emerald-500/70 animate-pulse" />
+                Ready for your input
+              </div>
+            )}
+            <div className="h-2" />
+          </div>
+        )}
+      </div>
+
+      <ChatInputBar
+        onSendInput={handleUserInput}
+        connected={connected}
+        onOpenAction={onOpenAction}
+      />
+    </div>
+  )
+}
diff --git a/web/components/sf/code-editor.tsx b/web/components/sf/code-editor.tsx
new file mode 100644
index 000000000..164b1ce0c
--- /dev/null
+++ b/web/components/sf/code-editor.tsx
@@ -0,0 +1,221 @@
+"use client"
+
+import { useMemo } from "react"
+import dynamic from "next/dynamic"
+import { useTheme } from "next-themes"
+import { Loader2 } from "lucide-react"
+import { createTheme } from "@uiw/codemirror-themes"
+import { tags as t } from "@lezer/highlight"
+import { loadLanguage, type LanguageName } from "@uiw/codemirror-extensions-langs"
+import { EditorView } from "@codemirror/view"
+import { cn } from "@/lib/utils"
+
+/* ── Dynamic import (no SSR — CodeMirror needs browser DOM) ── */
+
+const ReactCodeMirror = dynamic(() => import("@uiw/react-codemirror"), {
+  ssr: false,
+  loading: () => (
+    <div className="flex h-full min-h-[120px] items-center justify-center">
+      <Loader2 className="h-5 w-5 animate-spin text-muted-foreground" />
+    </div>
+  ),
+})
+
+/* ── Syntax highlighting styles ── */
+
+const darkStyles = [
+  { tag: [t.comment, t.lineComment, t.blockComment], color: "#6a737d" },
+  { tag: [t.keyword], color: "#ff7b72" },
+  { tag: [t.operator], color: "#79c0ff" },
+  { tag: [t.string, t.special(t.string)], color: "#a5d6ff" },
+  { tag: [t.number, t.bool, t.null], color: "#79c0ff" },
+  { tag: [t.variableName], color: "#c9d1d9" },
+  { tag: [t.definition(t.variableName)], color: "#d2a8ff" },
+  { tag: [t.function(t.variableName)], color: "#d2a8ff" },
+  { tag: [t.typeName, t.className], color: "#ffa657" },
+  { tag: [t.propertyName], color: "#79c0ff" },
+  { tag: [t.definition(t.propertyName)], color: "#c9d1d9" },
+  { tag: [t.bracket], color: "#8b949e" },
+  { tag: [t.punctuation], color: "#8b949e" },
+  { tag: [t.tagName], color: "#7ee787" },
+  { tag: [t.attributeName], color: "#79c0ff" },
+  { tag: [t.attributeValue], color: "#a5d6ff" },
+  { tag: [t.regexp], color: "#7ee787" },
+  { tag: [t.escape], color: "#79c0ff" },
+  { tag: [t.meta], color: "#8b949e" },
+]
+
+const lightStyles = [
+  { tag: [t.comment, t.lineComment, t.blockComment], color: "#6a737d" },
+  { tag: [t.keyword], color: "#cf222e" },
+  { tag: [t.operator], color: "#0550ae" },
+  { tag: [t.string, t.special(t.string)], color: "#0a3069" },
+  { tag: [t.number, t.bool, t.null], color: "#0550ae" },
+  { tag: [t.variableName], color: "#24292f" },
+  { tag: [t.definition(t.variableName)], color: "#8250df" },
+  { tag: [t.function(t.variableName)], color: "#8250df" },
+  { tag: [t.typeName, t.className], color: "#953800" },
+  { tag: [t.propertyName], color: "#0550ae" },
+  { tag: [t.definition(t.propertyName)], color: "#24292f" },
+  { tag: [t.bracket], color: "#57606a" },
+  { tag: [t.punctuation], color: "#57606a" },
+  { tag: [t.tagName], color: "#116329" },
+  { tag: [t.attributeName], color: "#0550ae" },
+  { tag: [t.attributeValue], color: "#0a3069" },
+  { tag: [t.regexp], color: "#116329" },
+  { tag: [t.escape], color: "#0550ae" },
+  { tag: [t.meta], color: "#57606a" },
+]
+
+/* ── Static theme objects (module-level, never recreated on render) ── */
+
+const darkTheme = createTheme({
+  theme: "dark",
+  settings: {
+    background: "oklch(0.09 0 0)",
+    foreground: "oklch(0.9 0 0)",
+    caret: "oklch(0.9 0 0)",
+    selection: "oklch(0.2 0 0)",
+    lineHighlight: "oklch(0.12 0 0)",
+    gutterBackground: "oklch(0.09 0 0)",
+    gutterForeground: "oklch(0.42 0 0)",
+    gutterBorder: "transparent",
+  },
+  styles: darkStyles,
+})
+
+const lightTheme = createTheme({
+  theme: "light",
+  settings: {
+    background: "oklch(0.98 0 0)",
+    foreground: "oklch(0.15 0 0)",
+    caret: "oklch(0.15 0 0)",
+    selection: "oklch(0.9 0 0)",
+    lineHighlight: "oklch(0.96 0 0)",
+    gutterBackground: "oklch(0.98 0 0)",
+    gutterForeground: "oklch(0.55 0 0)",
+    gutterBorder: "transparent",
+  },
+  styles: lightStyles,
+})
+
+/* ── Language mapping (shiki lang names → CodeMirror loadLanguage names) ── */
+
+const CM_LANG_MAP: Record<string, LanguageName | null> = {
+  // TypeScript / JavaScript family
+  typescript: "ts",
+  tsx: "tsx",
+  javascript: "js",
+  jsx: "jsx",
+  // Shell variants
+  bash: "bash",
+  sh: "sh",
+  zsh: "sh",
+  // Data formats
+  json: "json",
+  jsonc: "json",
+  yaml: "yaml",
+  toml: "toml",
+  // Markup
+  markdown: "markdown",
+  mdx: "markdown", // CM has no mdx — use markdown
+  html: "html",
+  xml: "xml",
+  // Styles
+  css: "css",
+  scss: "scss",
+  less: "less",
+  // Systems
+  python: "py",
+  ruby: "rb",
+  rust: "rs",
+  go: "go",
+  java: "java",
+  kotlin: "kt",
+  swift: "swift",
+  c: "c",
+  cpp: "cpp",
+  csharp: "cs",
+  // Other
+  php: "php",
+  sql: "sql",
+  graphql: null, // CM has no graphql support
+  dockerfile: null, // CM has no dockerfile support
+  makefile: null, // CM has no makefile support
+  lua: "lua",
+  r: "r",
+  latex: "tex",
+  diff: "diff",
+  // No CM equivalent → plain text
+  viml: null,
+  dotenv: null,
+  fish: null,
+  ini: "ini",
+}
+
+/* ── Component ── */
+
+interface CodeEditorProps {
+  value: string
+  onChange: (value: string) => void
+  language: string | null
+  fontSize: number
+  className?: string
+}
+
+export function CodeEditor({
+  value,
+  onChange,
+  language,
+  fontSize,
+  className,
+}: CodeEditorProps) {
+  const { resolvedTheme } = useTheme()
+  const theme = resolvedTheme !== "light" ? darkTheme : lightTheme
+
+  // Resolve and cache language extension
+  const langExtension = useMemo(() => {
+    if (!language) return null
+    const cmName = CM_LANG_MAP[language]
+    if (cmName === undefined || cmName === null) return null
+    return loadLanguage(cmName)
+  }, [language])
+
+  // Font size extension
+  const fontSizeExt = useMemo(
+    () =>
+      EditorView.theme({
+        "&": { fontSize: `${fontSize}px` },
+        ".cm-gutters": { fontSize: `${fontSize}px` },
+      }),
+    [fontSize],
+  )
+
+  // Combined extensions (memoized to avoid re-initialization)
+  const extensions = useMemo(() => {
+    const exts = [fontSizeExt]
+    if (langExtension) exts.push(langExtension)
+    return exts
+  }, [fontSizeExt, langExtension])
+
+  return (
+    <ReactCodeMirror
+      value={value}
+      onChange={onChange}
+      theme={theme}
+      extensions={extensions}
+      height="100%"
+      basicSetup={{
+        lineNumbers: true,
+        highlightActiveLine: true,
+        highlightActiveLineGutter: true,
+        foldGutter: true,
+        bracketMatching: true,
+        closeBrackets: true,
+        autocompletion: false,
+        tabSize: 2,
+      }}
+      className={cn("overflow-hidden rounded-md border", className)}
+    />
+  )
+}
diff --git a/web/components/sf/command-surface.tsx b/web/components/sf/command-surface.tsx
new file mode 100644
index 000000000..85c5f1b03
--- /dev/null
+++ b/web/components/sf/command-surface.tsx
@@ -0,0 +1,2341 @@
+"use client"
+
+import { useEffect, useMemo, useRef, useState } from "react"
+import {
+  Archive,
+  ArrowRightLeft,
+  Brain,
+  Check,
+  ChevronRight,
+  Cpu,
+  Download,
+  ExternalLink,
+  FileText,
+  FlaskConical,
+  FolderRoot,
+  GitBranch,
+  KeyRound,
+  LifeBuoy,
+  LoaderCircle,
+  LogIn,
+  LogOut,
+  PencilLine,
+  Radio,
+  RefreshCw,
+  Search,
+  ShieldCheck,
+  SlidersHorizontal,
+  SquareTerminal,
+  X,
+} from "lucide-react"
+
+import { toast } from "sonner"
+
+import { Badge } from "@/components/ui/badge"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { ScrollArea } from "@/components/ui/scroll-area"
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from "@/components/ui/sheet"
+import { Switch } from "@/components/ui/switch"
+import { Textarea } from "@/components/ui/textarea"
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
+import {
+  COMMAND_SURFACE_THINKING_LEVELS,
+  type CommandSurfaceSection,
+  type CommandSurfaceTarget,
+} from "@/lib/command-surface-contract"
+import { cn } from "@/lib/utils"
+import {
+  DEV_OVERRIDE_REGISTRY,
+  useDevOverrides,
+} from "@/lib/dev-overrides"
+import { DoctorPanel, ForensicsPanel, SkillHealthPanel } from "./diagnostics-panels"
+import { KnowledgeCapturesPanel } from "./knowledge-captures-panel"
+import { PrefsPanel, ModelRoutingPanel, BudgetPanel, RemoteQuestionsPanel, GeneralPanel, ExperimentalPanel } from "./settings-panels"
+import { DevRootSettingsSection } from "./projects-view"
+import {
+  QuickPanel,
+  HistoryPanel,
+  UndoPanel,
+  SteerPanel,
+  HooksPanel,
+  InspectPanel,
+  ExportPanel,
+  CleanupPanel,
+  QueuePanel,
+  StatusPanel,
+} from "./remaining-command-panels"
+import {
+  formatCost,
+  formatTokens,
+  getModelLabel,
+  getSessionLabelFromBridge,
+  shortenPath,
+  useGSDWorkspaceActions,
+  useGSDWorkspaceState,
+} from "@/lib/sf-workspace-store"
+
+// ─── Section metadata ────────────────────────────────────────────────
+
+const SETTINGS_SURFACE_SECTIONS = ["general", "model", "session-behavior", "recovery", "auth", "integrations", "workspace", "experimental"] as const
+const ADMIN_SECTION: CommandSurfaceSection = "admin"
+const GIT_SURFACE_SECTIONS = ["git"] as const
+const SESSION_SURFACE_SECTIONS = ["resume", "name", "fork", "session", "compact"] as const
+
+function availableSectionsForSurface(surface: string | null, includeAdmin: boolean = false): CommandSurfaceSection[] {
+  switch (surface) {
+    case "git":
+      return [...GIT_SURFACE_SECTIONS]
+    case "resume":
+    case "name":
+    case "fork":
+    case "session":
+    case "export":
+    case "compact":
+      return [...SESSION_SURFACE_SECTIONS]
+    default:
+      return includeAdmin
+        ? [...SETTINGS_SURFACE_SECTIONS, ADMIN_SECTION]
+        : [...SETTINGS_SURFACE_SECTIONS]
+  }
+}
+
+function sectionLabel(section: CommandSurfaceSection): string {
+  const labels: Partial<Record<CommandSurfaceSection, string>> = {
+    general: "General",
+    model: "Model",
+    thinking: "Thinking",
+    queue: "Queue",
+    compaction: "Compaction",
+    retry: "Retry",
+    "session-behavior": "Session",
+    recovery: "Recovery",
+    auth: "Auth",
+    admin: "Admin",
+    git: "Git",
+    resume: "Resume",
+    name: "Name",
+    fork: "Fork",
+    session: "Session",
+    compact: "Compact",
+    workspace: "Workspace",
+    integrations: "Integrations",
+    experimental: "Experimental",
+  }
+  return labels[section] ?? section
+}
+
+function sectionIcon(section: CommandSurfaceSection) {
+  const icons: Partial<Record<CommandSurfaceSection, React.ReactNode>> = {
+    general: <SlidersHorizontal className="h-4 w-4" />,
+    model: <Cpu className="h-4 w-4" />,
+    thinking: <Brain className="h-4 w-4" />,
+    queue: <ArrowRightLeft className="h-4 w-4" />,
+    compaction: <Archive className="h-4 w-4" />,
+    retry: <RefreshCw className="h-4 w-4" />,
+    "session-behavior": <ArrowRightLeft className="h-4 w-4" />,
+    recovery: <LifeBuoy className="h-4 w-4" />,
+    auth: <ShieldCheck className="h-4 w-4" />,
+    admin: <SquareTerminal className="h-4 w-4" />,
+    git: <GitBranch className="h-4 w-4" />,
+    resume: <ArrowRightLeft className="h-4 w-4" />,
+    name: <PencilLine className="h-4 w-4" />,
+    fork: <GitBranch className="h-4 w-4" />,
+    session: <FileText className="h-4 w-4" />,
+    compact: <Archive className="h-4 w-4" />,
+    workspace: <FolderRoot className="h-4 w-4" />,
+    integrations: <Radio className="h-4 w-4" />,
+    experimental: <FlaskConical className="h-4 w-4" />,
+  }
+  return icons[section] ?? null
+}
+
+function surfaceTitle(surface: string | null): string {
+  const titles: Record<string, string> = {
+    model: "Model",
+    thinking: "Thinking",
+    git: "Git",
+    login: "Login",
+    logout: "Logout",
+    settings: "Settings",
+    resume: "Resume",
+    name: "Name",
+    fork: "Fork",
+    session: "Session",
+    export: "Export",
+    compact: "Compact",
+  }
+  return titles[surface ?? ""] ?? "Settings"
+}
+
+function currentAuthIntent(activeSurface: string | null, selectedTarget: CommandSurfaceTarget | null): "login" | "logout" | "manage" {
+  if (selectedTarget?.kind === "auth") return selectedTarget.intent
+  if (activeSurface === "login") return "login"
+  if (activeSurface === "logout") return "logout"
+  return "manage"
+}
+
+function formatRelativeTime(isoDate: string): string {
+  const now = Date.now()
+  const then = new Date(isoDate).getTime()
+  const diffMs = now - then
+  if (diffMs < 60_000) return "just now"
+  const minutes = Math.floor(diffMs / 60_000)
+  if (minutes < 60) return `${minutes}m ago`
+  const hours = Math.floor(minutes / 60)
+  if (hours < 24) return `${hours}h ago`
+  const days = Math.floor(hours / 24)
+  return `${days}d ago`
+}
+
+// ─── Inline status dot ──────────────────────────────────────────────
+
+function StatusDot({ status }: { status: "ok" | "warning" | "error" | "idle" }) {
+  return (
+    <span
+      className={cn(
+        "inline-block h-1.5 w-1.5 rounded-full",
+        status === "ok" && "bg-success",
+        status === "warning" && "bg-warning",
+        status === "error" && "bg-destructive",
+        status === "idle" && "bg-foreground/20",
+      )}
+    />
+  )
+}
+
+// ─── Inline section header ──────────────────────────────────────────
+
+function SectionHeader({
+  title,
+  action,
+  status,
+}: {
+  title: string
+  action?: React.ReactNode
+  status?: React.ReactNode
+}) {
+  return (
+    <div className="flex items-center justify-between gap-3 pb-4">
+      <div className="flex items-center gap-2.5">
+        <h3 className="text-[13px] font-semibold uppercase tracking-[0.08em] text-muted-foreground">{title}</h3>
+        {status}
+      </div>
+      {action}
+    </div>
+  )
+}
+
+// ─── Inline key-value row ───────────────────────────────────────────
+
+function KV({ label, children, mono }: { label: string; children: React.ReactNode; mono?: boolean }) {
+  return (
+    <div className="flex items-baseline justify-between gap-4 py-1.5 text-sm">
+      <span className="shrink-0 text-muted-foreground">{label}</span>
+      <span className={cn("text-right text-foreground", mono && "font-mono text-xs")}>{children}</span>
+    </div>
+  )
+}
+
+// ─── Toggle row: label + switch ─────────────────────────────────────
+
+function ToggleRow({
+  label,
+  description,
+  checked,
+  onCheckedChange,
+  disabled,
+  busy,
+  testId,
+}: {
+  label: string
+  description?: string
+  checked: boolean
+  onCheckedChange: (checked: boolean) => void
+  disabled?: boolean
+  busy?: boolean
+  testId?: string
+}) {
+  return (
+    <div className="flex items-start justify-between gap-4 rounded-lg border border-border/50 bg-card/50 px-4 py-3">
+      <div className="min-w-0">
+        <div className="flex items-center gap-2 text-sm font-medium text-foreground">
+          {label}
+          {busy && <LoaderCircle className="h-3 w-3 animate-spin text-muted-foreground" />}
+        </div>
+        {description && <p className="mt-0.5 text-xs text-muted-foreground">{description}</p>}
+      </div>
+      <Switch checked={checked} onCheckedChange={onCheckedChange} disabled={disabled || busy} data-testid={testId} />
+    </div>
+  )
+}
+
+// ─── Segmented control ──────────────────────────────────────────────
+
+function SegmentedControl<T extends string>({
+  options,
+  value,
+  onChange,
+  disabled,
+}: {
+  options: { value: T; label: string }[]
+  value: T | null
+  onChange: (value: T) => void
+  disabled?: boolean
+}) {
+  return (
+    <div className="inline-flex rounded-lg border border-border bg-card/50 p-0.5">
+      {options.map((opt) => (
+        <button
+          key={opt.value}
+          type="button"
+          className={cn(
+            "rounded-md px-3 py-1.5 text-xs font-medium transition-all",
+            value === opt.value
+              ? "bg-foreground/10 text-foreground shadow-sm"
+              : "text-muted-foreground hover:text-foreground",
+          )}
+          onClick={() => onChange(opt.value)}
+          disabled={disabled || value === opt.value}
+        >
+          {opt.label}
+        </button>
+      ))}
+    </div>
+  )
+}
+
+
+
+// ═════════════════════════════════════════════════════════════════════
+// MAIN COMPONENT
+// ═════════════════════════════════════════════════════════════════════
+
+export function CommandSurface() {
+  const workspace = useGSDWorkspaceState()
+  const {
+    closeCommandSurface,
+    openCommandSurface,
+    refreshBoot,
+    setCommandSurfaceSection,
+    selectCommandSurfaceTarget,
+    loadGitSummary,
+    loadRecoveryDiagnostics,
+    loadForensicsDiagnostics,
+    loadDoctorDiagnostics,
+    loadSkillHealthDiagnostics,
+    loadKnowledgeData,
+    loadCapturesData,
+    loadSettingsData,
+    updateSessionBrowserState,
+    loadSessionBrowser,
+    renameSessionFromSurface,
+    loadAvailableModels,
+    applyModelSelection,
+    applyThinkingLevel,
+    setSteeringModeFromSurface,
+    setFollowUpModeFromSurface,
+    setAutoCompactionFromSurface,
+    setAutoRetryFromSurface,
+    abortRetryFromSurface,
+    switchSessionFromSurface,
+    loadSessionStats,
+    exportSessionFromSurface,
+    loadForkMessages,
+    forkSessionFromSurface,
+    compactSessionFromSurface,
+    saveApiKeyFromSurface,
+    startProviderFlowFromSurface,
+    submitProviderFlowInputFromSurface,
+    cancelProviderFlowFromSurface,
+    logoutProviderFromSurface,
+    loadHistoryData,
+    loadInspectData,
+    loadHooksData,
+    loadUndoInfo,
+    loadCleanupData,
+    loadSteerData,
+  } = useGSDWorkspaceActions()
+
+  const { commandSurface } = workspace
+  const onboarding = workspace.boot?.onboarding ?? null
+  const activeFlow = onboarding?.activeFlow ?? null
+  const gitSummary = commandSurface.gitSummary
+  const recovery = commandSurface.recovery
+  const sessionBrowser = commandSurface.sessionBrowser
+  const liveSessionState = workspace.boot?.bridge.sessionState ?? null
+  const settingsRequests = commandSurface.settingsRequests
+  const currentModelLabel = getModelLabel(workspace.boot?.bridge)
+  const currentSessionLabel = getSessionLabelFromBridge(workspace.boot?.bridge)
+  const [apiKeys, setApiKeys] = useState<Record<string, string>>({})
+  const [flowInput, setFlowInput] = useState("")
+  const commandSurfaceViewportRef = useRef<HTMLDivElement>(null)
+
+  // ─── Auto-loaders ──────────────────────────────────────────────────
+
+  useEffect(() => {
+    if (!commandSurface.open || commandSurface.section !== "model") return
+    if (commandSurface.availableModels.length > 0) return
+    if (commandSurface.pendingAction === "loading_models") return
+    void loadAvailableModels()
+  }, [commandSurface.open, commandSurface.section, commandSurface.availableModels.length, commandSurface.pendingAction, loadAvailableModels])
+
+  useEffect(() => {
+    if (!commandSurface.open || commandSurface.section !== "git") return
+    if (commandSurface.pendingAction === "load_git_summary") return
+    if (commandSurface.gitSummary.loaded || commandSurface.gitSummary.error) return
+    void loadGitSummary()
+  }, [commandSurface.open, commandSurface.section, commandSurface.pendingAction, commandSurface.gitSummary.loaded, commandSurface.gitSummary.error, loadGitSummary])
+
+  useEffect(() => {
+    if (!commandSurface.open || commandSurface.section !== "recovery") return
+    if (commandSurface.pendingAction === "load_recovery_diagnostics") return
+    if (commandSurface.recovery.pending) return
+    if (commandSurface.recovery.loaded && !commandSurface.recovery.stale && !commandSurface.recovery.error) return
+    void loadRecoveryDiagnostics()
+  }, [
+    commandSurface.open,
+    commandSurface.section,
+    commandSurface.pendingAction,
+    commandSurface.recovery.pending,
+    commandSurface.recovery.loaded,
+    commandSurface.recovery.stale,
+    commandSurface.recovery.error,
+    loadRecoveryDiagnostics,
+  ])
+
+  // Auto-fetch diagnostics panels when their sections open
+  const diagnostics = commandSurface.diagnostics
+  const knowledgeCaptures = commandSurface.knowledgeCaptures
+  const settingsData = commandSurface.settingsData
+  const remainingCommands = commandSurface.remainingCommands
+  useEffect(() => {
+    if (!commandSurface.open) return
+    if (commandSurface.section === "gsd-forensics" && diagnostics.forensics.phase === "idle") {
+      void loadForensicsDiagnostics()
+    } else if (commandSurface.section === "gsd-doctor" && diagnostics.doctor.phase === "idle") {
+      void loadDoctorDiagnostics()
+    } else if (commandSurface.section === "gsd-skill-health" && diagnostics.skillHealth.phase === "idle") {
+      void loadSkillHealthDiagnostics()
+    } else if (
+      commandSurface.section === "gsd-knowledge" &&
+      knowledgeCaptures.knowledge.phase === "idle"
+    ) {
+      void loadKnowledgeData()
+      void loadCapturesData()
+    } else if (
+      (commandSurface.section === "gsd-capture" || commandSurface.section === "gsd-triage") &&
+      knowledgeCaptures.captures.phase === "idle"
+    ) {
+      void loadCapturesData()
+      void loadKnowledgeData()
+    } else if (
+      (commandSurface.section === "gsd-prefs" ||
+       commandSurface.section === "gsd-mode" ||
+       commandSurface.section === "gsd-config" ||
+       commandSurface.section === "experimental") &&
+      settingsData.phase === "idle"
+    ) {
+      void loadSettingsData()
+    } else if (commandSurface.section === "gsd-history" && remainingCommands.history.phase === "idle") {
+      void loadHistoryData()
+    } else if (commandSurface.section === "gsd-inspect" && remainingCommands.inspect.phase === "idle") {
+      void loadInspectData()
+    } else if (commandSurface.section === "gsd-hooks" && remainingCommands.hooks.phase === "idle") {
+      void loadHooksData()
+    } else if (commandSurface.section === "gsd-undo" && remainingCommands.undo.phase === "idle") {
+      void loadUndoInfo()
+    } else if (commandSurface.section === "gsd-cleanup" && remainingCommands.cleanup.phase === "idle") {
+      void loadCleanupData()
+    } else if (commandSurface.section === "gsd-steer" && remainingCommands.steer.phase === "idle") {
+      void loadSteerData()
+    }
+  }, [
+    commandSurface.open,
+    commandSurface.section,
+    diagnostics.forensics.phase,
+    diagnostics.doctor.phase,
+    diagnostics.skillHealth.phase,
+    knowledgeCaptures.knowledge.phase,
+    knowledgeCaptures.captures.phase,
+    settingsData.phase,
+    remainingCommands.history.phase,
+    remainingCommands.inspect.phase,
+    remainingCommands.hooks.phase,
+    remainingCommands.undo.phase,
+    remainingCommands.cleanup.phase,
+    remainingCommands.steer.phase,
+    loadForensicsDiagnostics,
+    loadDoctorDiagnostics,
+    loadSkillHealthDiagnostics,
+    loadKnowledgeData,
+    loadCapturesData,
+    loadSettingsData,
+    loadHistoryData,
+    loadInspectData,
+    loadHooksData,
+    loadUndoInfo,
+    loadCleanupData,
+    loadSteerData,
+  ])
+
+  useEffect(() => {
+    if (!commandSurface.open || (commandSurface.section !== "resume" && commandSurface.section !== "name")) return
+    if (commandSurface.pendingAction === "load_session_browser") return
+    if (commandSurface.sessionBrowser.loaded) return
+    void loadSessionBrowser()
+  }, [commandSurface.open, commandSurface.section, commandSurface.pendingAction, commandSurface.sessionBrowser.loaded, loadSessionBrowser])
+
+  useEffect(() => {
+    if (!commandSurface.open) return
+    const viewport = commandSurfaceViewportRef.current
+    if (!viewport) return
+    viewport.scrollTop = 0
+  }, [commandSurface.open, commandSurface.activeSurface, commandSurface.section])
+
+  useEffect(() => {
+    if (!commandSurface.open || commandSurface.section !== "session") return
+    if (commandSurface.sessionStats) return
+    if (commandSurface.pendingAction === "load_session_stats") return
+    void loadSessionStats()
+  }, [commandSurface.open, commandSurface.section, commandSurface.sessionStats, commandSurface.pendingAction, loadSessionStats])
+
+  useEffect(() => {
+    if (!commandSurface.open || commandSurface.section !== "fork") return
+    if (commandSurface.forkMessages.length > 0) return
+    if (commandSurface.pendingAction === "load_fork_messages") return
+    void loadForkMessages()
+  }, [commandSurface.open, commandSurface.section, commandSurface.forkMessages.length, commandSurface.pendingAction, loadForkMessages])
+
+  useEffect(() => {
+    if (!commandSurface.open || commandSurface.section !== "resume") return
+    const selectedResumeTarget = commandSurface.selectedTarget?.kind === "resume" ? commandSurface.selectedTarget : null
+    if (selectedResumeTarget?.sessionPath) return
+    const defaultSession = sessionBrowser.sessions.find((session) => !session.isActive) ?? sessionBrowser.sessions[0]
+    if (!defaultSession) return
+    selectCommandSurfaceTarget({ kind: "resume", sessionPath: defaultSession.path })
+  }, [commandSurface.open, commandSurface.section, commandSurface.selectedTarget, sessionBrowser.sessions, selectCommandSurfaceTarget])
+
+  useEffect(() => {
+    if (!commandSurface.open || commandSurface.section !== "name") return
+    const selectedNameTarget = commandSurface.selectedTarget?.kind === "name" ? commandSurface.selectedTarget : null
+    if (selectedNameTarget?.sessionPath) return
+    const defaultSession = sessionBrowser.sessions.find((session) => session.isActive) ?? sessionBrowser.sessions[0]
+    if (!defaultSession) return
+    selectCommandSurfaceTarget({ kind: "name", sessionPath: defaultSession.path, name: defaultSession.name ?? "" })
+  }, [commandSurface.open, commandSurface.section, commandSurface.selectedTarget, sessionBrowser.sessions, selectCommandSurfaceTarget])
+
+  useEffect(() => {
+    const resetTimer = window.setTimeout(() => {
+      setFlowInput("")
+    }, 0)
+    return () => window.clearTimeout(resetTimer)
+  }, [activeFlow?.flowId])
+
+  // ─── Toast on action results ───────────────────────────────────────
+
+  useEffect(() => {
+    if (commandSurface.lastError) {
+      toast.error(commandSurface.lastError)
+    }
+  }, [commandSurface.lastError])
+
+  useEffect(() => {
+    if (commandSurface.lastResult) {
+      toast.success(commandSurface.lastResult)
+    }
+  }, [commandSurface.lastResult])
+
+  // ─── Derived state ─────────────────────────────────────────────────
+
+  const selectedModelTarget = commandSurface.selectedTarget?.kind === "model" ? commandSurface.selectedTarget : null
+  const selectedThinkingTarget = commandSurface.selectedTarget?.kind === "thinking" ? commandSurface.selectedTarget : null
+  const selectedAuthTarget = commandSurface.selectedTarget?.kind === "auth" ? commandSurface.selectedTarget : null
+  const selectedResumeTarget = commandSurface.selectedTarget?.kind === "resume" ? commandSurface.selectedTarget : null
+  const selectedNameTarget = commandSurface.selectedTarget?.kind === "name" ? commandSurface.selectedTarget : null
+  const selectedForkTarget = commandSurface.selectedTarget?.kind === "fork" ? commandSurface.selectedTarget : null
+  const selectedSessionTarget = commandSurface.selectedTarget?.kind === "session" ? commandSurface.selectedTarget : null
+  const selectedCompactTarget = commandSurface.selectedTarget?.kind === "compact" ? commandSurface.selectedTarget : null
+  const selectedAuthIntent = currentAuthIntent(commandSurface.activeSurface, commandSurface.selectedTarget)
+  const selectedAuthProvider = onboarding?.required.providers.find((provider) => provider.id === selectedAuthTarget?.providerId) ?? null
+  const modelQuery = (selectedModelTarget?.query ?? commandSurface.args).trim().toLowerCase()
+  const filteredModels = useMemo(() => {
+    if (!modelQuery) return commandSurface.availableModels
+    return commandSurface.availableModels.filter((model) =>
+      `${model.provider} ${model.modelId} ${model.name ?? ""}`.toLowerCase().includes(modelQuery),
+    )
+  }, [commandSurface.availableModels, modelQuery])
+
+  // Group filtered models by provider for display
+  const groupedModels = useMemo(() => {
+    const groups = new Map<string, typeof filteredModels>()
+    for (const model of filteredModels) {
+      const key = model.provider
+      const existing = groups.get(key)
+      if (existing) existing.push(model)
+      else groups.set(key, [model])
+    }
+    return groups
+  }, [filteredModels])
+
+  const authBusy = workspace.onboardingRequestState !== "idle"
+  const modelBusy = commandSurface.pendingAction === "loading_models" || workspace.commandInFlight === "get_available_models"
+  const gitSummaryBusy = commandSurface.pendingAction === "load_git_summary"
+  const recoveryBusy = commandSurface.pendingAction === "load_recovery_diagnostics" || recovery.pending
+  const recoveryDiagnostics = recovery.diagnostics
+  const sessionBrowserBusy = commandSurface.pendingAction === "load_session_browser"
+  const forkBusy = commandSurface.pendingAction === "load_fork_messages" || commandSurface.pendingAction === "fork_session"
+  const sessionBusy = commandSurface.pendingAction === "load_session_stats" || commandSurface.pendingAction === "export_html"
+  const resumeBusy = commandSurface.pendingAction === "switch_session"
+  const renameBusy = commandSurface.pendingAction === "rename_session"
+  const compactBusy = commandSurface.pendingAction === "compact_session" || liveSessionState?.isCompacting === true
+  const queueBusy = settingsRequests.steeringMode.pending || settingsRequests.followUpMode.pending
+  const autoCompactionBusy = settingsRequests.autoCompaction.pending
+  const autoRetryBusy = settingsRequests.autoRetry.pending
+  const abortRetryBusy = settingsRequests.abortRetry.pending
+  const selectedProviderApiKey = selectedAuthProvider ? apiKeys[selectedAuthProvider.id] ?? "" : ""
+  const devOverrides = useDevOverrides()
+  const surfaceSections = availableSectionsForSurface(commandSurface.activeSurface, devOverrides.isDevMode)
+  const surfaceKindLabel = `/${commandSurface.activeSurface ?? "settings"}`
+
+  const triggerRecoveryBrowserAction = (actionId: string) => {
+    switch (actionId) {
+      case "refresh_diagnostics":
+        void loadRecoveryDiagnostics()
+        return
+      case "refresh_workspace":
+        void refreshBoot({ soft: true })
+        return
+      case "open_retry_controls":
+        setCommandSurfaceSection("retry")
+        return
+      case "open_resume_controls":
+        openCommandSurface("resume", { source: "surface" })
+        return
+      case "open_auth_controls":
+        setCommandSurfaceSection("auth")
+        return
+      default:
+        return
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════
+  // SECTION RENDERERS
+  // ═══════════════════════════════════════════════════════════════════
+
+  const renderModelSection = () => (
+    <div className="space-y-4" data-testid="command-surface-models">
+      <SectionHeader
+        title="Model"
+        status={
+          <span className="font-mono text-xs text-muted-foreground">{currentModelLabel}</span>
+        }
+        action={
+          <Button type="button" variant="ghost" size="sm" onClick={() => void loadAvailableModels()} disabled={modelBusy} className="h-7 gap-1.5 text-xs">
+            <RefreshCw className={cn("h-3 w-3", modelBusy && "animate-spin")} />
+            Refresh
+          </Button>
+        }
+      />
+
+      {/* Search filter */}
+      <div className="relative">
+        <Search className="absolute left-3 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground" />
+        <Input
+          value={selectedModelTarget?.query ?? commandSurface.args}
+          onChange={(e) =>
+            selectCommandSurfaceTarget({
+              kind: "model",
+              provider: selectedModelTarget?.provider,
+              modelId: selectedModelTarget?.modelId,
+              query: e.target.value,
+            })
+          }
+          placeholder="Filter models…"
+          className="h-8 pl-9 text-xs"
+        />
+      </div>
+
+      {/* Model list */}
+      {modelBusy && commandSurface.availableModels.length === 0 ? (
+        <div className="flex items-center gap-2 py-8 text-xs text-muted-foreground">
+          <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+          Loading models…
+        </div>
+      ) : filteredModels.length > 0 ? (
+        <div className="space-y-4">
+          {Array.from(groupedModels.entries()).map(([provider, models]) => (
+            <div key={provider}>
+              <div className="mb-1.5 px-1 text-[10px] font-semibold uppercase tracking-widest text-muted-foreground">
+                {provider}
+              </div>
+              <div className="space-y-0.5">
+                {models.map((model) => {
+                  const selected = selectedModelTarget?.provider === model.provider && selectedModelTarget?.modelId === model.modelId
+                  return (
+                    <button
+                      key={`${model.provider}/${model.modelId}`}
+                      type="button"
+                      className={cn(
+                        "group flex w-full items-center gap-3 rounded-lg px-3 py-2 text-left transition-colors",
+                        selected
+                          ? "bg-foreground/[0.07]"
+                          : "hover:bg-foreground/[0.03]",
+                      )}
+                      onClick={() =>
+                        selectCommandSurfaceTarget({
+                          kind: "model",
+                          provider: model.provider,
+                          modelId: model.modelId,
+                          query: selectedModelTarget?.query,
+                        })
+                      }
+                    >
+                      {/* Selection indicator */}
+                      <div className={cn(
+                        "flex h-4 w-4 shrink-0 items-center justify-center rounded-full border transition-colors",
+                        selected ? "border-foreground bg-foreground" : "border-foreground/25",
+                      )}>
+                        {selected && <Check className="h-2.5 w-2.5 text-background" />}
+                      </div>
+
+                      {/* Model info */}
+                      <div className="min-w-0 flex-1">
+                        <div className="flex items-center gap-2">
+                          <span className="text-sm font-medium text-foreground">{model.name || model.modelId}</span>
+                          {model.isCurrent && <StatusDot status="ok" />}
+                        </div>
+                        <div className="mt-0.5 font-mono text-[11px] text-muted-foreground">
+                          {model.modelId}
+                        </div>
+                      </div>
+
+                      {/* Badges */}
+                      <div className="flex shrink-0 items-center gap-1.5">
+                        {model.isCurrent && (
+                          <span className="rounded bg-foreground/10 px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground">Active</span>
+                        )}
+                        {model.reasoning && (
+                          <span className="rounded bg-foreground/10 px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground">Thinking</span>
+                        )}
+                      </div>
+                    </button>
+                  )
+                })}
+              </div>
+            </div>
+          ))}
+        </div>
+      ) : (
+        <p className="py-6 text-center text-xs text-muted-foreground">No models matched.</p>
+      )}
+
+      {/* Apply */}
+      <div className="flex justify-end border-t border-border/50 pt-3">
+        <Button
+          type="button"
+          size="sm"
+          onClick={() =>
+            selectedModelTarget?.provider &&
+            selectedModelTarget?.modelId &&
+            void applyModelSelection(selectedModelTarget.provider, selectedModelTarget.modelId)
+          }
+          disabled={!selectedModelTarget?.provider || !selectedModelTarget.modelId || commandSurface.pendingAction === "set_model"}
+          data-testid="command-surface-apply-model"
+          className="h-8 gap-1.5"
+        >
+          {commandSurface.pendingAction === "set_model" ? (
+            <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+          ) : (
+            <Check className="h-3.5 w-3.5" />
+          )}
+          Apply model
+        </Button>
+      </div>
+    </div>
+  )
+
+  const renderThinkingSection = () => (
+    <div className="space-y-4" data-testid="command-surface-thinking">
+      <SectionHeader
+        title="Thinking level"
+        status={
+          <span className="font-mono text-xs text-muted-foreground">
+            {workspace.boot?.bridge.sessionState?.thinkingLevel ?? "off"}
+          </span>
+        }
+      />
+
+      <div className="space-y-1">
+        {COMMAND_SURFACE_THINKING_LEVELS.map((level) => {
+          const selected = selectedThinkingTarget?.level === level
+          const isCurrent = workspace.boot?.bridge.sessionState?.thinkingLevel === level
+          const description = level === "off" ? "No reasoning overhead" : level === "minimal" ? "Light reasoning" : level === "low" ? "Basic analysis" : level === "medium" ? "Balanced reasoning" : level === "high" ? "Deep analysis" : "Maximum deliberation"
+          return (
+            <button
+              key={level}
+              type="button"
+              className={cn(
+                "flex w-full items-center gap-3 rounded-lg px-3 py-2.5 text-left transition-colors",
+                selected ? "bg-foreground/[0.07]" : "hover:bg-foreground/[0.03]",
+              )}
+              onClick={() => selectCommandSurfaceTarget({ kind: "thinking", level })}
+            >
+              <div className={cn(
+                "flex h-4 w-4 shrink-0 items-center justify-center rounded-full border transition-colors",
+                selected ? "border-foreground bg-foreground" : "border-foreground/25",
+              )}>
+                {selected && <Check className="h-2.5 w-2.5 text-background" />}
+              </div>
+              <div className="min-w-0 flex-1">
+                <div className="flex items-center gap-2">
+                  <span className="text-sm font-medium capitalize text-foreground">{level}</span>
+                  {isCurrent && <StatusDot status="ok" />}
+                </div>
+                <span className="text-xs text-muted-foreground">{description}</span>
+              </div>
+            </button>
+          )
+        })}
+      </div>
+
+      <div className="flex justify-end border-t border-border/50 pt-3">
+        <Button
+          type="button"
+          size="sm"
+          onClick={() => selectedThinkingTarget && void applyThinkingLevel(selectedThinkingTarget.level)}
+          disabled={!selectedThinkingTarget || commandSurface.pendingAction === "set_thinking_level"}
+          data-testid="command-surface-apply-thinking"
+          className="h-8 gap-1.5"
+        >
+          {commandSurface.pendingAction === "set_thinking_level" ? (
+            <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+          ) : (
+            <Check className="h-3.5 w-3.5" />
+          )}
+          Apply
+        </Button>
+      </div>
+    </div>
+  )
+
+  const renderQueueSection = () => (
+    <div className="space-y-5" data-testid="command-surface-queue-settings">
+      <SectionHeader title="Queue modes" />
+
+      {/* Steering mode */}
+      <div className="space-y-3">
+        <div className="flex items-center justify-between">
+          <div>
+            <div className="text-sm font-medium text-foreground">Steering mode</div>
+            <p className="text-xs text-muted-foreground">How steering messages queue during streaming</p>
+          </div>
+          {settingsRequests.steeringMode.pending && <LoaderCircle className="h-3.5 w-3.5 animate-spin text-muted-foreground" />}
+        </div>
+        <SegmentedControl
+          options={[
+            { value: "all" as const, label: "Queue all" },
+            { value: "one-at-a-time" as const, label: "One at a time" },
+          ]}
+          value={liveSessionState?.steeringMode ?? null}
+          onChange={(v) => void setSteeringModeFromSurface(v)}
+          disabled={!liveSessionState || queueBusy}
+        />
+        {settingsRequests.steeringMode.error && (
+          <p className="text-xs text-destructive">{settingsRequests.steeringMode.error}</p>
+        )}
+      </div>
+
+      <div className="border-t border-border/50" />
+
+      {/* Follow-up mode */}
+      <div className="space-y-3">
+        <div className="flex items-center justify-between">
+          <div>
+            <div className="text-sm font-medium text-foreground">Follow-up mode</div>
+            <p className="text-xs text-muted-foreground">How follow-up prompts sequence during a live turn</p>
+          </div>
+          {settingsRequests.followUpMode.pending && <LoaderCircle className="h-3.5 w-3.5 animate-spin text-muted-foreground" />}
+        </div>
+        <SegmentedControl
+          options={[
+            { value: "all" as const, label: "Queue all" },
+            { value: "one-at-a-time" as const, label: "One at a time" },
+          ]}
+          value={liveSessionState?.followUpMode ?? null}
+          onChange={(v) => void setFollowUpModeFromSurface(v)}
+          disabled={!liveSessionState || queueBusy}
+        />
+        {settingsRequests.followUpMode.error && (
+          <p className="text-xs text-destructive">{settingsRequests.followUpMode.error}</p>
+        )}
+      </div>
+    </div>
+  )
+
+  const renderCompactionSection = () => (
+    <div className="space-y-4" data-testid="command-surface-auto-compaction-settings">
+      <SectionHeader
+        title="Auto-compaction"
+        status={
+          liveSessionState?.isCompacting ? (
+            <span className="flex items-center gap-1.5 text-xs text-warning">
+              <LoaderCircle className="h-3 w-3 animate-spin" /> Compacting
+            </span>
+          ) : null
+        }
+      />
+
+      <ToggleRow
+        label="Auto-compact"
+        description="Automatically compact when context thresholds are crossed"
+        checked={liveSessionState?.autoCompactionEnabled ?? false}
+        onCheckedChange={(checked) => void setAutoCompactionFromSurface(checked)}
+        disabled={!liveSessionState || autoCompactionBusy}
+        busy={autoCompactionBusy}
+        testId="command-surface-toggle-auto-compaction"
+      />
+
+      {settingsRequests.autoCompaction.error && (
+        <p className="text-xs text-destructive">{settingsRequests.autoCompaction.error}</p>
+      )}
+      {settingsRequests.autoCompaction.result && (
+        <p className="text-xs text-success">{settingsRequests.autoCompaction.result}</p>
+      )}
+    </div>
+  )
+
+  const renderRetrySection = () => (
+    <div className="space-y-4" data-testid="command-surface-retry-settings">
+      <SectionHeader
+        title="Retry"
+        status={
+          liveSessionState?.retryInProgress ? (
+            <span className="flex items-center gap-1.5 text-xs text-warning">
+              <Radio className="h-3 w-3" /> Attempt {Math.max(1, liveSessionState.retryAttempt)}
+            </span>
+          ) : null
+        }
+      />
+
+      <ToggleRow
+        label="Auto-retry"
+        description="Automatically retry on transient failures"
+        checked={liveSessionState?.autoRetryEnabled ?? false}
+        onCheckedChange={(checked) => void setAutoRetryFromSurface(checked)}
+        disabled={!liveSessionState || autoRetryBusy}
+        busy={autoRetryBusy}
+        testId="command-surface-toggle-auto-retry"
+      />
+
+      <p className="text-xs text-muted-foreground" data-testid="command-surface-auto-retry-state">
+        {autoRetryBusy
+          ? "Updating auto-retry…"
+          : settingsRequests.autoRetry.error
+            ? settingsRequests.autoRetry.error
+            : settingsRequests.autoRetry.result
+              ? settingsRequests.autoRetry.result
+              : liveSessionState?.autoRetryEnabled
+                ? "Auto-retry enabled"
+                : "Auto-retry disabled"}
+      </p>
+
+      {liveSessionState?.retryInProgress && (
+        <div className="flex items-center justify-between rounded-lg border border-warning/20 bg-warning/5 px-4 py-3">
+          <div>
+            <div className="text-sm font-medium text-foreground">Retry in progress</div>
+            <p className="text-xs text-muted-foreground">Attempt {Math.max(1, liveSessionState.retryAttempt)} is active</p>
+          </div>
+          <Button
+            type="button"
+            variant="destructive"
+            size="sm"
+            onClick={() => void abortRetryFromSurface()}
+            disabled={abortRetryBusy}
+            data-testid="command-surface-abort-retry"
+            className="h-7 gap-1.5 text-xs"
+          >
+            {abortRetryBusy ? <LoaderCircle className="h-3 w-3 animate-spin" /> : <X className="h-3 w-3" />}
+            Abort
+          </Button>
+        </div>
+      )}
+
+      {settingsRequests.autoRetry.error && <p className="text-xs text-destructive">{settingsRequests.autoRetry.error}</p>}
+      <p className="text-xs text-muted-foreground" data-testid="command-surface-abort-retry-state">
+        {abortRetryBusy
+          ? "Aborting retry…"
+          : settingsRequests.abortRetry.error
+            ? settingsRequests.abortRetry.error
+            : settingsRequests.abortRetry.result
+              ? settingsRequests.abortRetry.result
+              : liveSessionState?.retryInProgress
+                ? "Retry can be aborted"
+                : "No retry in progress"}
+      </p>
+      {settingsRequests.abortRetry.error && <p className="text-xs text-destructive">{settingsRequests.abortRetry.error}</p>}
+    </div>
+  )
+
+  const renderRecoverySection = () => {
+    const diag = recoveryDiagnostics
+    return (
+      <div className="space-y-4" data-testid="command-surface-recovery">
+        <div className="text-xs text-muted-foreground" data-testid="command-surface-recovery-state">
+          {recoveryBusy
+            ? "Loading recovery diagnostics…"
+            : recovery.error
+              ? "Recovery diagnostics failed"
+              : recovery.stale
+                ? "Recovery diagnostics stale"
+                : recovery.loaded
+                  ? "Recovery diagnostics loaded"
+                  : "Recovery diagnostics idle"}
+        </div>
+        <SectionHeader
+          title="Recovery"
+          status={
+            diag ? (
+              <StatusDot status={diag.summary.tone === "healthy" ? "ok" : diag.summary.tone === "warning" ? "warning" : "error"} />
+            ) : null
+          }
+          action={
+            <Button type="button" variant="ghost" size="sm" onClick={() => void loadRecoveryDiagnostics()} disabled={recoveryBusy} className="h-7 gap-1.5 text-xs">
+              <RefreshCw className={cn("h-3 w-3", recoveryBusy && "animate-spin")} />
+              Refresh
+            </Button>
+          }
+        />
+
+        {recovery.error && (
+          <div
+            className="rounded-lg border border-destructive/20 bg-destructive/5 px-3 py-2.5 text-xs text-destructive"
+            data-testid="command-surface-recovery-error"
+          >
+            {recovery.error}
+          </div>
+        )}
+
+        {recoveryBusy && !diag && (
+          <>
+            <div className="flex items-center gap-2 py-6 text-xs text-muted-foreground">
+              <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+              Loading diagnostics…
+            </div>
+            <div className="flex flex-wrap gap-2 border-t border-border/50 pt-3" data-testid="command-surface-recovery-actions">
+              <Button
+                type="button"
+                variant="default"
+                size="sm"
+                onClick={() => void loadRecoveryDiagnostics()}
+                data-testid="command-surface-recovery-action-refresh_diagnostics"
+                className="h-7 text-xs"
+              >
+                Refresh diagnostics
+              </Button>
+            </div>
+          </>
+        )}
+
+        {diag?.status === "unavailable" && !recovery.error && (
+          <>
+            <div className="space-y-1 rounded-lg border border-border/50 bg-card/50 px-4 py-3" data-testid="command-surface-recovery-summary">
+              <div className="text-sm font-medium text-foreground">{diag.summary.label}</div>
+              <p className="text-xs text-muted-foreground">{diag.summary.detail}</p>
+            </div>
+            <div className="flex flex-wrap gap-2 border-t border-border/50 pt-3" data-testid="command-surface-recovery-actions">
+              <Button
+                type="button"
+                variant="default"
+                size="sm"
+                onClick={() => void loadRecoveryDiagnostics()}
+                data-testid="command-surface-recovery-action-refresh_diagnostics"
+                className="h-7 text-xs"
+              >
+                Refresh diagnostics
+              </Button>
+            </div>
+          </>
+        )}
+
+        {diag && diag.status !== "unavailable" && (
+          <>
+            <div className="space-y-1" data-testid="command-surface-recovery-summary">
+              <div className="text-sm font-medium text-foreground">{diag.summary.label}</div>
+              <p className="text-xs text-muted-foreground">{diag.summary.detail}</p>
+            </div>
+
+            {/* Summary stats */}
+            <div className="grid grid-cols-2 gap-2">
+              <div className="rounded-lg border border-border/50 bg-card/50 px-3 py-2.5">
+                <div className="text-[10px] uppercase tracking-wider text-muted-foreground">Validation</div>
+                <div className="mt-1 text-lg font-semibold tabular-nums text-foreground">{diag.summary.validationCount}</div>
+              </div>
+              <div className="rounded-lg border border-border/50 bg-card/50 px-3 py-2.5">
+                <div className="text-[10px] uppercase tracking-wider text-muted-foreground">Doctor</div>
+                <div className="mt-1 text-lg font-semibold tabular-nums text-foreground">{diag.summary.doctorIssueCount}</div>
+              </div>
+            </div>
+
+            {/* Status badges */}
+            <div className="flex flex-wrap gap-1.5">
+              {diag.summary.retryInProgress && <Badge variant="default" className="text-[10px]">Retry {Math.max(1, diag.summary.retryAttempt)}</Badge>}
+              {diag.summary.compactionActive && <Badge variant="default" className="text-[10px]">Compacting</Badge>}
+              {diag.summary.lastFailurePhase && <Badge variant="destructive" className="text-[10px]">Phase {diag.summary.lastFailurePhase}</Badge>}
+              {recovery.stale && <Badge variant="outline" className="text-[10px]">Stale</Badge>}
+            </div>
+
+            {/* Last failure */}
+            {diag.bridge.lastFailure && (
+              <div
+                className="rounded-lg border border-destructive/20 bg-destructive/5 px-3 py-2.5"
+                data-testid="command-surface-recovery-last-failure"
+              >
+                <div className="text-xs font-medium text-destructive">Last failure</div>
+                <p className="mt-1 text-xs text-destructive/80">{diag.bridge.lastFailure.message}</p>
+                <div className="mt-1.5 flex gap-3 text-[10px] text-destructive/60">
+                  <span>Phase: {diag.bridge.lastFailure.phase}</span>
+                  <span>{formatRelativeTime(diag.bridge.lastFailure.at)}</span>
+                </div>
+              </div>
+            )}
+
+            {/* Validation issues */}
+            {diag.validation.topIssues.length > 0 && (
+              <div className="space-y-2">
+                <div className="text-xs font-medium text-muted-foreground">Validation issues</div>
+                {diag.validation.topIssues.map((issue) => (
+                  <div key={`${issue.code}:${issue.file ?? issue.message}`} className="rounded-lg border border-border/50 bg-card/50 px-3 py-2">
+                    <div className="flex items-center gap-2">
+                      <Badge variant={issue.severity === "error" ? "destructive" : "outline"} className="text-[10px]">{issue.code}</Badge>
+                    </div>
+                    <p className="mt-1 text-xs text-muted-foreground">{issue.message}</p>
+                    {issue.suggestion && <p className="mt-0.5 text-[11px] text-muted-foreground">→ {issue.suggestion}</p>}
+                  </div>
+                ))}
+              </div>
+            )}
+
+            {/* Doctor issues */}
+            {diag.doctor.topIssues.length > 0 && (
+              <div className="space-y-2">
+                <div className="text-xs font-medium text-muted-foreground">Doctor issues</div>
+                {diag.doctor.topIssues.map((issue) => (
+                  <div key={`${issue.code}:${issue.unitId ?? issue.message}`} className="rounded-lg border border-border/50 bg-card/50 px-3 py-2">
+                    <Badge variant="outline" className="text-[10px]">{issue.code}</Badge>
+                    <p className="mt-1 text-xs text-muted-foreground">{issue.message}</p>
+                  </div>
+                ))}
+              </div>
+            )}
+
+            {/* Interrupted run */}
+            {diag.interruptedRun.detected && (
+              <div className="rounded-lg border border-warning/20 bg-warning/5 px-3 py-2.5" data-testid="command-surface-recovery-interrupted-run">
+                <div className="text-xs font-medium text-warning">Interrupted run detected</div>
+                <div className="mt-1 space-y-1 text-xs text-warning/80">
+                  <p>Available: yes</p>
+                  <p>Detected: yes</p>
+                  <p>{diag.interruptedRun.detail}</p>
+                </div>
+                <div className="mt-1.5 grid gap-1 text-[10px] text-warning/60">
+                  <span>Tool calls: {diag.interruptedRun.counts.toolCalls}</span>
+                  <span>Files written: {diag.interruptedRun.counts.filesWritten}</span>
+                  <span>Commands: {diag.interruptedRun.counts.commandsRun}</span>
+                  <span>Errors: {diag.interruptedRun.counts.errors}</span>
+                  <span>Last forensic error: {diag.interruptedRun.lastError ?? "[redacted]"}</span>
+                </div>
+              </div>
+            )}
+
+            {/* Actions */}
+            <div className="flex flex-wrap gap-2 border-t border-border/50 pt-3" data-testid="command-surface-recovery-actions">
+              {diag.actions.browser.length > 0 ? (
+                diag.actions.browser.map((action) => (
+                  <Button
+                    key={action.id}
+                    type="button"
+                    variant={action.emphasis === "danger" ? "destructive" : action.emphasis === "primary" ? "default" : "outline"}
+                    size="sm"
+                    onClick={() => triggerRecoveryBrowserAction(action.id)}
+                    data-testid={`command-surface-recovery-action-${action.id}`}
+                    className="h-7 text-xs"
+                  >
+                    {action.label}
+                  </Button>
+                ))
+              ) : (
+                <span className="text-xs text-muted-foreground">
+                  {recoveryBusy ? "Loading recovery actions…" : "No browser recovery actions available."}
+                </span>
+              )}
+            </div>
+
+            {diag.actions.commands.length > 0 && (
+              <div className="space-y-2 border-t border-border/50 pt-3" data-testid="command-surface-recovery-commands">
+                <div className="text-xs font-medium text-muted-foreground">Suggested commands</div>
+                {diag.actions.commands.map((command) => (
+                  <div key={command.command} className="rounded-lg border border-border/50 bg-card/50 px-3 py-2 text-xs">
+                    <div className="font-mono text-foreground">{command.command}</div>
+                    <p className="mt-1 text-muted-foreground">{command.label}</p>
+                  </div>
+                ))}
+              </div>
+            )}
+          </>
+        )}
+      </div>
+    )
+  }
+
+  const gitFileStatusColor = (status: string) => {
+    switch (status) {
+      case "M": return "text-warning bg-warning/10"
+      case "A": return "text-success bg-success/10"
+      case "D": return "text-destructive bg-destructive/10"
+      case "R": return "text-info bg-info/10"
+      case "C": return "text-info bg-info/10"
+      case "U": return "text-destructive bg-destructive/10"
+      case "?": return "text-muted-foreground bg-foreground/5"
+      default: return "text-muted-foreground bg-foreground/5"
+    }
+  }
+
+  const renderGitSection = () => {
+    const result = gitSummary.result
+    return (
+      <div className="space-y-5" data-testid="command-surface-git-summary">
+        <div className="text-xs text-muted-foreground" data-testid="command-surface-git-state">
+          {gitSummaryBusy
+            ? "Loading git summary…"
+            : gitSummary.error
+              ? "Git summary failed"
+              : result?.kind === "not_repo"
+                ? "No git repository"
+                : result?.kind === "repo"
+                  ? `Repo ready${result.hasChanges ? " — changes detected" : " — clean"}`
+                  : "Git summary idle"}
+        </div>
+
+        {gitSummaryBusy && !result && (
+          <div className="flex flex-col items-center justify-center gap-3 py-16">
+            <LoaderCircle className="h-5 w-5 animate-spin text-muted-foreground" />
+            <span className="text-xs text-muted-foreground">Loading repo state…</span>
+          </div>
+        )}
+
+        {gitSummary.error && (
+          <div
+            className="rounded-lg border border-destructive/20 bg-destructive/5 px-4 py-3 text-xs text-destructive"
+            data-testid="command-surface-git-error"
+          >
+            {gitSummary.error}
+          </div>
+        )}
+
+        {!gitSummary.error && result?.kind === "not_repo" && (
+          <div className="flex flex-col items-center gap-3 py-16 text-center" data-testid="command-surface-git-not-repo">
+            <div className="flex h-10 w-10 items-center justify-center rounded-full border border-border/50 bg-card/50">
+              <GitBranch className="h-4.5 w-4.5 text-muted-foreground" />
+            </div>
+            <div>
+              <div className="text-sm font-medium text-foreground">No Git repository</div>
+              <p className="mt-1 text-xs text-muted-foreground">{result.message}</p>
+            </div>
+          </div>
+        )}
+
+        {!gitSummary.error && result?.kind === "repo" && (
+          <>
+            {/* Repo info bar */}
+            <div className="flex items-center gap-2 text-xs text-muted-foreground">
+              <span className="font-mono">{shortenPath(result.project.repoRoot, 3)}</span>
+              {result.project.repoRelativePath && (
+                <>
+                  <ChevronRight className="h-3 w-3 text-muted-foreground" />
+                  <span className="font-mono">{result.project.repoRelativePath}</span>
+                </>
+              )}
+            </div>
+
+            {/* Counts row */}
+            <div className="grid grid-cols-4 gap-1.5" data-testid="command-surface-git-counts">
+              {[
+                { label: "Staged", count: result.counts.staged, active: result.counts.staged > 0, color: "text-success" },
+                { label: "Modified", count: result.counts.dirty, active: result.counts.dirty > 0, color: "text-warning" },
+                { label: "Untracked", count: result.counts.untracked, active: result.counts.untracked > 0, color: "text-muted-foreground" },
+                { label: "Conflicts", count: result.counts.conflicts, active: result.counts.conflicts > 0, color: "text-destructive" },
+              ].map(({ label, count, active, color }) => (
+                <div key={label} className={cn(
+                  "rounded-md border px-2 py-2 text-center transition-colors",
+                  active ? "border-border bg-card" : "border-border/50 bg-card/50",
+                )}>
+                  <div className={cn(
+                    "text-base font-semibold tabular-nums leading-none",
+                    active ? color : "text-muted-foreground",
+                  )}>{count}</div>
+                  <div className={cn(
+                    "mt-1.5 text-[10px] leading-none",
+                    active ? "text-muted-foreground" : "text-muted-foreground",
+                  )}>{label}</div>
+                </div>
+              ))}
+            </div>
+
+            {/* Changed files */}
+            {result.changedFiles.length > 0 && (
+              <div data-testid="command-surface-git-files">
+                <div className="mb-2 flex items-center justify-between">
+                  <span className="text-[11px] font-medium uppercase tracking-[0.06em] text-muted-foreground">
+                    Changes
+                  </span>
+                  <span className="text-[11px] tabular-nums text-muted-foreground">
+                    {result.changedFiles.length}{result.truncatedFileCount > 0 ? `+${result.truncatedFileCount}` : ""} files
+                  </span>
+                </div>
+                <div className="space-y-px rounded-lg border border-border/50 bg-card/50 overflow-hidden">
+                  {result.changedFiles.map((file) => (
+                    <div
+                      key={`${file.status}:${file.repoPath}`}
+                      className="group flex items-center gap-2.5 px-3 py-2 transition-colors hover:bg-foreground/[0.03]"
+                    >
+                      <span className={cn(
+                        "flex h-5 w-5 shrink-0 items-center justify-center rounded text-[10px] font-semibold",
+                        gitFileStatusColor(file.status),
+                      )}>
+                        {file.status}
+                      </span>
+                      <span className="min-w-0 flex-1 truncate font-mono text-[11px] text-foreground/80">
+                        {file.path}
+                      </span>
+                      {file.conflict && (
+                        <span className="shrink-0 rounded bg-destructive/15 px-1.5 py-0.5 text-[9px] font-semibold uppercase tracking-wider text-destructive">
+                          conflict
+                        </span>
+                      )}
+                    </div>
+                  ))}
+                </div>
+                {result.truncatedFileCount > 0 && (
+                  <p className="mt-1.5 text-center text-[11px] text-muted-foreground">
+                    +{result.truncatedFileCount} more files not shown
+                  </p>
+                )}
+              </div>
+            )}
+
+            {result.changedFiles.length === 0 && (
+              <div className="flex flex-col items-center gap-2 py-8 text-center">
+                <Check className="h-4 w-4 text-success/60" />
+                <span className="text-xs text-muted-foreground">Working tree clean</span>
+              </div>
+            )}
+          </>
+        )}
+      </div>
+    )
+  }
+
+  const renderSessionBrowserSection = (mode: "resume" | "name") => {
+    const renameMode = mode === "name"
+    const selectedSessionPath = renameMode ? selectedNameTarget?.sessionPath : selectedResumeTarget?.sessionPath
+
+    return (
+      <div className="space-y-4" data-testid={renameMode ? "command-surface-name" : "command-surface-resume"}>
+        <SectionHeader
+          title={renameMode ? "Rename" : "Resume"}
+          status={
+            !renameMode ? (
+              <span className="text-xs text-muted-foreground">{currentSessionLabel ?? "pending"}</span>
+            ) : null
+          }
+        />
+
+        {/* Search bar */}
+        <div className="flex gap-2">
+          <div className="relative flex-1">
+            <Search className="absolute left-3 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground" />
+            <Input
+              value={sessionBrowser.query}
+              onChange={(e) => updateSessionBrowserState({ query: e.target.value })}
+              onKeyDown={(e) => { if (e.key === "Enter") { e.preventDefault(); void loadSessionBrowser() } }}
+              placeholder="Search sessions…"
+              className="h-8 pl-9 text-xs"
+              disabled={sessionBrowserBusy}
+              data-testid="command-surface-session-browser-query"
+            />
+          </div>
+          <Button type="button" variant="ghost" size="sm" onClick={() => void loadSessionBrowser()} disabled={sessionBrowserBusy} className="h-8 w-8 p-0">
+            <RefreshCw className={cn("h-3.5 w-3.5", sessionBrowserBusy && "animate-spin")} />
+          </Button>
+        </div>
+
+        {/* Sort/filter controls */}
+        <div className="flex items-center gap-2">
+          <SegmentedControl
+            options={[
+              { value: "threaded" as const, label: "Threaded" },
+              { value: "recent" as const, label: "Recent" },
+              { value: "relevance" as const, label: "Relevance" },
+            ]}
+            value={sessionBrowser.sortMode}
+            onChange={(v) => { updateSessionBrowserState({ sortMode: v }); void loadSessionBrowser({ sortMode: v }) }}
+            disabled={sessionBrowserBusy}
+          />
+          <button
+            type="button"
+            className={cn(
+              "rounded-md border border-border px-2.5 py-1.5 text-[11px] font-medium transition-colors",
+              sessionBrowser.nameFilter === "named" ? "bg-foreground/10 text-foreground" : "text-muted-foreground hover:text-foreground",
+            )}
+            onClick={() => {
+              const next = sessionBrowser.nameFilter === "named" ? "all" : "named"
+              updateSessionBrowserState({ nameFilter: next })
+              void loadSessionBrowser({ nameFilter: next })
+            }}
+            disabled={sessionBrowserBusy}
+          >
+            Named
+          </button>
+        </div>
+
+        {sessionBrowser.error && (
+          <div className="rounded-lg border border-destructive/20 bg-destructive/5 px-3 py-2.5 text-xs text-destructive">{sessionBrowser.error}</div>
+        )}
+
+        {/* Session list */}
+        {sessionBrowserBusy && sessionBrowser.sessions.length === 0 ? (
+          <div className="flex items-center gap-2 py-6 text-xs text-muted-foreground">
+            <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+            Loading sessions…
+          </div>
+        ) : sessionBrowser.sessions.length > 0 ? (
+          <div className="space-y-1" data-testid="command-surface-session-browser-results">
+            {sessionBrowser.sessions.map((session) => {
+              const selected = session.path === selectedSessionPath
+              return (
+                <button
+                  key={session.path}
+                  type="button"
+                  className={cn(
+                    "flex w-full items-start gap-3 rounded-lg px-3 py-2.5 text-left transition-colors",
+                    selected ? "bg-foreground/[0.07]" : "hover:bg-foreground/[0.03]",
+                  )}
+                  style={{ paddingLeft: `${0.75 + session.depth * 0.6}rem` }}
+                  onClick={() =>
+                    renameMode
+                      ? selectCommandSurfaceTarget({ kind: "name", sessionPath: session.path, name: selectedNameTarget?.sessionPath === session.path ? (selectedNameTarget?.name ?? session.name ?? "") : (session.name ?? "") })
+                      : selectCommandSurfaceTarget({ kind: "resume", sessionPath: session.path })
+                  }
+                  data-testid={`command-surface-session-browser-item-${session.id}`}
+                >
+                  <div className={cn(
+                    "mt-1 flex h-4 w-4 shrink-0 items-center justify-center rounded-full border transition-colors",
+                    selected ? "border-foreground bg-foreground" : "border-foreground/25",
+                  )}>
+                    {selected && <Check className="h-2.5 w-2.5 text-background" />}
+                  </div>
+                  <div className="min-w-0 flex-1">
+                    <div className="flex items-center gap-2">
+                      <span className="truncate text-sm font-medium text-foreground">
+                        {session.name || session.firstMessage || session.id}
+                      </span>
+                      {session.isActive && <StatusDot status="ok" />}
+                    </div>
+                    {session.name && session.firstMessage && (
+                      <p className="mt-0.5 truncate text-xs text-muted-foreground">{session.firstMessage}</p>
+                    )}
+                    <div className="mt-0.5 flex gap-3 text-[11px] text-muted-foreground">
+                      <span>{session.messageCount} msgs</span>
+                      <span>{formatRelativeTime(session.modifiedAt)}</span>
+                    </div>
+                  </div>
+                </button>
+              )
+            })}
+          </div>
+        ) : (
+          <p className="py-4 text-center text-xs text-muted-foreground">No sessions matched.</p>
+        )}
+
+        {sessionBrowser.loaded && (
+          <p className="text-[11px] text-muted-foreground" data-testid="command-surface-session-browser-meta">
+            Current-project sessions · {sessionBrowser.returnedSessions} of {sessionBrowser.totalSessions} · {sessionBrowser.sortMode} · {sessionBrowser.nameFilter}
+          </p>
+        )}
+
+        {/* Rename controls */}
+        {renameMode && (
+          <div className="space-y-3 border-t border-border/50 pt-3">
+            <div className="flex gap-2">
+              <Input
+                value={selectedNameTarget?.name ?? ""}
+                onChange={(e) =>
+                  selectCommandSurfaceTarget({ kind: "name", sessionPath: selectedNameTarget?.sessionPath, name: e.target.value })
+                }
+                placeholder="Session name"
+                className="h-8 flex-1 text-xs"
+                disabled={!selectedNameTarget?.sessionPath || renameBusy}
+                data-testid="command-surface-rename-input"
+              />
+              <Button
+                type="button"
+                size="sm"
+                onClick={() => selectedNameTarget?.sessionPath && void renameSessionFromSurface(selectedNameTarget.sessionPath, selectedNameTarget.name)}
+                disabled={!selectedNameTarget?.sessionPath || !selectedNameTarget.name.trim() || renameBusy}
+                data-testid="command-surface-apply-rename"
+                className="h-8 gap-1.5"
+              >
+                {renameBusy ? <LoaderCircle className="h-3.5 w-3.5 animate-spin" /> : <PencilLine className="h-3.5 w-3.5" />}
+                Rename
+              </Button>
+            </div>
+            {commandSurface.renameRequest.error && <p className="text-xs text-destructive">{commandSurface.renameRequest.error}</p>}
+            {commandSurface.renameRequest.result && <p className="text-xs text-success">{commandSurface.renameRequest.result}</p>}
+          </div>
+        )}
+
+        {/* Resume controls */}
+        {!renameMode && (
+          <div className="flex items-center justify-between border-t border-border/50 pt-3">
+            <span className="text-xs text-muted-foreground" data-testid="command-surface-resume-state">
+              {resumeBusy ? "Switching…" : commandSurface.resumeRequest.error ?? commandSurface.resumeRequest.result ?? "Select a session"}
+            </span>
+            <Button
+              type="button"
+              size="sm"
+              onClick={() => selectedResumeTarget?.sessionPath && void switchSessionFromSurface(selectedResumeTarget.sessionPath)}
+              disabled={!selectedResumeTarget?.sessionPath || resumeBusy}
+              data-testid="command-surface-apply-resume"
+              className="h-8 gap-1.5"
+            >
+              {resumeBusy ? <LoaderCircle className="h-3.5 w-3.5 animate-spin" /> : <ArrowRightLeft className="h-3.5 w-3.5" />}
+              Switch
+            </Button>
+          </div>
+        )}
+      </div>
+    )
+  }
+
+  const renderForkSection = () => (
+    <div className="space-y-4" data-testid="command-surface-fork">
+      <SectionHeader
+        title="Fork"
+        action={
+          <Button type="button" variant="ghost" size="sm" onClick={() => void loadForkMessages()} disabled={forkBusy} className="h-7 gap-1.5 text-xs">
+            <RefreshCw className={cn("h-3 w-3", commandSurface.pendingAction === "load_fork_messages" && "animate-spin")} />
+            Refresh
+          </Button>
+        }
+      />
+
+      {forkBusy && commandSurface.forkMessages.length === 0 ? (
+        <div className="flex items-center gap-2 py-6 text-xs text-muted-foreground">
+          <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+          Loading fork points…
+        </div>
+      ) : commandSurface.forkMessages.length > 0 ? (
+        <div className="space-y-1">
+          {commandSurface.forkMessages.map((message) => {
+            const selected = selectedForkTarget?.entryId === message.entryId
+            return (
+              <button
+                key={message.entryId}
+                type="button"
+                className={cn(
+                  "flex w-full items-start gap-3 rounded-lg px-3 py-2.5 text-left transition-colors",
+                  selected ? "bg-foreground/[0.07]" : "hover:bg-foreground/[0.03]",
+                )}
+                onClick={() => selectCommandSurfaceTarget({ kind: "fork", entryId: message.entryId })}
+              >
+                <div className={cn(
+                  "mt-1 flex h-4 w-4 shrink-0 items-center justify-center rounded-full border transition-colors",
+                  selected ? "border-foreground bg-foreground" : "border-foreground/25",
+                )}>
+                  {selected && <Check className="h-2.5 w-2.5 text-background" />}
+                </div>
+                <div className="min-w-0 flex-1">
+                  <div className="font-mono text-[10px] text-muted-foreground">{message.entryId}</div>
+                  <p className="mt-0.5 text-sm text-foreground">{message.text}</p>
+                </div>
+              </button>
+            )
+          })}
+        </div>
+      ) : (
+        <p className="py-4 text-center text-xs text-muted-foreground">No fork points available yet.</p>
+      )}
+
+      <div className="flex justify-end border-t border-border/50 pt-3">
+        <Button
+          type="button"
+          size="sm"
+          onClick={() => selectedForkTarget?.entryId && void forkSessionFromSurface(selectedForkTarget.entryId)}
+          disabled={!selectedForkTarget?.entryId || commandSurface.pendingAction === "fork_session"}
+          data-testid="command-surface-apply-fork"
+          className="h-8 gap-1.5"
+        >
+          {commandSurface.pendingAction === "fork_session" ? (
+            <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+          ) : (
+            <GitBranch className="h-3.5 w-3.5" />
+          )}
+          Create fork
+        </Button>
+      </div>
+    </div>
+  )
+
+  const renderSessionSection = () => (
+    <div className="space-y-4" data-testid="command-surface-session">
+      <SectionHeader
+        title="Session"
+        status={
+          <span className="text-xs text-muted-foreground">{currentSessionLabel ?? "pending"}</span>
+        }
+        action={
+          <Button type="button" variant="ghost" size="sm" onClick={() => void loadSessionStats()} disabled={sessionBusy} className="h-7 gap-1.5 text-xs">
+            <RefreshCw className={cn("h-3 w-3", commandSurface.pendingAction === "load_session_stats" && "animate-spin")} />
+            Refresh
+          </Button>
+        }
+      />
+
+      {commandSurface.sessionStats ? (
+        <>
+          {/* Token & cost grid */}
+          <div className="grid grid-cols-3 gap-2">
+            {[
+              { label: "Input", value: formatTokens(commandSurface.sessionStats.tokens.input) },
+              { label: "Output", value: formatTokens(commandSurface.sessionStats.tokens.output) },
+              { label: "Total", value: formatTokens(commandSurface.sessionStats.tokens.total) },
+            ].map(({ label, value }) => (
+              <div key={label} className="rounded-lg border border-border/50 bg-card/50 px-3 py-2.5 text-center">
+                <div className="text-[10px] uppercase tracking-wider text-muted-foreground">{label}</div>
+                <div className="mt-1 text-sm font-semibold tabular-nums text-foreground">{value}</div>
+              </div>
+            ))}
+          </div>
+
+          {/* Message breakdown */}
+          <div className="divide-y divide-border/30 rounded-lg border border-border/50 bg-card/50">
+            <div className="px-4 py-2">
+              <KV label="User messages">{commandSurface.sessionStats.userMessages}</KV>
+              <KV label="Assistant messages">{commandSurface.sessionStats.assistantMessages}</KV>
+              <KV label="Tool calls">{commandSurface.sessionStats.toolCalls}</KV>
+              <KV label="Tool results">{commandSurface.sessionStats.toolResults}</KV>
+            </div>
+            <div className="px-4 py-2">
+              <KV label="Total messages">{commandSurface.sessionStats.totalMessages}</KV>
+              <KV label="Cost">{formatCost(commandSurface.sessionStats.cost)}</KV>
+              {commandSurface.sessionStats.tokens.cacheRead > 0 && (
+                <KV label="Cache read">{formatTokens(commandSurface.sessionStats.tokens.cacheRead)}</KV>
+              )}
+            </div>
+          </div>
+        </>
+      ) : (
+        <p className="py-4 text-center text-xs text-muted-foreground">Refresh to load session stats.</p>
+      )}
+
+      {/* Export */}
+      <div className="space-y-3 border-t border-border/50 pt-3">
+        <div className="text-xs font-medium text-muted-foreground">Export</div>
+        <div className="flex gap-2">
+          <Input
+            value={selectedSessionTarget?.outputPath ?? ""}
+            onChange={(e) => selectCommandSurfaceTarget({ kind: "session", outputPath: e.target.value })}
+            placeholder="Output path (optional)"
+            className="h-8 flex-1 text-xs"
+            disabled={commandSurface.pendingAction === "export_html"}
+            data-testid="command-surface-export-path"
+          />
+          <Button
+            type="button"
+            size="sm"
+            onClick={() => void exportSessionFromSurface(selectedSessionTarget?.outputPath)}
+            disabled={commandSurface.pendingAction === "export_html"}
+            data-testid="command-surface-export-session"
+            className="h-8 gap-1.5"
+          >
+            {commandSurface.pendingAction === "export_html" ? (
+              <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+            ) : (
+              <Download className="h-3.5 w-3.5" />
+            )}
+            Export HTML
+          </Button>
+        </div>
+      </div>
+    </div>
+  )
+
+  const renderCompactSection = () => (
+    <div className="space-y-4" data-testid="command-surface-compact">
+      <SectionHeader
+        title="Manual compact"
+        status={
+          compactBusy ? (
+            <span className="flex items-center gap-1.5 text-xs text-warning">
+              <LoaderCircle className="h-3 w-3 animate-spin" /> Working
+            </span>
+          ) : null
+        }
+      />
+
+      <div className="space-y-2">
+        <label className="text-xs font-medium text-muted-foreground" htmlFor="command-surface-compact-instructions">
+          Custom instructions
+        </label>
+        <Textarea
+          id="command-surface-compact-instructions"
+          data-testid="command-surface-compact-instructions"
+          value={selectedCompactTarget?.customInstructions ?? ""}
+          onChange={(e) => selectCommandSurfaceTarget({ kind: "compact", customInstructions: e.target.value })}
+          placeholder="Tell compaction what to preserve or emphasize…"
+          rows={4}
+          disabled={compactBusy}
+          className="text-xs"
+        />
+      </div>
+
+      <div className="flex justify-end">
+        <Button
+          type="button"
+          size="sm"
+          onClick={() => void compactSessionFromSurface(selectedCompactTarget?.customInstructions)}
+          disabled={compactBusy}
+          data-testid="command-surface-apply-compact"
+          className="h-8 gap-1.5"
+        >
+          {compactBusy ? <LoaderCircle className="h-3.5 w-3.5 animate-spin" /> : <Archive className="h-3.5 w-3.5" />}
+          Compact now
+        </Button>
+      </div>
+
+      {commandSurface.lastCompaction && (
+        <div className="space-y-2 rounded-lg border border-border/50 bg-card/50 px-4 py-3">
+          <div className="flex items-center justify-between">
+            <span className="text-xs font-medium text-muted-foreground">Last compaction</span>
+            <span className="text-[11px] tabular-nums text-muted-foreground">{formatTokens(commandSurface.lastCompaction.tokensBefore)} before</span>
+          </div>
+          <p className="whitespace-pre-wrap text-xs text-foreground">{commandSurface.lastCompaction.summary}</p>
+          <p className="text-[11px] text-muted-foreground">First kept: {commandSurface.lastCompaction.firstKeptEntryId}</p>
+        </div>
+      )}
+    </div>
+  )
+
+  const renderAuthSection = () => {
+    if (!onboarding) return null
+    return (
+      <div className="space-y-4" data-testid="command-surface-auth">
+        <SectionHeader
+          title="Auth"
+          status={
+            <span className="text-xs text-muted-foreground">
+              {selectedAuthIntent === "login" ? "Login" : selectedAuthIntent === "logout" ? "Logout" : "Manage"}
+            </span>
+          }
+        />
+
+        {/* Provider list */}
+        <div className="space-y-1">
+          {onboarding.required.providers.map((provider) => {
+            const selected = provider.id === selectedAuthProvider?.id
+            return (
+              <button
+                key={provider.id}
+                type="button"
+                className={cn(
+                  "flex w-full items-center gap-3 rounded-lg px-3 py-2.5 text-left transition-colors",
+                  selected ? "bg-foreground/[0.07]" : "hover:bg-foreground/[0.03]",
+                )}
+                onClick={() =>
+                  selectCommandSurfaceTarget({ kind: "auth", providerId: provider.id, intent: selectedAuthIntent })
+                }
+              >
+                <div className={cn(
+                  "flex h-4 w-4 shrink-0 items-center justify-center rounded-full border transition-colors",
+                  selected ? "border-foreground bg-foreground" : "border-foreground/25",
+                )}>
+                  {selected && <Check className="h-2.5 w-2.5 text-background" />}
+                </div>
+                <div className="min-w-0 flex-1">
+                  <div className="flex items-center gap-2">
+                    <span className="text-sm font-medium text-foreground">{provider.label}</span>
+                    {provider.configured && <StatusDot status="ok" />}
+                  </div>
+                  <span className="text-xs text-muted-foreground">
+                    {provider.configured ? `via ${provider.configuredVia}` : "Not configured"}
+                  </span>
+                </div>
+                {provider.recommended && (
+                  <span className="rounded bg-foreground/10 px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground">Recommended</span>
+                )}
+              </button>
+            )
+          })}
+        </div>
+
+        {/* Selected provider details */}
+        {selectedAuthProvider && (
+          <div className="space-y-4 border-t border-border/50 pt-3">
+            <div className="flex items-center justify-between">
+              <div>
+                <div className="text-sm font-medium text-foreground">{selectedAuthProvider.label}</div>
+                <span className="text-xs text-muted-foreground">{selectedAuthProvider.configuredVia ?? "Not configured"}</span>
+              </div>
+            </div>
+
+            {/* API key form */}
+            {selectedAuthProvider.supports.apiKey && (
+              <form
+                className="space-y-3"
+                onSubmit={(e) => {
+                  e.preventDefault()
+                  if (!selectedProviderApiKey.trim()) return
+                  void saveApiKeyFromSurface(selectedAuthProvider.id, selectedProviderApiKey)
+                }}
+              >
+                <div className="flex gap-2">
+                  <Input
+                    type="password"
+                    autoComplete="off"
+                    value={selectedProviderApiKey}
+                    onChange={(e) =>
+                      setApiKeys((prev) => ({ ...prev, [selectedAuthProvider.id]: e.target.value }))
+                    }
+                    placeholder="Paste API key"
+                    className="h-8 flex-1 text-xs"
+                    disabled={authBusy}
+                    data-testid="command-surface-api-key-input"
+                  />
+                  <Button
+                    type="submit"
+                    size="sm"
+                    disabled={!selectedProviderApiKey.trim() || authBusy}
+                    data-testid="command-surface-save-api-key"
+                    className="h-8 gap-1.5"
+                  >
+                    {commandSurface.pendingAction === "save_api_key" ? (
+                      <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+                    ) : (
+                      <KeyRound className="h-3.5 w-3.5" />
+                    )}
+                    Save
+                  </Button>
+                </div>
+              </form>
+            )}
+
+            {/* OAuth / sign-in buttons */}
+            <div className="flex flex-wrap gap-2">
+              {selectedAuthProvider.supports.oauth && selectedAuthProvider.supports.oauthAvailable && (
+                <Button
+                  type="button"
+                  variant="outline"
+                  size="sm"
+                  disabled={authBusy}
+                  onClick={() => void startProviderFlowFromSurface(selectedAuthProvider.id)}
+                  data-testid="command-surface-start-provider-flow"
+                  className="h-8 gap-1.5 text-xs"
+                >
+                  {commandSurface.pendingAction === "start_provider_flow" ? (
+                    <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+                  ) : (
+                    <LogIn className="h-3.5 w-3.5" />
+                  )}
+                  Browser sign-in
+                </Button>
+              )}
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                disabled={authBusy}
+                onClick={() => void logoutProviderFromSurface(selectedAuthProvider.id)}
+                data-testid="command-surface-logout-provider"
+                className="h-8 gap-1.5 text-xs text-destructive hover:text-destructive"
+              >
+                {commandSurface.pendingAction === "logout_provider" ? (
+                  <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+                ) : (
+                  <LogOut className="h-3.5 w-3.5" />
+                )}
+                Logout
+              </Button>
+            </div>
+
+            {/* Active OAuth flow */}
+            {activeFlow && activeFlow.providerId === selectedAuthProvider.id && (
+              <div className="space-y-3 rounded-lg border border-foreground/10 bg-foreground/[0.03] px-4 py-3" data-testid="command-surface-active-flow">
+                <div className="flex items-center gap-2 text-xs">
+                  <Badge variant="outline" className="text-[10px]">{activeFlow.status.replaceAll("_", " ")}</Badge>
+                  <span className="text-muted-foreground">{new Date(activeFlow.updatedAt).toLocaleTimeString()}</span>
+                </div>
+
+                {activeFlow.auth?.instructions && (
+                  <p className="text-xs text-muted-foreground">{activeFlow.auth.instructions}</p>
+                )}
+
+                {activeFlow.auth?.url && (
+                  <Button asChild variant="outline" size="sm" className="h-7 gap-1.5 text-xs" data-testid="command-surface-open-auth-url">
+                    <a href={activeFlow.auth.url} target="_blank" rel="noreferrer">
+                      <ExternalLink className="h-3 w-3" />
+                      Open sign-in page
+                    </a>
+                  </Button>
+                )}
+
+                {activeFlow.progress.length > 0 && (
+                  <div className="space-y-1">
+                    {activeFlow.progress.map((message, index) => (
+                      <div key={`${activeFlow.flowId}-${index}`} className="rounded-md border border-border/50 bg-card/50 px-2.5 py-1.5 text-xs text-muted-foreground">
+                        {message}
+                      </div>
+                    ))}
+                  </div>
+                )}
+
+                {activeFlow.prompt && (
+                  <form
+                    className="space-y-2"
+                    onSubmit={(e) => {
+                      e.preventDefault()
+                      if (!activeFlow.prompt?.allowEmpty && !flowInput.trim()) return
+                      void submitProviderFlowInputFromSurface(activeFlow.flowId, flowInput)
+                    }}
+                  >
+                    <Input
+                      value={flowInput}
+                      onChange={(e) => setFlowInput(e.target.value)}
+                      placeholder={activeFlow.prompt.placeholder || "Enter value"}
+                      className="h-8 text-xs"
+                      disabled={authBusy}
+                      data-testid="command-surface-flow-input"
+                    />
+                    <p className="text-[11px] text-muted-foreground">{activeFlow.prompt.message}</p>
+                    <div className="flex gap-2">
+                      <Button type="submit" size="sm" disabled={authBusy || (!activeFlow.prompt.allowEmpty && !flowInput.trim())} className="h-7 gap-1.5 text-xs">
+                        {commandSurface.pendingAction === "submit_provider_flow_input" ? (
+                          <LoaderCircle className="h-3 w-3 animate-spin" />
+                        ) : (
+                          <ShieldCheck className="h-3 w-3" />
+                        )}
+                        Continue
+                      </Button>
+                      <Button type="button" variant="ghost" size="sm" disabled={authBusy} onClick={() => void cancelProviderFlowFromSurface(activeFlow.flowId)} className="h-7 text-xs">
+                        Cancel
+                      </Button>
+                    </div>
+                  </form>
+                )}
+              </div>
+            )}
+
+            {/* Bridge auth refresh status */}
+            {onboarding.bridgeAuthRefresh.phase !== "idle" && (
+              <div className="rounded-lg border border-border/50 bg-card/50 px-3 py-2.5 text-xs">
+                <span className="font-medium text-foreground">Auth refresh</span>
+                <span className="ml-2 text-muted-foreground">
+                  {onboarding.bridgeAuthRefresh.phase === "pending"
+                    ? "Refreshing…"
+                    : onboarding.bridgeAuthRefresh.phase === "failed"
+                      ? onboarding.bridgeAuthRefresh.error || "Failed."
+                      : "Complete."}
+                </span>
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    )
+  }
+
+  // ═══════════════════════════════════════════════════════════════════
+  // SECTION DISPATCH
+  // ═══════════════════════════════════════════════════════════════════
+
+  const renderAdminSection = () => (
+    <div className="space-y-5" data-testid="command-surface-admin">
+      <SectionHeader
+        title="Admin"
+        status={
+          <Badge variant="outline" className="border-warning/20 bg-warning/[0.06] text-[10px] text-warning">
+            Dev only
+          </Badge>
+        }
+      />
+
+      {/* Master toggle */}
+      <ToggleRow
+        label="UI overrides"
+        description="Enable keyboard shortcuts and forced UI states for development"
+        checked={devOverrides.enabled}
+        onCheckedChange={devOverrides.setEnabled}
+        testId="admin-ui-overrides-master"
+      />
+
+      {/* Individual overrides — only visible when master is on */}
+      {devOverrides.enabled && (
+        <div className="space-y-2 rounded-lg border border-border/50 bg-card/50 p-3">
+          <div className="text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">
+            Override shortcuts
+          </div>
+          {DEV_OVERRIDE_REGISTRY.map((entry) => (
+            <div
+              key={entry.key}
+              className="flex items-start justify-between gap-3 rounded-md px-3 py-2.5 transition-colors hover:bg-foreground/[0.03]"
+            >
+              <div className="min-w-0 flex-1">
+                <div className="flex items-center gap-2">
+                  <span className="text-sm font-medium text-foreground">{entry.label}</span>
+                  <Badge variant="outline" className="border-border font-mono text-[10px] text-muted-foreground">
+                    {entry.shortcutLabel}
+                  </Badge>
+                </div>
+                <p className="mt-0.5 text-xs text-muted-foreground">{entry.description}</p>
+              </div>
+              <Switch
+                checked={devOverrides.overrides[entry.key]}
+                onCheckedChange={() => devOverrides.toggle(entry.key)}
+                data-testid={`admin-override-${entry.key}`}
+              />
+            </div>
+          ))}
+        </div>
+      )}
+
+      {/* Onboarding — one-click launch */}
+      <div className="rounded-lg border border-border/50 bg-card/50 p-3 space-y-3">
+        <div className="text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">
+          Onboarding
+        </div>
+        <div className="flex items-center justify-between gap-3 px-3 py-2.5">
+          <div className="min-w-0 flex-1">
+            <div className="text-sm font-medium text-foreground">Run setup wizard</div>
+            <p className="mt-0.5 text-xs text-muted-foreground">
+              Opens the full onboarding flow as a new user would see it.
+            </p>
+          </div>
+          <Button
+            type="button"
+            size="sm"
+            className="h-8 shrink-0 gap-1.5 text-xs"
+            onClick={() => {
+              closeCommandSurface()
+              // Small delay so the sheet closes before the gate renders
+              window.setTimeout(() => {
+                if (!devOverrides.enabled) devOverrides.setEnabled(true)
+                if (!devOverrides.overrides.forceOnboarding) devOverrides.toggle("forceOnboarding")
+              }, 150)
+            }}
+            data-testid="admin-trigger-onboarding"
+          >
+            Launch
+          </Button>
+        </div>
+      </div>
+
+      <div className="rounded-lg border border-border/50 bg-card/50 px-3 py-2.5 text-xs text-muted-foreground">
+        This tab is only visible when running via{" "}
+        <code className="rounded bg-muted px-1 py-0.5 font-mono text-[11px]">npm run gsd:web</code>.
+        Overrides reset on page refresh.
+      </div>
+    </div>
+  )
+
+  const renderSection = () => {
+    switch (commandSurface.section) {
+      case "general": return <GeneralPanel />
+      case "experimental": return <ExperimentalPanel />
+      case "model": return (
+        <div className="space-y-8">
+          {renderModelSection()}
+          <div className="border-t border-border/50 pt-6">
+            {renderThinkingSection()}
+          </div>
+        </div>
+      )
+      case "thinking": return (
+        <div className="space-y-8">
+          {renderModelSection()}
+          <div className="border-t border-border/50 pt-6">
+            {renderThinkingSection()}
+          </div>
+        </div>
+      )
+      case "session-behavior": return (
+        <div className="space-y-6">
+          {renderQueueSection()}
+          <div className="border-t border-border/50 pt-4">
+            {renderCompactionSection()}
+          </div>
+          <div className="border-t border-border/50 pt-4">
+            {renderRetrySection()}
+          </div>
+        </div>
+      )
+      // Legacy section routes — redirect to merged panels
+      case "queue": return (
+        <div className="space-y-6">
+          {renderQueueSection()}
+          <div className="border-t border-border/50 pt-4">
+            {renderCompactionSection()}
+          </div>
+          <div className="border-t border-border/50 pt-4">
+            {renderRetrySection()}
+          </div>
+        </div>
+      )
+      case "compaction": return (
+        <div className="space-y-6">
+          {renderQueueSection()}
+          <div className="border-t border-border/50 pt-4">
+            {renderCompactionSection()}
+          </div>
+          <div className="border-t border-border/50 pt-4">
+            {renderRetrySection()}
+          </div>
+        </div>
+      )
+      case "retry": return (
+        <div className="space-y-6">
+          {renderQueueSection()}
+          <div className="border-t border-border/50 pt-4">
+            {renderCompactionSection()}
+          </div>
+          <div className="border-t border-border/50 pt-4">
+            {renderRetrySection()}
+          </div>
+        </div>
+      )
+      case "recovery": return renderRecoverySection()
+      case "auth": return renderAuthSection()
+      case "admin": return renderAdminSection()
+      case "git": return renderGitSection()
+      case "resume": return renderSessionBrowserSection("resume")
+      case "name": return renderSessionBrowserSection("name")
+      case "fork": return renderForkSection()
+      case "session": return renderSessionSection()
+      case "compact": return renderCompactSection()
+      case "workspace": return <DevRootSettingsSection />
+      case "integrations": return <RemoteQuestionsPanel />
+      case "gsd-forensics": return <ForensicsPanel />
+      case "gsd-doctor": return <DoctorPanel />
+      case "gsd-skill-health": return <SkillHealthPanel />
+      case "gsd-knowledge": return <KnowledgeCapturesPanel initialTab="knowledge" />
+      case "gsd-capture": return <KnowledgeCapturesPanel initialTab="captures" />
+      case "gsd-triage": return <KnowledgeCapturesPanel initialTab="captures" />
+      case "gsd-prefs": return (
+        <div className="space-y-6">
+          <DevRootSettingsSection />
+          <PrefsPanel />
+          <ModelRoutingPanel />
+          <BudgetPanel />
+          <RemoteQuestionsPanel />
+          <GeneralPanel />
+          <ExperimentalPanel />
+        </div>
+      )
+      case "gsd-mode": return <ModelRoutingPanel />
+      case "gsd-config": return <BudgetPanel />
+      case "gsd-quick": return <QuickPanel />
+      case "gsd-history": return <HistoryPanel />
+      case "gsd-undo": return <UndoPanel />
+      case "gsd-steer": return <SteerPanel />
+      case "gsd-hooks": return <HooksPanel />
+      case "gsd-inspect": return <InspectPanel />
+      case "gsd-export": return <ExportPanel />
+      case "gsd-cleanup": return <CleanupPanel />
+      case "gsd-queue": return <QueuePanel />
+      case "gsd-status": return <StatusPanel />
+      default:
+        // Safety net for any unknown GSD surface
+        if (commandSurface.section?.startsWith("gsd-")) {
+          return (
+            <div className="p-4 text-sm text-muted-foreground" data-testid={`gsd-surface-${commandSurface.section}`}>
+              <p className="font-medium text-foreground">/gsd {commandSurface.section.slice(4)}</p>
+              <p className="mt-1">Unknown GSD surface.</p>
+            </div>
+          )
+        }
+        return null
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════
+  // RENDER
+  // ═══════════════════════════════════════════════════════════════════
+
+  const isSingleSection = surfaceSections.length <= 1
+  const isGitSurface = commandSurface.activeSurface === "git"
+  const gitResult = gitSummary.result
+
+  const renderGitHeader = () => {
+    const branchName = gitResult?.kind === "repo" ? (gitResult.branch ?? "detached") : null
+    const mainBranch = gitResult?.kind === "repo" ? gitResult.mainBranch : null
+    const hasChanges = gitResult?.kind === "repo" ? gitResult.hasChanges : false
+    const isClean = gitResult?.kind === "repo" && !hasChanges
+
+    return (
+      <div className="border-b border-border/50 px-5 py-4">
+        <div className="flex items-start justify-between gap-3">
+          <div className="flex items-center gap-3">
+            <div className={cn(
+              "flex h-8 w-8 items-center justify-center rounded-lg",
+              isClean ? "bg-success/10" : hasChanges ? "bg-warning/10" : "bg-card/50",
+            )}>
+              <GitBranch className={cn(
+                "h-4 w-4",
+                isClean ? "text-success" : hasChanges ? "text-warning" : "text-muted-foreground",
+              )} />
+            </div>
+            <div>
+              <div className="flex items-center gap-2">
+                <h2 className="text-sm font-semibold text-foreground" data-testid="command-surface-title">
+                  {branchName ?? "Git"}
+                </h2>
+                {branchName && mainBranch && branchName !== mainBranch && (
+                  <span className="text-[11px] text-muted-foreground">from {mainBranch}</span>
+                )}
+              </div>
+              {gitResult?.kind === "repo" && (
+                <div className="mt-0.5 flex items-center gap-1.5">
+                  <StatusDot status={isClean ? "ok" : hasChanges ? "warning" : "idle"} />
+                  <span className="text-[11px] text-muted-foreground">
+                    {isClean ? "Clean" : hasChanges ? "Changes detected" : "Loading…"}
+                  </span>
+                </div>
+              )}
+            </div>
+          </div>
+          <div className="flex items-center gap-1">
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon"
+              onClick={() => void loadGitSummary()}
+              disabled={gitSummaryBusy}
+              aria-label="Refresh"
+              className="h-7 w-7"
+            >
+              <RefreshCw className={cn("h-3.5 w-3.5", gitSummaryBusy && "animate-spin")} />
+            </Button>
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon"
+              onClick={closeCommandSurface}
+              aria-label="Close"
+              className="h-7 w-7"
+            >
+              <X className="h-3.5 w-3.5" />
+            </Button>
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  const renderDefaultHeader = () => (
+    <div className="flex items-center justify-between gap-3 border-b border-border/50 px-5 py-4">
+      <div>
+        <div className="text-xs uppercase tracking-wider text-muted-foreground">Command surface</div>
+        <div className="text-lg font-semibold text-foreground" data-testid="command-surface-title">
+          {surfaceTitle(commandSurface.activeSurface)}
+        </div>
+      </div>
+      <div className="flex items-center gap-2">
+        <div className="rounded-full border border-border bg-card px-2.5 py-1 text-xs font-medium text-muted-foreground" data-testid="command-surface-kind">
+          {surfaceKindLabel}
+        </div>
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon"
+          onClick={closeCommandSurface}
+          aria-label="Close"
+          className="h-8 w-8"
+        >
+          <X className="h-4 w-4" />
+        </Button>
+      </div>
+    </div>
+  )
+
+  return (
+    <Sheet open={commandSurface.open} onOpenChange={(open) => !open && closeCommandSurface()}>
+      <SheetContent side="right" className="flex h-full w-full flex-col p-0 sm:max-w-[540px]" data-testid="command-surface">
+        {/* Visually hidden accessible title */}
+        <SheetHeader className="sr-only">
+          <SheetTitle>{surfaceTitle(commandSurface.activeSurface)}</SheetTitle>
+          <SheetDescription>Settings and controls</SheetDescription>
+        </SheetHeader>
+
+        <div className="flex h-full min-h-0">
+          {/* ─── Left nav rail (hidden for single-section surfaces) ─── */}
+          {!isSingleSection && (
+            <nav className="flex w-12 shrink-0 flex-col items-center gap-0.5 border-r border-border/50 bg-card/50 py-3" data-testid="command-surface-sections">
+              {surfaceSections.map((section) => {
+                const active = commandSurface.section === section
+                return (
+                  <Tooltip key={section}>
+                    <TooltipTrigger asChild>
+                      <button
+                        type="button"
+                        className={cn(
+                          "flex h-9 w-9 items-center justify-center rounded-lg transition-colors",
+                          active
+                            ? "bg-foreground/10 text-foreground"
+                            : "text-muted-foreground hover:bg-foreground/[0.04] hover:text-foreground",
+                        )}
+                        onClick={() => setCommandSurfaceSection(section)}
+                        data-testid={`command-surface-section-${section}`}
+                      >
+                        {sectionIcon(section)}
+                      </button>
+                    </TooltipTrigger>
+                    <TooltipContent side="right" sideOffset={6}>
+                      {sectionLabel(section)}
+                    </TooltipContent>
+                  </Tooltip>
+                )
+              })}
+            </nav>
+          )}
+
+          {/* ─── Right content area ────────────────────────────────── */}
+          <div className="flex min-h-0 min-w-0 flex-1 flex-col">
+            {isGitSurface ? renderGitHeader() : renderDefaultHeader()}
+            {(commandSurface.lastResult || commandSurface.lastError) && (
+              <div
+                className={cn(
+                  "border-b border-border/50 px-5 py-3 text-xs",
+                  commandSurface.lastError ? "bg-destructive/5 text-destructive" : "bg-success/5 text-success",
+                )}
+                data-testid="command-surface-result"
+              >
+                {commandSurface.lastError ?? commandSurface.lastResult}
+              </div>
+            )}
+            <ScrollArea className="min-h-0 flex-1" viewportRef={commandSurfaceViewportRef}>
+              <div className="px-5 py-5">
+                {renderSection()}
+              </div>
+            </ScrollArea>
+          </div>
+        </div>
+      </SheetContent>
+    </Sheet>
+  )
+}
diff --git a/web/components/sf/dashboard.tsx b/web/components/sf/dashboard.tsx
new file mode 100644
index 000000000..afa732ae8
--- /dev/null
+++ b/web/components/sf/dashboard.tsx
@@ -0,0 +1,442 @@
+"use client"
+
+import { useEffect, useState, useCallback } from "react"
+import {
+  Activity,
+  Clock,
+  DollarSign,
+  Zap,
+  CheckCircle2,
+  Circle,
+  Play,
+  GitBranch,
+  TrendingDown,
+} from "lucide-react"
+import { cn } from "@/lib/utils"
+import {
+  useGSDWorkspaceState,
+  useGSDWorkspaceActions,
+  buildPromptCommand,
+  buildProjectUrl,
+  formatDuration,
+  formatCost,
+  formatTokens,
+  getCurrentScopeLabel,
+  getCurrentBranch,
+  getCurrentSlice,
+  getLiveAutoDashboard,
+  getLiveWorkspaceIndex,
+  type WorkspaceTerminalLine,
+  type TerminalLineType,
+} from "@/lib/sf-workspace-store"
+import { getTaskStatus, type ItemStatus } from "@/lib/workspace-status"
+import { deriveWorkflowAction } from "@/lib/workflow-actions"
+import { executeWorkflowActionInPowerMode } from "@/lib/workflow-action-execution"
+import { Skeleton } from "@/components/ui/skeleton"
+import {
+  CurrentSliceCardSkeleton,
+  ActivityCardSkeleton,
+} from "@/components/sf/loading-skeletons"
+import { ScopeBadge } from "@/components/sf/scope-badge"
+import { ProjectWelcome } from "@/components/sf/project-welcome"
+import { authFetch } from "@/lib/auth"
+import { type ProjectTotals } from "@/lib/visualizer-types"
+
+/** Interpolate progress bar color from red (0%) through yellow (50%) to green (100%) using oklch. */
+function getProgressColor(percent: number): string {
+  const p = Math.max(0, Math.min(100, percent))
+  // Hue: 25 (red) → 85 (yellow) at 50% → 145 (green) at 100%
+  const hue = 25 + (p / 100) * 120
+  return `oklch(0.65 0.16 ${hue.toFixed(1)})`
+}
+
+interface MetricCardProps {
+  label: string
+  value: string | null
+  subtext?: string | null
+  icon: React.ReactNode
+}
+
+function MetricCard({ label, value, subtext, icon }: MetricCardProps) {
+  return (
+    <div className="rounded-md border border-border bg-card p-4">
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0">
+          <p className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
+            {label}
+          </p>
+          {value === null ? (
+            <>
+              <Skeleton className="mt-2 h-7 w-20" />
+              <Skeleton className="mt-1.5 h-3 w-16" />
+            </>
+          ) : (
+            <>
+              <p className="mt-1 truncate text-2xl font-semibold tracking-tight">{value}</p>
+              {subtext && <p className="mt-0.5 truncate text-xs text-muted-foreground">{subtext}</p>}
+            </>
+          )}
+        </div>
+        <div className="shrink-0 rounded-md bg-accent p-2 text-muted-foreground">{icon}</div>
+      </div>
+    </div>
+  )
+}
+
+function taskStatusIcon(status: ItemStatus) {
+  switch (status) {
+    case "done":
+      return <CheckCircle2 className="h-4 w-4 text-muted-foreground" />
+    case "in-progress":
+      return <Play className="h-4 w-4 text-foreground" />
+    case "pending":
+      return <Circle className="h-4 w-4 text-muted-foreground" />
+  }
+}
+
+function activityDotColor(type: TerminalLineType): string {
+  switch (type) {
+    case "success":
+      return "bg-success"
+    case "error":
+      return "bg-destructive"
+    default:
+      return "bg-foreground/50"
+  }
+}
+
+interface DashboardProps {
+  onSwitchView?: (view: string) => void
+  onExpandTerminal?: () => void
+}
+
+export function Dashboard({ onSwitchView, onExpandTerminal }: DashboardProps = {}) {
+  const state = useGSDWorkspaceState()
+  const { sendCommand } = useGSDWorkspaceActions()
+  const boot = state.boot
+  const workspace = getLiveWorkspaceIndex(state)
+  const auto = getLiveAutoDashboard(state)
+  const bridge = boot?.bridge ?? null
+  const freshness = state.live.freshness
+  const projectCwd = boot?.project.cwd
+
+  // ── Project-level totals from visualizer API ──
+  // Provides fallback metrics when auto-mode is not active (#2709).
+  // Same polling pattern as status-bar.tsx.
+  const [projectTotals, setProjectTotals] = useState<ProjectTotals | null>(null)
+
+  const fetchProjectTotals = useCallback(async () => {
+    try {
+      const resp = await authFetch(buildProjectUrl("/api/visualizer", projectCwd))
+      if (!resp.ok) return
+      const json = await resp.json()
+      if (json.totals) setProjectTotals(json.totals)
+    } catch {
+      // Silently ignore — dashboard metrics are non-critical
+    }
+  }, [projectCwd])
+
+  useEffect(() => {
+    const timeout = window.setTimeout(() => {
+      void fetchProjectTotals()
+    }, 0)
+    const interval = window.setInterval(() => {
+      void fetchProjectTotals()
+    }, 30_000)
+    return () => {
+      window.clearTimeout(timeout)
+      window.clearInterval(interval)
+    }
+  }, [fetchProjectTotals])
+
+  const elapsed = projectTotals?.duration ?? auto?.elapsed ?? 0
+  const totalCost = projectTotals?.cost ?? auto?.totalCost ?? 0
+  const totalTokens = projectTotals?.tokens.total ?? auto?.totalTokens ?? 0
+  const rtkSavings = auto?.rtkSavings ?? null
+  const rtkEnabled = auto?.rtkEnabled === true
+
+  const currentSlice = getCurrentSlice(workspace)
+  const doneTasks = currentSlice?.tasks.filter((t) => t.done).length ?? 0
+  const totalTasks = currentSlice?.tasks.length ?? 0
+  const progressPercent = totalTasks > 0 ? Math.round((doneTasks / totalTasks) * 100) : 0
+
+  const scopeLabel = getCurrentScopeLabel(workspace)
+  const branch = getCurrentBranch(workspace)
+  const isAutoActive = auto?.active ?? false
+  const currentUnitLabel = auto?.currentUnit?.id ?? scopeLabel
+  const currentUnitFreshness = freshness.auto.stale ? "stale" : freshness.auto.status
+
+  const workflowAction = deriveWorkflowAction({
+    phase: workspace?.active.phase ?? "pre-planning",
+    autoActive: auto?.active ?? false,
+    autoPaused: auto?.paused ?? false,
+    onboardingLocked: boot?.onboarding.locked ?? false,
+    commandInFlight: state.commandInFlight,
+    bootStatus: state.bootStatus,
+    hasMilestones: (workspace?.milestones.length ?? 0) > 0,
+    projectDetectionKind: boot?.projectDetection?.kind ?? null,
+  })
+
+  const handleWorkflowAction = (command: string) => {
+    executeWorkflowActionInPowerMode({
+      dispatch: () => sendCommand(buildPromptCommand(command, bridge)),
+    })
+  }
+
+  const handlePrimaryAction = () => {
+    if (!workflowAction.primary) return
+    handleWorkflowAction(workflowAction.primary.command)
+  }
+
+  const recentLines: WorkspaceTerminalLine[] = (state.terminalLines ?? []).slice(-6)
+  const isConnecting = state.bootStatus === "idle" || state.bootStatus === "loading"
+
+  const rtkValue = isConnecting ? null : formatTokens(rtkSavings?.savedTokens ?? 0)
+  const rtkSubtext = isConnecting
+    ? null
+    : rtkSavings && rtkSavings.commands > 0
+      ? `${Math.round(rtkSavings.savingsPct)}% saved • ${rtkSavings.commands} cmd${rtkSavings.commands === 1 ? "" : "s"}`
+      : "Waiting for shell usage"
+
+  // ─── Project Welcome Gate ───────────────────────────────────────────
+  // Show welcome screen for projects that aren't initialized with GSD yet
+  const detection = boot?.projectDetection
+  const showWelcome =
+    !isConnecting &&
+    detection &&
+    detection.kind !== "active-gsd" &&
+    detection.kind !== "empty-gsd"
+
+  if (showWelcome) {
+    return (
+      <div className="flex h-full flex-col overflow-hidden">
+        <ProjectWelcome
+          detection={detection}
+          onCommand={(cmd) => handleWorkflowAction(cmd)}
+          onSwitchView={(view) => onSwitchView?.(view)}
+          disabled={!!state.commandInFlight || boot?.onboarding.locked}
+        />
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex h-full flex-col overflow-hidden">
+      <div className="flex items-center justify-between border-b border-border px-3 py-2 md:px-6 md:py-3">
+        <div className="flex items-center gap-2 min-w-0">
+          <h1 className="text-base md:text-lg font-semibold shrink-0">Dashboard</h1>
+          {!isConnecting && scopeLabel && (
+            <>
+              <span className="hidden sm:inline text-lg font-thin text-muted-foreground select-none">/</span>
+              <span className="hidden sm:inline"><ScopeBadge label={scopeLabel} size="sm" /></span>
+            </>
+          )}
+          {isConnecting && <Skeleton className="h-4 w-40" />}
+        </div>
+        <div className="flex items-center gap-2 md:gap-3" data-testid="dashboard-action-bar">
+          {isConnecting ? (
+            <>
+              <Skeleton className="h-8 w-40 rounded-md" />
+            </>
+          ) : null}
+          {!isConnecting && (
+            <div className="flex items-center gap-2 rounded-md border border-border bg-card px-3 py-1.5 text-sm">
+              <span
+                className={cn(
+                  "h-2 w-2 rounded-full",
+                  isAutoActive ? "animate-pulse bg-success" : "bg-muted-foreground/50",
+                )}
+              />
+              <span className="font-medium">
+                {isAutoActive ? "Auto Mode Active" : "Auto Mode Inactive"}
+              </span>
+            </div>
+          )}
+          {!isConnecting && branch && (
+            <div className="flex items-center gap-2 text-sm text-muted-foreground">
+              <GitBranch className="h-4 w-4" />
+              <span className="font-mono">{branch}</span>
+            </div>
+          )}
+        </div>
+      </div>
+
+      <div className="flex-1 overflow-y-auto p-3 md:p-6">
+        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 md:grid-cols-2 xl:grid-cols-4 2xl:grid-cols-5">
+          <div className="rounded-md border border-border bg-card p-4" data-testid="dashboard-current-unit">
+            <div className="flex items-start justify-between gap-3">
+              <div className="min-w-0">
+                <p className="text-xs font-medium uppercase tracking-wider text-muted-foreground">Current Unit</p>
+                {isConnecting ? (
+                  <>
+                    <Skeleton className="mt-2 h-7 w-20" />
+                    <Skeleton className="mt-1.5 h-3 w-16" />
+                  </>
+                ) : (
+                  <>
+                    <div className="mt-2">
+                      <ScopeBadge label={currentUnitLabel} />
+                    </div>
+                    <p className="mt-1.5 text-xs text-muted-foreground" data-testid="dashboard-current-unit-freshness">
+                      Auto freshness: {currentUnitFreshness}
+                    </p>
+                  </>
+                )}
+              </div>
+              <div className="shrink-0 rounded-md bg-accent p-2 text-muted-foreground">
+                <Activity className="h-5 w-5" />
+              </div>
+            </div>
+          </div>
+          <MetricCard
+            label="Elapsed Time"
+            value={isConnecting ? null : formatDuration(elapsed)}
+            icon={<Clock className="h-5 w-5" />}
+          />
+          <MetricCard
+            label="Total Cost"
+            value={isConnecting ? null : formatCost(totalCost)}
+            icon={<DollarSign className="h-5 w-5" />}
+          />
+          <MetricCard
+            label="Tokens Used"
+            value={isConnecting ? null : formatTokens(totalTokens)}
+            icon={<Zap className="h-5 w-5" />}
+          />
+          {rtkEnabled && (
+            <MetricCard
+              label="RTK Saved"
+              value={rtkValue}
+              subtext={rtkSubtext}
+              icon={<TrendingDown className="h-5 w-5" />}
+            />
+          )}
+
+        </div>
+
+        <div className="mt-6">
+          {/* Current Slice */}
+          {isConnecting ? (
+            <CurrentSliceCardSkeleton />
+          ) : (
+            <div className="flex flex-col rounded-md border border-border bg-card">
+              {/* Header */}
+              <div className="border-b border-border px-4 py-3">
+                <div className="flex items-center justify-between gap-3">
+                  <div className="min-w-0">
+                    <h2 className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">Current Slice</h2>
+                    {currentSlice ? (
+                      <p className="mt-0.5 truncate text-sm font-medium text-foreground">
+                        {currentSlice.id} — {currentSlice.title}
+                      </p>
+                    ) : (
+                      <p className="mt-0.5 text-sm text-muted-foreground">No active slice</p>
+                    )}
+                  </div>
+                  {currentSlice && totalTasks > 0 && (
+                    <div className="shrink-0 text-right">
+                      <span className="text-2xl font-bold tabular-nums leading-none">{progressPercent}</span>
+                      <span className="text-xs text-muted-foreground">%</span>
+                    </div>
+                  )}
+                </div>
+                {currentSlice && totalTasks > 0 && (
+                  <div className="mt-3">
+                    <div className="h-1 w-full overflow-hidden rounded-full bg-accent">
+                      <div
+                        className="h-full rounded-full transition-all duration-500"
+                        style={{ width: `${progressPercent}%`, backgroundColor: getProgressColor(progressPercent) }}
+                      />
+                    </div>
+                    <p className="mt-1.5 text-xs text-muted-foreground">{doneTasks} of {totalTasks} tasks complete</p>
+                  </div>
+                )}
+              </div>
+              {/* Task list */}
+              <div className="flex-1 p-3">
+                {currentSlice && currentSlice.tasks.length > 0 ? (
+                  <div className="space-y-0.5">
+                    {currentSlice.tasks.map((task) => {
+                      const status = getTaskStatus(
+                        workspace!.active.milestoneId!,
+                        currentSlice.id,
+                        task,
+                        workspace!.active,
+                      )
+                      return (
+                        <div
+                          key={task.id}
+                          className={cn(
+                            "flex items-center gap-2.5 rounded px-2 py-1.5 transition-colors",
+                            status === "in-progress" && "bg-accent",
+                          )}
+                        >
+                          {taskStatusIcon(status)}
+                          <span
+                            className={cn(
+                              "min-w-0 flex-1 truncate text-xs",
+                              status === "done" && "text-muted-foreground line-through decoration-muted-foreground/40",
+                              status === "pending" && "text-muted-foreground",
+                              status === "in-progress" && "font-medium text-foreground",
+                            )}
+                          >
+                            <span className="font-mono text-muted-foreground">{task.id}</span>
+                            <span className="mx-1.5 text-border">·</span>
+                            {task.title}
+                          </span>
+                          {status === "in-progress" && (
+                            <span className="shrink-0 rounded-sm bg-foreground/10 px-1.5 py-0.5 text-[10px] font-medium uppercase tracking-wide text-muted-foreground">
+                              active
+                            </span>
+                          )}
+                        </div>
+                      )
+                    })}
+                  </div>
+                ) : (
+                  <p className="px-2 py-2 text-xs text-muted-foreground">
+                    No active slice or no tasks defined yet.
+                  </p>
+                )}
+              </div>
+            </div>
+          )}
+        </div>
+
+        {isConnecting ? (
+          <div className="mt-6">
+            <ActivityCardSkeleton />
+          </div>
+        ) : (
+          <div className="mt-6 rounded-md border border-border bg-card">
+            <div className="border-b border-border px-4 py-3">
+              <h2 className="text-sm font-semibold">Recent Activity</h2>
+            </div>
+            {recentLines.length > 0 ? (
+              <div className="divide-y divide-border">
+                {recentLines.map((line) => (
+                  <div key={line.id} className="flex items-center gap-3 px-4 py-2.5">
+                    <span className="w-16 flex-shrink-0 font-mono text-xs text-muted-foreground">
+                      {line.timestamp}
+                    </span>
+                    <span
+                      className={cn(
+                        "h-1.5 w-1.5 flex-shrink-0 rounded-full",
+                        activityDotColor(line.type),
+                      )}
+                    />
+                    <span className="truncate text-sm">{line.content}</span>
+                  </div>
+                ))}
+              </div>
+            ) : (
+              <div className="px-4 py-4 text-sm text-muted-foreground">
+                No activity yet.
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
diff --git a/web/components/sf/diagnostics-panels.tsx b/web/components/sf/diagnostics-panels.tsx
new file mode 100644
index 000000000..d9f40c626
--- /dev/null
+++ b/web/components/sf/diagnostics-panels.tsx
@@ -0,0 +1,523 @@
+"use client"
+
+import { AlertTriangle, CheckCircle2, Info, LoaderCircle, RefreshCw, ShieldAlert, Wrench, XCircle } from "lucide-react"
+
+import { Badge } from "@/components/ui/badge"
+import { Button } from "@/components/ui/button"
+import type {
+  DoctorIssue,
+  ForensicAnomaly,
+  ForensicReport,
+  DoctorReport,
+  SkillHealthReport,
+  SkillHealSuggestion,
+} from "@/lib/diagnostics-types"
+import { cn } from "@/lib/utils"
+import {
+  formatCost,
+  useGSDWorkspaceActions,
+  useGSDWorkspaceState,
+} from "@/lib/sf-workspace-store"
+
+// ═══════════════════════════════════════════════════════════════════════
+// SHARED
+// ═══════════════════════════════════════════════════════════════════════
+
+function SeverityIcon({ severity, className }: { severity: "info" | "warning" | "error" | "critical"; className?: string }) {
+  const base = cn("h-3.5 w-3.5 shrink-0", className)
+  switch (severity) {
+    case "error":
+    case "critical":
+      return <XCircle className={cn(base, "text-destructive")} />
+    case "warning":
+      return <AlertTriangle className={cn(base, "text-warning")} />
+    default:
+      return <Info className={cn(base, "text-info")} />
+  }
+}
+
+function severityBadgeVariant(s: string): "destructive" | "secondary" | "outline" {
+  if (s === "error" || s === "critical") return "destructive"
+  if (s === "warning") return "secondary"
+  return "outline"
+}
+
+function DiagHeader({
+  title,
+  subtitle,
+  status,
+  onRefresh,
+  refreshing,
+}: {
+  title: string
+  subtitle?: string | null
+  status?: React.ReactNode
+  onRefresh: () => void
+  refreshing: boolean
+}) {
+  return (
+    <div className="flex items-center justify-between gap-3 pb-4">
+      <div className="flex items-center gap-2.5">
+        <h3 className="text-[13px] font-semibold uppercase tracking-[0.08em] text-muted-foreground">{title}</h3>
+        {status}
+        {subtitle && <span className="text-[11px] text-muted-foreground">{subtitle}</span>}
+      </div>
+      <Button type="button" variant="ghost" size="sm" onClick={onRefresh} disabled={refreshing} className="h-7 gap-1.5 text-xs">
+        <RefreshCw className={cn("h-3 w-3", refreshing && "animate-spin")} />
+        Refresh
+      </Button>
+    </div>
+  )
+}
+
+function DiagError({ message }: { message: string }) {
+  return (
+    <div className="rounded-lg border border-destructive/20 bg-destructive/5 px-3 py-2.5 text-xs text-destructive">
+      {message}
+    </div>
+  )
+}
+
+function DiagLoading({ label }: { label: string }) {
+  return (
+    <div className="flex items-center gap-2 py-6 text-xs text-muted-foreground">
+      <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+      {label}
+    </div>
+  )
+}
+
+function DiagEmpty({ message }: { message: string }) {
+  return (
+    <div className="rounded-lg border border-border/50 bg-card/50 px-4 py-5 text-center text-xs text-muted-foreground">
+      {message}
+    </div>
+  )
+}
+
+function StatPill({ label, value, variant }: { label: string; value: number | string; variant?: "default" | "error" | "warning" | "info" }) {
+  return (
+    <div className={cn(
+      "flex items-center gap-1.5 rounded-md border px-2.5 py-1 text-xs",
+      variant === "error" && "border-destructive/20 bg-destructive/5 text-destructive",
+      variant === "warning" && "border-warning/20 bg-warning/5 text-warning",
+      variant === "info" && "border-info/20 bg-info/5 text-info",
+      (!variant || variant === "default") && "border-border/50 bg-card/50 text-foreground/80",
+    )}>
+      <span className="text-muted-foreground">{label}</span>
+      <span className="font-medium tabular-nums">{value}</span>
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// FORENSICS PANEL
+// ═══════════════════════════════════════════════════════════════════════
+
+function AnomalyRow({ anomaly }: { anomaly: ForensicAnomaly }) {
+  return (
+    <div className="rounded-lg border border-border/50 bg-card/50 px-3 py-2.5 space-y-1">
+      <div className="flex items-center gap-2">
+        <SeverityIcon severity={anomaly.severity} />
+        <Badge variant={severityBadgeVariant(anomaly.severity)} className="text-[10px] px-1.5 py-0">{anomaly.severity}</Badge>
+        <Badge variant="outline" className="text-[10px] px-1.5 py-0 font-mono">{anomaly.type}</Badge>
+        {anomaly.unitId && (
+          <span className="text-[10px] text-muted-foreground font-mono truncate">{anomaly.unitType}/{anomaly.unitId}</span>
+        )}
+      </div>
+      <p className="text-xs text-foreground">{anomaly.summary}</p>
+      {anomaly.details && anomaly.details !== anomaly.summary && (
+        <p className="text-[11px] text-muted-foreground leading-relaxed">{anomaly.details}</p>
+      )}
+    </div>
+  )
+}
+
+export function ForensicsPanel() {
+  const workspace = useGSDWorkspaceState()
+  const { loadForensicsDiagnostics } = useGSDWorkspaceActions()
+  const state = workspace.commandSurface.diagnostics.forensics
+  const data = state.data as ForensicReport | null
+  const busy = state.phase === "loading"
+
+  return (
+    <div className="space-y-4" data-testid="diagnostics-forensics">
+      <DiagHeader
+        title="Forensic Analysis"
+        subtitle={data ? new Date(data.timestamp).toLocaleString() : null}
+        status={data ? (
+          <span className={cn(
+            "inline-block h-1.5 w-1.5 rounded-full",
+            data.anomalies.length > 0 ? "bg-warning" : "bg-success",
+          )} />
+        ) : null}
+        onRefresh={() => void loadForensicsDiagnostics()}
+        refreshing={busy}
+      />
+
+      {state.error && <DiagError message={state.error} />}
+      {busy && !data && <DiagLoading label="Running forensic analysis…" />}
+
+      {data && (
+        <>
+          {/* Metrics summary */}
+          {data.metrics && (
+            <div className="flex flex-wrap gap-2">
+              <StatPill label="Units" value={data.metrics.totalUnits} />
+              <StatPill label="Cost" value={formatCost(data.metrics.totalCost)} />
+              <StatPill label="Duration" value={`${Math.round(data.metrics.totalDuration / 1000)}s`} />
+              <StatPill label="Traces" value={data.unitTraceCount} />
+            </div>
+          )}
+
+          {/* Crash lock */}
+          {data.crashLock ? (
+            <div className="rounded-lg border border-destructive/20 bg-destructive/5 px-3 py-2.5 space-y-1">
+              <div className="flex items-center gap-2">
+                <ShieldAlert className="h-3.5 w-3.5 text-destructive" />
+                <span className="text-xs font-medium text-destructive">Crash Lock Active</span>
+              </div>
+              <div className="grid grid-cols-2 gap-x-4 gap-y-0.5 text-[11px]">
+                <span className="text-muted-foreground">PID</span>
+                <span className="font-mono text-foreground/80">{data.crashLock.pid}</span>
+                <span className="text-muted-foreground">Started</span>
+                <span className="text-foreground/80">{new Date(data.crashLock.startedAt).toLocaleString()}</span>
+                <span className="text-muted-foreground">Unit</span>
+                <span className="font-mono text-foreground/80">{data.crashLock.unitType}/{data.crashLock.unitId}</span>
+              </div>
+            </div>
+          ) : (
+            <div className="flex items-center gap-2 rounded-lg border border-border/50 bg-card/50 px-3 py-2 text-xs text-muted-foreground">
+              <CheckCircle2 className="h-3.5 w-3.5 text-success" />
+              No crash lock
+            </div>
+          )}
+
+          {/* Anomalies */}
+          {data.anomalies.length > 0 ? (
+            <div className="space-y-2">
+              <h4 className="text-xs font-medium text-muted-foreground">Anomalies ({data.anomalies.length})</h4>
+              {data.anomalies.map((a, i) => <AnomalyRow key={i} anomaly={a} />)}
+            </div>
+          ) : (
+            <DiagEmpty message="No anomalies detected" />
+          )}
+
+          {/* Recent units */}
+          {data.recentUnits.length > 0 && (
+            <div className="space-y-2">
+              <h4 className="text-xs font-medium text-muted-foreground">Recent Units ({data.recentUnits.length})</h4>
+              <div className="overflow-x-auto rounded-lg border border-border/50">
+                <table className="w-full text-[11px]">
+                  <thead>
+                    <tr className="border-b border-border/50 bg-card/50">
+                      <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Type</th>
+                      <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">ID</th>
+                      <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Model</th>
+                      <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Cost</th>
+                      <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Duration</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {data.recentUnits.map((u, i) => (
+                      <tr key={i} className="border-b border-border/50 last:border-0">
+                        <td className="px-2.5 py-1.5 font-mono text-foreground/80">{u.type}</td>
+                        <td className="px-2.5 py-1.5 font-mono text-foreground/80 truncate max-w-[120px]">{u.id}</td>
+                        <td className="px-2.5 py-1.5 text-muted-foreground">{u.model}</td>
+                        <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">{formatCost(u.cost)}</td>
+                        <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">{Math.round(u.duration / 1000)}s</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// DOCTOR PANEL
+// ═══════════════════════════════════════════════════════════════════════
+
+function humanizeCode(code: string): string {
+  return code.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+function IssueRow({ issue }: { issue: DoctorIssue }) {
+  return (
+    <div className="rounded-lg border border-border/50 bg-card/50 px-3 py-2.5 space-y-1">
+      <div className="flex items-center gap-2 flex-wrap">
+        <SeverityIcon severity={issue.severity} />
+        <Badge variant={severityBadgeVariant(issue.severity)} className="text-[10px] px-1.5 py-0">{issue.severity}</Badge>
+        <Badge variant="outline" className="text-[10px] px-1.5 py-0 font-mono">{humanizeCode(issue.code)}</Badge>
+        {issue.scope && <span className="text-[10px] text-muted-foreground font-mono">{issue.scope}</span>}
+        {issue.fixable && (
+          <Badge variant="outline" className="text-[10px] px-1.5 py-0 border-success/30 text-success">
+            <Wrench className="h-2.5 w-2.5 mr-0.5" />fixable
+          </Badge>
+        )}
+      </div>
+      <p className="text-xs text-foreground">{issue.message}</p>
+      {issue.file && <p className="text-[10px] font-mono text-muted-foreground truncate">{issue.file}</p>}
+    </div>
+  )
+}
+
+export function DoctorPanel() {
+  const workspace = useGSDWorkspaceState()
+  const { loadDoctorDiagnostics, applyDoctorFixes } = useGSDWorkspaceActions()
+  const state = workspace.commandSurface.diagnostics.doctor
+  const data = state.data as DoctorReport | null
+  const busy = state.phase === "loading"
+
+  const fixableCount = data?.summary.fixable ?? 0
+
+  return (
+    <div className="space-y-4" data-testid="diagnostics-doctor">
+      <DiagHeader
+        title="Doctor Health Check"
+        status={data ? (
+          <span className={cn(
+            "inline-block h-1.5 w-1.5 rounded-full",
+            data.ok ? "bg-success" : "bg-destructive",
+          )} />
+        ) : null}
+        onRefresh={() => void loadDoctorDiagnostics()}
+        refreshing={busy}
+      />
+
+      {state.error && <DiagError message={state.error} />}
+      {busy && !data && <DiagLoading label="Running health check…" />}
+
+      {data && (
+        <>
+          {/* Summary bar */}
+          <div className="flex flex-wrap gap-2">
+            <StatPill label="Total" value={data.summary.total} />
+            {data.summary.errors > 0 && <StatPill label="Errors" value={data.summary.errors} variant="error" />}
+            {data.summary.warnings > 0 && <StatPill label="Warnings" value={data.summary.warnings} variant="warning" />}
+            {data.summary.infos > 0 && <StatPill label="Info" value={data.summary.infos} variant="info" />}
+            {fixableCount > 0 && (
+              <StatPill label="Fixable" value={fixableCount} variant="info" />
+            )}
+          </div>
+
+          {/* Apply fixes button */}
+          {fixableCount > 0 && (
+            <div className="flex items-center gap-3">
+              <Button
+                type="button"
+                variant="default"
+                size="sm"
+                onClick={() => void applyDoctorFixes()}
+                disabled={state.fixPending}
+                className="h-7 gap-1.5 text-xs"
+                data-testid="doctor-apply-fixes"
+              >
+                {state.fixPending ? (
+                  <LoaderCircle className="h-3 w-3 animate-spin" />
+                ) : (
+                  <Wrench className="h-3 w-3" />
+                )}
+                Apply Fixes ({fixableCount})
+              </Button>
+              {state.lastFixError && (
+                <span className="text-[11px] text-destructive">{state.lastFixError}</span>
+              )}
+            </div>
+          )}
+
+          {/* Fix results */}
+          {state.lastFixResult && state.lastFixResult.fixesApplied.length > 0 && (
+            <div className="rounded-lg border border-success/20 bg-success/5 px-3 py-2.5 space-y-1">
+              <div className="flex items-center gap-2">
+                <CheckCircle2 className="h-3.5 w-3.5 text-success" />
+                <span className="text-xs font-medium text-success">Fixes Applied</span>
+              </div>
+              <ul className="space-y-0.5 pl-5">
+                {state.lastFixResult.fixesApplied.map((fix, i) => (
+                  <li key={i} className="text-[11px] text-foreground/80 list-disc">{fix}</li>
+                ))}
+              </ul>
+            </div>
+          )}
+
+          {/* Issue list */}
+          {data.issues.length > 0 ? (
+            <div className="space-y-2">
+              <h4 className="text-xs font-medium text-muted-foreground">Issues ({data.issues.length})</h4>
+              {data.issues.map((issue, i) => <IssueRow key={i} issue={issue} />)}
+            </div>
+          ) : (
+            <DiagEmpty message="No issues found — workspace is healthy" />
+          )}
+        </>
+      )}
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// SKILL HEALTH PANEL
+// ═══════════════════════════════════════════════════════════════════════
+
+function trendArrow(trend: "stable" | "rising" | "declining"): string {
+  if (trend === "rising") return "↑"
+  if (trend === "declining") return "↓"
+  return "→"
+}
+
+function trendColor(trend: "stable" | "rising" | "declining"): string {
+  if (trend === "rising") return "text-warning"
+  if (trend === "declining") return "text-destructive"
+  return "text-muted-foreground"
+}
+
+function SuggestionRow({ suggestion }: { suggestion: SkillHealSuggestion }) {
+  return (
+    <div className="rounded-lg border border-border/50 bg-card/50 px-3 py-2.5 space-y-1">
+      <div className="flex items-center gap-2 flex-wrap">
+        <SeverityIcon severity={suggestion.severity} />
+        <Badge variant={severityBadgeVariant(suggestion.severity)} className="text-[10px] px-1.5 py-0">{suggestion.severity}</Badge>
+        <span className="text-[11px] font-medium text-foreground/80">{suggestion.skillName}</span>
+        <Badge variant="outline" className="text-[10px] px-1.5 py-0 font-mono">{suggestion.trigger.replace(/_/g, " ")}</Badge>
+      </div>
+      <p className="text-xs text-foreground">{suggestion.message}</p>
+    </div>
+  )
+}
+
+export function SkillHealthPanel() {
+  const workspace = useGSDWorkspaceState()
+  const { loadSkillHealthDiagnostics } = useGSDWorkspaceActions()
+  const state = workspace.commandSurface.diagnostics.skillHealth
+  const data = state.data as SkillHealthReport | null
+  const busy = state.phase === "loading"
+
+  return (
+    <div className="space-y-4" data-testid="diagnostics-skill-health">
+      <DiagHeader
+        title="Skill Health"
+        subtitle={data ? new Date(data.generatedAt).toLocaleString() : null}
+        status={data ? (
+          <span className={cn(
+            "inline-block h-1.5 w-1.5 rounded-full",
+            data.decliningSkills.length > 0 ? "bg-warning" : "bg-success",
+          )} />
+        ) : null}
+        onRefresh={() => void loadSkillHealthDiagnostics()}
+        refreshing={busy}
+      />
+
+      {state.error && <DiagError message={state.error} />}
+      {busy && !data && <DiagLoading label="Analyzing skill health…" />}
+
+      {data && (
+        <>
+          {/* Stats bar */}
+          <div className="flex flex-wrap gap-2">
+            <StatPill label="Skills" value={data.skills.length} />
+            {data.staleSkills.length > 0 && <StatPill label="Stale" value={data.staleSkills.length} variant="warning" />}
+            {data.decliningSkills.length > 0 && <StatPill label="Declining" value={data.decliningSkills.length} variant="error" />}
+            <StatPill label="Total units" value={data.totalUnitsWithSkills} />
+          </div>
+
+          {/* Skill table */}
+          {data.skills.length > 0 && (
+            <div className="space-y-2">
+              <h4 className="text-xs font-medium text-muted-foreground">Skills ({data.skills.length})</h4>
+              <div className="overflow-x-auto rounded-lg border border-border/50">
+                <table className="w-full text-[11px]">
+                  <thead>
+                    <tr className="border-b border-border/50 bg-card/50">
+                      <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Skill</th>
+                      <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Uses</th>
+                      <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Success</th>
+                      <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Tokens</th>
+                      <th className="px-2.5 py-1.5 text-center font-medium text-muted-foreground">Trend</th>
+                      <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Stale</th>
+                      <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Cost</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {data.skills.map((skill) => (
+                      <tr key={skill.name} className={cn(
+                        "border-b border-border/50 last:border-0",
+                        skill.flagged && "bg-destructive/3",
+                      )}>
+                        <td className="px-2.5 py-1.5 font-mono text-foreground/80">
+                          <span className="flex items-center gap-1.5">
+                            {skill.name}
+                            {skill.flagged && <AlertTriangle className="h-3 w-3 text-warning shrink-0" />}
+                          </span>
+                        </td>
+                        <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">{skill.totalUses}</td>
+                        <td className={cn(
+                          "px-2.5 py-1.5 text-right tabular-nums",
+                          skill.successRate >= 0.9 ? "text-success" : skill.successRate >= 0.7 ? "text-warning" : "text-destructive",
+                        )}>
+                          {(skill.successRate * 100).toFixed(0)}%
+                        </td>
+                        <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">{Math.round(skill.avgTokens)}</td>
+                        <td className={cn("px-2.5 py-1.5 text-center", trendColor(skill.tokenTrend))}>
+                          {trendArrow(skill.tokenTrend)}
+                        </td>
+                        <td className={cn(
+                          "px-2.5 py-1.5 text-right tabular-nums",
+                          skill.staleDays > 30 ? "text-warning" : "text-foreground/80",
+                        )}>
+                          {skill.staleDays > 0 ? `${skill.staleDays}d` : "—"}
+                        </td>
+                        <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">{formatCost(skill.avgCost)}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            </div>
+          )}
+
+          {/* Stale skills */}
+          {data.staleSkills.length > 0 && (
+            <div className="space-y-1.5">
+              <h4 className="text-xs font-medium text-muted-foreground">Stale Skills</h4>
+              <div className="flex flex-wrap gap-1.5">
+                {data.staleSkills.map((name) => (
+                  <Badge key={name} variant="secondary" className="text-[10px] font-mono">{name}</Badge>
+                ))}
+              </div>
+            </div>
+          )}
+
+          {/* Declining skills */}
+          {data.decliningSkills.length > 0 && (
+            <div className="space-y-1.5">
+              <h4 className="text-xs font-medium text-muted-foreground">Declining Skills</h4>
+              <div className="flex flex-wrap gap-1.5">
+                {data.decliningSkills.map((name) => (
+                  <Badge key={name} variant="destructive" className="text-[10px] font-mono">{name}</Badge>
+                ))}
+              </div>
+            </div>
+          )}
+
+          {/* Suggestions */}
+          {data.suggestions.length > 0 && (
+            <div className="space-y-2">
+              <h4 className="text-xs font-medium text-muted-foreground">Suggestions ({data.suggestions.length})</h4>
+              {data.suggestions.map((s, i) => <SuggestionRow key={i} suggestion={s} />)}
+            </div>
+          )}
+
+          {data.skills.length === 0 && data.suggestions.length === 0 && (
+            <DiagEmpty message="No skill usage data available" />
+          )}
+        </>
+      )}
+    </div>
+  )
+}
diff --git a/web/components/sf/dual-terminal.tsx b/web/components/sf/dual-terminal.tsx
new file mode 100644
index 000000000..5b4ec7b3b
--- /dev/null
+++ b/web/components/sf/dual-terminal.tsx
@@ -0,0 +1,119 @@
+"use client"
+
+import { useState, useRef, useEffect } from "react"
+import { GripVertical, Loader2 } from "lucide-react"
+import { MainSessionTerminal } from "@/components/sf/main-session-terminal"
+import { ShellTerminal } from "@/components/sf/shell-terminal"
+import { useTerminalFontSize } from "@/lib/use-terminal-font-size"
+import { useGSDWorkspaceState } from "@/lib/sf-workspace-store"
+import { derivePendingWorkflowCommandLabel } from "@/lib/workflow-action-execution"
+
+export function DualTerminal() {
+  const [splitPosition, setSplitPosition] = useState(50)
+  const containerRef = useRef<HTMLDivElement>(null)
+  const rootRef = useRef<HTMLDivElement>(null)
+  const isDragging = useRef(false)
+  const [terminalFontSize] = useTerminalFontSize()
+  const workspace = useGSDWorkspaceState()
+  const projectCwd = workspace.boot?.project.cwd
+  const pendingCommandLabel = derivePendingWorkflowCommandLabel({
+    commandInFlight: workspace.commandInFlight,
+    terminalLines: workspace.terminalLines,
+  })
+
+  const handleMouseDown = () => {
+    isDragging.current = true
+  }
+
+  const handleMouseMove = (e: MouseEvent) => {
+    if (!isDragging.current || !containerRef.current) return
+    const rect = containerRef.current.getBoundingClientRect()
+    const x = e.clientX - rect.left
+    const percent = (x / rect.width) * 100
+    setSplitPosition(Math.max(20, Math.min(80, percent)))
+  }
+
+  const handleMouseUp = () => {
+    isDragging.current = false
+  }
+
+  useEffect(() => {
+    document.addEventListener("mousemove", handleMouseMove)
+    document.addEventListener("mouseup", handleMouseUp)
+    return () => {
+      document.removeEventListener("mousemove", handleMouseMove)
+      document.removeEventListener("mouseup", handleMouseUp)
+    }
+  }, [])
+
+  // Prevent browser default file-open on drag/drop anywhere in the dual terminal.
+  // Uses native DOM listeners so xterm's internal DOM can't swallow the events first.
+  useEffect(() => {
+    const el = rootRef.current
+    if (!el) return
+
+    const preventDragDefault = (e: DragEvent) => {
+      e.preventDefault()
+    }
+
+    // Capture phase ensures we fire before any child element can consume the event
+    el.addEventListener("dragover", preventDragDefault, true)
+    el.addEventListener("drop", preventDragDefault, true)
+    return () => {
+      el.removeEventListener("dragover", preventDragDefault, true)
+      el.removeEventListener("drop", preventDragDefault, true)
+    }
+  }, [])
+
+  return (
+    <div ref={rootRef} className="flex h-full flex-col">
+      {/* Header */}
+      <div className="flex items-center justify-between border-b border-border bg-card px-4 py-2">
+        <span className="font-medium">Power User Mode</span>
+        <div className="flex items-center gap-4 text-xs text-muted-foreground">
+          {pendingCommandLabel && (
+            <span
+              className="inline-flex items-center gap-1.5 rounded-full border border-primary/20 bg-primary/10 px-2.5 py-1 text-primary"
+              data-testid="power-mode-pending-command"
+              title={pendingCommandLabel}
+            >
+              <Loader2 className="h-3 w-3 animate-spin" />
+              Sending {pendingCommandLabel}
+            </span>
+          )}
+          <span>Left: Main Session TUI</span>
+          <span className="text-border">|</span>
+          <span>Right: Interactive GSD</span>
+        </div>
+      </div>
+
+      {/* Split terminals */}
+      <div ref={containerRef} className="flex flex-1 overflow-hidden">
+        {/* Left terminal - Main bridge native TUI */}
+        <div style={{ width: `${splitPosition}%` }} className="flex h-full min-w-0 flex-col overflow-hidden bg-terminal">
+          <MainSessionTerminal className="min-h-0 flex-1" fontSize={terminalFontSize} projectCwd={projectCwd} />
+        </div>
+
+        {/* Divider */}
+        <div
+          className="flex w-1 cursor-col-resize items-center justify-center bg-border hover:bg-muted-foreground/30 transition-colors"
+          onMouseDown={handleMouseDown}
+        >
+          <GripVertical className="h-4 w-4 text-muted-foreground" />
+        </div>
+
+        {/* Right terminal - Interactive GSD instance */}
+        <div style={{ width: `${100 - splitPosition}%` }} className="h-full min-w-0 overflow-hidden bg-terminal">
+          <ShellTerminal
+            className="h-full"
+            command="gsd"
+            sessionPrefix="gsd-interactive"
+            fontSize={terminalFontSize}
+            hideInitialGsdHeader
+            projectCwd={projectCwd}
+          />
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/web/components/sf/file-content-viewer.tsx b/web/components/sf/file-content-viewer.tsx
new file mode 100644
index 000000000..50a706e7d
--- /dev/null
+++ b/web/components/sf/file-content-viewer.tsx
@@ -0,0 +1,740 @@
+"use client"
+
+import { useEffect, useMemo, useRef, useState, useCallback } from "react"
+import { Loader2, Save, X } from "lucide-react"
+import { cn } from "@/lib/utils"
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs"
+import { CodeEditor } from "@/components/sf/code-editor"
+import { useEditorFontSize } from "@/lib/use-editor-font-size"
+import { useTheme } from "next-themes"
+
+/* ── Language detection ── */
+
+const EXT_TO_LANG: Record<string, string> = {
+  ts: "typescript",
+  tsx: "tsx",
+  js: "javascript",
+  jsx: "jsx",
+  mjs: "javascript",
+  cjs: "javascript",
+  json: "json",
+  jsonc: "jsonc",
+  md: "markdown",
+  mdx: "mdx",
+  css: "css",
+  scss: "scss",
+  less: "less",
+  html: "html",
+  htm: "html",
+  xml: "xml",
+  svg: "xml",
+  yaml: "yaml",
+  yml: "yaml",
+  toml: "toml",
+  sh: "bash",
+  bash: "bash",
+  zsh: "bash",
+  fish: "fish",
+  py: "python",
+  rb: "ruby",
+  rs: "rust",
+  go: "go",
+  java: "java",
+  kt: "kotlin",
+  swift: "swift",
+  c: "c",
+  cpp: "cpp",
+  h: "c",
+  hpp: "cpp",
+  cs: "csharp",
+  php: "php",
+  sql: "sql",
+  graphql: "graphql",
+  gql: "graphql",
+  dockerfile: "dockerfile",
+  makefile: "makefile",
+  lua: "lua",
+  vim: "viml",
+  r: "r",
+  tex: "latex",
+  diff: "diff",
+  ini: "ini",
+  conf: "ini",
+  env: "dotenv",
+}
+
+const SPECIAL_FILENAMES: Record<string, string> = {
+  Dockerfile: "dockerfile",
+  Makefile: "makefile",
+  Containerfile: "dockerfile",
+  Justfile: "makefile",
+  Rakefile: "ruby",
+  Gemfile: "ruby",
+  ".env": "dotenv",
+  ".env.local": "dotenv",
+  ".env.example": "dotenv",
+  ".eslintrc": "json",
+  ".prettierrc": "json",
+  "tsconfig.json": "jsonc",
+  "jsconfig.json": "jsonc",
+}
+
+function detectLanguage(filepath: string): string | null {
+  const filename = filepath.split("/").pop() ?? ""
+
+  // Check special filenames first
+  if (SPECIAL_FILENAMES[filename]) return SPECIAL_FILENAMES[filename]
+
+  const ext = filename.includes(".") ? filename.split(".").pop()?.toLowerCase() : null
+  if (ext && EXT_TO_LANG[ext]) return EXT_TO_LANG[ext]
+
+  return null
+}
+
+function isMarkdown(filepath: string): boolean {
+  const ext = filepath.split(".").pop()?.toLowerCase()
+  return ext === "md" || ext === "mdx"
+}
+
+/* ── Shiki singleton ── */
+
+type ShikiHighlighter = {
+  codeToHtml: (code: string, options: { lang: string; theme: string }) => string
+}
+
+let highlighterPromise: Promise<ShikiHighlighter> | null = null
+
+async function getHighlighter(): Promise<ShikiHighlighter> {
+  if (!highlighterPromise) {
+    highlighterPromise = import("shiki").then((mod) =>
+      mod.createHighlighter({
+        themes: ["github-dark-default", "github-light-default"],
+        langs: [
+          "typescript", "tsx", "javascript", "jsx",
+          "json", "jsonc", "markdown", "mdx",
+          "css", "scss", "less", "html", "xml",
+          "yaml", "toml", "bash", "python", "ruby",
+          "rust", "go", "java", "kotlin", "swift",
+          "c", "cpp", "csharp", "php", "sql",
+          "graphql", "dockerfile", "makefile", "lua",
+          "diff", "ini", "dotenv",
+        ],
+      }),
+    ).catch((err) => {
+      // Reset so the next call retries instead of returning a rejected promise forever
+      highlighterPromise = null
+      throw err
+    })
+  }
+  return highlighterPromise
+}
+
+/* ── Code viewer (syntax highlighted) ── */
+
+function CodeViewer({ content, filepath, shikiTheme = "github-dark-default" }: { content: string; filepath: string; shikiTheme?: string }) {
+  const [html, setHtml] = useState<string | null>(null)
+  const [ready, setReady] = useState(false)
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  const lang = detectLanguage(filepath)
+
+  useEffect(() => {
+    let cancelled = false
+
+    if (!lang) {
+      const readyTimer = window.setTimeout(() => {
+        setReady(true)
+      }, 0)
+      return () => window.clearTimeout(readyTimer)
+    }
+
+    getHighlighter().then((highlighter) => {
+      if (cancelled) return
+      try {
+        const highlighted = highlighter.codeToHtml(content, {
+          lang,
+          theme: shikiTheme,
+        })
+        setHtml(highlighted)
+      } catch {
+        // Language not loaded or unsupported — fall back to plain
+        setHtml(null)
+      }
+      setReady(true)
+    }).catch(() => {
+      if (!cancelled) setReady(true)
+    })
+
+    return () => { cancelled = true }
+  }, [content, lang, shikiTheme])
+
+  if (!ready) {
+    return (
+      <div className="flex items-center justify-center py-12 text-muted-foreground">
+        <Loader2 className="h-4 w-4 animate-spin mr-2" />
+        Highlighting…
+      </div>
+    )
+  }
+
+  if (html) {
+    return (
+      <div
+        ref={containerRef}
+        className="file-viewer-code overflow-x-auto text-sm leading-relaxed"
+        dangerouslySetInnerHTML={{ __html: html }}
+      />
+    )
+  }
+
+  // Fallback: plain text with line numbers
+  return <PlainViewer content={content} />
+}
+
+/* ── Plain text viewer with line numbers ── */
+
+function PlainViewer({ content }: { content: string }) {
+  const lines = useMemo(() => content.split("\n"), [content])
+  const gutterWidth = String(lines.length).length
+
+  return (
+    <div className="overflow-x-auto text-sm leading-relaxed font-mono">
+      <table className="border-collapse">
+        <tbody>
+          {lines.map((line, i) => (
+            <tr key={i} className="hover:bg-accent/20">
+              <td
+                className="select-none pr-4 text-right text-muted-foreground align-top"
+                style={{ minWidth: `${gutterWidth + 1}ch` }}
+              >
+                {i + 1}
+              </td>
+              <td className="whitespace-pre text-muted-foreground">{line || " "}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}
+
+/* ── Markdown viewer ── */
+
+function MarkdownViewer({ content, filepath, shikiTheme = "github-dark-default" }: { content: string; filepath: string; shikiTheme?: string }) {
+  const [rendered, setRendered] = useState<React.ReactNode | null>(null)
+  const [ready, setReady] = useState(false)
+
+  useEffect(() => {
+    let cancelled = false
+
+    // Dynamic import to keep the main bundle lean
+    Promise.all([
+      import("react-markdown"),
+      import("remark-gfm"),
+      getHighlighter(),
+    ]).then(([ReactMarkdownMod, remarkGfmMod, highlighter]) => {
+      if (cancelled) return
+
+      const ReactMarkdown = ReactMarkdownMod.default
+      const remarkGfm = remarkGfmMod.default
+
+      setRendered(
+        <ReactMarkdown
+          remarkPlugins={[remarkGfm]}
+          components={{
+            code({ className, children, ...props }) {
+              const match = /language-(\w+)/.exec(className || "")
+              const codeStr = String(children).replace(/\n$/, "")
+
+              if (match) {
+                try {
+                  const highlighted = highlighter.codeToHtml(codeStr, {
+                    lang: match[1],
+                    theme: shikiTheme,
+                  })
+                  return (
+                    <div
+                      className="file-viewer-code my-3 rounded-md overflow-x-auto text-sm"
+                      dangerouslySetInnerHTML={{ __html: highlighted }}
+                    />
+                  )
+                } catch {
+                  // Fall through to default rendering
+                }
+              }
+
+              // Inline code or unknown language
+              const isInline = !className && !String(children).includes("\n")
+              if (isInline) {
+                return (
+                  <code className="rounded bg-muted px-1.5 py-0.5 text-sm font-mono" {...props}>
+                    {children}
+                  </code>
+                )
+              }
+
+              return (
+                <pre className="my-3 overflow-x-auto rounded-md bg-[#0d1117] p-4 text-sm">
+                  <code>{children}</code>
+                </pre>
+              )
+            },
+            pre({ children }) {
+              // Unwrap <pre> since code blocks handle their own wrapper
+              return <>{children}</>
+            },
+            table({ children }) {
+              return (
+                <div className="my-4 overflow-x-auto">
+                  <table className="min-w-full border-collapse border border-border text-sm">
+                    {children}
+                  </table>
+                </div>
+              )
+            },
+            th({ children }) {
+              return (
+                <th className="border border-border bg-muted/50 px-3 py-2 text-left font-medium">
+                  {children}
+                </th>
+              )
+            },
+            td({ children }) {
+              return (
+                <td className="border border-border px-3 py-2">{children}</td>
+              )
+            },
+            a({ href, children }) {
+              return (
+                <a href={href} className="text-info hover:underline" target="_blank" rel="noopener noreferrer">
+                  {children}
+                </a>
+              )
+            },
+            img({ src, alt }) {
+              return (
+                <span className="my-2 block rounded border border-border bg-muted/50 px-3 py-2 text-xs text-muted-foreground italic">
+                  🖼 {alt || (typeof src === "string" ? src : "") || "image"}
+                </span>
+              )
+            },
+          }}
+        >
+          {content}
+        </ReactMarkdown>,
+      )
+      setReady(true)
+    }).catch(() => {
+      if (!cancelled) setReady(true)
+    })
+
+    return () => { cancelled = true }
+  }, [content, filepath, shikiTheme])
+
+  if (!ready) {
+    return (
+      <div className="flex items-center justify-center py-12 text-muted-foreground">
+        <Loader2 className="h-4 w-4 animate-spin mr-2" />
+        Rendering…
+      </div>
+    )
+  }
+
+  if (!rendered) {
+    return <PlainViewer content={content} />
+  }
+
+  return <div className="markdown-body">{rendered}</div>
+}
+
+/* ── Inline diff viewer — shows before/after with red/green line highlights ── */
+
+function computeDiffLines(before: string, after: string): Array<{ type: "add" | "remove" | "context"; lineNum: number | null; text: string }> {
+  const oldLines = before.split("\n")
+  const newLines = after.split("\n")
+  const result: Array<{ type: "add" | "remove" | "context"; lineNum: number | null; text: string }> = []
+
+  // Simple LCS-based diff for inline display
+  const n = oldLines.length
+  const m = newLines.length
+
+  // For files that are too large, fall back to showing just additions/removals
+  if (n + m > 5000) {
+    oldLines.forEach((l, i) => result.push({ type: "remove", lineNum: i + 1, text: l }))
+    newLines.forEach((l, i) => result.push({ type: "add", lineNum: i + 1, text: l }))
+    return result
+  }
+
+  // Build edit script using O(ND) algorithm (simplified Myers)
+  const max = n + m
+  const v = new Int32Array(2 * max + 1)
+  const trace: Int32Array[] = []
+
+  outer:
+  for (let d = 0; d <= max; d++) {
+    const vCopy = new Int32Array(v)
+    trace.push(vCopy)
+    for (let k = -d; k <= d; k += 2) {
+      let x: number
+      if (k === -d || (k !== d && v[k - 1 + max] < v[k + 1 + max])) {
+        x = v[k + 1 + max]
+      } else {
+        x = v[k - 1 + max] + 1
+      }
+      let y = x - k
+      while (x < n && y < m && oldLines[x] === newLines[y]) {
+        x++
+        y++
+      }
+      v[k + max] = x
+      if (x >= n && y >= m) break outer
+    }
+  }
+
+  // Backtrack to produce diff
+  type Edit = { type: "add" | "remove" | "context"; oldIdx: number; newIdx: number }
+  const edits: Edit[] = []
+  let x = n, y = m
+  for (let d = trace.length - 1; d >= 0; d--) {
+    const vPrev = trace[d]
+    const k = x - y
+    let prevK: number
+    if (k === -d || (k !== d && vPrev[k - 1 + max] < vPrev[k + 1 + max])) {
+      prevK = k + 1
+    } else {
+      prevK = k - 1
+    }
+    const prevX = vPrev[prevK + max]
+    const prevY = prevX - prevK
+
+    // Diag moves = context lines
+    while (x > prevX && y > prevY) {
+      x--; y--
+      edits.push({ type: "context", oldIdx: x, newIdx: y })
+    }
+    if (d > 0) {
+      if (x === prevX) {
+        // Insert
+        y--
+        edits.push({ type: "add", oldIdx: x, newIdx: y })
+      } else {
+        // Delete
+        x--
+        edits.push({ type: "remove", oldIdx: x, newIdx: y })
+      }
+    }
+  }
+
+  edits.reverse()
+
+  // Convert to output lines, showing only changed regions with ±3 lines of context
+  const CONTEXT = 3
+  const important = new Set<number>()
+  edits.forEach((e, i) => {
+    if (e.type !== "context") {
+      for (let j = Math.max(0, i - CONTEXT); j <= Math.min(edits.length - 1, i + CONTEXT); j++) {
+        important.add(j)
+      }
+    }
+  })
+
+  let lastIncluded = -1
+  for (let i = 0; i < edits.length; i++) {
+    if (!important.has(i)) continue
+    if (lastIncluded >= 0 && i - lastIncluded > 1) {
+      result.push({ type: "context", lineNum: null, text: "···" })
+    }
+    const e = edits[i]
+    if (e.type === "context") {
+      result.push({ type: "context", lineNum: e.newIdx + 1, text: newLines[e.newIdx] })
+    } else if (e.type === "remove") {
+      result.push({ type: "remove", lineNum: e.oldIdx + 1, text: oldLines[e.oldIdx] })
+    } else {
+      result.push({ type: "add", lineNum: e.newIdx + 1, text: newLines[e.newIdx] })
+    }
+    lastIncluded = i
+  }
+
+  return result
+}
+
+function InlineDiffViewer({ before, after, onDismiss }: { before: string; after: string; onDismiss?: () => void }) {
+  const lines = useMemo(() => computeDiffLines(before, after), [before, after])
+
+  return (
+    <div className="flex-1 overflow-y-auto font-mono text-sm leading-relaxed">
+      <table className="w-full border-collapse">
+        <tbody>
+          {lines.map((line, i) => (
+            <tr
+              key={i}
+              className={cn(
+                line.type === "add" && "bg-emerald-500/10",
+                line.type === "remove" && "bg-red-500/10",
+              )}
+            >
+              <td className="select-none w-[1ch] pl-2 pr-1 text-center align-top">
+                {line.type === "add" ? (
+                  <span className="text-emerald-400/80">+</span>
+                ) : line.type === "remove" ? (
+                  <span className="text-red-400/80">−</span>
+                ) : null}
+              </td>
+              <td
+                className={cn(
+                  "select-none pr-3 text-right align-top min-w-[3ch]",
+                  line.type === "add" ? "text-emerald-400/40" :
+                  line.type === "remove" ? "text-red-400/40" :
+                  "text-muted-foreground/50",
+                )}
+              >
+                {line.lineNum ?? ""}
+              </td>
+              <td
+                className={cn(
+                  "whitespace-pre pr-4",
+                  line.type === "add" && "text-emerald-300",
+                  line.type === "remove" && "text-red-300 line-through decoration-red-400/30",
+                  line.type === "context" && line.text === "···" && "text-muted-foreground/50 text-center italic",
+                  line.type === "context" && line.text !== "···" && "text-muted-foreground",
+                )}
+              >
+                {line.text || " "}
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}
+
+/* ── Read-only content renderer (shared between standalone and tab modes) ── */
+
+function ReadOnlyContent({ content, filepath, fontSize, shikiTheme }: { content: string; filepath: string; fontSize?: number; shikiTheme?: string }) {
+  return (
+    <div style={fontSize ? { fontSize } : undefined}>
+      {isMarkdown(filepath) ? (
+        <MarkdownViewer content={content} filepath={filepath} shikiTheme={shikiTheme} />
+      ) : (
+        <CodeViewer content={content} filepath={filepath} shikiTheme={shikiTheme} />
+      )}
+    </div>
+  )
+}
+
+/* ── Exported component ── */
+
+interface FileContentViewerProps {
+  content: string
+  filepath: string
+  className?: string
+  /** Required for editing — the root context for the file */
+  root?: "gsd" | "project"
+  /** Required for editing — the relative path within the root */
+  path?: string
+  /** Required for editing — called with new content when the user saves */
+  onSave?: (newContent: string) => Promise<void>
+  /** When set, shows an inline diff overlay (before/after content) */
+  diff?: { before: string; after: string }
+  /** Called to dismiss the diff overlay */
+  onDismissDiff?: () => void
+  /** When true, MD files default to Edit tab so the raw changes are visible */
+  agentOpened?: boolean
+}
+
+export function FileContentViewer({
+  content,
+  filepath,
+  className,
+  root,
+  path,
+  onSave,
+  diff,
+  onDismissDiff,
+  agentOpened,
+}: FileContentViewerProps) {
+  const canEdit = root !== undefined && path !== undefined && onSave !== undefined
+
+  // ── Dirty state tracking ──
+  const [editContent, setEditContent] = useState(content)
+  const [isSaving, setIsSaving] = useState(false)
+  const [saveError, setSaveError] = useState<string | null>(null)
+
+  // Reset edit content when the source content changes (e.g. after save + re-fetch)
+  useEffect(() => {
+    setEditContent(content)
+  }, [content])
+
+  const isDirty = editContent !== content
+
+  const [fontSize] = useEditorFontSize()
+  const { resolvedTheme } = useTheme()
+  const shikiTheme = resolvedTheme === "light" ? "github-light-default" : "github-dark-default"
+  const language = detectLanguage(filepath)
+
+  const handleSave = useCallback(async () => {
+    if (!onSave || !isDirty || isSaving) return
+    setIsSaving(true)
+    setSaveError(null)
+    try {
+      await onSave(editContent)
+    } catch (err) {
+      setSaveError(err instanceof Error ? err.message : "Failed to save")
+    } finally {
+      setIsSaving(false)
+    }
+  }, [onSave, isDirty, isSaving, editContent])
+
+  // ── Ctrl+S / Cmd+S keyboard shortcut ──
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === "s") {
+        e.preventDefault()
+        handleSave()
+      }
+    }
+    document.addEventListener("keydown", handler)
+    return () => document.removeEventListener("keydown", handler)
+  }, [handleSave])
+
+  // ── Read-only mode (backward compatible) ──
+  if (!canEdit) {
+    return (
+      <div className={cn("flex-1 overflow-y-auto p-4", className)} style={{ fontSize }}>
+        <ReadOnlyContent content={content} filepath={filepath} fontSize={fontSize} shikiTheme={shikiTheme} />
+      </div>
+    )
+  }
+
+  // ── Diff overlay mode: agent just edited this file ──
+  if (diff) {
+    return (
+      <div className={cn("flex flex-1 flex-col overflow-hidden min-h-0", className)}>
+        <div className="flex items-center gap-2 border-b border-border px-4 h-9">
+          <span className="text-sm font-medium font-mono truncate">{filepath}</span>
+          <span className="ml-2 rounded-full bg-emerald-500/15 px-2 py-0.5 text-[10px] font-medium text-emerald-400 uppercase tracking-wide">
+            Changed
+          </span>
+          <div className="ml-auto flex items-center gap-2">
+            <button
+              onClick={onDismissDiff}
+              className="inline-flex items-center gap-1 rounded-md px-2 py-1 text-xs font-medium text-muted-foreground hover:text-foreground hover:bg-accent transition-colors"
+            >
+              <X className="h-3 w-3" />
+              Dismiss
+            </button>
+          </div>
+        </div>
+        <InlineDiffViewer before={diff.before} after={diff.after} onDismiss={onDismissDiff} />
+      </div>
+    )
+  }
+
+  // ── Editable mode: markdown keeps View/Edit tabs ──
+  if (isMarkdown(filepath)) {
+    return (
+      <Tabs key={agentOpened ? "agent-edit" : "normal"} defaultValue={agentOpened ? "edit" : "view"} className={cn("flex flex-1 flex-col overflow-hidden min-h-0", className)}>
+        <div className="flex items-center gap-2 border-b border-border px-4 h-9">
+          <span className="text-sm font-medium font-mono truncate mr-2">{filepath}</span>
+          <TabsList className="h-7 bg-transparent p-0 ml-auto">
+            <TabsTrigger
+              value="view"
+              className="h-6 rounded-md px-2 text-xs data-[state=active]:bg-muted"
+            >
+              View
+            </TabsTrigger>
+            <TabsTrigger
+              value="edit"
+              className="h-6 rounded-md px-2 text-xs data-[state=active]:bg-muted"
+            >
+              Edit
+            </TabsTrigger>
+          </TabsList>
+
+          {/* Save button */}
+          <div className="flex items-center gap-2">
+            {saveError && (
+              <span className="text-xs text-destructive max-w-[200px] truncate" title={saveError}>
+                {saveError}
+              </span>
+            )}
+            <button
+              onClick={handleSave}
+              disabled={!isDirty || isSaving}
+              className={cn(
+                "inline-flex items-center gap-1.5 rounded-md px-2.5 py-1 text-xs font-medium transition-colors",
+                isDirty && !isSaving
+                  ? "bg-foreground text-background hover:bg-foreground/90"
+                  : "bg-muted text-muted-foreground cursor-not-allowed opacity-50",
+              )}
+            >
+              {isSaving ? (
+                <Loader2 className="h-3 w-3 animate-spin" />
+              ) : (
+                <Save className="h-3 w-3" />
+              )}
+              Save
+            </button>
+          </div>
+        </div>
+
+        <TabsContent value="view" className="flex-1 overflow-y-auto p-4 mt-0" style={{ fontSize }}>
+          <ReadOnlyContent content={content} filepath={filepath} fontSize={fontSize} shikiTheme={shikiTheme} />
+        </TabsContent>
+
+        <TabsContent value="edit" className="flex-1 overflow-hidden mt-0 min-h-0">
+          <CodeEditor
+            value={editContent}
+            onChange={setEditContent}
+            language={language}
+            fontSize={fontSize}
+            className="h-full border-0 rounded-none"
+          />
+        </TabsContent>
+      </Tabs>
+    )
+  }
+
+  // ── Editable mode: non-markdown gets single CodeEditor view ──
+  return (
+    <div className={cn("flex flex-1 flex-col overflow-hidden min-h-0", className)}>
+      {/* Header bar with filepath and save button */}
+      <div className="flex items-center gap-2 border-b border-border px-4 h-9">
+        <span className="text-sm font-medium font-mono truncate">{filepath}</span>
+        <div className="ml-auto flex items-center gap-2">
+          {saveError && (
+            <span className="text-xs text-destructive max-w-[200px] truncate" title={saveError}>
+              {saveError}
+            </span>
+          )}
+          <button
+            onClick={handleSave}
+            disabled={!isDirty || isSaving}
+            className={cn(
+              "inline-flex items-center gap-1.5 rounded-md px-2.5 py-1 text-xs font-medium transition-colors",
+              isDirty && !isSaving
+                ? "bg-foreground text-background hover:bg-foreground/90"
+                : "bg-muted text-muted-foreground cursor-not-allowed opacity-50",
+            )}
+          >
+            {isSaving ? (
+              <Loader2 className="h-3 w-3 animate-spin" />
+            ) : (
+              <Save className="h-3 w-3" />
+            )}
+            Save
+          </button>
+        </div>
+      </div>
+      {/* CodeEditor fills remaining space */}
+      <CodeEditor
+        value={editContent}
+        onChange={setEditContent}
+        language={language}
+        fontSize={fontSize}
+        className="flex-1 min-h-0 border-0 rounded-none"
+      />
+    </div>
+  )
+}
diff --git a/web/components/sf/files-view.tsx b/web/components/sf/files-view.tsx
new file mode 100644
index 000000000..8604d2367
--- /dev/null
+++ b/web/components/sf/files-view.tsx
@@ -0,0 +1,1400 @@
+"use client"
+
+import { useState, useEffect, useCallback, useRef, useMemo } from "react"
+import {
+  FileText,
+  ChevronRight,
+  ChevronDown,
+  Folder,
+  FolderOpen,
+  FileCode,
+  File,
+  Loader2,
+  AlertCircle,
+  X,
+  FilePlus,
+  FolderPlus,
+  Pencil,
+  Trash2,
+  Copy,
+  ClipboardCopy,
+  Bot,
+} from "lucide-react"
+import { cn } from "@/lib/utils"
+import { useGSDWorkspaceState, buildProjectUrl } from "@/lib/sf-workspace-store"
+import { authFetch } from "@/lib/auth"
+import { FileContentViewer } from "@/components/sf/file-content-viewer"
+import { ChatPane } from "@/components/sf/chat-mode"
+
+type RootMode = "gsd" | "project"
+
+// Global pending file request — survives across component mount/unmount cycles.
+// Set by the custom event, consumed by FilesView on mount or when already mounted.
+let pendingFileRequest: { root: RootMode; path: string } | null = null
+
+// Set up the global event listener once (module-level, not component-level)
+if (typeof window !== "undefined") {
+  window.addEventListener("gsd:open-file", (e: Event) => {
+    const detail = (e as CustomEvent<{ root: RootMode; path: string }>).detail
+    if (detail?.root && detail?.path) {
+      pendingFileRequest = { root: detail.root, path: detail.path }
+    }
+  })
+}
+
+interface FileNode {
+  name: string
+  type: "file" | "directory"
+  children?: FileNode[]
+}
+
+/* ── Persistence helpers ── */
+
+function storageKey(projectCwd: string, root: RootMode): string {
+  return `gsd-files-expanded:${root}:${projectCwd}`
+}
+
+function loadExpanded(projectCwd: string | undefined, root: RootMode): Set<string> {
+  if (!projectCwd) return new Set()
+  try {
+    const raw = sessionStorage.getItem(storageKey(projectCwd, root))
+    if (raw) return new Set(JSON.parse(raw) as string[])
+  } catch { /* ignore */ }
+  return new Set()
+}
+
+function saveExpanded(projectCwd: string | undefined, root: RootMode, expanded: Set<string>): void {
+  if (!projectCwd) return
+  try {
+    sessionStorage.setItem(storageKey(projectCwd, root), JSON.stringify([...expanded]))
+  } catch { /* ignore */ }
+}
+
+/* ── Icons ── */
+
+function FileIcon({ name, isFolder, isOpen }: { name: string; isFolder: boolean; isOpen?: boolean }) {
+  if (isFolder) {
+    return isOpen ? (
+      <FolderOpen className="h-4 w-4 text-muted-foreground" />
+    ) : (
+      <Folder className="h-4 w-4 text-muted-foreground" />
+    )
+  }
+  if (name.endsWith(".md")) {
+    return <FileText className="h-4 w-4 text-muted-foreground" />
+  }
+  if (name.endsWith(".json") || name.endsWith(".ts") || name.endsWith(".tsx") || name.endsWith(".js") || name.endsWith(".jsx")) {
+    return <FileCode className="h-4 w-4 text-muted-foreground" />
+  }
+  return <File className="h-4 w-4 text-muted-foreground" />
+}
+
+/* ── Context menu ── */
+
+interface ContextMenuState {
+  x: number
+  y: number
+  path: string
+  type: "file" | "directory"
+  /** parent directory path (empty string = root) */
+  parentPath: string
+}
+
+interface ContextMenuProps {
+  menu: ContextMenuState
+  onClose: () => void
+  onNewFile: (parentDir: string) => void
+  onNewFolder: (parentDir: string) => void
+  onRename: (path: string) => void
+  onDelete: (path: string, type: "file" | "directory") => void
+  onCopyPath: (path: string) => void
+  onDuplicate: (path: string) => void
+}
+
+function TreeContextMenu({ menu, onClose, onNewFile, onNewFolder, onRename, onDelete, onCopyPath, onDuplicate }: ContextMenuProps) {
+  const menuRef = useRef<HTMLDivElement>(null)
+
+  // Close on click outside or escape
+  useEffect(() => {
+    const handleClick = (e: MouseEvent) => {
+      if (menuRef.current && !menuRef.current.contains(e.target as Node)) {
+        onClose()
+      }
+    }
+    const handleKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose()
+    }
+    document.addEventListener("mousedown", handleClick)
+    document.addEventListener("keydown", handleKey)
+    return () => {
+      document.removeEventListener("mousedown", handleClick)
+      document.removeEventListener("keydown", handleKey)
+    }
+  }, [onClose])
+
+  // Keep menu within viewport
+  const [pos, setPos] = useState({ x: menu.x, y: menu.y })
+  useEffect(() => {
+    if (!menuRef.current) return
+    const rect = menuRef.current.getBoundingClientRect()
+    let { x, y } = menu
+    if (x + rect.width > window.innerWidth) x = window.innerWidth - rect.width - 8
+    if (y + rect.height > window.innerHeight) y = window.innerHeight - rect.height - 8
+    if (x < 0) x = 8
+    if (y < 0) y = 8
+    setPos({ x, y })
+  }, [menu])
+
+  const parentDir = menu.type === "directory" ? menu.path : menu.parentPath
+
+  const items: { label: string; icon: React.ReactNode; action: () => void; destructive?: boolean; separator?: boolean }[] = [
+    {
+      label: "New File",
+      icon: <FilePlus className="h-3.5 w-3.5" />,
+      action: () => { onNewFile(parentDir); onClose() },
+    },
+    {
+      label: "New Folder",
+      icon: <FolderPlus className="h-3.5 w-3.5" />,
+      action: () => { onNewFolder(parentDir); onClose() },
+    },
+    {
+      label: "Rename",
+      icon: <Pencil className="h-3.5 w-3.5" />,
+      action: () => { onRename(menu.path); onClose() },
+      separator: true,
+    },
+    {
+      label: "Duplicate",
+      icon: <Copy className="h-3.5 w-3.5" />,
+      action: () => { onDuplicate(menu.path); onClose() },
+    },
+    {
+      label: "Copy Path",
+      icon: <ClipboardCopy className="h-3.5 w-3.5" />,
+      action: () => { onCopyPath(menu.path); onClose() },
+      separator: true,
+    },
+    {
+      label: "Delete",
+      icon: <Trash2 className="h-3.5 w-3.5" />,
+      action: () => { onDelete(menu.path, menu.type); onClose() },
+      destructive: true,
+    },
+  ]
+
+  return (
+    <div
+      ref={menuRef}
+      className="fixed z-50 min-w-[160px] rounded-md border border-border bg-popover py-1 shadow-lg animate-in fade-in-0 zoom-in-95"
+      style={{ left: pos.x, top: pos.y }}
+    >
+      {items.map((item, i) => (
+        <div key={i}>
+          {item.separator && i > 0 && <div className="my-1 h-px bg-border" />}
+          <button
+            onClick={item.action}
+            className={cn(
+              "flex w-full items-center gap-2 px-3 py-1.5 text-xs transition-colors",
+              item.destructive
+                ? "text-destructive hover:bg-destructive/10"
+                : "text-popover-foreground hover:bg-accent",
+            )}
+          >
+            {item.icon}
+            {item.label}
+          </button>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+/* ── Inline input (for rename / new file / new folder) ── */
+
+function InlineInput({
+  defaultValue,
+  onCommit,
+  onCancel,
+  depth,
+  icon,
+}: {
+  defaultValue: string
+  onCommit: (value: string) => void
+  onCancel: () => void
+  depth: number
+  icon: React.ReactNode
+}) {
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  useEffect(() => {
+    // Focus and select just the filename (not extension) on mount
+    const input = inputRef.current
+    if (!input) return
+    input.focus()
+    const dotIndex = defaultValue.lastIndexOf(".")
+    if (dotIndex > 0) {
+      input.setSelectionRange(0, dotIndex)
+    } else {
+      input.select()
+    }
+  }, [defaultValue])
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === "Enter") {
+      e.preventDefault()
+      const val = inputRef.current?.value.trim()
+      if (val && val.length > 0) onCommit(val)
+      else onCancel()
+    }
+    if (e.key === "Escape") {
+      e.preventDefault()
+      onCancel()
+    }
+  }
+
+  return (
+    <div
+      className="flex items-center gap-1.5 px-2 py-0.5"
+      style={{ paddingLeft: `${depth * 12 + 8}px` }}
+    >
+      {icon}
+      <input
+        ref={inputRef}
+        defaultValue={defaultValue}
+        onKeyDown={handleKeyDown}
+        onBlur={() => {
+          const val = inputRef.current?.value.trim()
+          if (val && val.length > 0) onCommit(val)
+          else onCancel()
+        }}
+        className="flex-1 bg-transparent text-sm outline-none border border-ring rounded px-1 py-0.5 text-foreground"
+        spellCheck={false}
+      />
+    </div>
+  )
+}
+
+/* ── Tree item ── */
+
+interface FileTreeItemProps {
+  node: FileNode
+  depth: number
+  parentPath: string
+  selectedPath: string | null
+  expandedPaths: Set<string>
+  renamingPath: string | null
+  creatingIn: { parentDir: string; type: "file" | "directory" } | null
+  onToggleDir: (path: string) => void
+  onSelectFile: (path: string) => void
+  onMoveFile: (fromPath: string, toDir: string) => void
+  onContextMenu: (e: React.MouseEvent, path: string, type: "file" | "directory", parentPath: string) => void
+  onRenameCommit: (oldPath: string, newName: string) => void
+  onRenameCancel: () => void
+  onCreateCommit: (parentDir: string, name: string, type: "file" | "directory") => void
+  onCreateCancel: () => void
+}
+
+function FileTreeItem({
+  node, depth, parentPath, selectedPath, expandedPaths,
+  renamingPath, creatingIn,
+  onToggleDir, onSelectFile, onMoveFile,
+  onContextMenu, onRenameCommit, onRenameCancel,
+  onCreateCommit, onCreateCancel,
+}: FileTreeItemProps) {
+  const fullPath = parentPath ? `${parentPath}/${node.name}` : node.name
+  const isOpen = node.type === "directory" && expandedPaths.has(fullPath)
+  const [dragOver, setDragOver] = useState(false)
+  const isRenaming = renamingPath === fullPath
+
+  // Should we show the "create new" input inside this directory?
+  const showCreateInput = creatingIn && creatingIn.parentDir === fullPath && node.type === "directory" && isOpen
+
+  const handleClick = () => {
+    if (node.type === "directory") {
+      onToggleDir(fullPath)
+    } else {
+      onSelectFile(fullPath)
+    }
+  }
+
+  const handleContextMenu = (e: React.MouseEvent) => {
+    e.preventDefault()
+    e.stopPropagation()
+    onContextMenu(e, fullPath, node.type, parentPath)
+  }
+
+  // ── Drag source ──
+  const handleDragStart = (e: React.DragEvent) => {
+    e.dataTransfer.setData("text/x-tree-path", fullPath)
+    e.dataTransfer.effectAllowed = "move"
+  }
+
+  // ── Drop target (directories only) ──
+  const handleDragOver = (e: React.DragEvent) => {
+    if (node.type !== "directory") return
+    const srcPath = e.dataTransfer.types.includes("text/x-tree-path") ? "pending" : null
+    if (!srcPath) return
+    e.preventDefault()
+    e.dataTransfer.dropEffect = "move"
+    setDragOver(true)
+  }
+
+  const handleDragLeave = () => {
+    setDragOver(false)
+  }
+
+  const handleDrop = (e: React.DragEvent) => {
+    setDragOver(false)
+    if (node.type !== "directory") return
+    e.preventDefault()
+    const srcPath = e.dataTransfer.getData("text/x-tree-path")
+    if (!srcPath || srcPath === fullPath) return
+    if (fullPath.startsWith(srcPath + "/")) return
+    const srcParent = srcPath.includes("/") ? srcPath.substring(0, srcPath.lastIndexOf("/")) : ""
+    if (srcParent === fullPath) return
+    onMoveFile(srcPath, fullPath)
+  }
+
+  // Inline rename mode
+  if (isRenaming) {
+    return (
+      <div data-tree-item>
+        <InlineInput
+          defaultValue={node.name}
+          onCommit={(newName) => onRenameCommit(fullPath, newName)}
+          onCancel={onRenameCancel}
+          depth={depth}
+          icon={<FileIcon name={node.name} isFolder={node.type === "directory"} isOpen={isOpen} />}
+        />
+      </div>
+    )
+  }
+
+  return (
+    <div data-tree-item>
+      <button
+        onClick={handleClick}
+        onContextMenu={handleContextMenu}
+        draggable
+        onDragStart={handleDragStart}
+        onDragOver={handleDragOver}
+        onDragLeave={handleDragLeave}
+        onDrop={handleDrop}
+        className={cn(
+          "flex w-full items-center gap-1.5 px-2 py-1 text-sm hover:bg-accent/50 transition-colors",
+          selectedPath === fullPath && node.type === "file" && "bg-accent",
+          dragOver && "bg-accent/70 outline outline-1 outline-ring",
+        )}
+        style={{ paddingLeft: `${depth * 12 + 8}px` }}
+      >
+        {node.type === "directory" && (
+          isOpen ? (
+            <ChevronDown className="h-3 w-3 text-muted-foreground" />
+          ) : (
+            <ChevronRight className="h-3 w-3 text-muted-foreground" />
+          )
+        )}
+        <FileIcon name={node.name} isFolder={node.type === "directory"} isOpen={isOpen} />
+        <span className="truncate">{node.name}</span>
+      </button>
+      {isOpen && node.children && (
+        <div>
+          {/* Create new item input at the top of the directory */}
+          {showCreateInput && (
+            <InlineInput
+              defaultValue={creatingIn!.type === "directory" ? "new-folder" : "new-file"}
+              onCommit={(name) => onCreateCommit(fullPath, name, creatingIn!.type)}
+              onCancel={onCreateCancel}
+              depth={depth + 1}
+              icon={creatingIn!.type === "directory"
+                ? <Folder className="h-4 w-4 text-muted-foreground" />
+                : <File className="h-4 w-4 text-muted-foreground" />
+              }
+            />
+          )}
+          {node.children.map((child, i) => (
+            <FileTreeItem
+              key={i}
+              node={child}
+              depth={depth + 1}
+              parentPath={fullPath}
+              selectedPath={selectedPath}
+              expandedPaths={expandedPaths}
+              renamingPath={renamingPath}
+              creatingIn={creatingIn}
+              onToggleDir={onToggleDir}
+              onSelectFile={onSelectFile}
+              onMoveFile={onMoveFile}
+              onContextMenu={onContextMenu}
+              onRenameCommit={onRenameCommit}
+              onRenameCancel={onRenameCancel}
+              onCreateCommit={onCreateCommit}
+              onCreateCancel={onCreateCancel}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/* ── Open tab model ── */
+
+interface OpenTab {
+  /** Unique key: "root:path" */
+  key: string
+  root: RootMode
+  path: string
+  content: string | null
+  loading: boolean
+  error: string | null
+  /** When set, the viewer shows an inline diff overlay */
+  diff?: { before: string; after: string } | null
+  /** Set when the agent just opened/edited this file — causes MD files to default to Edit tab */
+  agentOpened?: boolean
+}
+
+function tabKey(root: RootMode, path: string): string {
+  return `${root}:${path}`
+}
+
+function tabDisplayPath(tab: OpenTab): string {
+  return tab.root === "gsd" ? `.gsd/${tab.path}` : tab.path
+}
+
+function tabLabel(tab: OpenTab): string {
+  return tab.path.split("/").pop() ?? tab.path
+}
+
+/* ── Main view ── */
+
+type LeftPanel = "tree" | "agent"
+
+export function FilesView() {
+  const workspace = useGSDWorkspaceState()
+  const projectCwd = workspace.boot?.project.cwd
+
+  const [activeRoot, setActiveRoot] = useState<RootMode>("gsd")
+  const [leftPanel, setLeftPanel] = useState<LeftPanel>("tree")
+  const [gsdTree, setGsdTree] = useState<FileNode[] | null>(null)
+  const [projectTree, setProjectTree] = useState<FileNode[] | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  // ── Resizable tree panel ──
+  const [treeWidth, setTreeWidth] = useState(256)
+  const isDraggingTree = useRef(false)
+  const dragStartX = useRef(0)
+  const dragStartWidth = useRef(0)
+
+  useEffect(() => {
+    const handleMouseMove = (e: MouseEvent) => {
+      if (!isDraggingTree.current) return
+      const delta = e.clientX - dragStartX.current
+      const newWidth = Math.max(180, Math.min(480, dragStartWidth.current + delta))
+      setTreeWidth(newWidth)
+    }
+    const handleMouseUp = () => {
+      if (isDraggingTree.current) {
+        isDraggingTree.current = false
+        document.body.style.cursor = ""
+        document.body.style.userSelect = ""
+      }
+    }
+    document.addEventListener("mousemove", handleMouseMove)
+    document.addEventListener("mouseup", handleMouseUp)
+    return () => {
+      document.removeEventListener("mousemove", handleMouseMove)
+      document.removeEventListener("mouseup", handleMouseUp)
+    }
+  }, [])
+
+  const handleTreeDragStart = useCallback(
+    (e: React.MouseEvent) => {
+      isDraggingTree.current = true
+      dragStartX.current = e.clientX
+      dragStartWidth.current = treeWidth
+      document.body.style.cursor = "col-resize"
+      document.body.style.userSelect = "none"
+    },
+    [treeWidth],
+  )
+
+  // Expanded paths per root, restored from sessionStorage
+  const [gsdExpanded, setGsdExpanded] = useState<Set<string>>(() => loadExpanded(projectCwd, "gsd"))
+  const [projectExpanded, setProjectExpanded] = useState<Set<string>>(() => loadExpanded(projectCwd, "project"))
+
+  // Re-hydrate from storage once projectCwd is available (boot may arrive after first render)
+  const hydratedRef = useRef(false)
+  useEffect(() => {
+    if (!projectCwd || hydratedRef.current) return
+    hydratedRef.current = true
+    setGsdExpanded(loadExpanded(projectCwd, "gsd"))
+    setProjectExpanded(loadExpanded(projectCwd, "project"))
+  }, [projectCwd])
+
+  const expandedPaths = activeRoot === "gsd" ? gsdExpanded : projectExpanded
+  const setExpandedPaths = activeRoot === "gsd" ? setGsdExpanded : setProjectExpanded
+
+  // ── Multi-tab state ──
+  const [openTabs, setOpenTabs] = useState<OpenTab[]>([])
+  const [activeTabKey, setActiveTabKey] = useState<string | null>(null)
+  const [treeRootDragOver, setTreeRootDragOver] = useState(false)
+
+  // ── Context menu state ──
+  const [contextMenu, setContextMenu] = useState<ContextMenuState | null>(null)
+  const [renamingPath, setRenamingPath] = useState<string | null>(null)
+  const [creatingIn, setCreatingIn] = useState<{ parentDir: string; type: "file" | "directory" } | null>(null)
+  const [deleteConfirm, setDeleteConfirm] = useState<{ path: string; type: "file" | "directory" } | null>(null)
+
+  const activeTab = openTabs.find((t) => t.key === activeTabKey) ?? null
+
+  // The selected path in the tree corresponds to the active tab
+  const selectedPath = activeTab?.path ?? null
+
+  const tree = activeRoot === "gsd" ? gsdTree : projectTree
+  const treeLoaded = activeRoot === "gsd" ? gsdTree !== null : projectTree !== null
+
+  const fetchTree = useCallback(async (root: RootMode) => {
+    try {
+      setLoading(true)
+      setError(null)
+      const res = await authFetch(buildProjectUrl(`/api/files?root=${root}`, projectCwd))
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}))
+        throw new Error(data.error || `Failed to fetch files (${res.status})`)
+      }
+      const data = await res.json()
+      const nodes = data.tree ?? []
+      if (root === "gsd") {
+        setGsdTree(nodes)
+      } else {
+        setProjectTree(nodes)
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to fetch files")
+    } finally {
+      setLoading(false)
+    }
+  }, [projectCwd])
+
+  // Fetch tree when tab changes and data isn't cached
+  useEffect(() => {
+    if (!treeLoaded) {
+      fetchTree(activeRoot)
+    }
+  }, [activeRoot, treeLoaded, fetchTree])
+
+  // Initial load
+  useEffect(() => {
+    fetchTree("gsd")
+  }, [fetchTree])
+
+  // ── Open or focus a file tab and fetch its content ──
+  const openFileTab = useCallback(async (root: RootMode, path: string) => {
+    const key = tabKey(root, path)
+
+    // If already open, just focus it
+    setOpenTabs((prev) => {
+      const existing = prev.find((t) => t.key === key)
+      if (existing) return prev
+      // Add new tab
+      return [...prev, { key, root, path, content: null, loading: true, error: null }]
+    })
+    setActiveTabKey(key)
+
+    // Switch tree root to match
+    setActiveRoot(root)
+
+    // Auto-expand parent dirs
+    const parts = path.split("/")
+    const setExpanded = root === "gsd" ? setGsdExpanded : setProjectExpanded
+    setExpanded((prev) => {
+      const next = new Set(prev)
+      for (let i = 1; i < parts.length; i++) {
+        next.add(parts.slice(0, i).join("/"))
+      }
+      saveExpanded(projectCwd, root, next)
+      return next
+    })
+
+    // Check if we already have the content cached
+    setOpenTabs((prev) => {
+      const existing = prev.find((t) => t.key === key)
+      if (existing && existing.content !== null) return prev // already loaded
+      return prev // will fetch below
+    })
+
+    // Fetch content
+    try {
+      const res = await authFetch(buildProjectUrl(`/api/files?root=${root}&path=${encodeURIComponent(path)}`, projectCwd))
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}))
+        const errMsg = data.error || `Failed to fetch file (${res.status})`
+        setOpenTabs((prev) =>
+          prev.map((t) => (t.key === key ? { ...t, loading: false, error: errMsg } : t)),
+        )
+        return
+      }
+      const data = await res.json()
+      setOpenTabs((prev) =>
+        prev.map((t) =>
+          t.key === key ? { ...t, content: data.content ?? null, loading: false, error: null } : t,
+        ),
+      )
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : "Failed to fetch file content"
+      setOpenTabs((prev) =>
+        prev.map((t) => (t.key === key ? { ...t, loading: false, error: errMsg } : t)),
+      )
+    }
+  }, [projectCwd])
+
+  // ── Close a tab ──
+  const closeTab = useCallback((key: string, e?: React.MouseEvent) => {
+    e?.stopPropagation()
+    setOpenTabs((prev) => {
+      const idx = prev.findIndex((t) => t.key === key)
+      const next = prev.filter((t) => t.key !== key)
+
+      // If we're closing the active tab, switch to an adjacent one
+      if (key === activeTabKey) {
+        if (next.length === 0) {
+          setActiveTabKey(null)
+        } else {
+          // Prefer the tab to the right, then left
+          const newIdx = Math.min(idx, next.length - 1)
+          setActiveTabKey(next[newIdx].key)
+        }
+      }
+
+      return next
+    })
+  }, [activeTabKey])
+
+  // Process a file open request (used both on mount and on event)
+  const processFileOpen = useCallback(async (root: RootMode, path: string) => {
+    // Ensure tree is loaded for this root
+    if (root === "gsd" && !gsdTree) {
+      fetchTree("gsd")
+    } else if (root === "project" && !projectTree) {
+      fetchTree("project")
+    }
+
+    await openFileTab(root, path)
+  }, [gsdTree, projectTree, fetchTree, openFileTab])
+
+  // On mount: consume any pending file request that arrived before this component mounted
+  const consumedPendingRef = useRef(false)
+  useEffect(() => {
+    if (consumedPendingRef.current) return
+    if (pendingFileRequest) {
+      consumedPendingRef.current = true
+      const { root, path } = pendingFileRequest
+      pendingFileRequest = null
+      void processFileOpen(root, path)
+    }
+  }, [processFileOpen])
+
+  // Listen for file open events while mounted
+  useEffect(() => {
+    const handler = (e: Event) => {
+      const detail = (e as CustomEvent<{ root: RootMode; path: string }>).detail
+      if (!detail?.root || !detail?.path) return
+      pendingFileRequest = null // clear since we're handling it directly
+      void processFileOpen(detail.root, detail.path)
+    }
+    window.addEventListener("gsd:open-file", handler)
+    return () => window.removeEventListener("gsd:open-file", handler)
+  }, [processFileOpen])
+
+  const handleToggleDir = useCallback((path: string) => {
+    setExpandedPaths((prev) => {
+      const next = new Set(prev)
+      if (next.has(path)) {
+        next.delete(path)
+      } else {
+        next.add(path)
+      }
+      saveExpanded(projectCwd, activeRoot, next)
+      return next
+    })
+  }, [setExpandedPaths, projectCwd, activeRoot])
+
+  const handleTreeRootChange = (root: RootMode) => {
+    setActiveRoot(root)
+  }
+
+  const handleSelectFile = useCallback(async (path: string) => {
+    await openFileTab(activeRoot, path)
+  }, [activeRoot, openFileTab])
+
+  // ── Move file/directory via drag-and-drop ──
+  const handleMoveFile = useCallback(async (fromPath: string, toDir: string) => {
+    const fileName = fromPath.split("/").pop() ?? fromPath
+    const toPath = toDir ? `${toDir}/${fileName}` : fileName
+
+    try {
+      const res = await authFetch(buildProjectUrl("/api/files", projectCwd), {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ from: fromPath, to: toPath, root: activeRoot }),
+      })
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}))
+        console.error("Move failed:", data.error || res.statusText)
+        return
+      }
+
+      // Update any open tabs that referenced the moved path
+      const oldKey = tabKey(activeRoot, fromPath)
+      setOpenTabs((prev) =>
+        prev.map((t) => {
+          if (t.key === oldKey) {
+            const newKey = tabKey(activeRoot, toPath)
+            return { ...t, key: newKey, path: toPath }
+          }
+          // Also update tabs for files inside a moved directory
+          if (t.root === activeRoot && t.path.startsWith(fromPath + "/")) {
+            const newTabPath = toPath + t.path.slice(fromPath.length)
+            return { ...t, key: tabKey(activeRoot, newTabPath), path: newTabPath }
+          }
+          return t
+        }),
+      )
+      if (activeTabKey?.startsWith(`${activeRoot}:${fromPath}`)) {
+        if (activeTabKey === `${activeRoot}:${fromPath}`) {
+          setActiveTabKey(tabKey(activeRoot, toPath))
+        } else {
+          const suffix = activeTabKey.slice(`${activeRoot}:${fromPath}`.length)
+          setActiveTabKey(tabKey(activeRoot, toPath + suffix))
+        }
+      }
+
+      // Refresh tree
+      await fetchTree(activeRoot)
+    } catch (err) {
+      console.error("Move failed:", err)
+    }
+  }, [activeRoot, activeTabKey, fetchTree, projectCwd])
+
+  // ── Context menu handlers ──
+
+  const handleContextMenu = useCallback((e: React.MouseEvent, path: string, type: "file" | "directory", parentPath: string) => {
+    setContextMenu({ x: e.clientX, y: e.clientY, path, type, parentPath })
+  }, [])
+
+  const handleContextMenuClose = useCallback(() => {
+    setContextMenu(null)
+  }, [])
+
+  const handleNewFile = useCallback((parentDir: string) => {
+    // Ensure parent directory is expanded
+    if (parentDir) {
+      const setExpanded = activeRoot === "gsd" ? setGsdExpanded : setProjectExpanded
+      setExpanded((prev) => {
+        const next = new Set(prev)
+        const parts = parentDir.split("/")
+        for (let i = 1; i <= parts.length; i++) {
+          next.add(parts.slice(0, i).join("/"))
+        }
+        saveExpanded(projectCwd, activeRoot, next)
+        return next
+      })
+    }
+    setCreatingIn({ parentDir, type: "file" })
+  }, [activeRoot, projectCwd])
+
+  const handleNewFolder = useCallback((parentDir: string) => {
+    if (parentDir) {
+      const setExpanded = activeRoot === "gsd" ? setGsdExpanded : setProjectExpanded
+      setExpanded((prev) => {
+        const next = new Set(prev)
+        const parts = parentDir.split("/")
+        for (let i = 1; i <= parts.length; i++) {
+          next.add(parts.slice(0, i).join("/"))
+        }
+        saveExpanded(projectCwd, activeRoot, next)
+        return next
+      })
+    }
+    setCreatingIn({ parentDir, type: "directory" })
+  }, [activeRoot, projectCwd])
+
+  const handleCreateCommit = useCallback(async (parentDir: string, name: string, type: "file" | "directory") => {
+    const newPath = parentDir ? `${parentDir}/${name}` : name
+    try {
+      const res = await authFetch(buildProjectUrl("/api/files", projectCwd), {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ path: newPath, type, root: activeRoot }),
+      })
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}))
+        console.error("Create failed:", data.error || res.statusText)
+        return
+      }
+      await fetchTree(activeRoot)
+      // Open the file if it's a file
+      if (type === "file") {
+        await openFileTab(activeRoot, newPath)
+      }
+    } catch (err) {
+      console.error("Create failed:", err)
+    } finally {
+      setCreatingIn(null)
+    }
+  }, [activeRoot, fetchTree, openFileTab, projectCwd])
+
+  const handleCreateCancel = useCallback(() => {
+    setCreatingIn(null)
+  }, [])
+
+  const handleRenameStart = useCallback((path: string) => {
+    setRenamingPath(path)
+  }, [])
+
+  const handleRenameCommit = useCallback(async (oldPath: string, newName: string) => {
+    const parentDir = oldPath.includes("/") ? oldPath.substring(0, oldPath.lastIndexOf("/")) : ""
+    const newPath = parentDir ? `${parentDir}/${newName}` : newName
+
+    if (newPath === oldPath) {
+      setRenamingPath(null)
+      return
+    }
+
+    try {
+      const res = await authFetch(buildProjectUrl("/api/files", projectCwd), {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ from: oldPath, to: newPath, root: activeRoot }),
+      })
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}))
+        console.error("Rename failed:", data.error || res.statusText)
+        return
+      }
+
+      // Update open tabs
+      const oldKey = tabKey(activeRoot, oldPath)
+      setOpenTabs((prev) =>
+        prev.map((t) => {
+          if (t.key === oldKey) {
+            return { ...t, key: tabKey(activeRoot, newPath), path: newPath }
+          }
+          if (t.root === activeRoot && t.path.startsWith(oldPath + "/")) {
+            const newTabPath = newPath + t.path.slice(oldPath.length)
+            return { ...t, key: tabKey(activeRoot, newTabPath), path: newTabPath }
+          }
+          return t
+        }),
+      )
+      if (activeTabKey === `${activeRoot}:${oldPath}`) {
+        setActiveTabKey(tabKey(activeRoot, newPath))
+      } else if (activeTabKey?.startsWith(`${activeRoot}:${oldPath}/`)) {
+        const suffix = activeTabKey.slice(`${activeRoot}:${oldPath}`.length)
+        setActiveTabKey(tabKey(activeRoot, newPath + suffix))
+      }
+
+      await fetchTree(activeRoot)
+    } catch (err) {
+      console.error("Rename failed:", err)
+    } finally {
+      setRenamingPath(null)
+    }
+  }, [activeRoot, activeTabKey, fetchTree, projectCwd])
+
+  const handleRenameCancel = useCallback(() => {
+    setRenamingPath(null)
+  }, [])
+
+  const handleDelete = useCallback((path: string, type: "file" | "directory") => {
+    setDeleteConfirm({ path, type })
+  }, [])
+
+  const handleDeleteConfirm = useCallback(async () => {
+    if (!deleteConfirm) return
+    const { path, type } = deleteConfirm
+    try {
+      const res = await fetch(
+        buildProjectUrl(`/api/files?root=${activeRoot}&path=${encodeURIComponent(path)}`, projectCwd),
+        { method: "DELETE" },
+      )
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}))
+        console.error("Delete failed:", data.error || res.statusText)
+        return
+      }
+
+      // Close any tabs for the deleted path
+      setOpenTabs((prev) => {
+        const next = prev.filter((t) => {
+          if (t.root !== activeRoot) return true
+          if (t.path === path) return false
+          if (t.path.startsWith(path + "/")) return false
+          return true
+        })
+        // If active tab was removed, switch to adjacent
+        if (activeTabKey) {
+          const wasRemoved = !next.some((t) => t.key === activeTabKey)
+          if (wasRemoved) {
+            setActiveTabKey(next.length > 0 ? next[next.length - 1].key : null)
+          }
+        }
+        return next
+      })
+
+      await fetchTree(activeRoot)
+    } catch (err) {
+      console.error("Delete failed:", err)
+    } finally {
+      setDeleteConfirm(null)
+    }
+  }, [deleteConfirm, activeRoot, activeTabKey, fetchTree, projectCwd])
+
+  const handleDeleteCancel = useCallback(() => {
+    setDeleteConfirm(null)
+  }, [])
+
+  const handleCopyPath = useCallback((path: string) => {
+    const displayPath = activeRoot === "gsd" ? `.gsd/${path}` : path
+    void navigator.clipboard.writeText(displayPath)
+  }, [activeRoot])
+
+  const handleDuplicate = useCallback(async (path: string) => {
+    // Read original content
+    try {
+      const res = await authFetch(buildProjectUrl(`/api/files?root=${activeRoot}&path=${encodeURIComponent(path)}`, projectCwd))
+      if (!res.ok) return
+      const data = await res.json()
+      if (typeof data.content !== "string") return
+
+      // Compute duplicate name: file.ts -> file-copy.ts, folder -> folder-copy
+      const fileName = path.split("/").pop() ?? path
+      const parentDir = path.includes("/") ? path.substring(0, path.lastIndexOf("/")) : ""
+      const dotIndex = fileName.lastIndexOf(".")
+      let newName: string
+      if (dotIndex > 0) {
+        newName = `${fileName.substring(0, dotIndex)}-copy${fileName.substring(dotIndex)}`
+      } else {
+        newName = `${fileName}-copy`
+      }
+      const newPath = parentDir ? `${parentDir}/${newName}` : newName
+
+      // Create with content
+      const createRes = await authFetch(buildProjectUrl("/api/files", projectCwd), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ path: newPath, content: data.content, root: activeRoot }),
+      })
+      if (!createRes.ok) {
+        const errData = await createRes.json().catch(() => ({}))
+        console.error("Duplicate failed:", errData.error || createRes.statusText)
+        return
+      }
+      await fetchTree(activeRoot)
+      await openFileTab(activeRoot, newPath)
+    } catch (err) {
+      console.error("Duplicate failed:", err)
+    }
+  }, [activeRoot, fetchTree, openFileTab, projectCwd])
+
+  // Save handler: POST to /api/files, then re-fetch content
+  const handleSave = useCallback(async (newContent: string) => {
+    if (!activeTab) return
+    const { root, path, key } = activeTab
+    const res = await authFetch(buildProjectUrl("/api/files", projectCwd), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ path, content: newContent, root }),
+    })
+    if (!res.ok) {
+      const data = await res.json().catch(() => ({}))
+      throw new Error(data.error || `Save failed (${res.status})`)
+    }
+    // Re-fetch to sync the view tab
+    const refetch = await authFetch(buildProjectUrl(`/api/files?root=${root}&path=${encodeURIComponent(path)}`, projectCwd))
+    if (refetch.ok) {
+      const data = await refetch.json()
+      setOpenTabs((prev) =>
+        prev.map((t) =>
+          t.key === key ? { ...t, content: data.content ?? null } : t,
+        ),
+      )
+    }
+  }, [activeTab, projectCwd])
+
+  // Auto-select STATE.md on initial load if no tabs are open
+  const autoSelectedRef = useRef(false)
+  useEffect(() => {
+    if (autoSelectedRef.current) return
+    if (!gsdTree || openTabs.length > 0 || consumedPendingRef.current) return
+    const hasStateMd = gsdTree.some((n) => n.name === "STATE.md" && n.type === "file")
+    if (hasStateMd) {
+      autoSelectedRef.current = true
+      void openFileTab("gsd", "STATE.md")
+    }
+  }, [gsdTree, openTabs.length, openFileTab])
+
+  // ── Agent file-edit auto-open: watch tool executions for edit/write tools ──
+  const lastSeenToolCountRef = useRef(0)
+  const completedTools = workspace.completedToolExecutions
+  const activeToolExec = workspace.activeToolExecution
+  const diffTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    if (completedTools.length <= lastSeenToolCountRef.current) return
+    const newTools = completedTools.slice(lastSeenToolCountRef.current)
+    lastSeenToolCountRef.current = completedTools.length
+
+    for (const tool of newTools) {
+      if (tool.name !== "edit" && tool.name !== "write") continue
+      const filePath = typeof tool.args?.path === "string" ? tool.args.path : null
+      if (!filePath) continue
+
+      // Determine root and relative path
+      const gsdPrefix = ".gsd/"
+      let root: RootMode = "project"
+      let relativePath = filePath
+
+      // Strip leading project cwd if present
+      if (projectCwd && relativePath.startsWith(projectCwd)) {
+        relativePath = relativePath.slice(projectCwd.length)
+        if (relativePath.startsWith("/")) relativePath = relativePath.slice(1)
+      }
+
+      if (relativePath.startsWith(gsdPrefix)) {
+        root = "gsd"
+        relativePath = relativePath.slice(gsdPrefix.length)
+      }
+
+      const key = tabKey(root, relativePath)
+
+      // Capture old content before re-fetching (for diff)
+      const existingTab = openTabs.find((t) => t.key === key)
+      const oldContent = existingTab?.content ?? null
+
+      // Fetch new content, then store diff
+      ;(async () => {
+        try {
+          const res = await authFetch(buildProjectUrl(`/api/files?root=${root}&path=${encodeURIComponent(relativePath)}`, projectCwd))
+          if (!res.ok) return
+          const data = await res.json()
+          const newContent: string | null = data.content ?? null
+
+          if (newContent !== null) {
+            const diffData = oldContent !== null && oldContent !== newContent
+              ? { before: oldContent, after: newContent }
+              : null
+
+            setOpenTabs((prev) => {
+              const exists = prev.find((t) => t.key === key)
+              if (exists) {
+                return prev.map((t) =>
+                  t.key === key ? { ...t, content: newContent, loading: false, error: null, diff: diffData, agentOpened: true } : t,
+                )
+              }
+              // New tab
+              return [...prev, { key, root, path: relativePath, content: newContent, loading: false, error: null, diff: diffData, agentOpened: true }]
+            })
+            setActiveTabKey(key)
+
+            // Auto-clear diff after 8 seconds
+            if (diffData) {
+              if (diffTimerRef.current) clearTimeout(diffTimerRef.current)
+              diffTimerRef.current = setTimeout(() => {
+                setOpenTabs((prev) =>
+                  prev.map((t) => t.key === key ? { ...t, diff: null } : t),
+                )
+              }, 8000)
+            }
+          }
+        } catch { /* ignore */ }
+      })()
+    }
+  }, [completedTools, projectCwd, openTabs])
+
+  // While a file-modifying tool is active, show which file is being worked on
+  const activeEditFile = useMemo(() => {
+    if (!activeToolExec) return null
+    if (activeToolExec.name !== "edit" && activeToolExec.name !== "write") return null
+    return typeof activeToolExec.args?.path === "string" ? activeToolExec.args.path : null
+  }, [activeToolExec])
+
+  return (
+    <div className="flex h-full">
+      {/* Left panel (file tree or agent chat) */}
+      <div className="flex-shrink-0 border-r border-border overflow-hidden flex flex-col" style={{ width: treeWidth }}>
+        {/* Tab bar */}
+        <div className="flex border-b border-border flex-shrink-0">
+          <button
+            onClick={() => { setLeftPanel("tree"); handleTreeRootChange("gsd") }}
+            className={cn(
+              "flex-1 px-3 py-2 text-xs font-medium transition-colors",
+              leftPanel === "tree" && activeRoot === "gsd"
+                ? "border-b-2 border-foreground text-foreground"
+                : "text-muted-foreground hover:text-foreground",
+            )}
+          >
+            GSD
+          </button>
+          <button
+            onClick={() => { setLeftPanel("tree"); handleTreeRootChange("project") }}
+            className={cn(
+              "flex-1 px-3 py-2 text-xs font-medium transition-colors",
+              leftPanel === "tree" && activeRoot === "project"
+                ? "border-b-2 border-foreground text-foreground"
+                : "text-muted-foreground hover:text-foreground",
+            )}
+          >
+            Project
+          </button>
+          <button
+            onClick={() => setLeftPanel("agent")}
+            className={cn(
+              "flex-1 px-3 py-2 text-xs font-medium transition-colors flex items-center justify-center gap-1.5",
+              leftPanel === "agent"
+                ? "border-b-2 border-foreground text-foreground"
+                : "text-muted-foreground hover:text-foreground",
+            )}
+          >
+            <Bot className="h-3 w-3" />
+            Agent
+          </button>
+        </div>
+
+        {/* Panel content */}
+        {leftPanel === "agent" ? (
+          <div className="flex-1 overflow-hidden flex flex-col min-h-0">
+            <ChatPane className="flex-1 min-h-0" />
+          </div>
+        ) : (
+          /* Tree content */
+          <div
+            className={cn("flex-1 overflow-y-auto py-2", treeRootDragOver && "bg-accent/30")}
+          onDragOver={(e) => {
+            // Only highlight if dragging directly over the root area, not a folder
+            if ((e.target as HTMLElement).closest("[data-tree-item]")) return
+            if (!e.dataTransfer.types.includes("text/x-tree-path")) return
+            e.preventDefault()
+            e.dataTransfer.dropEffect = "move"
+            setTreeRootDragOver(true)
+          }}
+          onDragLeave={(e) => {
+            // Only clear if leaving the root container entirely
+            if (!(e.currentTarget as HTMLElement).contains(e.relatedTarget as Node)) {
+              setTreeRootDragOver(false)
+            }
+          }}
+          onDrop={(e) => {
+            setTreeRootDragOver(false)
+            if ((e.target as HTMLElement).closest("[data-tree-item]")) return
+            e.preventDefault()
+            const srcPath = e.dataTransfer.getData("text/x-tree-path")
+            if (!srcPath) return
+            // Already at root level?
+            if (!srcPath.includes("/")) return
+            handleMoveFile(srcPath, "")
+          }}
+          onContextMenu={(e) => {
+            // Right-click on empty space in tree — offer New File/Folder at root
+            if ((e.target as HTMLElement).closest("[data-tree-item]")) return
+            e.preventDefault()
+            setContextMenu({ x: e.clientX, y: e.clientY, path: "", type: "directory", parentPath: "" })
+          }}
+        >
+          {loading && !treeLoaded ? (
+            <div className="flex items-center justify-center py-8 text-muted-foreground">
+              <Loader2 className="h-4 w-4 animate-spin mr-2" />
+              Loading…
+            </div>
+          ) : error && !treeLoaded ? (
+            <div className="flex items-center justify-center py-8 text-destructive text-xs px-3">
+              <AlertCircle className="h-4 w-4 mr-2 shrink-0" />
+              {error}
+            </div>
+          ) : tree && tree.length === 0 ? (
+            <div className="flex items-center justify-center py-8 text-muted-foreground text-xs">
+              {activeRoot === "gsd" ? "No .gsd/ files found" : "No files found"}
+            </div>
+          ) : tree ? (
+            <>
+              {/* Root-level create input */}
+              {creatingIn && creatingIn.parentDir === "" && (
+                <InlineInput
+                  defaultValue={creatingIn.type === "directory" ? "new-folder" : "new-file"}
+                  onCommit={(name) => handleCreateCommit("", name, creatingIn.type)}
+                  onCancel={handleCreateCancel}
+                  depth={0}
+                  icon={creatingIn.type === "directory"
+                    ? <Folder className="h-4 w-4 text-muted-foreground" />
+                    : <File className="h-4 w-4 text-muted-foreground" />
+                  }
+                />
+              )}
+              {tree.map((node, i) => (
+                <FileTreeItem
+                  key={`${activeRoot}-${i}`}
+                  node={node}
+                  depth={0}
+                  parentPath=""
+                  selectedPath={selectedPath}
+                  expandedPaths={expandedPaths}
+                  renamingPath={renamingPath}
+                  creatingIn={creatingIn}
+                  onToggleDir={handleToggleDir}
+                  onSelectFile={handleSelectFile}
+                  onMoveFile={handleMoveFile}
+                  onContextMenu={handleContextMenu}
+                  onRenameCommit={handleRenameCommit}
+                  onRenameCancel={handleRenameCancel}
+                  onCreateCommit={handleCreateCommit}
+                  onCreateCancel={handleCreateCancel}
+                />
+              ))}
+            </>
+          ) : null}
+        </div>
+        )}
+      </div>
+
+      {/* Resize drag handle */}
+      <div className="relative flex items-stretch" style={{ flexShrink: 0 }}>
+        <div
+          className="absolute left-[-3px] top-0 bottom-0 w-[7px] cursor-col-resize z-10 hover:bg-muted-foreground/20 transition-colors"
+          onMouseDown={handleTreeDragStart}
+        />
+      </div>
+
+      {/* File content panel */}
+      <div className="flex-1 overflow-hidden flex flex-col min-h-0">
+        {/* Open file tabs */}
+        {openTabs.length > 0 && (
+          <div className="flex border-b border-border flex-shrink-0 overflow-x-auto bg-background">
+            {openTabs.map((tab) => (
+              <button
+                key={tab.key}
+                onClick={() => {
+                  setActiveTabKey(tab.key)
+                  setActiveRoot(tab.root)
+                }}
+                className={cn(
+                  "group flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium border-r border-border transition-colors shrink-0 max-w-[180px]",
+                  tab.key === activeTabKey
+                    ? "bg-accent/50 text-foreground"
+                    : "text-muted-foreground hover:text-foreground hover:bg-accent/20",
+                )}
+              >
+                <span className="truncate" title={tabDisplayPath(tab)}>
+                  {tabLabel(tab)}
+                </span>
+                <span
+                  role="button"
+                  tabIndex={0}
+                  onClick={(e) => closeTab(tab.key, e)}
+                  onKeyDown={(e) => {
+                    if (e.key === "Enter" || e.key === " ") {
+                      e.preventDefault()
+                      closeTab(tab.key)
+                    }
+                  }}
+                  className="ml-0.5 rounded p-0.5 opacity-0 group-hover:opacity-100 hover:bg-accent transition-opacity"
+                >
+                  <X className="h-3 w-3" />
+                </span>
+              </button>
+            ))}
+          </div>
+        )}
+
+        {/* Active tab content */}
+        {activeTab ? (
+          <>
+            {activeTab.loading ? (
+              <div className="flex flex-1 items-center justify-center text-muted-foreground">
+                <Loader2 className="h-4 w-4 animate-spin mr-2" />
+                Loading…
+              </div>
+            ) : activeTab.error ? (
+              <div className="flex flex-1 items-center justify-center text-destructive">
+                <AlertCircle className="h-4 w-4 mr-2" />
+                {activeTab.error}
+              </div>
+            ) : activeTab.content !== null ? (
+              <FileContentViewer
+                content={activeTab.content}
+                filepath={tabDisplayPath(activeTab)}
+                root={activeTab.root}
+                path={activeTab.path}
+                onSave={handleSave}
+                diff={activeTab.diff ?? undefined}
+                agentOpened={activeTab.agentOpened}
+                onDismissDiff={() => {
+                  setOpenTabs((prev) =>
+                    prev.map((t) => t.key === activeTab.key ? { ...t, diff: null, agentOpened: false } : t),
+                  )
+                }}
+              />
+            ) : (
+              <div className="flex flex-1 items-center justify-center text-muted-foreground italic">
+                No preview available
+              </div>
+            )}
+          </>
+        ) : (
+          <div className="flex h-full items-center justify-center text-muted-foreground">
+            Select a file to view
+          </div>
+        )}
+      </div>
+
+      {/* Context menu */}
+      {contextMenu && (
+        <TreeContextMenu
+          menu={contextMenu}
+          onClose={handleContextMenuClose}
+          onNewFile={handleNewFile}
+          onNewFolder={handleNewFolder}
+          onRename={handleRenameStart}
+          onDelete={handleDelete}
+          onCopyPath={handleCopyPath}
+          onDuplicate={handleDuplicate}
+        />
+      )}
+
+      {/* Delete confirmation dialog */}
+      {deleteConfirm && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50 animate-in fade-in-0">
+          <div className="w-full max-w-sm rounded-lg border border-border bg-popover p-4 shadow-lg animate-in zoom-in-95">
+            <h3 className="text-sm font-medium text-popover-foreground">
+              Delete {deleteConfirm.type === "directory" ? "folder" : "file"}?
+            </h3>
+            <p className="mt-2 text-xs text-muted-foreground">
+              Are you sure you want to delete{" "}
+              <span className="font-mono font-medium text-popover-foreground">
+                {deleteConfirm.path.split("/").pop()}
+              </span>
+              ?{deleteConfirm.type === "directory" && " This will delete all contents."}
+              {" "}This cannot be undone.
+            </p>
+            <div className="mt-4 flex justify-end gap-2">
+              <button
+                onClick={handleDeleteCancel}
+                className="rounded-md px-3 py-1.5 text-xs font-medium text-muted-foreground hover:bg-accent transition-colors"
+              >
+                Cancel
+              </button>
+              <button
+                onClick={handleDeleteConfirm}
+                className="rounded-md bg-destructive px-3 py-1.5 text-xs font-medium text-destructive-foreground hover:bg-destructive/90 transition-colors"
+              >
+                Delete
+              </button>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
diff --git a/web/components/sf/focused-panel.tsx b/web/components/sf/focused-panel.tsx
new file mode 100644
index 000000000..eeee7b508
--- /dev/null
+++ b/web/components/sf/focused-panel.tsx
@@ -0,0 +1,332 @@
+"use client"
+
+import { useState } from "react"
+import { CheckSquare, MessageSquare, Send, TextCursorInput, Type } from "lucide-react"
+
+import { Button } from "@/components/ui/button"
+import { Checkbox } from "@/components/ui/checkbox"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+} from "@/components/ui/sheet"
+import { Textarea } from "@/components/ui/textarea"
+import {
+  type PendingUiRequest,
+  useGSDWorkspaceActions,
+  useGSDWorkspaceState,
+} from "@/lib/sf-workspace-store"
+import { cn } from "@/lib/utils"
+
+function methodIcon(method: PendingUiRequest["method"]) {
+  switch (method) {
+    case "select":
+      return <CheckSquare className="h-4 w-4" />
+    case "confirm":
+      return <MessageSquare className="h-4 w-4" />
+    case "input":
+      return <TextCursorInput className="h-4 w-4" />
+    case "editor":
+      return <Type className="h-4 w-4" />
+  }
+}
+
+function methodLabel(method: PendingUiRequest["method"]): string {
+  switch (method) {
+    case "select":
+      return "Selection"
+    case "confirm":
+      return "Confirmation"
+    case "input":
+      return "Input"
+    case "editor":
+      return "Editor"
+  }
+}
+
+// --- Renderers for each blocking UI request type ---
+
+function SelectRenderer({
+  request,
+  onSubmit,
+  disabled,
+}: {
+  request: Extract<PendingUiRequest, { method: "select" }>
+  onSubmit: (value: Record<string, unknown>) => void
+  disabled: boolean
+}) {
+  const isMulti = Boolean(request.allowMultiple)
+  const [singleValue, setSingleValue] = useState("")
+  const [multiValues, setMultiValues] = useState<Set<string>>(new Set())
+
+  const handleSubmit = () => {
+    if (isMulti) {
+      onSubmit({ value: Array.from(multiValues) })
+    } else {
+      onSubmit({ value: singleValue })
+    }
+  }
+
+  const canSubmit = isMulti ? multiValues.size > 0 : singleValue !== ""
+
+  if (isMulti) {
+    return (
+      <div className="space-y-4">
+        <div className="space-y-2">
+          {request.options.map((option) => (
+            <label
+              key={option}
+              className="flex cursor-pointer items-center gap-3 rounded-lg border border-border bg-background px-3 py-2.5 transition-colors hover:bg-accent/40"
+            >
+              <Checkbox
+                checked={multiValues.has(option)}
+                onCheckedChange={(checked) => {
+                  const next = new Set(multiValues)
+                  if (checked) {
+                    next.add(option)
+                  } else {
+                    next.delete(option)
+                  }
+                  setMultiValues(next)
+                }}
+                disabled={disabled}
+              />
+              <span className="text-sm">{option}</span>
+            </label>
+          ))}
+        </div>
+        <Button onClick={handleSubmit} disabled={disabled || !canSubmit} className="w-full">
+          <Send className="h-4 w-4" />
+          Submit selection ({multiValues.size})
+        </Button>
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-4">
+      <RadioGroup value={singleValue} onValueChange={setSingleValue} disabled={disabled}>
+        {request.options.map((option) => (
+          <label
+            key={option}
+            className="flex cursor-pointer items-center gap-3 rounded-lg border border-border bg-background px-3 py-2.5 transition-colors hover:bg-accent/40"
+          >
+            <RadioGroupItem value={option} id={`select-${option}`} />
+            <Label htmlFor={`select-${option}`} className="cursor-pointer text-sm font-normal">
+              {option}
+            </Label>
+          </label>
+        ))}
+      </RadioGroup>
+      <Button onClick={handleSubmit} disabled={disabled || !canSubmit} className="w-full">
+        <Send className="h-4 w-4" />
+        Submit
+      </Button>
+    </div>
+  )
+}
+
+function ConfirmRenderer({
+  request,
+  onSubmit,
+  onCancel,
+  disabled,
+}: {
+  request: Extract<PendingUiRequest, { method: "confirm" }>
+  onSubmit: (value: Record<string, unknown>) => void
+  onCancel: () => void
+  disabled: boolean
+}) {
+  return (
+    <div className="space-y-4">
+      <div className="rounded-lg border border-border bg-background px-4 py-3 text-sm leading-relaxed">
+        {request.message}
+      </div>
+      <div className="flex gap-3">
+        <Button onClick={() => onSubmit({ value: true })} disabled={disabled} className="flex-1">
+          Confirm
+        </Button>
+        <Button onClick={onCancel} disabled={disabled} variant="outline" className="flex-1">
+          Cancel
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+function InputRenderer({
+  request,
+  onSubmit,
+  disabled,
+}: {
+  request: Extract<PendingUiRequest, { method: "input" }>
+  onSubmit: (value: Record<string, unknown>) => void
+  disabled: boolean
+}) {
+  const [value, setValue] = useState("")
+
+  return (
+    <form
+      className="space-y-4"
+      onSubmit={(e) => {
+        e.preventDefault()
+        if (value.trim()) onSubmit({ value })
+      }}
+    >
+      <Input
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        placeholder={request.placeholder || "Enter a value"}
+        disabled={disabled}
+        autoFocus
+      />
+      <Button type="submit" disabled={disabled || !value.trim()} className="w-full">
+        <Send className="h-4 w-4" />
+        Submit
+      </Button>
+    </form>
+  )
+}
+
+function EditorRenderer({
+  request,
+  onSubmit,
+  disabled,
+}: {
+  request: Extract<PendingUiRequest, { method: "editor" }>
+  onSubmit: (value: Record<string, unknown>) => void
+  disabled: boolean
+}) {
+  const [value, setValue] = useState(request.prefill || "")
+
+  return (
+    <form
+      className="space-y-4"
+      onSubmit={(e) => {
+        e.preventDefault()
+        onSubmit({ value })
+      }}
+    >
+      <Textarea
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        disabled={disabled}
+        className="min-h-[200px] font-mono text-sm"
+        autoFocus
+      />
+      <Button type="submit" disabled={disabled} className="w-full">
+        <Send className="h-4 w-4" />
+        Submit
+      </Button>
+    </form>
+  )
+}
+
+function RequestBody({
+  request,
+  onSubmit,
+  onCancel,
+  disabled,
+}: {
+  request: PendingUiRequest
+  onSubmit: (value: Record<string, unknown>) => void
+  onCancel: () => void
+  disabled: boolean
+}) {
+  switch (request.method) {
+    case "select":
+      return <SelectRenderer request={request} onSubmit={onSubmit} disabled={disabled} />
+    case "confirm":
+      return <ConfirmRenderer request={request} onSubmit={onSubmit} onCancel={onCancel} disabled={disabled} />
+    case "input":
+      return <InputRenderer request={request} onSubmit={onSubmit} disabled={disabled} />
+    case "editor":
+      return <EditorRenderer request={request} onSubmit={onSubmit} disabled={disabled} />
+  }
+}
+
+export function FocusedPanel() {
+  const workspace = useGSDWorkspaceState()
+  const { respondToUiRequest, dismissUiRequest } = useGSDWorkspaceActions()
+
+  const pending = workspace.pendingUiRequests
+  const isOpen = pending.length > 0
+  const current = pending[0] ?? null
+  const isSubmitting = workspace.commandInFlight === "extension_ui_response"
+
+  const handleSubmit = (response: Record<string, unknown>) => {
+    if (!current) return
+    void respondToUiRequest(current.id, response)
+  }
+
+  const handleDismiss = () => {
+    if (!current) return
+    void dismissUiRequest(current.id)
+  }
+
+  // Prevent the Sheet from closing via overlay click / escape while submitting
+  const handleOpenChange = (open: boolean) => {
+    if (!open && !isSubmitting && current) {
+      handleDismiss()
+    }
+  }
+
+  return (
+    <Sheet open={isOpen} onOpenChange={handleOpenChange}>
+      <SheetContent side="right" className="flex flex-col sm:max-w-md" data-testid="focused-panel">
+        {current && (
+          <>
+            <SheetHeader>
+              <div className="flex items-center gap-2">
+                {methodIcon(current.method)}
+                <SheetTitle>{current.title || methodLabel(current.method)}</SheetTitle>
+              </div>
+              <SheetDescription>
+                <span className="flex items-center gap-2">
+                  <span>{methodLabel(current.method)} requested by the agent</span>
+                  {pending.length > 1 && (
+                    <span
+                      className={cn(
+                        "inline-flex h-5 min-w-5 items-center justify-center rounded-full bg-foreground px-1.5 text-[11px] font-semibold text-background",
+                      )}
+                      data-testid="focused-panel-queue-badge"
+                    >
+                      +{pending.length - 1}
+                    </span>
+                  )}
+                </span>
+              </SheetDescription>
+            </SheetHeader>
+
+            <div className="flex-1 overflow-y-auto px-4 py-2">
+              <RequestBody
+                request={current}
+                onSubmit={handleSubmit}
+                onCancel={handleDismiss}
+                disabled={isSubmitting}
+              />
+            </div>
+
+            <SheetFooter>
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={handleDismiss}
+                disabled={isSubmitting}
+                className="text-muted-foreground"
+              >
+                Dismiss
+              </Button>
+            </SheetFooter>
+          </>
+        )}
+      </SheetContent>
+    </Sheet>
+  )
+}
diff --git a/web/components/sf/guided-dialog.tsx b/web/components/sf/guided-dialog.tsx
new file mode 100644
index 000000000..22850fc2c
--- /dev/null
+++ b/web/components/sf/guided-dialog.tsx
@@ -0,0 +1,74 @@
+"use client"
+
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog"
+import { ChatPane } from "@/components/sf/chat-mode"
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface GuidedDialogProps {
+  /** Whether the dialog is open */
+  open: boolean
+  /** Callback when open state changes (e.g. close button clicked) */
+  onOpenChange: (open: boolean) => void
+  /** Detection kind for contextual title */
+  detectionKind?: string
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function getDialogTitle(detectionKind?: string): string {
+  switch (detectionKind) {
+    case "v1-legacy":
+      return "Migrating to GSD v2"
+    case "brownfield":
+      return "Mapping Your Project"
+    case "blank":
+      return "Setting Up Your Project"
+    default:
+      return "Getting Started"
+  }
+}
+
+// ─── Component ──────────────────────────────────────────────────────────────
+
+/**
+ * Full-screen dialog that embeds ChatPane to render the bridge session
+ * response to an onboarding CTA command.
+ *
+ * The initial command dispatch is NOT handled here — it is managed by
+ * the parent (Dashboard) via a useEffect keyed on open + command.
+ */
+export function GuidedDialog({
+  open,
+  onOpenChange,
+  detectionKind,
+}: GuidedDialogProps) {
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent
+        className="sm:max-w-4xl h-[85vh] flex flex-col p-0 gap-0"
+        data-testid="guided-dialog"
+      >
+        <DialogHeader className="px-6 py-4 border-b border-border shrink-0">
+          <DialogTitle className="text-base font-semibold">
+            {getDialogTitle(detectionKind)}
+          </DialogTitle>
+          <DialogDescription className="sr-only">
+            Interactive guided setup — responses stream below as they are generated.
+          </DialogDescription>
+        </DialogHeader>
+
+        {/* ChatPane without onOpenAction hides the Discuss/Next/Auto action buttons */}
+        <div className="flex-1 min-h-0 overflow-hidden">
+          <ChatPane className="h-full" />
+        </div>
+      </DialogContent>
+    </Dialog>
+  )
+}
diff --git a/web/components/sf/knowledge-captures-panel.tsx b/web/components/sf/knowledge-captures-panel.tsx
new file mode 100644
index 000000000..2951d5728
--- /dev/null
+++ b/web/components/sf/knowledge-captures-panel.tsx
@@ -0,0 +1,457 @@
+"use client"
+
+import { useState } from "react"
+import {
+  BookOpen,
+  InboxIcon,
+  LoaderCircle,
+  RefreshCw,
+  Zap,
+  Clock,
+  Tag,
+  FileText,
+  Lightbulb,
+  Repeat2,
+  StickyNote,
+  ArrowRightLeft,
+  CalendarClock,
+  ListTodo,
+} from "lucide-react"
+
+import { Badge } from "@/components/ui/badge"
+import { Button } from "@/components/ui/button"
+import type {
+  KnowledgeData,
+  KnowledgeEntry,
+  CapturesData,
+  CaptureEntry,
+  Classification,
+} from "@/lib/knowledge-captures-types"
+import { cn } from "@/lib/utils"
+import {
+  useGSDWorkspaceActions,
+  useGSDWorkspaceState,
+} from "@/lib/sf-workspace-store"
+
+// ═══════════════════════════════════════════════════════════════════════
+// SHARED HELPERS
+// ═══════════════════════════════════════════════════════════════════════
+
+function PanelHeader({
+  title,
+  subtitle,
+  status,
+  onRefresh,
+  refreshing,
+}: {
+  title: string
+  subtitle?: string | null
+  status?: React.ReactNode
+  onRefresh: () => void
+  refreshing: boolean
+}) {
+  return (
+    <div className="flex items-center justify-between gap-3 pb-4">
+      <div className="flex items-center gap-2.5">
+        <h3 className="text-[13px] font-semibold uppercase tracking-[0.08em] text-muted-foreground">{title}</h3>
+        {status}
+        {subtitle && <span className="text-[11px] text-muted-foreground">{subtitle}</span>}
+      </div>
+      <Button type="button" variant="ghost" size="sm" onClick={onRefresh} disabled={refreshing} className="h-7 gap-1.5 text-xs">
+        <RefreshCw className={cn("h-3 w-3", refreshing && "animate-spin")} />
+        Refresh
+      </Button>
+    </div>
+  )
+}
+
+function PanelError({ message }: { message: string }) {
+  return (
+    <div className="rounded-lg border border-destructive/20 bg-destructive/5 px-3 py-2.5 text-xs text-destructive">
+      {message}
+    </div>
+  )
+}
+
+function PanelLoading({ label }: { label: string }) {
+  return (
+    <div className="flex items-center gap-2 py-6 text-xs text-muted-foreground">
+      <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+      {label}
+    </div>
+  )
+}
+
+function PanelEmpty({ message }: { message: string }) {
+  return (
+    <div className="rounded-lg border border-border/50 bg-card/50 px-4 py-5 text-center text-xs text-muted-foreground">
+      {message}
+    </div>
+  )
+}
+
+function StatPill({ label, value, variant }: { label: string; value: number | string; variant?: "default" | "error" | "warning" | "info" }) {
+  return (
+    <div className={cn(
+      "flex items-center gap-1.5 rounded-md border px-2.5 py-1 text-xs",
+      variant === "error" && "border-destructive/20 bg-destructive/5 text-destructive",
+      variant === "warning" && "border-warning/20 bg-warning/5 text-warning",
+      variant === "info" && "border-info/20 bg-info/5 text-info",
+      (!variant || variant === "default") && "border-border/50 bg-card/50 text-foreground/80",
+    )}>
+      <span className="text-muted-foreground">{label}</span>
+      <span className="font-medium tabular-nums">{value}</span>
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// KNOWLEDGE TYPE STYLING
+// ═══════════════════════════════════════════════════════════════════════
+
+function knowledgeTypeBadge(type: KnowledgeEntry["type"]) {
+  switch (type) {
+    case "rule":
+      return { label: "Rule", className: "border-violet-500/30 bg-violet-500/10 text-violet-400" }
+    case "pattern":
+      return { label: "Pattern", className: "border-info/30 bg-info/10 text-info" }
+    case "lesson":
+      return { label: "Lesson", className: "border-warning/30 bg-warning/10 text-warning" }
+    case "freeform":
+      return { label: "Freeform", className: "border-success/30 bg-success/10 text-success" }
+  }
+}
+
+function KnowledgeTypeIcon({ type, className }: { type: KnowledgeEntry["type"]; className?: string }) {
+  const base = cn("h-3.5 w-3.5 shrink-0", className)
+  switch (type) {
+    case "rule":
+      return <Tag className={cn(base, "text-violet-400")} />
+    case "pattern":
+      return <Repeat2 className={cn(base, "text-info")} />
+    case "lesson":
+      return <Lightbulb className={cn(base, "text-warning")} />
+    case "freeform":
+      return <FileText className={cn(base, "text-success")} />
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// CAPTURE STATUS STYLING
+// ═══════════════════════════════════════════════════════════════════════
+
+function captureStatusStyle(status: CaptureEntry["status"]) {
+  switch (status) {
+    case "pending":
+      return { label: "Pending", className: "border-warning/30 bg-warning/10 text-warning" }
+    case "triaged":
+      return { label: "Triaged", className: "border-info/30 bg-info/10 text-info" }
+    case "resolved":
+      return { label: "Resolved", className: "border-success/30 bg-success/10 text-success" }
+  }
+}
+
+function classificationLabel(c: Classification): string {
+  switch (c) {
+    case "quick-task": return "Quick Task"
+    case "inject": return "Inject"
+    case "defer": return "Defer"
+    case "replan": return "Replan"
+    case "note": return "Note"
+  }
+}
+
+function ClassificationIcon({ classification, className }: { classification: Classification; className?: string }) {
+  const base = cn("h-3 w-3 shrink-0", className)
+  switch (classification) {
+    case "quick-task": return <Zap className={base} />
+    case "inject": return <ArrowRightLeft className={base} />
+    case "defer": return <CalendarClock className={base} />
+    case "replan": return <ListTodo className={base} />
+    case "note": return <StickyNote className={base} />
+  }
+}
+
+const CLASSIFICATION_OPTIONS: Classification[] = ["quick-task", "inject", "defer", "replan", "note"]
+
+// ═══════════════════════════════════════════════════════════════════════
+// KNOWLEDGE TAB CONTENT
+// ═══════════════════════════════════════════════════════════════════════
+
+function KnowledgeEntryRow({ entry }: { entry: KnowledgeEntry }) {
+  const badge = knowledgeTypeBadge(entry.type)
+  return (
+    <div className="group rounded-lg border border-border/50 bg-card/50 px-3 py-2.5 transition-colors hover:bg-card/50">
+      <div className="flex items-start gap-2.5">
+        <KnowledgeTypeIcon type={entry.type} className="mt-0.5" />
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center gap-2">
+            <span className="text-xs font-medium text-foreground truncate">{entry.title}</span>
+            <Badge variant="outline" className={cn("text-[10px] px-1.5 py-0 h-4 shrink-0", badge.className)}>
+              {badge.label}
+            </Badge>
+          </div>
+          {entry.content && (
+            <p className="mt-1 text-[11px] text-muted-foreground line-clamp-2 leading-relaxed">
+              {entry.content}
+            </p>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function KnowledgeTabContent({
+  data,
+  phase,
+  error,
+  onRefresh,
+}: {
+  data: KnowledgeData | null
+  phase: string
+  error: string | null
+  onRefresh: () => void
+}) {
+  if (phase === "loading") return <PanelLoading label="Loading knowledge base…" />
+  if (phase === "error" && error) return <PanelError message={error} />
+  if (!data || data.entries.length === 0) return <PanelEmpty message="No knowledge entries found" />
+
+  return (
+    <div className="space-y-3">
+      <PanelHeader
+        title="Knowledge Base"
+        subtitle={`${data.entries.length} entries`}
+        onRefresh={onRefresh}
+        refreshing={phase === "loading"}
+      />
+      <div className="space-y-1.5">
+        {data.entries.map((entry) => (
+          <KnowledgeEntryRow key={entry.id} entry={entry} />
+        ))}
+      </div>
+      {data.lastModified && (
+        <p className="pt-2 text-[10px] text-muted-foreground">
+          Last modified: {new Date(data.lastModified).toLocaleString()}
+        </p>
+      )}
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// CAPTURES TAB CONTENT
+// ═══════════════════════════════════════════════════════════════════════
+
+function CaptureEntryRow({
+  entry,
+  onResolve,
+  resolvePending,
+}: {
+  entry: CaptureEntry
+  onResolve: (captureId: string, classification: Classification) => void
+  resolvePending: boolean
+}) {
+  const status = captureStatusStyle(entry.status)
+
+  return (
+    <div className="group rounded-lg border border-border/50 bg-card/50 px-3 py-2.5 transition-colors hover:bg-card/50">
+      <div className="flex items-start gap-2.5">
+        <div className={cn(
+          "mt-1 h-2 w-2 shrink-0 rounded-full",
+          entry.status === "pending" && "bg-warning",
+          entry.status === "triaged" && "bg-info",
+          entry.status === "resolved" && "bg-success",
+        )} />
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center gap-2 flex-wrap">
+            <span className="text-xs text-foreground">{entry.text}</span>
+            <Badge variant="outline" className={cn("text-[10px] px-1.5 py-0 h-4 shrink-0", status.className)}>
+              {status.label}
+            </Badge>
+            {entry.classification && (
+              <Badge variant="outline" className="text-[10px] px-1.5 py-0 h-4 shrink-0 border-border/50 text-muted-foreground">
+                {classificationLabel(entry.classification)}
+              </Badge>
+            )}
+          </div>
+          {entry.timestamp && (
+            <div className="mt-1 flex items-center gap-1 text-[10px] text-muted-foreground">
+              <Clock className="h-2.5 w-2.5" />
+              {entry.timestamp}
+            </div>
+          )}
+          {entry.resolution && (
+            <p className="mt-1 text-[10px] text-muted-foreground italic">{entry.resolution}</p>
+          )}
+          {entry.status === "pending" && (
+            <div className="mt-2 flex flex-wrap gap-1">
+              {CLASSIFICATION_OPTIONS.map((c) => (
+                <Button
+                  key={c}
+                  type="button"
+                  variant="outline"
+                  size="sm"
+                  disabled={resolvePending}
+                  onClick={() => onResolve(entry.id, c)}
+                  className="h-6 gap-1 px-2 text-[10px] font-normal border-border/50 hover:bg-foreground/5"
+                >
+                  <ClassificationIcon classification={c} />
+                  {classificationLabel(c)}
+                </Button>
+              ))}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function CapturesTabContent({
+  data,
+  phase,
+  error,
+  resolvePending,
+  resolveError,
+  onRefresh,
+  onResolve,
+}: {
+  data: CapturesData | null
+  phase: string
+  error: string | null
+  resolvePending: boolean
+  resolveError: string | null
+  onRefresh: () => void
+  onResolve: (captureId: string, classification: Classification) => void
+}) {
+  if (phase === "loading") return <PanelLoading label="Loading captures…" />
+  if (phase === "error" && error) return <PanelError message={error} />
+  if (!data || data.entries.length === 0) return <PanelEmpty message="No captures found" />
+
+  return (
+    <div className="space-y-3">
+      <PanelHeader
+        title="Captures"
+        subtitle={`${data.entries.length} total`}
+        status={
+          <div className="flex gap-1.5">
+            <StatPill label="Pending" value={data.pendingCount} variant={data.pendingCount > 0 ? "warning" : "default"} />
+            <StatPill label="Actionable" value={data.actionableCount} variant={data.actionableCount > 0 ? "info" : "default"} />
+          </div>
+        }
+        onRefresh={onRefresh}
+        refreshing={phase === "loading"}
+      />
+
+      {resolveError && (
+        <div className="rounded-lg border border-destructive/20 bg-destructive/5 px-3 py-2 text-[11px] text-destructive">
+          Resolve error: {resolveError}
+        </div>
+      )}
+
+      <div className="space-y-1.5">
+        {data.entries.map((entry) => (
+          <CaptureEntryRow
+            key={entry.id}
+            entry={entry}
+            onResolve={onResolve}
+            resolvePending={resolvePending}
+          />
+        ))}
+      </div>
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// MAIN PANEL COMPONENT
+// ═══════════════════════════════════════════════════════════════════════
+
+interface KnowledgeCapturesPanelProps {
+  initialTab: "knowledge" | "captures"
+}
+
+export function KnowledgeCapturesPanel({ initialTab }: KnowledgeCapturesPanelProps) {
+  const [activeTab, setActiveTab] = useState<"knowledge" | "captures">(initialTab)
+  const workspace = useGSDWorkspaceState()
+  const { loadKnowledgeData, loadCapturesData, resolveCaptureAction } = useGSDWorkspaceActions()
+
+  const knowledgeCaptures = workspace.commandSurface.knowledgeCaptures
+  const knowledgeState = knowledgeCaptures.knowledge
+  const capturesState = knowledgeCaptures.captures
+  const resolveState = knowledgeCaptures.resolveRequest
+
+  const capturesData = capturesState.data as CapturesData | null
+  const pendingCount = capturesData?.pendingCount ?? 0
+
+  const handleResolve = (captureId: string, classification: Classification) => {
+    void resolveCaptureAction({
+      captureId,
+      classification,
+      resolution: "Manual browser triage",
+      rationale: "Triaged via web UI",
+    })
+  }
+
+  return (
+    <div className="space-y-0">
+      {/* Tab bar */}
+      <div className="flex items-center gap-0.5 border-b border-border/50 px-1">
+        <button
+          type="button"
+          onClick={() => setActiveTab("knowledge")}
+          className={cn(
+            "flex items-center gap-1.5 px-3 py-2 text-xs font-medium transition-all border-b-2 -mb-px",
+            activeTab === "knowledge"
+              ? "border-foreground/60 text-foreground"
+              : "border-transparent text-muted-foreground hover:text-muted-foreground",
+          )}
+        >
+          <BookOpen className="h-3.5 w-3.5" />
+          Knowledge
+        </button>
+        <button
+          type="button"
+          onClick={() => setActiveTab("captures")}
+          className={cn(
+            "flex items-center gap-1.5 px-3 py-2 text-xs font-medium transition-all border-b-2 -mb-px",
+            activeTab === "captures"
+              ? "border-foreground/60 text-foreground"
+              : "border-transparent text-muted-foreground hover:text-muted-foreground",
+          )}
+        >
+          <InboxIcon className="h-3.5 w-3.5" />
+          Captures
+          {pendingCount > 0 && (
+            <Badge variant="outline" className="ml-1 h-4 px-1.5 py-0 text-[10px] border-warning/30 bg-warning/10 text-warning">
+              {pendingCount} pending
+            </Badge>
+          )}
+        </button>
+      </div>
+
+      {/* Tab content */}
+      <div className="p-4">
+        {activeTab === "knowledge" ? (
+          <KnowledgeTabContent
+            data={knowledgeState.data as KnowledgeData | null}
+            phase={knowledgeState.phase}
+            error={knowledgeState.error}
+            onRefresh={() => void loadKnowledgeData()}
+          />
+        ) : (
+          <CapturesTabContent
+            data={capturesData}
+            phase={capturesState.phase}
+            error={capturesState.error}
+            resolvePending={resolveState.pending}
+            resolveError={resolveState.lastError}
+            onRefresh={() => void loadCapturesData()}
+            onResolve={handleResolve}
+          />
+        )}
+      </div>
+    </div>
+  )
+}
diff --git a/web/components/sf/loading-skeletons.tsx b/web/components/sf/loading-skeletons.tsx
new file mode 100644
index 000000000..a99462e62
--- /dev/null
+++ b/web/components/sf/loading-skeletons.tsx
@@ -0,0 +1,198 @@
+"use client"
+
+import { Skeleton } from "@/components/ui/skeleton"
+import { cn } from "@/lib/utils"
+
+// ─── Dashboard skeletons ──────────────────────────────────────────────────────
+
+function MetricCardSkeleton({ label, icon }: { label: string; icon: React.ReactNode }) {
+  return (
+    <div className="rounded-md border border-border bg-card p-4">
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0 flex-1">
+          <p className="text-xs font-medium uppercase tracking-wider text-muted-foreground">{label}</p>
+          <Skeleton className="mt-2 h-7 w-24" />
+          <Skeleton className="mt-1.5 h-3 w-20" />
+        </div>
+        <div className="shrink-0 rounded-md bg-accent p-2 text-muted-foreground">{icon}</div>
+      </div>
+    </div>
+  )
+}
+
+function CurrentUnitCardSkeleton({ icon }: { icon: React.ReactNode }) {
+  return (
+    <div className="rounded-md border border-border bg-card p-4">
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0 flex-1">
+          <p className="text-xs font-medium uppercase tracking-wider text-muted-foreground">Current Unit</p>
+          <Skeleton className="mt-2 h-7 w-20" />
+          <Skeleton className="mt-1.5 h-3 w-16" />
+        </div>
+        <div className="shrink-0 rounded-md bg-accent p-2 text-muted-foreground">{icon}</div>
+      </div>
+    </div>
+  )
+}
+
+export function CurrentSliceCardSkeleton() {
+  return (
+    <div className="rounded-md border border-border bg-card">
+      <div className="border-b border-border px-4 py-3">
+        <h2 className="text-sm font-semibold">Current Slice</h2>
+      </div>
+      <div className="space-y-3 p-4">
+        {[1, 2, 3].map((i) => (
+          <div key={i} className="flex items-center gap-3">
+            <Skeleton className="h-4 w-4 shrink-0 rounded-full" />
+            <Skeleton className={cn("h-4", i === 1 ? "w-48" : i === 2 ? "w-40" : "w-36")} />
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+export function SessionCardSkeleton() {
+  return (
+    <div className="rounded-md border border-border bg-card">
+      <div className="border-b border-border px-4 py-3">
+        <h2 className="text-sm font-semibold">Session</h2>
+      </div>
+      <div className="p-4">
+        <div className="space-y-3">
+          {[1, 2, 3].map((i) => (
+            <div key={i} className="flex items-center justify-between text-sm">
+              <div className="flex items-center gap-2">
+                <Skeleton className="h-3.5 w-3.5 rounded" />
+                <span className="text-muted-foreground">{i === 1 ? "Model" : i === 2 ? "Cost" : "Tokens"}</span>
+              </div>
+              <Skeleton className={cn("h-4", i === 1 ? "w-28" : "w-12")} />
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export function RecoveryCardSkeleton() {
+  return (
+    <div className="rounded-md border border-border bg-card">
+      <div className="border-b border-border px-4 py-3">
+        <h2 className="text-sm font-semibold">Recovery Summary</h2>
+      </div>
+      <div className="space-y-4 p-4">
+        <div className="space-y-1.5">
+          <Skeleton className="h-4 w-44" />
+          <Skeleton className="h-3 w-full" />
+          <Skeleton className="h-3 w-3/4" />
+        </div>
+        <div className="space-y-1.5">
+          {[1, 2, 3, 4].map((i) => (
+            <Skeleton key={i} className={cn("h-3", i % 2 === 0 ? "w-28" : "w-36")} />
+          ))}
+        </div>
+        <Skeleton className="h-9 w-36 rounded-md" />
+      </div>
+    </div>
+  )
+}
+
+export function ActivityCardSkeleton() {
+  return (
+    <div className="rounded-md border border-border bg-card">
+      <div className="border-b border-border px-4 py-3">
+        <h2 className="text-sm font-semibold">Recent Activity</h2>
+      </div>
+      <div className="divide-y divide-border">
+        {[1, 2, 3, 4].map((i) => (
+          <div key={i} className="flex items-center gap-3 px-4 py-2.5">
+            <Skeleton className="h-3 w-16 shrink-0" />
+            <Skeleton className="h-1.5 w-1.5 shrink-0 rounded-full" />
+            <Skeleton className={cn("h-4 flex-1", i % 3 === 0 ? "max-w-xs" : i % 3 === 1 ? "max-w-sm" : "max-w-md")} />
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+interface DashboardSkeletonProps {
+  icons: {
+    Activity: React.ReactNode
+    Clock: React.ReactNode
+    DollarSign: React.ReactNode
+    Zap: React.ReactNode
+  }
+}
+
+export function DashboardMetricsSkeleton({ icons }: DashboardSkeletonProps) {
+  return (
+    <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4 2xl:grid-cols-5">
+      <CurrentUnitCardSkeleton icon={icons.Activity} />
+      <MetricCardSkeleton label="Elapsed Time" icon={icons.Clock} />
+      <MetricCardSkeleton label="Total Cost" icon={icons.DollarSign} />
+      <MetricCardSkeleton label="Tokens Used" icon={icons.Zap} />
+      <MetricCardSkeleton label="Progress" icon={icons.Activity} />
+    </div>
+  )
+}
+
+// ─── Sidebar skeletons ────────────────────────────────────────────────────────
+
+/** Only the data-dependent portion of the sidebar content panel */
+export function SidebarDataSkeleton() {
+  return (
+    <>
+      {/* Project path */}
+      <Skeleton className="mt-2 h-3 w-36" />
+
+      {/* Scope section */}
+      <div className="border-b border-border px-3 py-3">
+        <div className="space-y-1.5">
+          <p className="text-[10px] uppercase tracking-wider text-muted-foreground">Active scope</p>
+          <Skeleton className="h-3.5 w-32" />
+          <Skeleton className="h-2.5 w-28" />
+        </div>
+      </div>
+
+      {/* Milestones list */}
+      <div className="flex-1 overflow-y-auto py-1">
+        <div className="px-2 py-1.5">
+          <span className="text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
+            Milestones
+          </span>
+        </div>
+        <div className="space-y-0.5 px-1">
+          {[1, 2].map((m) => (
+            <div key={m}>
+              <div className="flex items-center gap-1.5 px-2 py-1.5">
+                <Skeleton className="h-4 w-4 shrink-0 rounded" />
+                <Skeleton className="h-4 w-4 shrink-0 rounded-full" />
+                <Skeleton className={cn("h-4", m === 1 ? "w-40" : "w-32")} />
+              </div>
+              {m === 1 && (
+                <div className="ml-4 space-y-0.5">
+                  {[1, 2, 3].map((s) => (
+                    <div key={s} className="flex items-center gap-1.5 px-2 py-1.5">
+                      <Skeleton className="h-4 w-4 shrink-0 rounded" />
+                      <Skeleton className="h-4 w-4 shrink-0 rounded-full" />
+                      <Skeleton className={cn("h-3.5", s === 1 ? "w-32" : s === 2 ? "w-28" : "w-24")} />
+                    </div>
+                  ))}
+                </div>
+              )}
+            </div>
+          ))}
+        </div>
+      </div>
+    </>
+  )
+}
+
+// ─── Status bar value skeletons ───────────────────────────────────────────────
+
+export function StatusBarValueSkeleton({ width = "w-16" }: { width?: string }) {
+  return <Skeleton className={cn("h-3 inline-block", width)} />
+}
diff --git a/web/components/sf/main-session-terminal.tsx b/web/components/sf/main-session-terminal.tsx
new file mode 100644
index 000000000..95216badc
--- /dev/null
+++ b/web/components/sf/main-session-terminal.tsx
@@ -0,0 +1,394 @@
+"use client"
+
+import { useCallback, useEffect, useRef, useState } from "react"
+import { useTheme } from "next-themes"
+import { Loader2, ImagePlus } from "lucide-react"
+import { cn } from "@/lib/utils"
+import { validateImageFile } from "@/lib/image-utils"
+import { buildProjectAbsoluteUrl, buildProjectPath } from "@/lib/project-url"
+import { authFetch, appendAuthParam } from "@/lib/auth"
+import { getXtermOptions, getXtermTheme } from "@/lib/xterm-theme"
+import "@xterm/xterm/css/xterm.css"
+
+type XTerminal = import("@xterm/xterm").Terminal
+type XFitAddon = import("@xterm/addon-fit").FitAddon
+
+interface MainSessionTerminalProps {
+  className?: string
+  fontSize?: number
+  projectCwd?: string
+}
+
+const MIN_INITIAL_ATTACH_WIDTH = 180
+const MIN_INITIAL_ATTACH_HEIGHT = 120
+const MIN_INITIAL_ATTACH_COLS = 20
+const MIN_INITIAL_ATTACH_ROWS = 8
+
+function getAttachableTerminalSize(container: HTMLDivElement | null, terminal: XTerminal | null): { cols: number; rows: number } | null {
+  if (!container || !terminal) return null
+
+  const rect = container.getBoundingClientRect()
+  if (rect.width < MIN_INITIAL_ATTACH_WIDTH || rect.height < MIN_INITIAL_ATTACH_HEIGHT) {
+    return null
+  }
+
+  if (terminal.cols < MIN_INITIAL_ATTACH_COLS || terminal.rows < MIN_INITIAL_ATTACH_ROWS) {
+    return null
+  }
+
+  return { cols: terminal.cols, rows: terminal.rows }
+}
+
+async function settleTerminalLayout(
+  container: HTMLDivElement | null,
+  terminal: XTerminal | null,
+  fitAddon: XFitAddon | null,
+  isDisposed: () => boolean,
+): Promise<{ cols: number; rows: number } | null> {
+  if (typeof document !== "undefined" && "fonts" in document) {
+    try {
+      await Promise.race([
+        document.fonts.ready,
+        new Promise<void>((resolve) => setTimeout(resolve, 1000)),
+      ])
+    } catch {
+      // Ignore font loading failures and fall through to repeated fit attempts.
+    }
+  }
+
+  for (let attempt = 0; attempt < 12; attempt++) {
+    if (isDisposed()) return null
+
+    await new Promise<void>((resolve) => {
+      requestAnimationFrame(() => resolve())
+    })
+
+    if (isDisposed()) return null
+
+    try {
+      fitAddon?.fit()
+    } catch {
+      // Hidden or detached.
+    }
+
+    const size = getAttachableTerminalSize(container, terminal)
+    if (size) {
+      return size
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 50))
+  }
+
+  return getAttachableTerminalSize(container, terminal)
+}
+
+export function MainSessionTerminal({ className, fontSize, projectCwd }: MainSessionTerminalProps) {
+  const { resolvedTheme } = useTheme()
+  const isDark = resolvedTheme !== "light"
+  const wrapperRef = useRef<HTMLDivElement>(null)
+  const containerRef = useRef<HTMLDivElement>(null)
+  const termRef = useRef<XTerminal | null>(null)
+  const fitAddonRef = useRef<XFitAddon | null>(null)
+  const eventSourceRef = useRef<EventSource | null>(null)
+  const resizeTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const inputQueueRef = useRef<string[]>([])
+  const flushingRef = useRef(false)
+  const [connectionState, setConnectionState] = useState<"connecting" | "connected" | "error">("connecting")
+  const [hasOutput, setHasOutput] = useState(false)
+  const [isDragOver, setIsDragOver] = useState(false)
+
+  const flushInputQueue = useCallback(async () => {
+    if (flushingRef.current) return
+    flushingRef.current = true
+    while (inputQueueRef.current.length > 0) {
+      const data = inputQueueRef.current.shift()!
+      try {
+        await authFetch(buildProjectPath("/api/bridge-terminal/input", projectCwd), {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ data }),
+        })
+      } catch {
+        inputQueueRef.current.unshift(data)
+        break
+      }
+    }
+    flushingRef.current = false
+  }, [projectCwd])
+
+  const sendInput = useCallback((data: string) => {
+    inputQueueRef.current.push(data)
+    void flushInputQueue()
+  }, [flushInputQueue])
+
+  const sendResize = useCallback((cols: number, rows: number) => {
+    if (resizeTimeoutRef.current) clearTimeout(resizeTimeoutRef.current)
+    resizeTimeoutRef.current = setTimeout(() => {
+      void authFetch(buildProjectPath("/api/bridge-terminal/resize", projectCwd), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ cols, rows }),
+      })
+    }, 75)
+  }, [projectCwd])
+
+  useEffect(() => {
+    if (termRef.current) {
+      termRef.current.options.theme = getXtermTheme(isDark)
+    }
+  }, [isDark])
+
+  useEffect(() => {
+    if (!termRef.current) return
+    termRef.current.options.fontSize = fontSize ?? 13
+    try {
+      fitAddonRef.current?.fit()
+      sendResize(termRef.current.cols, termRef.current.rows)
+    } catch {
+      // Hidden or not mounted yet.
+    }
+  }, [fontSize, sendResize])
+
+  useEffect(() => {
+    if (!containerRef.current) return
+
+    let disposed = false
+    let resizeObserver: ResizeObserver | null = null
+    let terminal: XTerminal | null = null
+    let fitAddon: XFitAddon | null = null
+
+    const init = async () => {
+      const [{ Terminal }, { FitAddon }] = await Promise.all([
+        import("@xterm/xterm"),
+        import("@xterm/addon-fit"),
+      ])
+
+      if (disposed) return
+
+      terminal = new Terminal(getXtermOptions(isDark, fontSize))
+      fitAddon = new FitAddon()
+      terminal.loadAddon(fitAddon)
+      terminal.open(containerRef.current!)
+
+      termRef.current = terminal
+      fitAddonRef.current = fitAddon
+
+      const initialSize = await settleTerminalLayout(containerRef.current, terminal, fitAddon, () => disposed)
+      if (disposed) return
+
+      terminal.onData((data) => {
+        sendInput(data)
+      })
+      terminal.onBinary((data) => {
+        sendInput(data)
+      })
+
+      const connectStream = (preferredSize: { cols: number; rows: number } | null) => {
+        const streamUrl = buildProjectAbsoluteUrl(
+          "/api/bridge-terminal/stream",
+          window.location.origin,
+          projectCwd,
+        )
+        if (preferredSize) {
+          streamUrl.searchParams.set("cols", String(preferredSize.cols))
+          streamUrl.searchParams.set("rows", String(preferredSize.rows))
+        }
+
+        const es = new EventSource(appendAuthParam(streamUrl.toString()))
+        eventSourceRef.current = es
+        setConnectionState((current) => (current === "connected" ? current : "connecting"))
+
+        es.onmessage = (event) => {
+          try {
+            const message = JSON.parse(event.data) as { type: string; data?: string }
+            if (message.type === "connected") {
+              setConnectionState("connected")
+              void settleTerminalLayout(containerRef.current, termRef.current, fitAddonRef.current, () => disposed).then((size) => {
+                if (!size) return
+                sendResize(size.cols, size.rows)
+              })
+              return
+            }
+
+            if (message.type === "output" && typeof message.data === "string") {
+              termRef.current?.write(message.data)
+              setHasOutput(true)
+            }
+          } catch {
+            setConnectionState("error")
+          }
+        }
+
+        es.onerror = () => {
+          setConnectionState("error")
+        }
+      }
+
+      connectStream(initialSize)
+
+      resizeObserver = new ResizeObserver(() => {
+        if (disposed) return
+        try {
+          fitAddon?.fit()
+          if (terminal) {
+            sendResize(terminal.cols, terminal.rows)
+          }
+        } catch {
+          // Hidden or detached.
+        }
+      })
+      resizeObserver.observe(containerRef.current!)
+    }
+
+    void init()
+
+    return () => {
+      disposed = true
+      if (resizeTimeoutRef.current) clearTimeout(resizeTimeoutRef.current)
+      eventSourceRef.current?.close()
+      eventSourceRef.current = null
+      resizeObserver?.disconnect()
+      terminal?.dispose()
+      termRef.current = null
+      fitAddonRef.current = null
+    }
+  }, [fontSize, isDark, projectCwd, sendInput, sendResize])
+
+  const handleClick = useCallback(() => {
+    termRef.current?.focus()
+  }, [])
+
+  // ── Shift+Enter → newline (native DOM, capture phase) ────────────────────
+  // xterm.js sends \r for both Enter and Shift+Enter. The pi TUI editor
+  // recognizes \n (LF) as "insert newline". Capture-phase keydown intercepts
+  // before xterm's internal textarea processes the event.
+  useEffect(() => {
+    const el = wrapperRef.current
+    if (!el) return
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Enter" && e.shiftKey && !e.ctrlKey && !e.altKey && !e.metaKey) {
+        e.preventDefault()
+        e.stopPropagation()
+        sendInput("\n")
+      }
+    }
+
+    el.addEventListener("keydown", onKeyDown, true)
+    return () => el.removeEventListener("keydown", onKeyDown, true)
+  }, [sendInput])
+
+  // ── Drag-and-drop image upload (native DOM, capture phase) ──────────────
+  // React synthetic events don't reliably fire through xterm's internal DOM.
+  // Native capture-phase listeners intercept before xterm can swallow them —
+  // same pattern used for paste in ShellTerminal.
+
+  useEffect(() => {
+    const el = wrapperRef.current
+    if (!el) return
+
+    let counter = 0
+
+    const onDragEnter = (e: DragEvent) => {
+      e.preventDefault()
+      e.stopPropagation()
+      counter += 1
+      if (counter === 1) setIsDragOver(true)
+    }
+
+    const onDragOver = (e: DragEvent) => {
+      e.preventDefault()
+      e.stopPropagation()
+    }
+
+    const onDragLeave = (e: DragEvent) => {
+      e.preventDefault()
+      e.stopPropagation()
+      counter -= 1
+      if (counter <= 0) {
+        counter = 0
+        setIsDragOver(false)
+      }
+    }
+
+    const onDrop = (e: DragEvent) => {
+      e.preventDefault()
+      e.stopPropagation()
+      counter = 0
+      setIsDragOver(false)
+
+      const files = Array.from(e.dataTransfer?.files ?? [])
+      const imageFile = files.find((f) => f.type.startsWith("image/"))
+      if (!imageFile) return
+
+      const validation = validateImageFile(imageFile)
+      if (!validation.valid) {
+        console.warn("[main-terminal-upload] validation failed:", validation.error)
+        return
+      }
+
+      const formData = new FormData()
+      formData.append("file", imageFile)
+
+      void (async () => {
+        try {
+          const res = await authFetch(buildProjectPath("/api/terminal/upload", projectCwd), {
+            method: "POST",
+            body: formData,
+          })
+          const data = (await res.json()) as { ok?: boolean; path?: string; error?: string }
+          if (!res.ok || !data.path) {
+            console.error("[main-terminal-upload] upload failed:", data.error ?? `HTTP ${res.status}`)
+            return
+          }
+          console.log("[main-terminal-upload] injecting path:", data.path)
+          sendInput(`@${data.path} `)
+        } catch (err) {
+          console.error("[main-terminal-upload] upload request failed:", err)
+        }
+      })()
+    }
+
+    el.addEventListener("dragenter", onDragEnter, true)
+    el.addEventListener("dragover", onDragOver, true)
+    el.addEventListener("dragleave", onDragLeave, true)
+    el.addEventListener("drop", onDrop, true)
+    return () => {
+      el.removeEventListener("dragenter", onDragEnter, true)
+      el.removeEventListener("dragover", onDragOver, true)
+      el.removeEventListener("dragleave", onDragLeave, true)
+      el.removeEventListener("drop", onDrop, true)
+    }
+  }, [projectCwd, sendInput])
+
+  useEffect(() => {
+    const timer = setTimeout(() => termRef.current?.focus(), 80)
+    return () => clearTimeout(timer)
+  }, [])
+
+  return (
+    <div
+      ref={wrapperRef}
+      className={cn("relative h-full w-full bg-terminal", className)}
+      onClick={handleClick}
+      data-testid="main-session-native-terminal"
+    >
+      {!hasOutput && (
+        <div className="absolute inset-0 z-10 flex flex-col items-center justify-center gap-3 bg-terminal">
+          <Loader2 className="h-5 w-5 animate-spin text-muted-foreground" />
+          <span className="text-xs text-muted-foreground">
+            {connectionState === "error" ? "Reconnecting main session terminal…" : "Connecting to main session…"}
+          </span>
+        </div>
+      )}
+      {/* Drop overlay */}
+      {isDragOver && (
+        <div className="absolute inset-0 z-20 flex flex-col items-center justify-center gap-2 bg-background backdrop-blur-sm border-2 border-dashed border-primary rounded-md pointer-events-none">
+          <ImagePlus className="h-8 w-8 text-primary" />
+          <span className="text-sm font-medium text-primary">Drop image here</span>
+        </div>
+      )}
+      <div ref={containerRef} className="h-full w-full" style={{ padding: "8px 4px 4px 8px" }} />
+    </div>
+  )
+}
diff --git a/web/components/sf/onboarding-gate.tsx b/web/components/sf/onboarding-gate.tsx
new file mode 100644
index 000000000..15643fc5a
--- /dev/null
+++ b/web/components/sf/onboarding-gate.tsx
@@ -0,0 +1,303 @@
+"use client"
+
+import { useCallback, useEffect, useMemo, useState } from "react"
+import { AnimatePresence, motion } from "motion/react"
+import Image from "next/image"
+import {
+  type WorkspaceOnboardingProviderState,
+  useGSDWorkspaceActions,
+  useGSDWorkspaceState,
+} from "@/lib/sf-workspace-store"
+import { useDevOverrides } from "@/lib/dev-overrides"
+import { useUserMode, type UserMode } from "@/lib/use-user-mode"
+import { navigateToGSDView } from "@/lib/workflow-action-execution"
+import { cn } from "@/lib/utils"
+
+import { StepWelcome } from "./onboarding/step-welcome"
+import { StepMode } from "./onboarding/step-mode"
+import { StepProvider } from "./onboarding/step-provider"
+import { StepAuthenticate } from "./onboarding/step-authenticate"
+import { StepDevRoot } from "./onboarding/step-dev-root"
+import { StepOptional } from "./onboarding/step-optional"
+import { StepRemote } from "./onboarding/step-remote"
+import { StepReady } from "./onboarding/step-ready"
+import { StepProject } from "./onboarding/step-project"
+
+// ─── Constants ──────────────────────────────────────────────────────
+
+const WIZARD_STEPS = [
+  { id: "welcome", label: "Welcome" },
+  { id: "mode", label: "Mode" },
+  { id: "provider", label: "Provider" },
+  { id: "authenticate", label: "Auth" },
+  { id: "devRoot", label: "Root" },
+  { id: "optional", label: "Extras" },
+  { id: "remote", label: "Remote" },
+  { id: "ready", label: "Ready" },
+  { id: "project", label: "Project" },
+] as const
+
+const TOTAL_STEPS = WIZARD_STEPS.length
+const EMPTY_PROVIDERS: WorkspaceOnboardingProviderState[] = []
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function chooseDefaultProvider(providers: WorkspaceOnboardingProviderState[]): string | null {
+  const unresolvedRecommended = providers.find((p) => !p.configured && p.recommended)
+  if (unresolvedRecommended) return unresolvedRecommended.id
+  const unresolved = providers.find((p) => !p.configured)
+  if (unresolved) return unresolved.id
+  return providers[0]?.id ?? null
+}
+
+// Slide animation
+const slideVariants = {
+  enter: (dir: number) => ({ x: dir > 0 ? 50 : -50, opacity: 0 }),
+  center: { x: 0, opacity: 1 },
+  exit: (dir: number) => ({ x: dir < 0 ? 50 : -50, opacity: 0 }),
+}
+
+// ─── Step indicator (centered row of dots with labels) ──────────────
+
+function StepIndicator({ current, total }: { current: number; total: number }) {
+  return (
+    <div className="flex items-center gap-1">
+      {Array.from({ length: total }, (_, i) => (
+        <div
+          key={i}
+          className={cn(
+            "rounded-full transition-all duration-300",
+            i === current
+              ? "h-1.5 w-5 bg-foreground"
+              : i < current
+                ? "h-1.5 w-1.5 bg-foreground/40"
+                : "h-1.5 w-1.5 bg-foreground/10",
+          )}
+        />
+      ))}
+    </div>
+  )
+}
+
+// ─── Main Component ─────────────────────────────────────────────────
+
+export function OnboardingGate() {
+  const workspace = useGSDWorkspaceState()
+  const {
+    refreshOnboarding,
+    saveApiKey,
+    startProviderFlow,
+    submitProviderFlowInput,
+    cancelProviderFlow,
+    refreshBoot,
+  } = useGSDWorkspaceActions()
+  const devOverrides = useDevOverrides()
+
+  const onboarding = workspace.boot?.onboarding
+  const forceVisible = devOverrides.isActive("forceOnboarding")
+  const isBusy = workspace.onboardingRequestState !== "idle"
+
+  // ─── Wizard state ───
+  const [stepIndex, setStepIndex] = useState(0)
+  const [direction, setDirection] = useState(0)
+  const [selectedProviderId, setSelectedProviderId] = useState<string | null>(null)
+  const [dismissedAfterSuccess, setDismissedAfterSuccess] = useState(false)
+  const [userMode, setUserMode] = useUserMode()
+  const [selectedMode, setSelectedMode] = useState<UserMode | null>(userMode)
+
+  const providers = onboarding?.required.providers ?? EMPTY_PROVIDERS
+  const effectiveSelectedProviderId = useMemo(() => {
+    if (onboarding?.activeFlow?.providerId) return onboarding.activeFlow.providerId
+    if (selectedProviderId && providers.some((p) => p.id === selectedProviderId)) return selectedProviderId
+    return chooseDefaultProvider(providers)
+  }, [onboarding?.activeFlow?.providerId, providers, selectedProviderId])
+  const shouldHideAfterSuccess = dismissedAfterSuccess && !onboarding?.locked && !isBusy
+
+  // Track whether auth was locked when the user arrived at step 3.
+  // Auto-advance only fires when auth transitions from locked → unlocked
+  // while the user is on the auth step — not when navigating back or
+  // when the provider was already configured.
+  const [authWasLockedOnArrival, setAuthWasLockedOnArrival] = useState(false)
+
+  const goTo = useCallback(
+    (target: number) => {
+      // When arriving at auth step, snapshot the locked state
+      if (target === 3 && onboarding?.locked) {
+        setAuthWasLockedOnArrival(true)
+      } else if (target === 3 && !onboarding?.locked) {
+        // Already unlocked — don't set the flag (prevents auto-advance)
+        setAuthWasLockedOnArrival(false)
+      }
+      setDirection(target > stepIndex ? 1 : -1)
+      setStepIndex(target)
+    },
+    [stepIndex, onboarding?.locked],
+  )
+
+  // Auto-advance past auth only when it just succeeded during this visit
+  useEffect(() => {
+    if (!onboarding) return
+    if (stepIndex !== 3) return
+    if (!authWasLockedOnArrival) return
+    const isUnlocked = !onboarding.locked
+    const bridgeDone = onboarding.bridgeAuthRefresh.phase === "succeeded" || onboarding.bridgeAuthRefresh.phase === "idle"
+    if (!isUnlocked || !bridgeDone) return
+    const t = window.setTimeout(() => goTo(4), 0)
+    return () => window.clearTimeout(t)
+  }, [onboarding, goTo, stepIndex, authWasLockedOnArrival])
+
+  const selectedProvider = useMemo(() => {
+    return providers.find((p) => p.id === effectiveSelectedProviderId) ?? null
+  }, [effectiveSelectedProviderId, providers])
+
+
+  // ─── Gate check ───
+  if (!onboarding) return null
+  const onboardingSettled =
+    !onboarding.locked ||
+    (onboarding.lastValidation?.status === "succeeded" &&
+      (onboarding.bridgeAuthRefresh.phase === "succeeded" || onboarding.bridgeAuthRefresh.phase === "idle"))
+  if (!forceVisible && (onboardingSettled || shouldHideAfterSuccess)) return null
+
+  const stepLabel = WIZARD_STEPS[stepIndex]?.label ?? ""
+
+  return (
+    <div className="pointer-events-auto absolute inset-0 z-30 flex flex-col bg-background" data-testid="onboarding-gate">
+      {/* Header */}
+      <header className="relative z-10 flex h-12 shrink-0 items-center justify-between px-5 md:px-8">
+        {/* Left — logo */}
+        <div className="flex w-24 items-center gap-2">
+          <Image src="/logo-white.svg" alt="GSD" width={57} height={16} className="hidden h-4 w-auto dark:block" />
+          <Image src="/logo-black.svg" alt="GSD" width={57} height={16} className="h-4 w-auto dark:hidden" />
+        </div>
+
+        {/* Center — step indicator */}
+        <div className="absolute inset-x-0 flex justify-center pointer-events-none">
+          <div className="pointer-events-auto">
+            <StepIndicator current={stepIndex} total={TOTAL_STEPS} />
+          </div>
+        </div>
+
+        {/* Right — step label */}
+        <div className="flex w-24 justify-end">
+          <span className="text-xs text-muted-foreground">{stepLabel}</span>
+        </div>
+      </header>
+
+      {/* Thin progress — hidden when not needed */}
+
+      {/* Content — full remaining height, scrollable */}
+      <div className="flex-1 overflow-y-auto">
+        <div className="mx-auto flex min-h-full w-full max-w-2xl flex-col justify-center px-5 py-10 md:px-8 md:py-16">
+          <AnimatePresence mode="wait" custom={direction}>
+            <motion.div
+              key={stepIndex}
+              custom={direction}
+              variants={slideVariants}
+              initial="enter"
+              animate="center"
+              exit="exit"
+              transition={{ type: "spring", stiffness: 400, damping: 35, opacity: { duration: 0.15 } }}
+            >
+              {stepIndex === 0 && <StepWelcome onNext={() => goTo(1)} />}
+
+              {stepIndex === 1 && (
+                <StepMode
+                  selected={selectedMode}
+                  onSelect={(mode) => { setSelectedMode(mode); setUserMode(mode) }}
+                  onNext={() => goTo(2)}
+                  onBack={() => goTo(0)}
+                />
+              )}
+
+              {stepIndex === 2 && (
+                <StepProvider
+                  providers={onboarding.required.providers}
+                  selectedId={effectiveSelectedProviderId}
+                  onSelect={(id) => {
+                    setSelectedProviderId(id)
+                    goTo(3)
+                  }}
+                  onNext={() => goTo(4)}
+                  onBack={() => goTo(1)}
+                />
+              )}
+
+              {stepIndex === 3 && selectedProvider && (
+                <StepAuthenticate
+                  provider={selectedProvider}
+                  activeFlow={onboarding.activeFlow}
+                  lastValidation={onboarding.lastValidation}
+                  requestState={workspace.onboardingRequestState}
+                  requestProviderId={workspace.onboardingRequestProviderId}
+                  onSaveApiKey={async (pid, key) => {
+                    const next = await saveApiKey(pid, key)
+                    const settled = Boolean(
+                      next && !next.locked &&
+                      (next.bridgeAuthRefresh.phase === "succeeded" || next.bridgeAuthRefresh.phase === "idle"),
+                    )
+                    if (settled) { setDismissedAfterSuccess(true); void refreshBoot() }
+                    return next
+                  }}
+                  onStartFlow={(pid) => void startProviderFlow(pid)}
+                  onSubmitFlowInput={(fid, input) => void submitProviderFlowInput(fid, input)}
+                  onCancelFlow={(fid) => void cancelProviderFlow(fid)}
+                  onBack={() => goTo(2)}
+                  onNext={() => goTo(2)}
+                  bridgeRefreshPhase={onboarding.bridgeAuthRefresh.phase}
+                  bridgeRefreshError={onboarding.bridgeAuthRefresh.error}
+                />
+              )}
+
+              {stepIndex === 4 && <StepDevRoot onBack={() => goTo(2)} onNext={() => goTo(5)} />}
+
+              {stepIndex === 5 && (
+                <StepOptional
+                  sections={onboarding.optional.sections}
+                  onBack={() => goTo(4)}
+                  onNext={() => goTo(6)}
+                />
+              )}
+
+              {stepIndex === 6 && (
+                <StepRemote
+                  onBack={() => goTo(5)}
+                  onNext={() => goTo(7)}
+                />
+              )}
+
+              {stepIndex === 7 && (
+                <StepReady
+                  providerLabel={
+                    onboarding.lastValidation?.providerId
+                      ? onboarding.required.providers.find((p) => p.id === onboarding.lastValidation?.providerId)?.label ?? "Provider"
+                      : "Provider"
+                  }
+                  onFinish={() => goTo(8)}
+                />
+              )}
+
+              {stepIndex === 8 && (
+                <StepProject
+                  onBack={() => goTo(7)}
+                  onBeforeSwitch={() => {
+                    // Disarm the gate BEFORE switchProject triggers a store remount
+                    if (devOverrides.isActive("forceOnboarding")) {
+                      devOverrides.toggle("forceOnboarding")
+                    }
+                    setDismissedAfterSuccess(true)
+                  }}
+                  onFinish={() => {
+                    const mode = selectedMode ?? userMode
+                    navigateToGSDView("dashboard")
+                    void refreshBoot()
+                  }}
+                />
+              )}
+            </motion.div>
+          </AnimatePresence>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/web/components/sf/onboarding/step-authenticate.tsx b/web/components/sf/onboarding/step-authenticate.tsx
new file mode 100644
index 000000000..36544c2d4
--- /dev/null
+++ b/web/components/sf/onboarding/step-authenticate.tsx
@@ -0,0 +1,496 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import { motion, AnimatePresence } from "motion/react"
+import {
+  ArrowRight,
+  ArrowUpRight,
+  CheckCircle2,
+  ClipboardCopy,
+  ExternalLink,
+  KeyRound,
+  LoaderCircle,
+  RotateCcw,
+  ShieldAlert,
+  ShieldCheck,
+  XCircle,
+} from "lucide-react"
+
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Progress } from "@/components/ui/progress"
+import type {
+  WorkspaceOnboardingFlowState,
+  WorkspaceOnboardingProviderState,
+  WorkspaceOnboardingRequestState,
+  WorkspaceOnboardingState,
+  WorkspaceOnboardingValidationResult,
+} from "@/lib/sf-workspace-store"
+import { cn } from "@/lib/utils"
+
+// ─── Error parsing ──────────────────────────────────────────────────
+
+function parseValidationError(raw: string | null | undefined): { title: string; detail: string | null } {
+  if (!raw) return { title: "Validation failed", detail: null }
+
+  const jsonInStatusMatch = raw.match(/^\d{3}\s+[^:]+:\s*(.+)$/s)
+  const jsonCandidate = jsonInStatusMatch?.[1] ?? raw
+
+  try {
+    const parsed = JSON.parse(jsonCandidate)
+    if (typeof parsed === "object" && parsed !== null) {
+      const message = parsed.error_details?.message ?? parsed.error?.message ?? parsed.message ?? parsed.error ?? null
+      if (typeof message === "string" && message.length > 0) {
+        if (/subscription.*(ended|expired|cancelled)/i.test(message))
+          return { title: "Subscription expired", detail: message.replace(/\.$/, "") + ". Check your plan status with this provider." }
+        if (/rate.limit/i.test(message))
+          return { title: "Rate limited", detail: "Too many requests. Wait a moment and try again." }
+        if (/invalid.*key|invalid.*token|incorrect.*key/i.test(message))
+          return { title: "Invalid credentials", detail: "The API key was rejected. Double-check and try again." }
+        if (/quota|billing|payment/i.test(message))
+          return { title: "Billing issue", detail: message }
+        return { title: "Provider error", detail: message }
+      }
+    }
+  } catch { /* not JSON */ }
+
+  if (/^401\b/i.test(raw)) return { title: "Unauthorized", detail: "The credentials were rejected. Double-check your API key." }
+  if (/^403\b/i.test(raw)) return { title: "Access denied", detail: "Your account doesn't have access. Check your subscription or permissions." }
+  if (/^429\b/i.test(raw)) return { title: "Rate limited", detail: "Too many requests. Wait a moment and try again." }
+  if (/^5\d{2}\b/i.test(raw)) return { title: "Server error", detail: "The provider returned an error. Try again in a minute." }
+
+  return { title: "Validation failed", detail: raw.length > 200 ? raw.slice(0, 200) + "…" : raw }
+}
+
+/** Extract a device code from instructions/prompt text */
+function extractDeviceCode(flow: WorkspaceOnboardingFlowState): string | null {
+  const sources = [flow.prompt?.message, flow.auth?.instructions].filter(Boolean)
+  for (const src of sources) {
+    const match = src?.match(/(?:code|Code)[:\s]+([A-Z0-9]{4}[-–][A-Z0-9]{4})/i)
+    if (match) return match[1]
+  }
+  return null
+}
+
+// ─── Component ──────────────────────────────────────────────────────
+
+interface StepAuthenticateProps {
+  provider: WorkspaceOnboardingProviderState
+  activeFlow: WorkspaceOnboardingFlowState | null
+  lastValidation: WorkspaceOnboardingValidationResult | null
+  requestState: WorkspaceOnboardingRequestState
+  requestProviderId: string | null
+  onSaveApiKey: (providerId: string, apiKey: string) => Promise<WorkspaceOnboardingState | null>
+  onStartFlow: (providerId: string) => void
+  onSubmitFlowInput: (flowId: string, input: string) => void
+  onCancelFlow: (flowId: string) => void
+  onBack: () => void
+  onNext: () => void
+  bridgeRefreshPhase: "idle" | "pending" | "succeeded" | "failed"
+  bridgeRefreshError: string | null
+}
+
+export function StepAuthenticate({
+  provider,
+  activeFlow,
+  lastValidation,
+  requestState,
+  requestProviderId,
+  onSaveApiKey,
+  onStartFlow,
+  onSubmitFlowInput,
+  onCancelFlow,
+  onBack,
+  onNext,
+  bridgeRefreshPhase,
+  bridgeRefreshError,
+}: StepAuthenticateProps) {
+  const [apiKey, setApiKey] = useState("")
+  const [flowInput, setFlowInput] = useState("")
+  const [copied, setCopied] = useState(false)
+
+  const isBusy = requestState !== "idle"
+  const isThisProviderBusy = requestProviderId === provider.id && isBusy
+  const isValidated = lastValidation?.status === "succeeded" && lastValidation.providerId === provider.id
+  const isBridgeDone = bridgeRefreshPhase === "succeeded" || bridgeRefreshPhase === "idle"
+  const canProceed = isValidated && isBridgeDone
+  const validationFailed = lastValidation?.status === "failed" && lastValidation.providerId === provider.id
+  const parsedError = validationFailed ? parseValidationError(lastValidation.message) : null
+
+  const isOAuthOnly = !provider.supports.apiKey && provider.supports.oauth
+  const hasOAuth = provider.supports.oauth && provider.supports.oauthAvailable
+  const hasApiKey = provider.supports.apiKey
+
+  // Active flow state
+  const flowActive = activeFlow && activeFlow.providerId === provider.id && !canProceed
+  const flowFailed = flowActive && activeFlow.status === "failed"
+  const flowRunning = flowActive && (activeFlow.status === "running" || activeFlow.status === "awaiting_browser_auth")
+  const flowWaiting = flowActive && activeFlow.status === "awaiting_input"
+  const deviceCode = flowActive ? extractDeviceCode(activeFlow) : null
+
+  useEffect(() => {
+    if (lastValidation?.status !== "succeeded") return
+    const t = window.setTimeout(() => setApiKey(""), 0)
+    return () => window.clearTimeout(t)
+  }, [lastValidation?.checkedAt, lastValidation?.status])
+
+  useEffect(() => {
+    const t = window.setTimeout(() => setFlowInput(""), 0)
+    return () => window.clearTimeout(t)
+  }, [activeFlow?.flowId])
+
+  useEffect(() => {
+    if (!copied) return
+    const t = window.setTimeout(() => setCopied(false), 2000)
+    return () => window.clearTimeout(t)
+  }, [copied])
+
+  const copyCode = (code: string) => {
+    navigator.clipboard.writeText(code).then(() => setCopied(true)).catch(() => {})
+  }
+
+  return (
+    <div className="flex flex-col items-center">
+      <motion.div
+        initial={{ opacity: 0, y: 12 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ duration: 0.4 }}
+        className="text-center"
+      >
+        <h2 className="text-2xl font-bold tracking-tight text-foreground sm:text-3xl">
+          Connect {provider.label}
+        </h2>
+        <p className="mt-2 max-w-sm text-sm leading-relaxed text-muted-foreground">
+          {canProceed
+            ? "Authenticated and ready to go."
+            : hasApiKey && hasOAuth
+              ? "Paste an API key or sign in through your browser."
+              : hasApiKey
+                ? "Paste your API key to authenticate."
+                : "Sign in through your browser to authenticate."}
+        </p>
+      </motion.div>
+
+      <motion.div
+        initial={{ opacity: 0, y: 16 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.08, duration: 0.45 }}
+        className="mt-8 w-full max-w-md space-y-4"
+      >
+        {/* ─── Success state ─── */}
+        <AnimatePresence>
+          {canProceed && (
+            <motion.div
+              initial={{ opacity: 0, scale: 0.95 }}
+              animate={{ opacity: 1, scale: 1 }}
+              transition={{ type: "spring", duration: 0.4, bounce: 0 }}
+              className="flex flex-col items-center gap-3 rounded-xl border border-success/15 bg-success/[0.04] px-6 py-6 text-center"
+            >
+              <div className="flex h-10 w-10 items-center justify-center rounded-full bg-success/15">
+                <ShieldCheck className="h-5 w-5 text-success" />
+              </div>
+              <div className="text-sm font-medium text-foreground">{provider.label} authenticated</div>
+            </motion.div>
+          )}
+        </AnimatePresence>
+
+        {/* ─── Validation error ─── */}
+        {validationFailed && parsedError && (
+          <div className="flex items-start gap-3 rounded-xl border border-destructive/20 bg-destructive/[0.06] px-4 py-3 text-sm">
+            <ShieldAlert className="mt-0.5 h-4 w-4 shrink-0 text-destructive" />
+            <div>
+              <div className="font-medium text-destructive">{parsedError.title}</div>
+              {parsedError.detail && <div className="mt-0.5 text-muted-foreground">{parsedError.detail}</div>}
+            </div>
+          </div>
+        )}
+
+        {/* ─── Bridge refresh ─── */}
+        {bridgeRefreshPhase === "pending" && (
+          <div className="space-y-2">
+            <div className="flex items-center gap-3 rounded-xl border border-foreground/10 bg-foreground/[0.03] px-4 py-3 text-sm text-foreground/80">
+              <LoaderCircle className="h-4 w-4 shrink-0 animate-spin" />
+              Connecting to provider…
+            </div>
+            <Progress value={66} className="h-1" />
+          </div>
+        )}
+
+        {bridgeRefreshPhase === "failed" && bridgeRefreshError && (
+          <div className="flex items-start gap-3 rounded-xl border border-destructive/20 bg-destructive/[0.06] px-4 py-3 text-sm">
+            <ShieldAlert className="mt-0.5 h-4 w-4 shrink-0 text-destructive" />
+            <div>
+              <div className="font-medium text-destructive">Connection failed</div>
+              <div className="mt-0.5 text-muted-foreground">{bridgeRefreshError}</div>
+            </div>
+          </div>
+        )}
+
+        {/* ─── API key form ─── */}
+        {hasApiKey && !canProceed && (
+          <div className="space-y-3 rounded-xl border border-border/50 bg-card/50 p-4">
+            <div className="text-sm font-medium text-foreground">API key</div>
+            <form
+              className="space-y-3"
+              onSubmit={async (e) => {
+                e.preventDefault()
+                if (!apiKey.trim()) return
+                const next = await onSaveApiKey(provider.id, apiKey)
+                if (next && !next.locked && (next.bridgeAuthRefresh.phase === "succeeded" || next.bridgeAuthRefresh.phase === "idle")) {
+                  onNext()
+                }
+              }}
+            >
+              <Input
+                data-testid="onboarding-api-key-input"
+                type="password"
+                autoComplete="off"
+                value={apiKey}
+                onChange={(e) => setApiKey(e.target.value)}
+                placeholder={`Paste your ${provider.label} API key`}
+                disabled={isBusy}
+                className="font-mono text-sm"
+              />
+              <div className="flex items-center gap-2">
+                <Button
+                  type="submit"
+                  disabled={!apiKey.trim() || isBusy}
+                  className="gap-2 transition-transform active:scale-[0.96]"
+                  data-testid="onboarding-save-api-key"
+                >
+                  {isThisProviderBusy && requestState === "saving_api_key" ? (
+                    <LoaderCircle className="h-4 w-4 animate-spin" />
+                  ) : (
+                    <KeyRound className="h-4 w-4" />
+                  )}
+                  Validate & save
+                </Button>
+              </div>
+            </form>
+          </div>
+        )}
+
+        {/* ─── OAuth section ─── */}
+        {hasOAuth && !canProceed && (
+          <div className="space-y-3">
+            {/* Divider between API key and OAuth */}
+            {hasApiKey && (
+              <div className="flex items-center gap-3 py-1">
+                <div className="h-px flex-1 bg-border/50" />
+                <span className="text-xs text-muted-foreground">or</span>
+                <div className="h-px flex-1 bg-border/50" />
+              </div>
+            )}
+
+            {/* ─── No active flow: show start button ─── */}
+            {!flowActive && (
+              <div className="rounded-xl border border-border/50 bg-card/50 p-4">
+                <div className="flex items-center justify-between gap-3">
+                  <div>
+                    <div className="text-sm font-medium text-foreground">Browser sign-in</div>
+                    <p className="mt-0.5 text-xs text-muted-foreground">
+                      Opens a new tab to authenticate with {provider.label}
+                    </p>
+                  </div>
+                  <Button
+                    variant="outline"
+                    disabled={isBusy}
+                    onClick={() => onStartFlow(provider.id)}
+                    className="shrink-0 gap-2 transition-transform active:scale-[0.96]"
+                    data-testid="onboarding-start-provider-flow"
+                  >
+                    {isThisProviderBusy && requestState === "starting_provider_flow" ? (
+                      <LoaderCircle className="h-4 w-4 animate-spin" />
+                    ) : (
+                      <ArrowUpRight className="h-4 w-4" />
+                    )}
+                    Sign in
+                  </Button>
+                </div>
+              </div>
+            )}
+
+            {/* ─── Active flow: device code UX ─── */}
+            {flowActive && (
+              <motion.div
+                initial={{ opacity: 0, y: 8 }}
+                animate={{ opacity: 1, y: 0 }}
+                transition={{ duration: 0.3 }}
+                className="rounded-xl border border-border/50 bg-card/50 p-4 space-y-4"
+                data-testid="onboarding-active-flow"
+              >
+                {/* Device code — big and prominent */}
+                {deviceCode && (
+                  <div className="flex flex-col items-center gap-3 py-2">
+                    <div className="text-xs text-muted-foreground">Enter this code on the sign-in page</div>
+                    <button
+                      type="button"
+                      onClick={() => copyCode(deviceCode)}
+                      className="group flex items-center gap-3 rounded-lg border border-border bg-background/50 px-5 py-3 transition-colors hover:border-foreground/20 active:scale-[0.98]"
+                    >
+                      <span className="font-mono text-2xl font-bold tracking-[0.15em] text-foreground">
+                        {deviceCode}
+                      </span>
+                      <span className="text-muted-foreground transition-colors group-hover:text-muted-foreground">
+                        {copied ? (
+                          <CheckCircle2 className="h-4 w-4 text-success" />
+                        ) : (
+                          <ClipboardCopy className="h-4 w-4" />
+                        )}
+                      </span>
+                    </button>
+                    <div className="text-[11px] text-muted-foreground">
+                      {copied ? "Copied!" : "Click to copy"}
+                    </div>
+                  </div>
+                )}
+
+                {/* Instructions text (when no device code extracted) */}
+                {!deviceCode && activeFlow.auth?.instructions && (
+                  <p className="text-sm text-muted-foreground">{activeFlow.auth.instructions}</p>
+                )}
+
+                {/* Open sign-in page button */}
+                {activeFlow.auth?.url && (
+                  <Button asChild className="w-full gap-2 transition-transform active:scale-[0.96]">
+                    <a href={activeFlow.auth.url} target="_blank" rel="noreferrer">
+                      <ExternalLink className="h-4 w-4" />
+                      Open sign-in page
+                    </a>
+                  </Button>
+                )}
+
+                {/* Status indicator */}
+                <div className="flex items-center justify-between text-xs">
+                  <div className="flex items-center gap-2 text-muted-foreground">
+                    {flowRunning && (
+                      <>
+                        <LoaderCircle className="h-3 w-3 animate-spin" />
+                        <span>Waiting for authentication…</span>
+                      </>
+                    )}
+                    {flowFailed && (
+                      <>
+                        <XCircle className="h-3 w-3 text-destructive" />
+                        <span className="text-destructive">Sign-in failed or timed out</span>
+                      </>
+                    )}
+                    {flowWaiting && !deviceCode && (
+                      <>
+                        <LoaderCircle className="h-3 w-3 animate-spin" />
+                        <span>Waiting for input…</span>
+                      </>
+                    )}
+                  </div>
+                  <div className="flex items-center gap-1">
+                    {flowFailed && (
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="sm"
+                        onClick={() => onStartFlow(provider.id)}
+                        disabled={isBusy}
+                        className="h-7 gap-1.5 text-xs text-muted-foreground"
+                      >
+                        <RotateCcw className="h-3 w-3" />
+                        Retry
+                      </Button>
+                    )}
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="sm"
+                      onClick={() => onCancelFlow(activeFlow.flowId)}
+                      disabled={isBusy}
+                      className="h-7 text-xs text-muted-foreground"
+                    >
+                      Cancel
+                    </Button>
+                  </div>
+                </div>
+
+                {/* Generic prompt input (non-device-code) */}
+                {activeFlow.prompt && !deviceCode && (
+                  <form
+                    className="space-y-2 border-t border-border/50 pt-3"
+                    onSubmit={(e) => {
+                      e.preventDefault()
+                      if (!activeFlow.prompt?.allowEmpty && !flowInput.trim()) return
+                      onSubmitFlowInput(activeFlow.flowId, flowInput)
+                    }}
+                  >
+                    <div className="text-xs text-muted-foreground">{activeFlow.prompt.message}</div>
+                    <div className="flex gap-2">
+                      <Input
+                        data-testid="onboarding-flow-input"
+                        value={flowInput}
+                        onChange={(e) => setFlowInput(e.target.value)}
+                        placeholder={activeFlow.prompt.placeholder || "Enter value"}
+                        disabled={isBusy}
+                        className="text-sm"
+                      />
+                      <Button
+                        type="submit"
+                        disabled={isBusy || (!activeFlow.prompt.allowEmpty && !flowInput.trim())}
+                        className="shrink-0 transition-transform active:scale-[0.96]"
+                      >
+                        {requestState === "submitting_provider_flow_input" ? (
+                          <LoaderCircle className="h-4 w-4 animate-spin" />
+                        ) : (
+                          "Submit"
+                        )}
+                      </Button>
+                    </div>
+                  </form>
+                )}
+
+                {/* Progress messages */}
+                {activeFlow.progress.length > 0 && (
+                  <div className="space-y-1 border-t border-border/50 pt-3">
+                    {activeFlow.progress.map((message, i) => (
+                      <div key={`${activeFlow.flowId}-${i}`} className="text-xs text-muted-foreground">
+                        {message}
+                      </div>
+                    ))}
+                  </div>
+                )}
+              </motion.div>
+            )}
+          </div>
+        )}
+
+        {/* OAuth unavailable */}
+        {provider.supports.oauth && !provider.supports.oauthAvailable && !hasApiKey && (
+          <div className="rounded-xl border border-border/50 bg-card/50 px-4 py-3.5 text-sm text-muted-foreground">
+            Browser sign-in is not available in this runtime. Go back and choose a provider with API-key support.
+          </div>
+        )}
+      </motion.div>
+
+      {/* Navigation */}
+      <motion.div
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        transition={{ delay: 0.15, duration: 0.3 }}
+        className="mt-8 flex w-full max-w-md items-center justify-between"
+      >
+        <Button
+          variant="ghost"
+          onClick={onBack}
+          className="text-muted-foreground transition-transform active:scale-[0.96]"
+        >
+          Back
+        </Button>
+        <Button
+          onClick={onNext}
+          disabled={!canProceed}
+          className="group gap-2 transition-transform active:scale-[0.96]"
+          data-testid="onboarding-auth-continue"
+        >
+          Configure another provider
+          <ArrowRight className="h-4 w-4 transition-transform group-hover:translate-x-0.5" />
+        </Button>
+      </motion.div>
+    </div>
+  )
+}
diff --git a/web/components/sf/onboarding/step-dev-root.tsx b/web/components/sf/onboarding/step-dev-root.tsx
new file mode 100644
index 000000000..eb45d9660
--- /dev/null
+++ b/web/components/sf/onboarding/step-dev-root.tsx
@@ -0,0 +1,369 @@
+"use client"
+
+import { useCallback, useEffect, useState } from "react"
+import { motion, AnimatePresence } from "motion/react"
+import {
+  ArrowRight,
+  ChevronRight,
+  CornerLeftUp,
+  Folder,
+  FolderOpen,
+  FolderRoot,
+  Loader2,
+  SkipForward,
+} from "lucide-react"
+
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { ScrollArea } from "@/components/ui/scroll-area"
+import { cn } from "@/lib/utils"
+import { authFetch } from "@/lib/auth"
+
+interface StepDevRootProps {
+  onNext: () => void
+  onBack: () => void
+}
+
+const SUGGESTED_PATHS = ["~/Projects", "~/Developer", "~/Code", "~/dev"]
+
+// ─── Inline folder browser ──────────────────────────────────────────
+
+interface BrowseEntry {
+  name: string
+  path: string
+}
+
+function InlineFolderBrowser({
+  onSelect,
+  onCancel,
+}: {
+  onSelect: (path: string) => void
+  onCancel: () => void
+}) {
+  const [currentPath, setCurrentPath] = useState("")
+  const [parentPath, setParentPath] = useState<string | null>(null)
+  const [entries, setEntries] = useState<BrowseEntry[]>([])
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const browse = useCallback(async (targetPath?: string) => {
+    setLoading(true)
+    setError(null)
+    try {
+      const param = targetPath ? `?path=${encodeURIComponent(targetPath)}` : ""
+      const res = await authFetch(`/api/browse-directories${param}`)
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({}))
+        throw new Error((body as { error?: string }).error ?? `${res.status}`)
+      }
+      const data = (await res.json()) as { current: string; parent: string | null; entries: BrowseEntry[] }
+      setCurrentPath(data.current)
+      setParentPath(data.parent)
+      setEntries(data.entries)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to browse")
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    void browse()
+  }, [browse])
+
+  return (
+    <div className="rounded-xl border border-border/50 bg-card/50 overflow-hidden">
+      {/* Current path */}
+      <div className="flex items-center justify-between gap-2 border-b border-border/50 px-4 py-2.5">
+        <p className="min-w-0 truncate font-mono text-xs text-muted-foreground" title={currentPath}>
+          {currentPath}
+        </p>
+        <Button
+          type="button"
+          size="sm"
+          onClick={() => onSelect(currentPath)}
+          className="shrink-0 h-7 gap-1.5 text-xs transition-transform active:scale-[0.96]"
+        >
+          Select this folder
+        </Button>
+      </div>
+
+      {/* Directory listing */}
+      <ScrollArea className="h-[240px]">
+        <div className="px-1.5 py-1">
+          {loading && (
+            <div className="flex items-center justify-center py-10">
+              <Loader2 className="h-4 w-4 animate-spin text-muted-foreground" />
+            </div>
+          )}
+
+          {error && (
+            <div className="px-3 py-4 text-center text-xs text-destructive">{error}</div>
+          )}
+
+          {!loading && !error && (
+            <>
+              {parentPath && (
+                <button
+                  type="button"
+                  onClick={() => void browse(parentPath)}
+                  className="flex w-full items-center gap-2.5 rounded-lg px-3 py-2 text-left text-sm transition-colors hover:bg-accent/50"
+                >
+                  <CornerLeftUp className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                  <span className="text-muted-foreground">..</span>
+                </button>
+              )}
+
+              {entries.map((entry) => (
+                <button
+                  key={entry.path}
+                  type="button"
+                  onClick={() => void browse(entry.path)}
+                  className="group flex w-full items-center gap-2.5 rounded-lg px-3 py-2 text-left text-sm transition-colors hover:bg-accent/50"
+                >
+                  <Folder className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                  <span className="min-w-0 flex-1 truncate text-foreground">{entry.name}</span>
+                  <ChevronRight className="h-3 w-3 shrink-0 text-muted-foreground/50 opacity-0 transition-opacity group-hover:opacity-100" />
+                </button>
+              ))}
+
+              {entries.length === 0 && !parentPath && (
+                <div className="px-3 py-8 text-center text-xs text-muted-foreground">
+                  No subdirectories
+                </div>
+              )}
+            </>
+          )}
+        </div>
+      </ScrollArea>
+
+      {/* Cancel */}
+      <div className="border-t border-border/50 px-4 py-2">
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          onClick={onCancel}
+          className="h-7 text-xs text-muted-foreground"
+        >
+          Cancel
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+// ─── Main step ──────────────────────────────────────────────────────
+
+export function StepDevRoot({ onNext, onBack }: StepDevRootProps) {
+  const [path, setPath] = useState("")
+  const [saving, setSaving] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [browsing, setBrowsing] = useState(false)
+
+  const handleSuggestionClick = useCallback((suggestion: string) => {
+    setPath(suggestion)
+    setError(null)
+  }, [])
+
+  const handleContinue = useCallback(async () => {
+    const trimmed = path.trim()
+    if (!trimmed) {
+      setError("Enter a path or skip this step")
+      return
+    }
+
+    setSaving(true)
+    setError(null)
+
+    try {
+      const res = await authFetch("/api/preferences", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ devRoot: trimmed }),
+      })
+
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({}))
+        throw new Error(
+          (body as { error?: string }).error ?? `Request failed (${res.status})`,
+        )
+      }
+
+      onNext()
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to save preference")
+    } finally {
+      setSaving(false)
+    }
+  }, [path, onNext])
+
+  return (
+    <div className="flex flex-col items-center text-center">
+      {/* Icon */}
+      <motion.div
+        initial={{ opacity: 0, scale: 0.85 }}
+        animate={{ opacity: 1, scale: 1 }}
+        transition={{ type: "spring", duration: 0.5, bounce: 0 }}
+        className="mb-8"
+      >
+        <div className="flex h-14 w-14 items-center justify-center rounded-xl border border-border/50 bg-card/50">
+          <FolderRoot className="h-7 w-7 text-foreground/80" strokeWidth={1.5} />
+        </div>
+      </motion.div>
+
+      <motion.h2
+        initial={{ opacity: 0, y: 12 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.06, duration: 0.4 }}
+        className="text-2xl font-bold tracking-tight text-foreground sm:text-3xl"
+      >
+        Dev root
+      </motion.h2>
+
+      <motion.p
+        initial={{ opacity: 0, y: 12 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.12, duration: 0.4 }}
+        className="mt-2 max-w-sm text-sm leading-relaxed text-muted-foreground"
+      >
+        The folder that contains your projects. GSD discovers and manages workspaces inside it.
+      </motion.p>
+
+      {/* Input + browse */}
+      <motion.div
+        initial={{ opacity: 0, y: 16 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.18, duration: 0.45 }}
+        className="mt-8 w-full max-w-md space-y-4"
+      >
+        <AnimatePresence mode="wait">
+          {browsing ? (
+            <motion.div
+              key="browser"
+              initial={{ opacity: 0, height: 0 }}
+              animate={{ opacity: 1, height: "auto" }}
+              exit={{ opacity: 0, height: 0 }}
+              transition={{ duration: 0.2 }}
+            >
+              <InlineFolderBrowser
+                onSelect={(selected) => {
+                  setPath(selected)
+                  setBrowsing(false)
+                  setError(null)
+                }}
+                onCancel={() => setBrowsing(false)}
+              />
+            </motion.div>
+          ) : (
+            <motion.div key="input" className="space-y-4">
+              <div className="flex gap-2">
+                <Input
+                  value={path}
+                  onChange={(e) => {
+                    setPath(e.target.value)
+                    if (error) setError(null)
+                  }}
+                  placeholder="/Users/you/Projects"
+                  className={cn(
+                    "h-11 flex-1 font-mono text-sm",
+                    error && "border-destructive/50 focus-visible:ring-destructive/30",
+                  )}
+                  data-testid="onboarding-devroot-input"
+                  autoFocus
+                  onKeyDown={(e) => {
+                    if (e.key === "Enter" && path.trim()) {
+                      void handleContinue()
+                    }
+                  }}
+                />
+                <Button
+                  type="button"
+                  variant="outline"
+                  onClick={() => setBrowsing(true)}
+                  className="h-11 gap-2 shrink-0 transition-transform active:scale-[0.96]"
+                >
+                  <FolderOpen className="h-4 w-4" />
+                  Browse
+                </Button>
+              </div>
+
+              {error && (
+                <p className="text-sm text-destructive" role="alert">
+                  {error}
+                </p>
+              )}
+
+              {/* Suggestions */}
+              <div className="flex flex-wrap items-center justify-center gap-2">
+                {SUGGESTED_PATHS.map((suggestion) => (
+                  <button
+                    key={suggestion}
+                    type="button"
+                    onClick={() => handleSuggestionClick(suggestion)}
+                    className={cn(
+                      "rounded-full border px-3 py-1 font-mono text-xs transition-all duration-150",
+                      "active:scale-[0.96]",
+                      path === suggestion
+                        ? "border-foreground/25 bg-foreground/10 text-foreground"
+                        : "border-border/50 text-muted-foreground hover:border-foreground/15 hover:text-foreground",
+                    )}
+                  >
+                    {suggestion}
+                  </button>
+                ))}
+              </div>
+            </motion.div>
+          )}
+        </AnimatePresence>
+      </motion.div>
+
+      {/* Navigation */}
+      <motion.div
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        transition={{ delay: 0.25, duration: 0.3 }}
+        className="mt-8 flex w-full max-w-md items-center justify-between"
+      >
+        <Button
+          variant="ghost"
+          onClick={onBack}
+          className="text-muted-foreground transition-transform active:scale-[0.96]"
+        >
+          Back
+        </Button>
+
+        <div className="flex items-center gap-2">
+          <Button
+            variant="ghost"
+            onClick={onNext}
+            className="gap-1.5 text-muted-foreground transition-transform active:scale-[0.96]"
+            data-testid="onboarding-devroot-skip"
+          >
+            Skip
+            <SkipForward className="h-3.5 w-3.5" />
+          </Button>
+
+          <Button
+            onClick={() => void handleContinue()}
+            className="group gap-2 transition-transform active:scale-[0.96]"
+            disabled={saving || browsing}
+            data-testid="onboarding-devroot-continue"
+          >
+            {saving ? (
+              <>
+                <Loader2 className="h-4 w-4 animate-spin" />
+                Saving…
+              </>
+            ) : (
+              <>
+                Continue
+                <ArrowRight className="h-4 w-4 transition-transform group-hover:translate-x-0.5" />
+              </>
+            )}
+          </Button>
+        </div>
+      </motion.div>
+    </div>
+  )
+}
diff --git a/web/components/sf/onboarding/step-mode.tsx b/web/components/sf/onboarding/step-mode.tsx
new file mode 100644
index 000000000..c2f7a2e61
--- /dev/null
+++ b/web/components/sf/onboarding/step-mode.tsx
@@ -0,0 +1,186 @@
+"use client"
+
+import { motion } from "motion/react"
+import { ArrowRight, Code2, MessageCircle } from "lucide-react"
+
+import { Button } from "@/components/ui/button"
+import { cn } from "@/lib/utils"
+import type { UserMode } from "@/lib/use-user-mode"
+
+interface StepModeProps {
+  selected: UserMode | null
+  onSelect: (mode: UserMode) => void
+  onNext: () => void
+  onBack: () => void
+}
+
+const MODE_OPTIONS: {
+  id: UserMode
+  label: string
+  icon: typeof Code2
+  tagline: string
+  description: string
+}[] = [
+  {
+    id: "expert",
+    label: "Expert",
+    icon: Code2,
+    tagline: "Full control",
+    description:
+      "Dashboard metrics, dual-pane power mode, and direct /gsd command access. Built for people who want visibility into every milestone and task.",
+  },
+  {
+    id: "vibe-coder",
+    label: "Vibe Coder",
+    icon: MessageCircle,
+    tagline: "Just chat",
+    description:
+      "Conversational interface with the AI agent. Describe what you want and let GSD handle the structure. Same engine, friendlier surface.",
+  },
+]
+
+export function StepMode({ selected, onSelect, onNext, onBack }: StepModeProps) {
+  return (
+    <div className="flex flex-col items-center text-center">
+      <motion.h2
+        initial={{ opacity: 0, y: 12 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ duration: 0.4 }}
+        className="text-2xl font-bold tracking-tight text-foreground sm:text-3xl"
+        style={{ textWrap: "balance" } as React.CSSProperties}
+      >
+        How do you want to work?
+      </motion.h2>
+
+      <motion.p
+        initial={{ opacity: 0, y: 12 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.06, duration: 0.4 }}
+        className="mt-2 max-w-sm text-sm leading-relaxed text-muted-foreground"
+      >
+        You can switch anytime from settings.
+      </motion.p>
+
+      <motion.div
+        initial={{ opacity: 0, y: 16 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.12, duration: 0.45 }}
+        className="mt-8 grid w-full max-w-lg gap-3 sm:grid-cols-2"
+      >
+        {MODE_OPTIONS.map((opt) => {
+          const isSelected = selected === opt.id
+          const Icon = opt.icon
+
+          return (
+            <button
+              key={opt.id}
+              type="button"
+              onClick={() => onSelect(opt.id)}
+              className={cn(
+                "group relative flex flex-col rounded-xl border px-5 py-5 text-left transition-all duration-200",
+                "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                "active:scale-[0.98]",
+                isSelected
+                  ? "border-foreground/30 bg-foreground/[0.06] shadow-[0_0_0_1px_rgba(255,255,255,0.06)]"
+                  : "border-border/50 bg-card/50 hover:border-foreground/15 hover:bg-card/50",
+              )}
+              data-testid={`onboarding-mode-${opt.id}`}
+            >
+              {/* Selection indicator */}
+              <div className="absolute right-3.5 top-3.5">
+                <div
+                  className={cn(
+                    "flex h-5 w-5 items-center justify-center rounded-full border-[1.5px] transition-all duration-200",
+                    isSelected
+                      ? "border-foreground bg-foreground"
+                      : "border-foreground/20",
+                  )}
+                >
+                  {isSelected && (
+                    <motion.svg
+                      initial={{ scale: 0, opacity: 0 }}
+                      animate={{ scale: 1, opacity: 1 }}
+                      transition={{ type: "spring", duration: 0.3, bounce: 0 }}
+                      viewBox="0 0 12 12"
+                      className="h-2.5 w-2.5 text-background"
+                      fill="none"
+                      stroke="currentColor"
+                      strokeWidth={2.5}
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                    >
+                      <polyline points="2.5 6 5 8.5 9.5 3.5" />
+                    </motion.svg>
+                  )}
+                </div>
+              </div>
+
+              {/* Icon */}
+              <div
+                className={cn(
+                  "mb-4 flex h-10 w-10 items-center justify-center rounded-lg transition-colors duration-200",
+                  isSelected
+                    ? "bg-foreground/10"
+                    : "bg-foreground/[0.04]",
+                )}
+              >
+                <Icon
+                  className={cn(
+                    "h-5 w-5 transition-colors duration-200",
+                    isSelected ? "text-foreground" : "text-muted-foreground",
+                  )}
+                  strokeWidth={1.5}
+                />
+              </div>
+
+              {/* Label + tagline */}
+              <div className="pr-7">
+                <span className="text-[15px] font-semibold text-foreground">
+                  {opt.label}
+                </span>
+                <span
+                  className={cn(
+                    "ml-2 text-xs font-medium transition-colors duration-200",
+                    isSelected ? "text-muted-foreground" : "text-muted-foreground",
+                  )}
+                >
+                  {opt.tagline}
+                </span>
+              </div>
+
+              {/* Description */}
+              <p className="mt-2 text-[13px] leading-relaxed text-muted-foreground">
+                {opt.description}
+              </p>
+            </button>
+          )
+        })}
+      </motion.div>
+
+      {/* Navigation */}
+      <motion.div
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        transition={{ delay: 0.2, duration: 0.3 }}
+        className="mt-8 flex w-full max-w-lg items-center justify-between"
+      >
+        <Button
+          variant="ghost"
+          onClick={onBack}
+          className="text-muted-foreground transition-transform active:scale-[0.96]"
+        >
+          Back
+        </Button>
+        <Button
+          onClick={onNext}
+          disabled={!selected}
+          className="group gap-2 transition-transform active:scale-[0.96]"
+          data-testid="onboarding-mode-continue"
+        >
+          Continue
+          <ArrowRight className="h-4 w-4 transition-transform group-hover:translate-x-0.5" />
+        </Button>
+      </motion.div>
+    </div>
+  )
+}
diff --git a/web/components/sf/onboarding/step-optional.tsx b/web/components/sf/onboarding/step-optional.tsx
new file mode 100644
index 000000000..bbcc68e7c
--- /dev/null
+++ b/web/components/sf/onboarding/step-optional.tsx
@@ -0,0 +1,161 @@
+"use client"
+
+import { motion } from "motion/react"
+import { ArrowRight, Check, CircleDashed } from "lucide-react"
+
+import { Badge } from "@/components/ui/badge"
+import { Button } from "@/components/ui/button"
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
+import type { WorkspaceOnboardingOptionalSectionState } from "@/lib/sf-workspace-store"
+import { cn } from "@/lib/utils"
+
+interface StepOptionalProps {
+  sections: WorkspaceOnboardingOptionalSectionState[]
+  onBack: () => void
+  onNext: () => void
+}
+
+export function StepOptional({ sections, onBack, onNext }: StepOptionalProps) {
+  // Remote questions has its own dedicated step — don't show it here
+  const filtered = sections.filter((s) => s.id !== "remote_questions")
+  const configuredCount = filtered.filter((s) => s.configured).length
+
+  return (
+    <div className="flex flex-col items-center">
+      <motion.div
+        initial={{ opacity: 0, y: 12 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ duration: 0.4 }}
+        className="text-center"
+      >
+        <h2 className="text-2xl font-bold tracking-tight text-foreground sm:text-3xl">
+          Integrations
+        </h2>
+        <p className="mt-2 text-sm leading-relaxed text-muted-foreground">
+          Optional tools. Nothing here blocks the workspace — configure later from settings.
+        </p>
+      </motion.div>
+
+      {configuredCount > 0 && (
+        <motion.div
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          transition={{ delay: 0.08, duration: 0.3 }}
+          className="mt-4"
+        >
+          <span className="text-xs text-muted-foreground">
+            <span className="font-medium text-success">{configuredCount}</span>
+            {" of "}
+            {filtered.length} configured
+          </span>
+        </motion.div>
+      )}
+
+      <motion.div
+        initial={{ opacity: 0, y: 16 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.1, duration: 0.45 }}
+        className="mt-8 w-full space-y-2"
+      >
+        {filtered.map((section) => (
+          <div
+            key={section.id}
+            className={cn(
+              "flex items-start gap-3.5 rounded-xl border px-4 py-3.5 transition-colors",
+              section.configured
+                ? "border-success/15 bg-success/[0.03]"
+                : "border-border/50 bg-card/50",
+            )}
+            data-testid={`onboarding-optional-${section.id}`}
+          >
+            {/* Status dot */}
+            <div
+              className={cn(
+                "mt-0.5 flex h-5 w-5 shrink-0 items-center justify-center rounded-full",
+                section.configured
+                  ? "bg-success/15 text-success"
+                  : "bg-foreground/[0.05] text-muted-foreground",
+              )}
+            >
+              {section.configured ? (
+                <Check className="h-3 w-3" strokeWidth={3} />
+              ) : (
+                <CircleDashed className="h-3 w-3" />
+              )}
+            </div>
+
+            <div className="flex-1 min-w-0">
+              <div className="flex items-center justify-between gap-2">
+                <span className="text-sm font-medium text-foreground">{section.label}</span>
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <Badge
+                      variant="outline"
+                      className={cn(
+                        "text-[10px]",
+                        section.configured
+                          ? "border-success/15 text-success/70"
+                          : "border-border/50 text-muted-foreground",
+                      )}
+                    >
+                      {section.configured ? "Ready" : "Skipped"}
+                    </Badge>
+                  </TooltipTrigger>
+                  <TooltipContent>
+                    {section.configured
+                      ? "This integration is configured and active"
+                      : "You can set this up later from workspace settings"}
+                  </TooltipContent>
+                </Tooltip>
+              </div>
+
+              {section.configuredItems.length > 0 && (
+                <div className="mt-1.5 flex flex-wrap gap-1">
+                  {section.configuredItems.map((item) => (
+                    <Badge
+                      key={item}
+                      variant="outline"
+                      className="border-border/50 text-[10px] text-muted-foreground"
+                    >
+                      {item}
+                    </Badge>
+                  ))}
+                </div>
+              )}
+
+              {section.configuredItems.length === 0 && (
+                <p className="mt-0.5 text-xs text-muted-foreground">
+                  Not configured — add later from settings.
+                </p>
+              )}
+            </div>
+          </div>
+        ))}
+      </motion.div>
+
+      {/* Navigation */}
+      <motion.div
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        transition={{ delay: 0.18, duration: 0.3 }}
+        className="mt-8 flex w-full items-center justify-between"
+      >
+        <Button
+          variant="ghost"
+          onClick={onBack}
+          className="text-muted-foreground transition-transform active:scale-[0.96]"
+        >
+          Back
+        </Button>
+        <Button
+          onClick={onNext}
+          className="group gap-2 transition-transform active:scale-[0.96]"
+          data-testid="onboarding-optional-continue"
+        >
+          Continue
+          <ArrowRight className="h-4 w-4 transition-transform group-hover:translate-x-0.5" />
+        </Button>
+      </motion.div>
+    </div>
+  )
+}
diff --git a/web/components/sf/onboarding/step-project.tsx b/web/components/sf/onboarding/step-project.tsx
new file mode 100644
index 000000000..6eeba3696
--- /dev/null
+++ b/web/components/sf/onboarding/step-project.tsx
@@ -0,0 +1,470 @@
+"use client"
+
+import { useCallback, useEffect, useRef, useState } from "react"
+import { motion } from "motion/react"
+import {
+  ArrowRight,
+  FolderOpen,
+  GitBranch,
+  Layers,
+  Loader2,
+  Plus,
+  Sparkles,
+  Zap,
+} from "lucide-react"
+
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { useProjectStoreManager } from "@/lib/project-store-manager"
+import { cn } from "@/lib/utils"
+import { authFetch } from "@/lib/auth"
+
+// ─── Types ──────────────────────────────────────────────────────────
+
+type ProjectDetectionKind = "active-gsd" | "empty-gsd" | "v1-legacy" | "brownfield" | "blank"
+
+interface ProjectDetectionSignals {
+  hasGsdFolder: boolean
+  hasPlanningFolder: boolean
+  hasGitRepo: boolean
+  hasPackageJson: boolean
+  fileCount: number
+  hasMilestones?: boolean
+  hasCargo?: boolean
+  hasGoMod?: boolean
+  hasPyproject?: boolean
+  isMonorepo?: boolean
+}
+
+interface ProjectProgressInfo {
+  activeMilestone: string | null
+  activeSlice: string | null
+  phase: string | null
+  milestonesCompleted: number
+  milestonesTotal: number
+}
+
+interface ProjectMetadata {
+  name: string
+  path: string
+  kind: ProjectDetectionKind
+  signals: ProjectDetectionSignals
+  lastModified: number
+  progress?: ProjectProgressInfo | null
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+const KIND_STYLE: Record<ProjectDetectionKind, { label: string; color: string; icon: typeof Layers }> = {
+  "active-gsd": { label: "Active", color: "text-success", icon: Layers },
+  "empty-gsd": { label: "Initialized", color: "text-info", icon: FolderOpen },
+  brownfield: { label: "Existing", color: "text-warning", icon: GitBranch },
+  "v1-legacy": { label: "Legacy", color: "text-warning", icon: GitBranch },
+  blank: { label: "New", color: "text-muted-foreground", icon: Sparkles },
+}
+
+function techStack(signals: ProjectDetectionSignals): string[] {
+  const tags: string[] = []
+  if (signals.isMonorepo) tags.push("Monorepo")
+  if (signals.hasGitRepo) tags.push("Git")
+  if (signals.hasPackageJson) tags.push("Node.js")
+  if (signals.hasCargo) tags.push("Rust")
+  if (signals.hasGoMod) tags.push("Go")
+  if (signals.hasPyproject) tags.push("Python")
+  return tags
+}
+
+function progressLabel(p: ProjectProgressInfo): string | null {
+  if (p.milestonesTotal === 0) return null
+  const parts: string[] = []
+  if (p.activeMilestone) parts.push(p.activeMilestone)
+  if (p.activeSlice) parts.push(p.activeSlice)
+  if (p.phase) parts.push(p.phase)
+  return parts.join(" · ") || null
+}
+
+function shortenPath(p: string): string {
+  const home = typeof window !== "undefined" ? "" : ""
+  // Show last 2-3 segments
+  const parts = p.split("/").filter(Boolean)
+  if (parts.length <= 3) return p
+  return "…/" + parts.slice(-2).join("/")
+}
+
+// ─── Component ──────────────────────────────────────────────────────
+
+interface StepProjectProps {
+  onFinish: (projectPath: string) => void
+  onBack: () => void
+  /** Called immediately before a project switch starts — use to disarm gates. */
+  onBeforeSwitch?: () => void
+}
+
+export function StepProject({ onFinish, onBack, onBeforeSwitch }: StepProjectProps) {
+  const manager = useProjectStoreManager()
+
+  const [devRoot, setDevRoot] = useState<string | null>(null)
+  const [projects, setProjects] = useState<ProjectMetadata[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  const [showCreate, setShowCreate] = useState(false)
+  const [newName, setNewName] = useState("")
+  const [creating, setCreating] = useState(false)
+  const [createError, setCreateError] = useState<string | null>(null)
+  const createInputRef = useRef<HTMLInputElement>(null)
+
+  const [switchingTo, setSwitchingTo] = useState<string | null>(null)
+  const switchPollRef = useRef<ReturnType<typeof setInterval> | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    async function load() {
+      setLoading(true)
+      setError(null)
+      try {
+        const prefsRes = await authFetch("/api/preferences")
+        if (!prefsRes.ok) throw new Error("Failed to load preferences")
+        const prefs = await prefsRes.json()
+        if (!prefs.devRoot) { setDevRoot(null); setProjects([]); setLoading(false); return }
+        setDevRoot(prefs.devRoot)
+        const projRes = await authFetch(`/api/projects?root=${encodeURIComponent(prefs.devRoot)}&detail=true`)
+        if (!projRes.ok) throw new Error("Failed to discover projects")
+        const discovered = (await projRes.json()) as ProjectMetadata[]
+        if (!cancelled) setProjects(discovered)
+      } catch (err) {
+        if (!cancelled) setError(err instanceof Error ? err.message : "Unknown error")
+      } finally {
+        if (!cancelled) setLoading(false)
+      }
+    }
+    load()
+    return () => { cancelled = true }
+  }, [])
+
+  useEffect(() => {
+    return () => { if (switchPollRef.current) clearInterval(switchPollRef.current) }
+  }, [])
+
+  useEffect(() => {
+    if (showCreate) {
+      const t = setTimeout(() => createInputRef.current?.focus(), 50)
+      return () => clearTimeout(t)
+    }
+  }, [showCreate])
+
+  const existingNames = projects.map((p) => p.name)
+  const nameValid = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(newName)
+  const nameConflict = existingNames.includes(newName)
+  const canCreate = newName.length > 0 && nameValid && !nameConflict && !creating
+
+  const handleSelectProject = useCallback((project: ProjectMetadata) => {
+    onBeforeSwitch?.()
+    setSwitchingTo(project.path)
+    const store = manager.switchProject(project.path)
+    if (switchPollRef.current) clearInterval(switchPollRef.current)
+    const startTime = Date.now()
+    switchPollRef.current = setInterval(() => {
+      const state = store.getSnapshot()
+      const elapsed = Date.now() - startTime
+      if (state.bootStatus === "ready" || state.bootStatus === "error" || elapsed > 30000) {
+        if (switchPollRef.current) clearInterval(switchPollRef.current)
+        switchPollRef.current = null
+        setSwitchingTo(null)
+        onFinish(project.path)
+      }
+    }, 150)
+  }, [manager, onFinish, onBeforeSwitch])
+
+  const handleCreate = useCallback(async () => {
+    if (!canCreate || !devRoot) return
+    setCreating(true)
+    setCreateError(null)
+    try {
+      const res = await authFetch("/api/projects", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ devRoot, name: newName }),
+      })
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({}))
+        throw new Error((body as { error?: string }).error ?? `Failed (${res.status})`)
+      }
+      const project = (await res.json()) as ProjectMetadata
+      setProjects((prev) => [...prev, project].sort((a, b) => a.name.localeCompare(b.name)))
+      setNewName("")
+      setShowCreate(false)
+      handleSelectProject(project)
+    } catch (err) {
+      setCreateError(err instanceof Error ? err.message : "Failed to create project")
+      setCreating(false)
+    }
+  }, [canCreate, devRoot, newName, handleSelectProject])
+
+  const noDevRoot = !loading && !devRoot
+
+  // Sort: active-gsd first, then by name
+  const sortedProjects = [...projects].sort((a, b) => {
+    const kindOrder: Record<ProjectDetectionKind, number> = { "active-gsd": 0, "empty-gsd": 1, brownfield: 2, "v1-legacy": 3, blank: 4 }
+    const ka = kindOrder[a.kind] ?? 5
+    const kb = kindOrder[b.kind] ?? 5
+    if (ka !== kb) return ka - kb
+    return a.name.localeCompare(b.name)
+  })
+
+  return (
+    <div className="flex flex-col items-center">
+      <motion.div
+        initial={{ opacity: 0, y: 12 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ duration: 0.4 }}
+        className="text-center"
+      >
+        <h2 className="text-2xl font-bold tracking-tight text-foreground sm:text-3xl">
+          Open a project
+        </h2>
+        <p className="mt-2 max-w-sm text-sm leading-relaxed text-muted-foreground">
+          {noDevRoot
+            ? "Set a dev root first to discover your projects."
+            : "Pick a project to start working in, or create a new one."}
+        </p>
+      </motion.div>
+
+      <motion.div
+        initial={{ opacity: 0, y: 16 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.08, duration: 0.45 }}
+        className="mt-8 w-full max-w-lg space-y-2"
+      >
+        {loading && (
+          <div className="flex items-center justify-center gap-2 py-10 text-xs text-muted-foreground">
+            <Loader2 className="h-4 w-4 animate-spin" />
+            Discovering projects…
+          </div>
+        )}
+
+        {error && (
+          <div className="rounded-xl border border-destructive/20 bg-destructive/[0.06] px-4 py-3 text-sm text-destructive">
+            {error}
+          </div>
+        )}
+
+        {noDevRoot && (
+          <div className="rounded-xl border border-border/50 bg-card/50 px-4 py-6 text-center text-sm text-muted-foreground">
+            No dev root configured. Go back and set one, or finish setup to configure later.
+          </div>
+        )}
+
+        {/* Project cards */}
+        {!loading && sortedProjects.length > 0 && (
+          <div className="space-y-2">
+            {sortedProjects.map((project) => {
+              const isSwitching = switchingTo === project.path
+              const style = KIND_STYLE[project.kind]
+              const KindIcon = style.icon
+              const stack = techStack(project.signals)
+              const progress = project.progress ? progressLabel(project.progress) : null
+              const milestoneCount = project.progress
+                ? `${project.progress.milestonesCompleted}/${project.progress.milestonesTotal}`
+                : null
+
+              return (
+                <button
+                  key={project.path}
+                  type="button"
+                  onClick={() => handleSelectProject(project)}
+                  disabled={!!switchingTo}
+                  className={cn(
+                    "group flex w-full items-start gap-3.5 rounded-xl border px-4 py-3.5 text-left transition-all duration-200",
+                    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                    "active:scale-[0.98]",
+                    isSwitching
+                      ? "border-foreground/30 bg-foreground/[0.06]"
+                      : "border-border/50 bg-card/50 hover:border-foreground/15 hover:bg-card/50",
+                    switchingTo && !isSwitching && "opacity-40 pointer-events-none",
+                  )}
+                >
+                  {/* Icon */}
+                  <div className={cn(
+                    "flex h-9 w-9 shrink-0 items-center justify-center rounded-lg mt-0.5",
+                    project.kind === "active-gsd" ? "bg-success/10" : "bg-foreground/[0.04]",
+                  )}>
+                    {isSwitching ? (
+                      <Loader2 className="h-4 w-4 animate-spin text-muted-foreground" />
+                    ) : (
+                      <KindIcon className={cn("h-4 w-4", style.color)} />
+                    )}
+                  </div>
+
+                  {/* Content */}
+                  <div className="min-w-0 flex-1">
+                    {/* Row 1: name + kind badge */}
+                    <div className="flex items-center gap-2">
+                      <span className="text-sm font-semibold text-foreground truncate">{project.name}</span>
+                      <span className={cn("text-[10px] font-medium shrink-0", style.color)}>
+                        {style.label}
+                      </span>
+                    </div>
+
+                    {/* Row 2: tech stack tags */}
+                    {stack.length > 0 && (
+                      <div className="mt-1 flex items-center gap-1.5">
+                        {stack.map((tag) => (
+                          <span
+                            key={tag}
+                            className="rounded bg-foreground/[0.04] px-1.5 py-0.5 text-[10px] text-muted-foreground"
+                          >
+                            {tag}
+                          </span>
+                        ))}
+                      </div>
+                    )}
+
+                    {/* Row 3: progress info (for active-gsd projects) */}
+                    {progress && (
+                      <div className="mt-1.5 text-[11px] text-muted-foreground">
+                        {progress}
+                      </div>
+                    )}
+
+                    {/* Row 4: milestone bar (for active-gsd with milestones) */}
+                    {project.progress && project.progress.milestonesTotal > 0 && (
+                      <div className="mt-2 flex items-center gap-2">
+                        <div className="h-1 flex-1 overflow-hidden rounded-full bg-foreground/[0.06]">
+                          <div
+                            className="h-full rounded-full bg-success/60 transition-all"
+                            style={{
+                              width: `${Math.round((project.progress.milestonesCompleted / project.progress.milestonesTotal) * 100)}%`,
+                            }}
+                          />
+                        </div>
+                        <span className="text-[10px] tabular-nums text-muted-foreground">
+                          {milestoneCount}
+                        </span>
+                      </div>
+                    )}
+                  </div>
+
+                  {/* Arrow */}
+                  <ArrowRight className="mt-1 h-4 w-4 shrink-0 text-muted-foreground/50 transition-all group-hover:text-muted-foreground group-hover:translate-x-0.5" />
+                </button>
+              )
+            })}
+          </div>
+        )}
+
+        {!loading && devRoot && projects.length === 0 && !error && (
+          <div className="rounded-xl border border-border/50 bg-card/50 px-4 py-6 text-center text-sm text-muted-foreground">
+            No projects found in {devRoot}
+          </div>
+        )}
+
+        {/* Create new project */}
+        {!loading && devRoot && (
+          <>
+            {!showCreate ? (
+              <button
+                type="button"
+                onClick={() => setShowCreate(true)}
+                disabled={!!switchingTo}
+                className={cn(
+                  "flex w-full items-center gap-3.5 rounded-xl border border-dashed px-4 py-3.5 text-left transition-all duration-200",
+                  "border-border/50 text-muted-foreground hover:border-foreground/15 hover:text-foreground",
+                  "active:scale-[0.98]",
+                  switchingTo && "opacity-40 pointer-events-none",
+                )}
+              >
+                <div className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-foreground/[0.04]">
+                  <Plus className="h-4 w-4" />
+                </div>
+                <div>
+                  <span className="text-sm font-medium">Create new project</span>
+                  <p className="mt-0.5 text-[11px] text-muted-foreground">Initialize a new directory with Git</p>
+                </div>
+              </button>
+            ) : (
+              <motion.div
+                initial={{ opacity: 0, height: 0 }}
+                animate={{ opacity: 1, height: "auto" }}
+                transition={{ duration: 0.2 }}
+                className="rounded-xl border border-border/50 bg-card/50 p-4 space-y-3"
+              >
+                <div className="text-sm font-medium text-foreground">New project</div>
+                <form
+                  onSubmit={(e) => { e.preventDefault(); void handleCreate() }}
+                  className="space-y-2"
+                >
+                  <Input
+                    ref={createInputRef}
+                    value={newName}
+                    onChange={(e) => { setNewName(e.target.value); setCreateError(null) }}
+                    placeholder="my-project"
+                    autoComplete="off"
+                    className="text-sm"
+                    disabled={creating}
+                  />
+                  {newName && !nameValid && (
+                    <p className="text-xs text-destructive">Letters, numbers, hyphens, underscores, dots. Must start with a letter or number.</p>
+                  )}
+                  {nameConflict && (
+                    <p className="text-xs text-destructive">A project with this name already exists</p>
+                  )}
+                  {createError && (
+                    <p className="text-xs text-destructive">{createError}</p>
+                  )}
+                  {newName && nameValid && !nameConflict && (
+                    <p className="font-mono text-xs text-muted-foreground">{devRoot}/{newName}</p>
+                  )}
+                  <div className="flex items-center gap-2 pt-1">
+                    <Button
+                      type="submit"
+                      size="sm"
+                      disabled={!canCreate}
+                      className="gap-1.5 transition-transform active:scale-[0.96]"
+                    >
+                      {creating ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : <Plus className="h-3.5 w-3.5" />}
+                      Create & open
+                    </Button>
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="sm"
+                      onClick={() => { setShowCreate(false); setNewName(""); setCreateError(null) }}
+                      disabled={creating}
+                      className="text-muted-foreground"
+                    >
+                      Cancel
+                    </Button>
+                  </div>
+                </form>
+              </motion.div>
+            )}
+          </>
+        )}
+      </motion.div>
+
+      {/* Navigation */}
+      <motion.div
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        transition={{ delay: 0.15, duration: 0.3 }}
+        className="mt-8 flex w-full max-w-lg items-center justify-between"
+      >
+        <Button
+          variant="ghost"
+          onClick={onBack}
+          className="text-muted-foreground transition-transform active:scale-[0.96]"
+        >
+          Back
+        </Button>
+        <Button
+          onClick={() => { onBeforeSwitch?.(); onFinish("") }}
+          className="group gap-2 transition-transform active:scale-[0.96]"
+        >
+          Finish setup
+          <Zap className="h-4 w-4 transition-transform group-hover:scale-110" />
+        </Button>
+      </motion.div>
+    </div>
+  )
+}
diff --git a/web/components/sf/onboarding/step-provider.tsx b/web/components/sf/onboarding/step-provider.tsx
new file mode 100644
index 000000000..c807c7010
--- /dev/null
+++ b/web/components/sf/onboarding/step-provider.tsx
@@ -0,0 +1,189 @@
+"use client"
+
+import { useMemo } from "react"
+import { motion } from "motion/react"
+import { ArrowRight, Check, ShieldCheck } from "lucide-react"
+
+import { Badge } from "@/components/ui/badge"
+import { Button } from "@/components/ui/button"
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
+import type { WorkspaceOnboardingProviderState } from "@/lib/sf-workspace-store"
+import { cn } from "@/lib/utils"
+
+interface StepProviderProps {
+  providers: WorkspaceOnboardingProviderState[]
+  selectedId: string | null
+  onSelect: (id: string) => void
+  onNext: () => void
+  onBack: () => void
+}
+
+function capabilityBadges(provider: WorkspaceOnboardingProviderState): string[] {
+  const badges: string[] = []
+  if (provider.supports.apiKey) badges.push("API key")
+  if (provider.supports.oauth)
+    badges.push(provider.supports.oauthAvailable ? "Browser sign-in" : "OAuth unavailable")
+  return badges
+}
+
+function configuredViaLabel(source: WorkspaceOnboardingProviderState["configuredVia"]): string {
+  switch (source) {
+    case "auth_file": return "Saved auth"
+    case "environment": return "Environment variable"
+    case "runtime": return "Runtime"
+    default: return "Not configured"
+  }
+}
+
+/** Group providers: configured first, then recommended, then rest. */
+function groupProviders(providers: WorkspaceOnboardingProviderState[]): {
+  label: string
+  items: WorkspaceOnboardingProviderState[]
+}[] {
+  const configured = providers.filter((p) => p.configured)
+  const recommended = providers.filter((p) => !p.configured && p.recommended)
+  const rest = providers.filter((p) => !p.configured && !p.recommended)
+
+  const groups: { label: string; items: WorkspaceOnboardingProviderState[] }[] = []
+  if (configured.length > 0) groups.push({ label: "Configured", items: configured })
+  if (recommended.length > 0) groups.push({ label: "Recommended", items: recommended })
+  if (rest.length > 0) groups.push({ label: "Other Providers", items: rest })
+  return groups
+}
+
+export function StepProvider({ providers, selectedId, onSelect, onNext, onBack }: StepProviderProps) {
+  const groups = useMemo(() => groupProviders(providers), [providers])
+  const hasConfigured = providers.some((p) => p.configured)
+
+  return (
+    <div className="flex flex-col items-center">
+      <motion.div
+        initial={{ opacity: 0, y: 12 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ duration: 0.4 }}
+        className="text-center"
+      >
+        <h2 className="text-2xl font-bold tracking-tight text-foreground sm:text-3xl">
+          Choose a provider
+        </h2>
+        <p className="mt-2 text-sm leading-relaxed text-muted-foreground">
+          Click a provider to configure it. Set up as many as you want, then continue.
+        </p>
+      </motion.div>
+
+      <motion.div
+        initial={{ opacity: 0, y: 16 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.08, duration: 0.45 }}
+        className="mt-8 w-full space-y-5"
+      >
+        {groups.map((group) => (
+          <div key={group.label}>
+            <div className="mb-2 px-0.5 text-[11px] font-medium uppercase tracking-widest text-muted-foreground">
+              {group.label}
+            </div>
+            <div className="grid gap-2 sm:grid-cols-2">
+              {group.items.map((provider) => {
+                const selected = provider.id === selectedId
+                return (
+                  <button
+                    key={provider.id}
+                    type="button"
+                    onClick={() => onSelect(provider.id)}
+                    className={cn(
+                      "group relative rounded-xl border px-4 py-3.5 text-left transition-all duration-200",
+                      "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                      "active:scale-[0.98]",
+                      selected
+                        ? "border-foreground/30 bg-foreground/[0.06]"
+                        : "border-border/50 bg-card/50 hover:border-foreground/15 hover:bg-card/50",
+                    )}
+                    data-testid={`onboarding-provider-${provider.id}`}
+                  >
+                    {/* Radio dot */}
+                    <div className="absolute right-3 top-3">
+                      <div
+                        className={cn(
+                          "flex h-5 w-5 items-center justify-center rounded-full border-[1.5px] transition-all duration-200",
+                          selected ? "border-foreground bg-foreground" : "border-foreground/15",
+                        )}
+                      >
+                        {selected && <Check className="h-2.5 w-2.5 text-background" strokeWidth={3} />}
+                      </div>
+                    </div>
+
+                    <div className="pr-8">
+                      <div className="flex items-center gap-2">
+                        <span className="text-sm font-semibold text-foreground">{provider.label}</span>
+                        {provider.recommended && (
+                          <Badge variant="outline" className="border-foreground/10 bg-foreground/[0.03] text-[9px] text-muted-foreground">
+                            Recommended
+                          </Badge>
+                        )}
+                      </div>
+
+                      <div className="mt-1 flex items-center gap-1.5 text-xs text-muted-foreground">
+                        {provider.configured ? (
+                          <>
+                            <ShieldCheck className="h-3 w-3 text-success/80" />
+                            <span>{configuredViaLabel(provider.configuredVia)}</span>
+                          </>
+                        ) : (
+                          <span className="text-muted-foreground">Not configured</span>
+                        )}
+                      </div>
+                    </div>
+
+                    <div className="mt-2.5 flex flex-wrap gap-1">
+                      {capabilityBadges(provider).map((cap) => (
+                        <Tooltip key={cap}>
+                          <TooltipTrigger asChild>
+                            <Badge variant="outline" className="border-border/50 text-[10px] text-muted-foreground">
+                              {cap}
+                            </Badge>
+                          </TooltipTrigger>
+                          <TooltipContent side="bottom">
+                            {cap === "API key"
+                              ? "Enter an API key to authenticate"
+                              : cap === "Browser sign-in"
+                                ? "Authenticate through your browser"
+                                : "This auth method is not available"}
+                          </TooltipContent>
+                        </Tooltip>
+                      ))}
+                    </div>
+                  </button>
+                )
+              })}
+            </div>
+          </div>
+        ))}
+      </motion.div>
+
+      {/* Navigation — pinned inside the step */}
+      <motion.div
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        transition={{ delay: 0.15, duration: 0.3 }}
+        className="mt-8 flex w-full items-center justify-between"
+      >
+        <Button
+          variant="ghost"
+          onClick={onBack}
+          className="text-muted-foreground transition-transform active:scale-[0.96]"
+        >
+          Back
+        </Button>
+        <Button
+          onClick={onNext}
+          disabled={!hasConfigured}
+          className="group gap-2 transition-transform active:scale-[0.96]"
+          data-testid="onboarding-provider-continue"
+        >
+          Continue
+          <ArrowRight className="h-4 w-4 transition-transform group-hover:translate-x-0.5" />
+        </Button>
+      </motion.div>
+    </div>
+  )
+}
diff --git a/web/components/sf/onboarding/step-ready.tsx b/web/components/sf/onboarding/step-ready.tsx
new file mode 100644
index 000000000..96c17dd81
--- /dev/null
+++ b/web/components/sf/onboarding/step-ready.tsx
@@ -0,0 +1,98 @@
+"use client"
+
+import Image from "next/image"
+import { motion } from "motion/react"
+import { CheckCircle2, Zap } from "lucide-react"
+
+import { Button } from "@/components/ui/button"
+
+interface StepReadyProps {
+  providerLabel: string
+  onFinish: () => void
+}
+
+export function StepReady({ providerLabel, onFinish }: StepReadyProps) {
+  return (
+    <div className="flex flex-col items-center text-center">
+      {/* Success icon with staggered entrance */}
+      <motion.div
+        initial={{ opacity: 0, scale: 0.7 }}
+        animate={{ opacity: 1, scale: 1 }}
+        transition={{ type: "spring", duration: 0.6, bounce: 0.15 }}
+        className="relative mb-8"
+      >
+        <div className="absolute inset-0 rounded-full bg-success/10 blur-2xl" />
+        <div className="relative flex h-16 w-16 items-center justify-center rounded-2xl border border-success/20 bg-success/10">
+          <CheckCircle2 className="h-8 w-8 text-success" strokeWidth={1.5} />
+        </div>
+      </motion.div>
+
+      <motion.h2
+        initial={{ opacity: 0, y: 12 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.1, duration: 0.4 }}
+        className="text-3xl font-bold tracking-tight text-foreground sm:text-4xl"
+      >
+        You&apos;re all set
+      </motion.h2>
+
+      <motion.p
+        initial={{ opacity: 0, y: 12 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.18, duration: 0.4 }}
+        className="mt-3 max-w-sm text-[15px] leading-relaxed text-muted-foreground"
+      >
+        <span className="font-medium text-foreground">{providerLabel}</span> is
+        validated. The workspace is live.
+      </motion.p>
+
+      {/* Compact summary strip */}
+      <motion.div
+        initial={{ opacity: 0, y: 12 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.26, duration: 0.4 }}
+        className="mt-8 flex items-center gap-4 rounded-xl border border-border/50 bg-card/50 px-5 py-3"
+      >
+        <div className="flex items-center gap-2 text-xs text-muted-foreground">
+          <Image
+            src="/logo-icon-white.svg"
+            alt=""
+            width={14}
+            height={14}
+            className="hidden opacity-40 dark:block"
+          />
+          <Image
+            src="/logo-icon-black.svg"
+            alt=""
+            width={14}
+            height={14}
+            className="opacity-40 dark:hidden"
+          />
+          <span>Shell unlocked</span>
+        </div>
+        <div className="h-3 w-px bg-border" />
+        <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
+          <span className="h-1.5 w-1.5 rounded-full bg-success" />
+          <span>{providerLabel}</span>
+        </div>
+      </motion.div>
+
+      <motion.div
+        initial={{ opacity: 0, y: 8 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.35, duration: 0.4 }}
+        className="mt-8"
+      >
+        <Button
+          size="lg"
+          className="group gap-2.5 px-8 text-[15px] transition-transform active:scale-[0.96]"
+          onClick={onFinish}
+          data-testid="onboarding-finish"
+        >
+          Launch workspace
+          <Zap className="h-4 w-4 transition-transform group-hover:scale-110" />
+        </Button>
+      </motion.div>
+    </div>
+  )
+}
diff --git a/web/components/sf/onboarding/step-remote.tsx b/web/components/sf/onboarding/step-remote.tsx
new file mode 100644
index 000000000..143199470
--- /dev/null
+++ b/web/components/sf/onboarding/step-remote.tsx
@@ -0,0 +1,385 @@
+"use client"
+
+import { useCallback, useEffect, useState } from "react"
+import { motion } from "motion/react"
+import {
+  ArrowRight,
+  CheckCircle2,
+  Eye,
+  EyeOff,
+  KeyRound,
+  LoaderCircle,
+  MessageSquare,
+  SkipForward,
+} from "lucide-react"
+
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { cn } from "@/lib/utils"
+import { authFetch } from "@/lib/auth"
+
+// ─── Types ──────────────────────────────────────────────────────────
+
+type RemoteChannel = "slack" | "discord" | "telegram"
+
+interface RemoteQuestionsApiResponse {
+  config: {
+    channel: RemoteChannel
+    channelId: string
+    timeoutMinutes: number
+    pollIntervalSeconds: number
+  } | null
+  envVarSet: boolean
+  tokenSet: boolean
+  envVarName: string | null
+  status: string
+  error?: string
+}
+
+const CHANNEL_OPTIONS: { value: RemoteChannel; label: string; description: string }[] = [
+  { value: "slack", label: "Slack", description: "Get notified in a Slack channel" },
+  { value: "discord", label: "Discord", description: "Get notified in a Discord channel" },
+  { value: "telegram", label: "Telegram", description: "Get notified via Telegram bot" },
+]
+
+const CHANNEL_ID_HINTS: Record<RemoteChannel, string> = {
+  slack: "Channel ID (e.g. C01ABCD2EFG)",
+  discord: "Channel ID (17–20 digit number)",
+  telegram: "Chat ID (numeric, may start with -)",
+}
+
+const CHANNEL_ID_PATTERNS: Record<RemoteChannel, RegExp> = {
+  slack: /^[A-Z0-9]{9,12}$/,
+  discord: /^\d{17,20}$/,
+  telegram: /^-?\d{5,20}$/,
+}
+
+const ENV_KEYS: Record<RemoteChannel, string> = {
+  slack: "SLACK_BOT_TOKEN",
+  discord: "DISCORD_BOT_TOKEN",
+  telegram: "TELEGRAM_BOT_TOKEN",
+}
+
+// ─── Component ──────────────────────────────────────────────────────
+
+interface StepRemoteProps {
+  onBack: () => void
+  onNext: () => void
+}
+
+export function StepRemote({ onBack, onNext }: StepRemoteProps) {
+  const [channel, setChannel] = useState<RemoteChannel | null>(null)
+  const [channelId, setChannelId] = useState("")
+  const [saving, setSaving] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [success, setSuccess] = useState(false)
+  const [alreadyConfigured, setAlreadyConfigured] = useState(false)
+  const [loading, setLoading] = useState(true)
+  const [botToken, setBotToken] = useState("")
+  const [showToken, setShowToken] = useState(false)
+  const [savingToken, setSavingToken] = useState(false)
+  const [tokenSet, setTokenSet] = useState(false)
+  const [tokenSuccess, setTokenSuccess] = useState<string | null>(null)
+
+  // Check if already configured
+  useEffect(() => {
+    authFetch("/api/remote-questions", { cache: "no-store" })
+      .then((res) => res.json())
+      .then((data: RemoteQuestionsApiResponse) => {
+        if (data.tokenSet) setTokenSet(true)
+        if (data.status === "configured" && data.config) {
+          setAlreadyConfigured(true)
+          setChannel(data.config.channel)
+          setChannelId(data.config.channelId)
+          setSuccess(true)
+        }
+      })
+      .catch(() => {})
+      .finally(() => setLoading(false))
+  }, [])
+
+  const channelIdValid =
+    channel !== null &&
+    channelId.trim().length > 0 &&
+    CHANNEL_ID_PATTERNS[channel].test(channelId.trim())
+
+  const handleSave = useCallback(async () => {
+    if (!channel || !channelIdValid) return
+    setSaving(true)
+    setError(null)
+
+    try {
+      const res = await authFetch("/api/remote-questions", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          channel,
+          channelId: channelId.trim(),
+          timeoutMinutes: 5,
+          pollIntervalSeconds: 5,
+        }),
+      })
+      const json = await res.json()
+      if (!res.ok) {
+        setError(json.error ?? `Save failed (${res.status})`)
+        return
+      }
+      setSuccess(true)
+      setAlreadyConfigured(true)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to save")
+    } finally {
+      setSaving(false)
+    }
+  }, [channel, channelId, channelIdValid])
+
+  const handleSaveToken = useCallback(async () => {
+    if (!channel || !botToken.trim()) return
+    setSavingToken(true)
+    setError(null)
+    setTokenSuccess(null)
+    try {
+      const res = await authFetch("/api/remote-questions", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ channel, token: botToken.trim() }),
+      })
+      const json = await res.json()
+      if (!res.ok) { setError(json.error ?? `Token save failed (${res.status})`); return }
+      setTokenSuccess(`Token saved (${json.masked})`)
+      setTokenSet(true)
+      setBotToken("")
+      setShowToken(false)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to save token")
+    } finally {
+      setSavingToken(false)
+    }
+  }, [channel, botToken])
+
+  return (
+    <div className="flex flex-col items-center">
+      {/* Icon */}
+      <motion.div
+        initial={{ opacity: 0, scale: 0.85 }}
+        animate={{ opacity: 1, scale: 1 }}
+        transition={{ type: "spring", duration: 0.5, bounce: 0 }}
+        className="mb-8"
+      >
+        <div className="flex h-14 w-14 items-center justify-center rounded-xl border border-border/50 bg-card/50">
+          <MessageSquare className="h-7 w-7 text-foreground/80" strokeWidth={1.5} />
+        </div>
+      </motion.div>
+
+      <motion.div
+        initial={{ opacity: 0, y: 12 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.06, duration: 0.4 }}
+        className="text-center"
+      >
+        <h2 className="text-2xl font-bold tracking-tight text-foreground sm:text-3xl">
+          Remote notifications
+        </h2>
+        <p className="mt-2 max-w-sm text-sm leading-relaxed text-muted-foreground">
+          Get notified when GSD needs your input. Connect a chat channel and
+          the agent pings you instead of waiting silently.
+        </p>
+      </motion.div>
+
+      <motion.div
+        initial={{ opacity: 0, y: 16 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.12, duration: 0.45 }}
+        className="mt-8 w-full max-w-md space-y-5"
+      >
+        {/* Already configured banner */}
+        {success && (
+          <div className="flex items-center gap-3 rounded-xl border border-success/15 bg-success/[0.04] px-4 py-3 text-sm">
+            <CheckCircle2 className="h-4 w-4 shrink-0 text-success" />
+            <span className="text-muted-foreground">
+              {alreadyConfigured && !saving
+                ? `Connected to ${channel ?? "channel"}`
+                : "Configuration saved"}
+            </span>
+          </div>
+        )}
+
+        {/* Channel picker */}
+        {!loading && (
+          <div className="space-y-2">
+            <div className="text-xs font-medium text-muted-foreground">Channel</div>
+            <div className="grid grid-cols-3 gap-2">
+              {CHANNEL_OPTIONS.map((opt) => (
+                <button
+                  key={opt.value}
+                  type="button"
+                  onClick={() => {
+                    setChannel(opt.value)
+                    setError(null)
+                    if (success && !alreadyConfigured) setSuccess(false)
+                  }}
+                  disabled={saving}
+                  className={cn(
+                    "rounded-xl border px-3 py-3 text-left transition-all duration-200",
+                    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                    "active:scale-[0.97]",
+                    channel === opt.value
+                      ? "border-foreground/30 bg-foreground/[0.06]"
+                      : "border-border/50 bg-card/50 hover:border-foreground/15 hover:bg-card/50",
+                  )}
+                >
+                  <div className="text-sm font-medium text-foreground">{opt.label}</div>
+                  <div className="mt-0.5 text-[11px] text-muted-foreground">{opt.description}</div>
+                </button>
+              ))}
+            </div>
+          </div>
+        )}
+
+        {/* Channel ID input */}
+        {channel && !loading && (
+          <div className="space-y-2">
+            <div className="text-xs font-medium text-muted-foreground">Channel ID</div>
+            <Input
+              value={channelId}
+              onChange={(e) => {
+                setChannelId(e.target.value)
+                if (error) setError(null)
+              }}
+              placeholder={CHANNEL_ID_HINTS[channel]}
+              disabled={saving}
+              className="font-mono text-sm"
+              onKeyDown={(e) => {
+                if (e.key === "Enter" && channelIdValid) {
+                  void handleSave()
+                }
+              }}
+            />
+            {channelId.trim().length > 0 && !CHANNEL_ID_PATTERNS[channel].test(channelId.trim()) && (
+              <p className="text-xs text-destructive/70">
+                Doesn't match the expected format for {channel}
+              </p>
+            )}
+          </div>
+        )}
+
+        {/* Bot token input */}
+        {channel && !loading && (
+          <div className="space-y-2">
+            <div className="text-xs font-medium text-muted-foreground">
+              Bot token
+              {tokenSet && (
+                <span className="ml-2 text-success">✓ configured</span>
+              )}
+            </div>
+
+            {tokenSuccess && (
+              <div className="flex items-center gap-2 rounded-xl border border-success/15 bg-success/[0.04] px-3 py-2 text-xs text-muted-foreground">
+                <CheckCircle2 className="h-3.5 w-3.5 shrink-0 text-success" />
+                {tokenSuccess}
+              </div>
+            )}
+
+            <div className="flex gap-2">
+              <div className="relative flex-1">
+                <Input
+                  type={showToken ? "text" : "password"}
+                  value={botToken}
+                  onChange={(e) => setBotToken(e.target.value)}
+                  placeholder={`Paste your ${ENV_KEYS[channel]}`}
+                  disabled={savingToken}
+                  className="pr-9 font-mono text-sm"
+                  onKeyDown={(e) => {
+                    if (e.key === "Enter" && botToken.trim()) void handleSaveToken()
+                  }}
+                />
+                <button
+                  type="button"
+                  onClick={() => setShowToken((v) => !v)}
+                  className="absolute right-3 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-muted-foreground transition-colors"
+                >
+                  {showToken ? <EyeOff className="h-3.5 w-3.5" /> : <Eye className="h-3.5 w-3.5" />}
+                </button>
+              </div>
+              <Button
+                type="button"
+                variant="outline"
+                onClick={() => void handleSaveToken()}
+                disabled={!botToken.trim() || savingToken}
+                className="gap-1.5 transition-transform active:scale-[0.96]"
+              >
+                {savingToken ? <LoaderCircle className="h-3.5 w-3.5 animate-spin" /> : <KeyRound className="h-3.5 w-3.5" />}
+                Save
+              </Button>
+            </div>
+          </div>
+        )}
+
+        {/* Error */}
+        {error && (
+          <div className="rounded-xl border border-destructive/20 bg-destructive/[0.06] px-4 py-3 text-sm text-destructive">
+            {error}
+          </div>
+        )}
+
+        {/* Save button */}
+        {channel && channelId.trim().length > 0 && !success && (
+          <Button
+            onClick={() => void handleSave()}
+            disabled={!channelIdValid || saving}
+            className="gap-2 transition-transform active:scale-[0.96]"
+          >
+            {saving ? (
+              <LoaderCircle className="h-4 w-4 animate-spin" />
+            ) : (
+              <CheckCircle2 className="h-4 w-4" />
+            )}
+            Save & connect
+          </Button>
+        )}
+
+        {loading && (
+          <div className="flex items-center gap-2 py-4 text-xs text-muted-foreground">
+            <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+            Checking existing configuration…
+          </div>
+        )}
+      </motion.div>
+
+      {/* Navigation */}
+      <motion.div
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        transition={{ delay: 0.2, duration: 0.3 }}
+        className="mt-8 flex w-full max-w-md items-center justify-between"
+      >
+        <Button
+          variant="ghost"
+          onClick={onBack}
+          className="text-muted-foreground transition-transform active:scale-[0.96]"
+        >
+          Back
+        </Button>
+        <div className="flex items-center gap-2">
+          {!success && (
+            <Button
+              variant="ghost"
+              onClick={onNext}
+              className="gap-1.5 text-muted-foreground transition-transform active:scale-[0.96]"
+            >
+              Skip
+              <SkipForward className="h-3.5 w-3.5" />
+            </Button>
+          )}
+          <Button
+            onClick={onNext}
+            className="group gap-2 transition-transform active:scale-[0.96]"
+          >
+            {success ? "Continue" : "Continue"}
+            <ArrowRight className="h-4 w-4 transition-transform group-hover:translate-x-0.5" />
+          </Button>
+        </div>
+      </motion.div>
+    </div>
+  )
+}
diff --git a/web/components/sf/onboarding/step-welcome.tsx b/web/components/sf/onboarding/step-welcome.tsx
new file mode 100644
index 000000000..feeae92b1
--- /dev/null
+++ b/web/components/sf/onboarding/step-welcome.tsx
@@ -0,0 +1,87 @@
+"use client"
+
+import Image from "next/image"
+import { motion } from "motion/react"
+import { ArrowRight } from "lucide-react"
+
+import { Button } from "@/components/ui/button"
+
+interface StepWelcomeProps {
+  onNext: () => void
+}
+
+export function StepWelcome({ onNext }: StepWelcomeProps) {
+  return (
+    <div className="flex flex-col items-center text-center">
+      {/* Logo mark with glow */}
+      <motion.div
+        initial={{ opacity: 0, scale: 0.8 }}
+        animate={{ opacity: 1, scale: 1 }}
+        transition={{ type: "spring", duration: 0.6, bounce: 0 }}
+        className="relative"
+      >
+        <div className="absolute inset-0 rounded-2xl bg-foreground/5 blur-2xl" />
+        <div className="relative mb-4 flex h-18 items-center justify-center">
+          <Image
+            src="/logo-white.svg"
+            alt="GSD"
+            height={70}
+            width={200}
+            className="hidden dark:block"
+          />
+          <Image
+            src="/logo-black.svg"
+            alt="GSD"
+            height={70}
+            width={200}
+            className="dark:hidden"
+          />
+        </div>
+      </motion.div>
+
+      {/* Headline */}
+      <motion.p
+        initial={{ opacity: 0, y: 12 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.16, duration: 0.4 }}
+        className="max-w-sm text-[15px] leading-relaxed text-muted-foreground"
+      >
+        Let's get your workspace ready. This takes about a minute.
+      </motion.p>
+
+      {/* Steps preview */}
+      <motion.div
+        initial={{ opacity: 0, y: 12 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.24, duration: 0.4 }}
+        className="mt-10 flex items-center gap-3 text-xs text-muted-foreground"
+      >
+        {["Mode", "Provider", "Auth", "Workspace"].map((label, i) => (
+          <span key={label} className="flex items-center gap-3">
+            {i > 0 && (
+              <span className="h-px w-5 bg-border" />
+            )}
+            <span className="font-medium">{label}</span>
+          </span>
+        ))}
+      </motion.div>
+
+      <motion.div
+        initial={{ opacity: 0, y: 8 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.35, duration: 0.4 }}
+        className="mt-10"
+      >
+        <Button
+          size="lg"
+          className="group gap-2.5 px-8 text-[15px] transition-transform active:scale-[0.96]"
+          onClick={onNext}
+          data-testid="onboarding-start"
+        >
+          Get started
+          <ArrowRight className="h-4 w-4 transition-transform group-hover:translate-x-0.5" />
+        </Button>
+      </motion.div>
+    </div>
+  )
+}
diff --git a/web/components/sf/onboarding/wizard-stepper.tsx b/web/components/sf/onboarding/wizard-stepper.tsx
new file mode 100644
index 000000000..d62a442cf
--- /dev/null
+++ b/web/components/sf/onboarding/wizard-stepper.tsx
@@ -0,0 +1,88 @@
+"use client"
+
+import { cn } from "@/lib/utils"
+import { Check } from "lucide-react"
+
+export interface WizardStep {
+  id: string
+  label: string
+  shortLabel?: string
+}
+
+interface WizardStepperProps {
+  steps: WizardStep[]
+  currentIndex: number
+  onStepClick?: (index: number) => void
+  className?: string
+}
+
+export function WizardStepper({ steps, currentIndex, onStepClick, className }: WizardStepperProps) {
+  return (
+    <nav aria-label="Onboarding progress" className={cn("flex items-center gap-0", className)}>
+      {steps.map((step, index) => {
+        const isComplete = index < currentIndex
+        const isCurrent = index === currentIndex
+        const isClickable = onStepClick && index <= currentIndex
+
+        return (
+          <div key={step.id} className="flex items-center">
+            {/* Step node */}
+            <button
+              type="button"
+              onClick={() => isClickable && onStepClick(index)}
+              disabled={!isClickable}
+              aria-current={isCurrent ? "step" : undefined}
+              className={cn(
+                "group relative flex items-center gap-2.5 rounded-full px-1 py-1 transition-all duration-300",
+                isClickable && "cursor-pointer",
+                !isClickable && "cursor-default",
+              )}
+            >
+              {/* Circle indicator */}
+              <div
+                className={cn(
+                  "relative flex h-8 w-8 shrink-0 items-center justify-center rounded-full border-2 transition-all duration-300",
+                  isComplete && "border-foreground/80 bg-foreground/90 text-background",
+                  isCurrent && "border-foreground bg-foreground text-background shadow-[0_0_12px_rgba(255,255,255,0.15)]",
+                  !isComplete && !isCurrent && "border-border bg-background text-muted-foreground",
+                )}
+              >
+                {isComplete ? (
+                  <Check className="h-3.5 w-3.5" strokeWidth={3} />
+                ) : (
+                  <span className={cn("text-xs font-semibold tabular-nums", isCurrent && "text-background")}>
+                    {index + 1}
+                  </span>
+                )}
+              </div>
+
+              {/* Label */}
+              <span
+                className={cn(
+                  "hidden text-sm font-medium transition-colors duration-200 sm:inline",
+                  isCurrent && "text-foreground",
+                  isComplete && "text-muted-foreground",
+                  !isComplete && !isCurrent && "text-muted-foreground",
+                )}
+              >
+                {step.shortLabel ?? step.label}
+              </span>
+            </button>
+
+            {/* Connector line */}
+            {index < steps.length - 1 && (
+              <div className="mx-1 hidden h-px w-8 sm:block lg:w-12">
+                <div
+                  className={cn(
+                    "h-full transition-all duration-500",
+                    index < currentIndex ? "bg-foreground/50" : "bg-border",
+                  )}
+                />
+              </div>
+            )}
+          </div>
+        )
+      })}
+    </nav>
+  )
+}
diff --git a/web/components/sf/project-welcome.tsx b/web/components/sf/project-welcome.tsx
new file mode 100644
index 000000000..55193d6ab
--- /dev/null
+++ b/web/components/sf/project-welcome.tsx
@@ -0,0 +1,253 @@
+"use client"
+
+import {
+  ArrowRight,
+  FolderOpen,
+  GitBranch,
+  Package,
+  FileCode,
+  Sparkles,
+  ArrowUpCircle,
+  Folder,
+} from "lucide-react"
+import { cn } from "@/lib/utils"
+import type { ProjectDetection } from "@/lib/sf-workspace-store"
+
+// ─── Variant Config ─────────────────────────────────────────────────────────
+
+interface WelcomeVariant {
+  icon: React.ReactNode
+  headline: string
+  body: string
+  detail?: string
+  primaryLabel: string
+  primaryCommand: string
+  secondary?: {
+    label: string
+    action: "files-view" | "command"
+    command?: string
+  }
+}
+
+function getVariant(detection: ProjectDetection): WelcomeVariant {
+  switch (detection.kind) {
+    case "brownfield":
+      return {
+        icon: <FolderOpen className="h-8 w-8 text-foreground" strokeWidth={1.5} />,
+        headline: "Existing project detected",
+        body: "GSD will map your codebase and ask a few questions about what you want to build. From there it generates structured milestones and deliverable slices.",
+        primaryLabel: "Map & Initialize",
+        primaryCommand: "/gsd",
+        secondary: {
+          label: "Browse files first",
+          action: "files-view",
+        },
+      }
+
+    case "v1-legacy":
+      return {
+        icon: <ArrowUpCircle className="h-8 w-8 text-foreground" strokeWidth={1.5} />,
+        headline: "GSD v1 project found",
+        body: "This project has a .planning/ folder from an earlier GSD version. Migration converts your existing planning data into the new .gsd/ format.",
+        detail: "Your original files will be preserved — migration creates the new structure alongside them.",
+        primaryLabel: "Migrate to v2",
+        primaryCommand: "/gsd migrate",
+        secondary: {
+          label: "Start fresh instead",
+          action: "command",
+          command: "/gsd",
+        },
+      }
+
+    case "blank":
+      return {
+        icon: <Sparkles className="h-8 w-8 text-foreground" strokeWidth={1.5} />,
+        headline: "Start a new project",
+        body: "This folder is empty. GSD will ask what you want to build, then generate a structured plan — milestones broken into deliverable slices with risk-ordered execution.",
+        primaryLabel: "Start Project Setup",
+        primaryCommand: "/gsd",
+      }
+
+    // active-gsd and empty-gsd shouldn't reach here, but handle gracefully
+    default:
+      return {
+        icon: <Folder className="h-8 w-8 text-foreground" strokeWidth={1.5} />,
+        headline: "Set up your project",
+        body: "Run the GSD wizard to get started.",
+        primaryLabel: "Get Started",
+        primaryCommand: "/gsd",
+      }
+  }
+}
+
+// ─── Signal Chips ───────────────────────────────────────────────────────────
+
+function SignalChip({ icon, label }: { icon: React.ReactNode; label: string }) {
+  return (
+    <span className="inline-flex items-center gap-1.5 rounded-md border border-border bg-card px-2.5 py-1 text-xs text-muted-foreground">
+      {icon}
+      {label}
+    </span>
+  )
+}
+
+function SignalChips({ signals }: { signals: ProjectDetection["signals"] }) {
+  const chips: { icon: React.ReactNode; label: string }[] = []
+
+  if (signals.hasGitRepo) {
+    chips.push({ icon: <GitBranch className="h-3 w-3" />, label: "Git repository" })
+  }
+  if (signals.hasPackageJson) {
+    chips.push({ icon: <Package className="h-3 w-3" />, label: "Node.js project" })
+  }
+  if (signals.fileCount > 0) {
+    chips.push({
+      icon: <FileCode className="h-3 w-3" />,
+      label: `${signals.fileCount} file${signals.fileCount === 1 ? "" : "s"}`,
+    })
+  }
+
+  if (chips.length === 0) return null
+
+  return (
+    <div className="flex flex-wrap gap-2">
+      {chips.map((chip) => (
+        <SignalChip key={chip.label} icon={chip.icon} label={chip.label} />
+      ))}
+    </div>
+  )
+}
+
+// ─── Main Component ─────────────────────────────────────────────────────────
+
+interface ProjectWelcomeProps {
+  detection: ProjectDetection
+  onCommand: (command: string) => void
+  onSwitchView: (view: string) => void
+  disabled?: boolean
+}
+
+export function ProjectWelcome({
+  detection,
+  onCommand,
+  onSwitchView,
+  disabled = false,
+}: ProjectWelcomeProps) {
+  const variant = getVariant(detection)
+  const showSignals = detection.kind === "brownfield" || detection.kind === "v1-legacy"
+
+  return (
+    <div className="flex h-full items-center justify-center p-8">
+      <div className="w-full max-w-lg">
+        {/* Icon */}
+        <div className="mb-6 flex h-16 w-16 items-center justify-center rounded-xl border border-border bg-card">
+          {variant.icon}
+        </div>
+
+        {/* Headline */}
+        <h2 className="text-2xl font-bold tracking-tight text-foreground">
+          {variant.headline}
+        </h2>
+
+        {/* Body */}
+        <p className="mt-3 text-sm leading-relaxed text-muted-foreground">
+          {variant.body}
+        </p>
+
+        {/* Detail note */}
+        {variant.detail && (
+          <p className="mt-2 text-xs leading-relaxed text-muted-foreground">
+            {variant.detail}
+          </p>
+        )}
+
+        {/* Detected signals */}
+        {showSignals && (
+          <div className="mt-5">
+            <SignalChips signals={detection.signals} />
+          </div>
+        )}
+
+        {/* Actions */}
+        <div className="mt-8 flex items-center gap-3">
+          <button
+            onClick={() => onCommand(variant.primaryCommand)}
+            disabled={disabled}
+            className={cn(
+              "inline-flex items-center gap-2 rounded-md bg-foreground px-5 py-2.5 text-sm font-medium text-background transition-colors hover:bg-foreground/90",
+              disabled && "cursor-not-allowed opacity-50",
+            )}
+          >
+            {variant.primaryLabel}
+            <ArrowRight className="h-3.5 w-3.5" />
+          </button>
+
+          {variant.secondary && (
+            <button
+              onClick={() => {
+                if (variant.secondary!.action === "files-view") {
+                  onSwitchView("files")
+                } else if (variant.secondary!.command) {
+                  onCommand(variant.secondary!.command)
+                }
+              }}
+              disabled={disabled}
+              className={cn(
+                "inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-4 py-2.5 text-sm font-medium text-foreground transition-colors hover:bg-accent",
+                disabled && "cursor-not-allowed opacity-50",
+              )}
+            >
+              {variant.secondary.label}
+            </button>
+          )}
+        </div>
+
+        {/* What happens next — for blank projects */}
+        {detection.kind === "blank" && (
+          <div className="mt-8 rounded-lg border border-border/50 bg-card/50 p-4">
+            <p className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
+              What happens next
+            </p>
+            <ul className="mt-2.5 space-y-2">
+              {[
+                "A few questions about what you're building",
+                "Codebase analysis and context gathering",
+                "Structured milestone and slice generation",
+              ].map((step, i) => (
+                <li key={i} className="flex items-start gap-2.5 text-xs text-muted-foreground">
+                  <span className="mt-0.5 flex h-4 w-4 shrink-0 items-center justify-center rounded-full border border-border text-[10px] font-medium text-muted-foreground">
+                    {i + 1}
+                  </span>
+                  {step}
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+
+        {/* What happens next — for brownfield */}
+        {detection.kind === "brownfield" && (
+          <div className="mt-8 rounded-lg border border-border/50 bg-card/50 p-4">
+            <p className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
+              What happens next
+            </p>
+            <ul className="mt-2.5 space-y-2">
+              {[
+                "GSD scans your codebase and asks about your goals",
+                "You discuss scope, constraints, and priorities",
+                "A milestone with risk-ordered slices is generated",
+              ].map((step, i) => (
+                <li key={i} className="flex items-start gap-2.5 text-xs text-muted-foreground">
+                  <span className="mt-0.5 flex h-4 w-4 shrink-0 items-center justify-center rounded-full border border-border text-[10px] font-medium text-muted-foreground">
+                    {i + 1}
+                  </span>
+                  {step}
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
diff --git a/web/components/sf/projects-view.tsx b/web/components/sf/projects-view.tsx
new file mode 100644
index 000000000..af3903015
--- /dev/null
+++ b/web/components/sf/projects-view.tsx
@@ -0,0 +1,1328 @@
+"use client"
+
+import Image from "next/image"
+import { useEffect, useState, useCallback, useRef, useSyncExternalStore } from "react"
+import {
+  FolderOpen,
+  Loader2,
+  AlertCircle,
+  Layers,
+  Sparkles,
+  ArrowUpCircle,
+  GitBranch,
+  CheckCircle2,
+  FolderRoot,
+  Plus,
+  ArrowRight,
+  X,
+  ChevronRight,
+  Folder,
+  CornerLeftUp,
+  Search,
+  Clock,
+} from "lucide-react"
+import { cn } from "@/lib/utils"
+import { useProjectStoreManager } from "@/lib/project-store-manager"
+import {
+  useGSDWorkspaceState,
+  getLiveWorkspaceIndex,
+  getLiveAutoDashboard,
+  formatCost,
+  getCurrentSlice,
+} from "@/lib/sf-workspace-store"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from "@/components/ui/sheet"
+import { ScrollArea } from "@/components/ui/scroll-area"
+import { authFetch } from "@/lib/auth"
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog"
+
+// ─── Types (mirroring server-side ProjectMetadata) ─────────────────────────
+
+type ProjectDetectionKind = "active-gsd" | "empty-gsd" | "v1-legacy" | "brownfield" | "blank"
+
+interface ProjectDetectionSignals {
+  hasGsdFolder: boolean
+  hasPlanningFolder: boolean
+  hasGitRepo: boolean
+  hasPackageJson: boolean
+  fileCount: number
+  hasMilestones?: boolean
+  hasCargo?: boolean
+  hasGoMod?: boolean
+  hasPyproject?: boolean
+  isMonorepo?: boolean
+}
+
+interface ProjectProgressInfo {
+  activeMilestone: string | null
+  activeSlice: string | null
+  phase: string | null
+  milestonesCompleted: number
+  milestonesTotal: number
+}
+
+interface ProjectMetadata {
+  name: string
+  path: string
+  kind: ProjectDetectionKind
+  signals: ProjectDetectionSignals
+  lastModified: number
+  progress?: ProjectProgressInfo | null
+}
+
+// ─── Kind style config ─────────────────────────────────────────────────
+
+const KIND_STYLE: Record<ProjectDetectionKind, { label: string; color: string; bgClass: string; icon: typeof Layers }> = {
+  "active-gsd": {
+    label: "Active",
+    color: "text-success",
+    bgClass: "bg-success/10",
+    icon: Layers,
+  },
+  "empty-gsd": {
+    label: "Initialized",
+    color: "text-info",
+    bgClass: "bg-info/10",
+    icon: FolderOpen,
+  },
+  brownfield: {
+    label: "Existing",
+    color: "text-warning",
+    bgClass: "bg-warning/10",
+    icon: GitBranch,
+  },
+  "v1-legacy": {
+    label: "Legacy",
+    color: "text-warning",
+    bgClass: "bg-warning/10",
+    icon: ArrowUpCircle,
+  },
+  blank: {
+    label: "New",
+    color: "text-muted-foreground",
+    bgClass: "bg-foreground/[0.04]",
+    icon: Sparkles,
+  },
+}
+
+function techStack(signals: ProjectDetectionSignals): string[] {
+  const tags: string[] = []
+  if (signals.isMonorepo) tags.push("Monorepo")
+  if (signals.hasGitRepo) tags.push("Git")
+  if (signals.hasPackageJson) tags.push("Node.js")
+  if (signals.hasCargo) tags.push("Rust")
+  if (signals.hasGoMod) tags.push("Go")
+  if (signals.hasPyproject) tags.push("Python")
+  return tags
+}
+
+function progressLabel(p: ProjectProgressInfo): string | null {
+  if (p.milestonesTotal === 0) return null
+  const parts: string[] = []
+  if (p.activeMilestone) parts.push(p.activeMilestone)
+  if (p.activeSlice) parts.push(p.activeSlice)
+  if (p.phase) parts.push(p.phase)
+  return parts.join(" · ") || null
+}
+
+function relativeTime(timestamp: number): string {
+  const now = Date.now()
+  const diffMs = now - timestamp
+  if (diffMs < 60_000) return "just now"
+  const minutes = Math.floor(diffMs / 60_000)
+  if (minutes < 60) return `${minutes}m ago`
+  const hours = Math.floor(minutes / 60)
+  if (hours < 24) return `${hours}h ago`
+  const days = Math.floor(hours / 24)
+  if (days < 30) return `${days}d ago`
+  return new Date(timestamp).toLocaleDateString(undefined, { month: "short", day: "numeric" })
+}
+
+// ─── Shared project card component ─────────────────────────────────────
+
+function ProjectCard({
+  project,
+  isActive = false,
+  onClick,
+  disabled = false,
+}: {
+  project: ProjectMetadata
+  isActive?: boolean
+  onClick: () => void
+  disabled?: boolean
+}) {
+  const style = KIND_STYLE[project.kind]
+  const KindIcon = style.icon
+  const stack = techStack(project.signals)
+  const progress = project.progress ? progressLabel(project.progress) : null
+  const milestoneCount = project.progress
+    ? `${project.progress.milestonesCompleted}/${project.progress.milestonesTotal}`
+    : null
+
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      className={cn(
+        "group flex w-full items-start gap-3.5 rounded-xl border px-4 py-3.5 text-left transition-all duration-200",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        "active:scale-[0.98]",
+        isActive
+          ? "border-primary/30 bg-primary/[0.08]"
+          : "border-border/50 bg-card/50 hover:border-foreground/15 hover:bg-card/50",
+        disabled && "opacity-40 pointer-events-none",
+      )}
+    >
+      {/* Icon */}
+      <div
+        className={cn(
+          "flex h-9 w-9 shrink-0 items-center justify-center rounded-lg mt-0.5",
+          isActive ? "bg-primary/15" : style.bgClass,
+        )}
+      >
+        {isActive ? (
+          <CheckCircle2 className="h-4 w-4 text-primary" />
+        ) : (
+          <KindIcon className={cn("h-4 w-4", style.color)} />
+        )}
+      </div>
+
+      {/* Content */}
+      <div className="min-w-0 flex-1">
+        {/* Row 1: name + kind badge */}
+        <div className="flex items-center gap-2">
+          <span className="text-sm font-semibold text-foreground truncate">{project.name}</span>
+          <span className={cn("text-[10px] font-medium shrink-0", isActive ? "text-primary" : style.color)}>
+            {isActive ? "Current" : style.label}
+          </span>
+        </div>
+
+        {/* Row 2: tech stack tags */}
+        {stack.length > 0 && (
+          <div className="mt-1 flex items-center gap-1.5">
+            {stack.map((tag) => (
+              <span
+                key={tag}
+                className="rounded bg-foreground/[0.06] px-1.5 py-0.5 text-[10px] text-muted-foreground"
+              >
+                {tag}
+              </span>
+            ))}
+          </div>
+        )}
+
+        {/* Row 3: progress info */}
+        {progress && (
+          <div className="mt-1.5 text-[11px] text-muted-foreground">{progress}</div>
+        )}
+
+        {/* Row 4: milestone progress bar */}
+        {project.progress && project.progress.milestonesTotal > 0 && (
+          <div className="mt-2 flex items-center gap-2">
+            <div className="h-1 flex-1 overflow-hidden rounded-full bg-foreground/[0.08]">
+              <div
+                className="h-full rounded-full bg-success/70 transition-all"
+                style={{
+                  width: `${Math.round(
+                    (project.progress.milestonesCompleted / project.progress.milestonesTotal) * 100,
+                  )}%`,
+                }}
+              />
+            </div>
+            <span className="text-[10px] tabular-nums text-muted-foreground">{milestoneCount}</span>
+          </div>
+        )}
+      </div>
+
+      {/* Arrow */}
+      <ArrowRight className="mt-1 h-4 w-4 shrink-0 text-muted-foreground/50 transition-all group-hover:text-muted-foreground group-hover:translate-x-0.5" />
+    </button>
+  )
+}
+
+// ─── ProjectsPanel (slide-out sheet from sidebar) ──────────────────────
+
+export function ProjectsPanel({
+  open,
+  onOpenChange,
+}: {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+}) {
+  const manager = useProjectStoreManager()
+  const activeProjectCwd = useSyncExternalStore(manager.subscribe, manager.getSnapshot, manager.getSnapshot)
+
+  const [projects, setProjects] = useState<ProjectMetadata[]>([])
+  const [devRoot, setDevRoot] = useState<string | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  const loadProjects = useCallback(async (root: string) => {
+    const projRes = await authFetch(`/api/projects?root=${encodeURIComponent(root)}&detail=true`)
+    if (!projRes.ok) throw new Error(`Failed to discover projects: ${projRes.status}`)
+    return (await projRes.json()) as ProjectMetadata[]
+  }, [])
+
+  // Load projects when panel opens
+  useEffect(() => {
+    if (!open) return
+    let cancelled = false
+
+    async function load() {
+      setLoading(true)
+      setError(null)
+      try {
+        const prefsRes = await authFetch("/api/preferences")
+        if (!prefsRes.ok) throw new Error(`Failed to load preferences: ${prefsRes.status}`)
+        const prefs = await prefsRes.json()
+
+        if (!prefs.devRoot) {
+          setDevRoot(null)
+          setProjects([])
+          setLoading(false)
+          return
+        }
+
+        setDevRoot(prefs.devRoot)
+        const discovered = await loadProjects(prefs.devRoot)
+        if (!cancelled) setProjects(discovered)
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : "Unknown error")
+        }
+      } finally {
+        if (!cancelled) setLoading(false)
+      }
+    }
+
+    load()
+    return () => {
+      cancelled = true
+    }
+  }, [open, loadProjects])
+
+  const handleDevRootSaved = useCallback(
+    async (newRoot: string) => {
+      setLoading(true)
+      setError(null)
+      try {
+        // Validate path and persist in a single call
+        const res = await authFetch("/api/switch-root", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ devRoot: newRoot }),
+        })
+
+        if (!res.ok) {
+          const body = await res.json().catch(() => ({}))
+          throw new Error((body as { error?: string }).error ?? `Request failed (${res.status})`)
+        }
+
+        const data = await res.json() as { devRoot: string; projects: ProjectMetadata[] }
+        setDevRoot(data.devRoot)
+        setProjects(data.projects)
+      } catch (err) {
+        setError(err instanceof Error ? err.message : "Failed to switch project root")
+      } finally {
+        setLoading(false)
+      }
+    },
+    [],
+  )
+
+  const [newProjectOpen, setNewProjectOpen] = useState(false)
+  const [changeRootOpen, setChangeRootOpen] = useState(false)
+  const workspaceState = useGSDWorkspaceState()
+
+  const handleProjectCreated = useCallback(
+    (newProject: ProjectMetadata) => {
+      setProjects((prev) => [...prev, newProject].sort((a, b) => a.name.localeCompare(b.name)))
+      setNewProjectOpen(false)
+      handleSelectProject(newProject)
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  )
+
+  function handleSelectProject(project: ProjectMetadata) {
+    // Already active — just close the panel
+    if (activeProjectCwd === project.path) {
+      onOpenChange(false)
+      return
+    }
+
+    // Close panel immediately — boot happens in the background with a
+    // loading toast managed by WorkspaceChrome
+    onOpenChange(false)
+    manager.switchProject(project.path)
+  }
+
+  // Sort: active-gsd first, then by name
+  const sortedProjects = [...projects].sort((a, b) => {
+    const kindOrder: Record<ProjectDetectionKind, number> = {
+      "active-gsd": 0,
+      "empty-gsd": 1,
+      brownfield: 2,
+      "v1-legacy": 3,
+      blank: 4,
+    }
+    const ka = kindOrder[a.kind] ?? 5
+    const kb = kindOrder[b.kind] ?? 5
+    if (ka !== kb) return ka - kb
+    return a.name.localeCompare(b.name)
+  })
+
+  // ─── Content for the various states ──────────────────────────────
+
+  let content: React.ReactNode
+
+  if (loading) {
+    content = (
+      <div className="flex items-center justify-center gap-2 py-16 text-xs text-muted-foreground">
+        <Loader2 className="h-4 w-4 animate-spin" />
+        Discovering projects…
+      </div>
+    )
+  } else if (error) {
+    content = (
+      <div className="flex flex-col items-center gap-3 px-5 py-16 text-center">
+        <AlertCircle className="h-8 w-8 text-destructive" />
+        <p className="text-sm text-destructive">{error}</p>
+      </div>
+    )
+  } else if (!devRoot) {
+    content = <DevRootSetup onSaved={handleDevRootSaved} />
+  } else if (sortedProjects.length === 0) {
+    content = (
+      <div className="flex flex-col items-center gap-4 px-5 py-16 text-center">
+        <div className="flex h-14 w-14 items-center justify-center rounded-2xl bg-muted">
+          <FolderOpen className="h-7 w-7 text-muted-foreground" />
+        </div>
+        <div className="space-y-2">
+          <h3 className="text-base font-semibold text-foreground">No projects found</h3>
+          <p className="text-sm text-muted-foreground leading-relaxed">
+            No project directories discovered in{" "}
+            <code className="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">
+              {devRoot}
+            </code>
+          </p>
+        </div>
+      </div>
+    )
+  } else {
+    content = (
+      <div className="space-y-2">
+        {/* Project cards */}
+        {sortedProjects.map((project) => (
+          <ProjectCard
+            key={project.path}
+            project={project}
+            isActive={activeProjectCwd === project.path}
+            onClick={() => handleSelectProject(project)}
+          />
+        ))}
+
+        {/* Create new project button */}
+        <button
+          type="button"
+          onClick={() => setNewProjectOpen(true)}
+          className={cn(
+            "flex w-full items-center gap-3.5 rounded-xl border border-dashed px-4 py-3.5 text-left transition-all duration-200",
+            "border-border/50 text-muted-foreground hover:border-foreground/15 hover:text-foreground",
+            "active:scale-[0.98]",
+          )}
+        >
+          <div className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-foreground/[0.04]">
+            <Plus className="h-4 w-4" />
+          </div>
+          <div>
+            <span className="text-sm font-medium">Create new project</span>
+            <p className="mt-0.5 text-[11px] text-muted-foreground">Initialize a new directory with Git</p>
+          </div>
+        </button>
+
+        {/* New project dialog */}
+        <NewProjectDialog
+          open={newProjectOpen}
+          onOpenChange={setNewProjectOpen}
+          devRoot={devRoot}
+          existingNames={projects.map((p) => p.name)}
+          onCreated={handleProjectCreated}
+        />
+      </div>
+    )
+  }
+
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent side="left" className="flex h-full w-full flex-col p-0 sm:max-w-[420px]" data-testid="projects-panel">
+        <SheetHeader className="sr-only">
+          <SheetTitle>Projects</SheetTitle>
+          <SheetDescription>Switch between projects or create a new one</SheetDescription>
+        </SheetHeader>
+
+        {/* Visible header */}
+        <div className="flex items-center justify-between border-b border-border/50 px-5 py-4">
+          <div>
+            <h2 className="text-base font-semibold text-foreground">Projects</h2>
+            {devRoot && !loading && (
+              <div className="mt-0.5 flex items-center gap-1.5 text-xs text-muted-foreground">
+                <code className="rounded bg-muted px-1 py-0.5 font-mono text-[10px] truncate max-w-[200px]">{devRoot}</code>
+                <button
+                  type="button"
+                  onClick={() => setChangeRootOpen(true)}
+                  className="shrink-0 text-[10px] text-primary hover:text-primary/80 transition-colors font-medium"
+                  data-testid="projects-panel-change-root"
+                >
+                  Change
+                </button>
+                <span className="text-muted-foreground">·</span>
+                <span>{projects.length} project{projects.length !== 1 ? "s" : ""}</span>
+              </div>
+            )}
+          </div>
+          <Button variant="ghost" size="icon" className="h-8 w-8 shrink-0" onClick={() => onOpenChange(false)}>
+            <X className="h-4 w-4" />
+          </Button>
+        </div>
+
+        {/* Scrollable project list */}
+        <ScrollArea className="min-h-0 flex-1">
+          <div className="px-5 py-4">{content}</div>
+        </ScrollArea>
+
+        {/* Folder picker for changing dev root */}
+        <FolderPickerDialog
+          open={changeRootOpen}
+          onOpenChange={setChangeRootOpen}
+          onSelect={(path) => void handleDevRootSaved(path)}
+          initialPath={devRoot}
+        />
+      </SheetContent>
+    </Sheet>
+  )
+}
+
+// ─── Active project inline summary (compact for panel card) ────────────
+
+function ActiveProjectSummary({ workspaceState }: { workspaceState: ReturnType<typeof useGSDWorkspaceState> }) {
+  const workspace = getLiveWorkspaceIndex(workspaceState)
+  const dashboard = getLiveAutoDashboard(workspaceState)
+  const currentSlice = getCurrentSlice(workspace)
+
+  if (!workspace) return null
+
+  const activeMilestone = workspace.milestones.find((m) => m.id === workspace.active.milestoneId)
+  const cost = dashboard?.totalCost ?? 0
+
+  const parts: string[] = []
+  if (activeMilestone) parts.push(activeMilestone.id)
+  if (currentSlice) parts.push(currentSlice.id)
+  if (cost > 0) parts.push(formatCost(cost))
+
+  if (parts.length === 0) return null
+
+  return <div className="mt-1.5 text-[11px] text-muted-foreground">{parts.join(" · ")}</div>
+}
+
+// ─── New Project Dialog ────────────────────────────────────────────────
+
+function NewProjectDialog({
+  open,
+  onOpenChange,
+  devRoot,
+  existingNames,
+  onCreated,
+}: {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  devRoot: string
+  existingNames: string[]
+  onCreated: (project: ProjectMetadata) => void
+}) {
+  const [name, setName] = useState("")
+  const [creating, setCreating] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  useEffect(() => {
+    if (open) {
+      setName("")
+      setError(null)
+      setCreating(false)
+      const t = setTimeout(() => inputRef.current?.focus(), 100)
+      return () => clearTimeout(t)
+    }
+  }, [open])
+
+  const nameValid = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name)
+  const nameConflict = existingNames.includes(name)
+  const canSubmit = name.length > 0 && nameValid && !nameConflict && !creating
+
+  const validationHint = (() => {
+    if (!name) return null
+    if (nameConflict) return "A project with this name already exists"
+    if (!nameValid) return "Use letters, numbers, hyphens, underscores, dots. Must start with a letter or number."
+    return null
+  })()
+
+  async function handleCreate() {
+    if (!canSubmit) return
+    setCreating(true)
+    setError(null)
+    try {
+      const res = await authFetch("/api/projects", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ devRoot, name }),
+      })
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({}))
+        throw new Error((body as { error?: string }).error ?? `Failed (${res.status})`)
+      }
+      const project = (await res.json()) as ProjectMetadata
+      onCreated(project)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to create project")
+      setCreating(false)
+    }
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>New Project</DialogTitle>
+          <DialogDescription>
+            Create a new project directory in{" "}
+            <code className="rounded bg-muted px-1 py-0.5 text-xs font-mono">{devRoot}</code>
+          </DialogDescription>
+        </DialogHeader>
+
+        <form
+          onSubmit={(e) => {
+            e.preventDefault()
+            void handleCreate()
+          }}
+          className="space-y-4 py-2"
+        >
+          <div className="space-y-2">
+            <Label htmlFor="project-name">Project name</Label>
+            <Input
+              ref={inputRef}
+              id="project-name"
+              placeholder="my-project"
+              value={name}
+              onChange={(e) => {
+                setName(e.target.value)
+                setError(null)
+              }}
+              autoComplete="off"
+              aria-invalid={!!validationHint}
+            />
+            {validationHint && <p className="text-xs text-destructive">{validationHint}</p>}
+            {error && <p className="text-xs text-destructive">{error}</p>}
+            {name && nameValid && !nameConflict && (
+              <p className="text-xs text-muted-foreground font-mono">
+                {devRoot}/{name}
+              </p>
+            )}
+          </div>
+        </form>
+
+        <DialogFooter>
+          <Button variant="ghost" size="sm" onClick={() => onOpenChange(false)} disabled={creating}>
+            Cancel
+          </Button>
+          <Button size="sm" onClick={() => void handleCreate()} disabled={!canSubmit} className="gap-1.5">
+            {creating ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : <Plus className="h-3.5 w-3.5" />}
+            Create
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+// ─── Folder Picker Dialog ───────────────────────────────────────────────
+
+interface BrowseEntry {
+  name: string
+  path: string
+}
+
+interface BrowseResult {
+  current: string
+  parent: string | null
+  entries: BrowseEntry[]
+}
+
+function FolderPickerDialog({
+  open,
+  onOpenChange,
+  onSelect,
+  initialPath,
+}: {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  onSelect: (path: string) => void
+  initialPath?: string | null
+}) {
+  const [currentPath, setCurrentPath] = useState<string>("")
+  const [parentPath, setParentPath] = useState<string | null>(null)
+  const [entries, setEntries] = useState<BrowseEntry[]>([])
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const browse = useCallback(async (targetPath?: string) => {
+    setLoading(true)
+    setError(null)
+    try {
+      const param = targetPath ? `?path=${encodeURIComponent(targetPath)}` : ""
+      const res = await authFetch(`/api/browse-directories${param}`)
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({}))
+        throw new Error((body as { error?: string }).error ?? `${res.status}`)
+      }
+      const data: BrowseResult = await res.json()
+      setCurrentPath(data.current)
+      setParentPath(data.parent)
+      setEntries(data.entries)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to browse")
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    if (open) {
+      void browse(initialPath ?? undefined)
+    }
+  }, [open, initialPath, browse])
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-lg gap-0 p-0 overflow-hidden">
+        <DialogHeader className="px-5 pt-5 pb-3">
+          <DialogTitle className="text-base">Choose Folder</DialogTitle>
+          <DialogDescription className="text-xs">
+            Navigate to the folder that contains your project directories.
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="border-y border-border/50 bg-muted/50 px-5 py-2">
+          <p className="font-mono text-xs text-muted-foreground truncate" title={currentPath}>
+            {currentPath}
+          </p>
+        </div>
+
+        <ScrollArea className="h-[320px]">
+          <div className="px-2 py-1">
+            {loading && (
+              <div className="flex items-center justify-center py-12">
+                <Loader2 className="h-5 w-5 animate-spin text-muted-foreground" />
+              </div>
+            )}
+
+            {error && <div className="px-3 py-4 text-center text-xs text-destructive">{error}</div>}
+
+            {!loading && !error && (
+              <>
+                {parentPath && (
+                  <button
+                    onClick={() => void browse(parentPath)}
+                    className="flex w-full items-center gap-2.5 rounded-md px-3 py-2 text-left text-sm transition-colors hover:bg-accent/50"
+                  >
+                    <CornerLeftUp className="h-4 w-4 text-muted-foreground shrink-0" />
+                    <span className="text-muted-foreground">..</span>
+                  </button>
+                )}
+
+                {entries.map((entry) => (
+                  <button
+                    key={entry.path}
+                    onClick={() => void browse(entry.path)}
+                    className="flex w-full items-center gap-2.5 rounded-md px-3 py-2 text-left text-sm transition-colors hover:bg-accent/50 group"
+                  >
+                    <Folder className="h-4 w-4 text-muted-foreground shrink-0" />
+                    <span className="text-foreground truncate flex-1">{entry.name}</span>
+                    <ChevronRight className="h-3.5 w-3.5 text-muted-foreground opacity-0 group-hover:opacity-100 transition-opacity shrink-0" />
+                  </button>
+                ))}
+
+                {!parentPath && entries.length === 0 && (
+                  <div className="px-3 py-8 text-center text-xs text-muted-foreground">No subdirectories</div>
+                )}
+              </>
+            )}
+          </div>
+        </ScrollArea>
+
+        <DialogFooter className="border-t border-border/50 px-5 py-3">
+          <Button variant="ghost" size="sm" onClick={() => onOpenChange(false)}>
+            Cancel
+          </Button>
+          <Button
+            size="sm"
+            onClick={() => {
+              onSelect(currentPath)
+              onOpenChange(false)
+            }}
+            disabled={!currentPath}
+            className="gap-1.5"
+          >
+            <FolderOpen className="h-3.5 w-3.5" />
+            Select This Folder
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+// ─── Dev Root Setup Component ───────────────────────────────────────────
+
+function DevRootSetup({
+  onSaved,
+  currentRoot,
+}: {
+  onSaved: (root: string) => void
+  currentRoot?: string | null
+}) {
+  const [saving, setSaving] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [success, setSuccess] = useState(false)
+  const [pickerOpen, setPickerOpen] = useState(false)
+
+  const handleSave = useCallback(
+    async (selectedPath: string) => {
+      setSaving(true)
+      setError(null)
+      setSuccess(false)
+
+      try {
+        const res = await authFetch("/api/preferences", {
+          method: "PUT",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ devRoot: selectedPath }),
+        })
+
+        if (!res.ok) {
+          const body = await res.json().catch(() => ({}))
+          throw new Error((body as { error?: string }).error ?? `Request failed (${res.status})`)
+        }
+
+        setSuccess(true)
+        onSaved(selectedPath)
+      } catch (err) {
+        setError(err instanceof Error ? err.message : "Failed to save preference")
+      } finally {
+        setSaving(false)
+      }
+    },
+    [onSaved],
+  )
+
+  const isCompact = !!currentRoot
+
+  if (isCompact) {
+    return (
+      <div className="space-y-3" data-testid="devroot-settings">
+        <div className="flex items-center gap-2">
+          <code className="flex-1 truncate rounded border border-border/50 bg-muted/50 px-3 py-2 font-mono text-xs text-foreground">
+            {currentRoot}
+          </code>
+          <Button
+            size="sm"
+            variant="outline"
+            onClick={() => setPickerOpen(true)}
+            disabled={saving}
+            className="h-9 gap-1.5 shrink-0"
+          >
+            {saving ? (
+              <Loader2 className="h-3.5 w-3.5 animate-spin" />
+            ) : success ? (
+              <CheckCircle2 className="h-3.5 w-3.5 text-success" />
+            ) : (
+              <>
+                <FolderOpen className="h-3.5 w-3.5" />
+                Change
+              </>
+            )}
+          </Button>
+        </div>
+
+        {error && <p className="text-xs text-destructive">{error}</p>}
+        {success && <p className="text-xs text-success">Dev root updated</p>}
+
+        <FolderPickerDialog
+          open={pickerOpen}
+          onOpenChange={setPickerOpen}
+          onSelect={(path) => void handleSave(path)}
+          initialPath={currentRoot}
+        />
+      </div>
+    )
+  }
+
+  // Inline setup for first-time configuration
+  return (
+    <div className="rounded-md border border-border bg-card p-6">
+      <div className="flex items-start gap-4">
+        <div className="flex h-10 w-10 shrink-0 items-center justify-center rounded-md border border-border bg-accent">
+          <FolderRoot className="h-5 w-5 text-muted-foreground" />
+        </div>
+        <div className="min-w-0 flex-1">
+          <h3 className="text-sm font-semibold text-foreground">Set your development root</h3>
+          <p className="mt-1 text-xs text-muted-foreground leading-relaxed">
+            Point GSD at the folder that contains your project directories. It scans one level deep.
+          </p>
+          <Button
+            onClick={() => setPickerOpen(true)}
+            disabled={saving}
+            size="sm"
+            className="mt-3 gap-2"
+            data-testid="projects-devroot-browse"
+          >
+            {saving ? (
+              <Loader2 className="h-3.5 w-3.5 animate-spin" />
+            ) : (
+              <>
+                <FolderOpen className="h-3.5 w-3.5" />
+                Browse
+              </>
+            )}
+          </Button>
+          {error && <p className="mt-2 text-xs text-destructive">{error}</p>}
+        </div>
+      </div>
+
+      <FolderPickerDialog open={pickerOpen} onOpenChange={setPickerOpen} onSelect={(path) => void handleSave(path)} />
+    </div>
+  )
+}
+
+// ─── Exported Dev Root Section for Settings ──────────────────────────────
+
+export function DevRootSettingsSection() {
+  const [devRoot, setDevRoot] = useState<string | null>(null)
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    authFetch("/api/preferences")
+      .then((r) => r.json())
+      .then((prefs) => setDevRoot(prefs.devRoot ?? null))
+      .catch(() => setDevRoot(null))
+      .finally(() => setLoading(false))
+  }, [])
+
+  if (loading) {
+    return (
+      <div className="flex items-center gap-2 py-4 text-xs text-muted-foreground">
+        <Loader2 className="h-3.5 w-3.5 animate-spin" />
+        Loading preferences…
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-3" data-testid="settings-devroot">
+      <div className="flex items-center gap-2.5">
+        <FolderRoot className="h-3.5 w-3.5 text-muted-foreground" />
+        <h3 className="text-[13px] font-semibold uppercase tracking-[0.08em] text-muted-foreground">
+          Development Root
+        </h3>
+      </div>
+      <p className="text-xs text-muted-foreground leading-relaxed">
+        The parent folder containing your project directories. GSD scans one level deep for projects.
+      </p>
+      <DevRootSetup currentRoot={devRoot ?? ""} onSaved={(root) => setDevRoot(root)} />
+    </div>
+  )
+}
+
+// ─── Project Selection Gate ─────────────────────────────────────────────
+//
+// Full-screen IDE-style welcome shown before any project is opened.
+// Designed to feel like opening the app — not a wizard or onboarding flow.
+// Mirrors the app shell layout: header bar, sidebar-width left column,
+// project list as the main content area.
+
+export function ProjectSelectionGate() {
+  const manager = useProjectStoreManager()
+
+  const [projects, setProjects] = useState<ProjectMetadata[]>([])
+  const [devRoot, setDevRoot] = useState<string | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+  const [newProjectOpen, setNewProjectOpen] = useState(false)
+  const [changeRootOpen, setChangeRootOpen] = useState(false)
+  const [filter, setFilter] = useState("")
+
+  const loadProjects = useCallback(async (root: string) => {
+    const projRes = await authFetch(`/api/projects?root=${encodeURIComponent(root)}&detail=true`)
+    if (!projRes.ok) throw new Error(`Failed to discover projects: ${projRes.status}`)
+    return (await projRes.json()) as ProjectMetadata[]
+  }, [])
+
+  useEffect(() => {
+    let cancelled = false
+
+    async function load() {
+      setLoading(true)
+      setError(null)
+      try {
+        const prefsRes = await authFetch("/api/preferences")
+        if (!prefsRes.ok) throw new Error(`Failed to load preferences: ${prefsRes.status}`)
+        const prefs = await prefsRes.json()
+
+        if (!prefs.devRoot) {
+          setDevRoot(null)
+          setProjects([])
+          setLoading(false)
+          return
+        }
+
+        setDevRoot(prefs.devRoot)
+        const discovered = await loadProjects(prefs.devRoot)
+        if (!cancelled) setProjects(discovered)
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : "Unknown error")
+        }
+      } finally {
+        if (!cancelled) setLoading(false)
+      }
+    }
+
+    load()
+    return () => {
+      cancelled = true
+    }
+  }, [loadProjects])
+
+  const handleDevRootSaved = useCallback(
+    async (newRoot: string) => {
+      setLoading(true)
+      setError(null)
+      try {
+        const res = await authFetch("/api/switch-root", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ devRoot: newRoot }),
+        })
+
+        if (!res.ok) {
+          const body = await res.json().catch(() => ({}))
+          throw new Error((body as { error?: string }).error ?? `Request failed (${res.status})`)
+        }
+
+        const data = await res.json() as { devRoot: string; projects: ProjectMetadata[] }
+        setDevRoot(data.devRoot)
+        setProjects(data.projects)
+      } catch (err) {
+        setError(err instanceof Error ? err.message : "Failed to switch project root")
+      } finally {
+        setLoading(false)
+      }
+    },
+    [],
+  )
+
+  const handleProjectCreated = useCallback(
+    (newProject: ProjectMetadata) => {
+      setProjects((prev) => [...prev, newProject].sort((a, b) => a.name.localeCompare(b.name)))
+      setNewProjectOpen(false)
+      manager.switchProject(newProject.path)
+    },
+    [manager],
+  )
+
+  function handleSelectProject(project: ProjectMetadata) {
+    manager.switchProject(project.path)
+  }
+
+  // Sort: active-gsd first, then by name
+  const sortedProjects = [...projects].sort((a, b) => {
+    const kindOrder: Record<ProjectDetectionKind, number> = {
+      "active-gsd": 0,
+      "empty-gsd": 1,
+      brownfield: 2,
+      "v1-legacy": 3,
+      blank: 4,
+    }
+    const ka = kindOrder[a.kind] ?? 5
+    const kb = kindOrder[b.kind] ?? 5
+    if (ka !== kb) return ka - kb
+    return a.name.localeCompare(b.name)
+  })
+
+  // Filter projects by name
+  const filteredProjects = filter.trim()
+    ? sortedProjects.filter((p) => p.name.toLowerCase().includes(filter.toLowerCase()))
+    : sortedProjects
+
+  const hasProjects = !loading && sortedProjects.length > 0
+  const showFilter = sortedProjects.length > 5
+
+  return (
+    <div className="flex h-screen flex-col bg-background text-foreground" data-testid="project-selection-gate">
+      {/* ─── Main content ─── */}
+      <div className="flex-1 overflow-y-auto">
+        <div className="mx-auto max-w-2xl px-6 pt-16 pb-10 md:px-10 lg:pt-24">
+
+          {/* ─── Logo + subtitle ─── */}
+          <div className="flex flex-col items-center text-center mb-10">
+            <Image
+              src="/logo-black.svg"
+              alt="GSD"
+              width={100}
+              height={28}
+              className="h-7 w-auto dark:hidden"
+            />
+            <Image
+              src="/logo-white.svg"
+              alt="GSD"
+              width={100}
+              height={28}
+              className="h-7 w-auto hidden dark:block"
+            />
+            <p className="mt-3 text-sm text-muted-foreground">
+              Select a project to get started
+            </p>
+          </div>
+
+            {/* Loading */}
+            {loading && (
+              <div className="flex items-center gap-3 py-20 justify-center text-sm text-muted-foreground">
+                <Loader2 className="h-4 w-4 animate-spin" />
+                Scanning for projects…
+              </div>
+            )}
+
+            {/* Error */}
+            {error && !loading && (
+              <div className="rounded-md border border-destructive/20 bg-destructive/[0.06] px-4 py-3 text-sm text-destructive">
+                {error}
+              </div>
+            )}
+
+            {/* No dev root — show setup */}
+            {!devRoot && !loading && !error && (
+              <div className="space-y-6">
+                <div>
+                  <h2 className="text-lg font-semibold tracking-tight text-foreground">
+                    Welcome to GSD
+                  </h2>
+                  <p className="mt-1 text-sm text-muted-foreground">
+                    Set a development root to get started. GSD will discover projects inside it.
+                  </p>
+                </div>
+                <DevRootSetup onSaved={handleDevRootSaved} />
+              </div>
+            )}
+
+            {/* No projects found */}
+            {devRoot && !loading && sortedProjects.length === 0 && !error && (
+              <div className="space-y-6">
+                <div>
+                  <h2 className="text-lg font-semibold tracking-tight text-foreground">No projects found</h2>
+                  <p className="mt-1 text-sm text-muted-foreground">
+                    No project directories were discovered. Create one to get started.
+                  </p>
+                </div>
+                <button
+                  type="button"
+                  onClick={() => setNewProjectOpen(true)}
+                  className="flex items-center gap-3 rounded-md border border-dashed border-border px-4 py-3 text-sm text-muted-foreground transition-colors hover:border-foreground/20 hover:text-foreground"
+                >
+                  <Plus className="h-4 w-4" />
+                  Create a new project
+                </button>
+              </div>
+            )}
+
+            {/* ─── Project list ─── */}
+            {hasProjects && (
+              <div className="space-y-5">
+                {/* Dev root + change button */}
+                {devRoot && (
+                  <div className="flex items-center gap-2 text-xs text-muted-foreground">
+                    <FolderRoot className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                    <code className="rounded bg-muted px-1.5 py-0.5 font-mono text-[10px] text-muted-foreground truncate">{devRoot}</code>
+                    <button
+                      type="button"
+                      onClick={() => setChangeRootOpen(true)}
+                      className="shrink-0 text-[11px] text-primary hover:text-primary/80 transition-colors font-medium"
+                      data-testid="gate-change-root"
+                    >
+                      Change
+                    </button>
+                  </div>
+                )}
+
+                {/* Filter + count */}
+                <div className="flex items-center justify-between gap-4">
+                  <p className="text-xs text-muted-foreground tabular-nums">
+                    {sortedProjects.length} project{sortedProjects.length !== 1 ? "s" : ""}
+                  </p>
+                  {showFilter && (
+                    <div className="relative w-48">
+                      <Search className="absolute left-2.5 top-1/2 -translate-y-1/2 h-3.5 w-3.5 text-muted-foreground" />
+                      <input
+                        type="text"
+                        placeholder="Filter…"
+                        value={filter}
+                        onChange={(e) => setFilter(e.target.value)}
+                        className="h-8 w-full rounded-md border border-border bg-background pl-8 pr-3 text-xs text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-1 focus:ring-ring"
+                      />
+                    </div>
+                  )}
+                </div>
+
+                {/* Project rows — table-like, dense */}
+                <div className="rounded-md border border-border bg-card overflow-hidden divide-y divide-border">
+                  {filteredProjects.map((project) => {
+                    const style = KIND_STYLE[project.kind]
+                    const KindIcon = style.icon
+                    const stack = techStack(project.signals)
+                    const progress = project.progress ? progressLabel(project.progress) : null
+                    const hasBar = project.progress && project.progress.milestonesTotal > 0
+                    const pct = hasBar
+                      ? Math.round((project.progress!.milestonesCompleted / project.progress!.milestonesTotal) * 100)
+                      : 0
+
+                    return (
+                      <button
+                        key={project.path}
+                        type="button"
+                        onClick={() => handleSelectProject(project)}
+                        className="group flex w-full items-center gap-4 px-4 py-3 text-left transition-colors hover:bg-accent/50 focus-visible:outline-none focus-visible:bg-accent/50"
+                      >
+                        {/* Icon */}
+                        <div className={cn("flex h-8 w-8 shrink-0 items-center justify-center rounded-md", style.bgClass)}>
+                          <KindIcon className={cn("h-3.5 w-3.5", style.color)} />
+                        </div>
+
+                        {/* Name + metadata */}
+                        <div className="min-w-0 flex-1">
+                          <div className="flex items-center gap-2">
+                            <span className="text-sm font-medium text-foreground truncate">{project.name}</span>
+                            <span className={cn("text-[10px] font-medium shrink-0", style.color)}>{style.label}</span>
+                          </div>
+                          {/* Stack tags + progress on one line */}
+                          <div className="mt-0.5 flex items-center gap-2 text-[11px] text-muted-foreground">
+                            {stack.length > 0 && (
+                              <span>{stack.join(" · ")}</span>
+                            )}
+                            {stack.length > 0 && progress && (
+                              <span className="text-muted-foreground/50">—</span>
+                            )}
+                            {progress && (
+                              <span className="truncate">{progress}</span>
+                            )}
+                          </div>
+                        </div>
+
+                        {/* Progress bar (compact) */}
+                        {hasBar && (
+                          <div className="hidden sm:flex items-center gap-2 shrink-0 w-24">
+                            <div className="h-1 flex-1 overflow-hidden rounded-full bg-foreground/[0.08]">
+                              <div
+                                className="h-full rounded-full bg-success/70 transition-all"
+                                style={{ width: `${pct}%` }}
+                              />
+                            </div>
+                            <span className="text-[10px] tabular-nums text-muted-foreground w-6 text-right">
+                              {project.progress!.milestonesCompleted}/{project.progress!.milestonesTotal}
+                            </span>
+                          </div>
+                        )}
+
+                        {/* Modified time */}
+                        {project.lastModified > 0 && (
+                          <span className="hidden lg:inline text-[10px] text-muted-foreground shrink-0 w-16 text-right tabular-nums">
+                            {relativeTime(project.lastModified)}
+                          </span>
+                        )}
+
+                        {/* Arrow */}
+                        <ChevronRight className="h-4 w-4 shrink-0 text-muted-foreground/50 transition-colors group-hover:text-muted-foreground" />
+                      </button>
+                    )
+                  })}
+
+                  {/* Empty filter state */}
+                  {filteredProjects.length === 0 && filter.trim() && (
+                    <div className="px-4 py-8 text-center text-xs text-muted-foreground">
+                      No projects matching "{filter}"
+                    </div>
+                  )}
+                </div>
+
+                {/* Create new row */}
+                <button
+                  type="button"
+                  onClick={() => setNewProjectOpen(true)}
+                  className="flex items-center gap-3 rounded-md border border-dashed border-border px-4 py-2.5 text-sm text-muted-foreground transition-colors hover:border-foreground/20 hover:text-foreground w-full"
+                >
+                  <Plus className="h-3.5 w-3.5" />
+                  New project
+                </button>
+
+                {devRoot && (
+                  <NewProjectDialog
+                    open={newProjectOpen}
+                    onOpenChange={setNewProjectOpen}
+                    devRoot={devRoot}
+                    existingNames={projects.map((p) => p.name)}
+                    onCreated={handleProjectCreated}
+                  />
+                )}
+              </div>
+            )}
+
+            {/* Change root for "no projects" and "no devRoot" states */}
+            {devRoot && !loading && sortedProjects.length === 0 && !error && (
+              <div className="mt-4">
+                <button
+                  type="button"
+                  onClick={() => setChangeRootOpen(true)}
+                  className="flex items-center gap-2 text-xs text-primary hover:text-primary/80 transition-colors font-medium"
+                  data-testid="gate-change-root-empty"
+                >
+                  <FolderOpen className="h-3.5 w-3.5" />
+                  Change project root
+                </button>
+              </div>
+            )}
+        </div>
+      </div>
+
+      {/* Folder picker for changing dev root */}
+      <FolderPickerDialog
+        open={changeRootOpen}
+        onOpenChange={setChangeRootOpen}
+        onSelect={(path) => void handleDevRootSaved(path)}
+        initialPath={devRoot}
+      />
+    </div>
+  )
+}
diff --git a/web/components/sf/remaining-command-panels.tsx b/web/components/sf/remaining-command-panels.tsx
new file mode 100644
index 000000000..e5744a06b
--- /dev/null
+++ b/web/components/sf/remaining-command-panels.tsx
@@ -0,0 +1,1264 @@
+"use client"
+
+import { useState } from "react"
+import {
+  AlertTriangle,
+  Archive,
+  CheckCircle2,
+  Clock,
+  Database,
+  Download,
+  GitBranch,
+  Layers,
+  ListChecks,
+  LoaderCircle,
+  Navigation,
+  RefreshCw,
+  RotateCcw,
+  Scissors,
+  Terminal,
+  Trash2,
+  Undo2,
+  XCircle,
+  Zap,
+} from "lucide-react"
+
+import { Badge } from "@/components/ui/badge"
+import { Button } from "@/components/ui/button"
+import { Textarea } from "@/components/ui/textarea"
+import type {
+  HistoryData,
+  HistoryPhaseAggregate,
+  HistorySliceAggregate,
+  HistoryModelAggregate,
+  InspectData,
+  HooksData,
+  HookStatusEntry,
+  ExportResult,
+  UndoInfo,
+  UndoResult,
+  CleanupData,
+  CleanupBranch,
+  CleanupSnapshot,
+  CleanupResult,
+  SteerData,
+} from "@/lib/remaining-command-types"
+import { cn } from "@/lib/utils"
+import {
+  formatCost,
+  getLiveWorkspaceIndex,
+  useGSDWorkspaceActions,
+  useGSDWorkspaceState,
+  type WorkspaceMilestoneTarget,
+  type WorkspaceSliceTarget,
+} from "@/lib/sf-workspace-store"
+
+// ═══════════════════════════════════════════════════════════════════════
+// SHARED INFRASTRUCTURE
+// ═══════════════════════════════════════════════════════════════════════
+
+function PanelHeader({
+  title,
+  icon,
+  subtitle,
+  status,
+  onRefresh,
+  refreshing,
+}: {
+  title: string
+  icon: React.ReactNode
+  subtitle?: string | null
+  status?: React.ReactNode
+  onRefresh?: () => void
+  refreshing?: boolean
+}) {
+  return (
+    <div className="flex items-center justify-between gap-3 pb-4">
+      <div className="flex items-center gap-2.5">
+        <span className="text-muted-foreground">{icon}</span>
+        <h3 className="text-[13px] font-semibold uppercase tracking-[0.08em] text-muted-foreground">{title}</h3>
+        {status}
+        {subtitle && <span className="text-[11px] text-muted-foreground">{subtitle}</span>}
+      </div>
+      {onRefresh && (
+        <Button type="button" variant="ghost" size="sm" onClick={onRefresh} disabled={refreshing} className="h-7 gap-1.5 text-xs">
+          <RefreshCw className={cn("h-3 w-3", refreshing && "animate-spin")} />
+          Refresh
+        </Button>
+      )}
+    </div>
+  )
+}
+
+function PanelError({ message }: { message: string }) {
+  return (
+    <div className="rounded-lg border border-destructive/20 bg-destructive/5 px-3 py-2.5 text-xs text-destructive">
+      {message}
+    </div>
+  )
+}
+
+function PanelLoading({ label }: { label: string }) {
+  return (
+    <div className="flex items-center gap-2 py-6 text-xs text-muted-foreground">
+      <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+      {label}
+    </div>
+  )
+}
+
+function PanelEmpty({ message }: { message: string }) {
+  return (
+    <div className="rounded-lg border border-border/50 bg-card/50 px-4 py-5 text-center text-xs text-muted-foreground">
+      {message}
+    </div>
+  )
+}
+
+function InfoPill({ label, value, variant }: { label: string; value: string | number; variant?: "default" | "info" | "warning" | "success" | "error" }) {
+  return (
+    <div className={cn(
+      "flex items-center gap-1.5 rounded-md border px-2.5 py-1 text-xs",
+      variant === "info" && "border-info/20 bg-info/5 text-info",
+      variant === "warning" && "border-warning/20 bg-warning/5 text-warning",
+      variant === "success" && "border-success/20 bg-success/5 text-success",
+      variant === "error" && "border-destructive/20 bg-destructive/5 text-destructive",
+      (!variant || variant === "default") && "border-border/50 bg-card/50 text-foreground/80",
+    )}>
+      <span className="text-muted-foreground">{label}</span>
+      <span className="font-medium tabular-nums">{value}</span>
+    </div>
+  )
+}
+
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`
+  const seconds = Math.round(ms / 1000)
+  if (seconds < 60) return `${seconds}s`
+  const minutes = Math.floor(seconds / 60)
+  const remainingSec = seconds % 60
+  if (minutes < 60) return remainingSec > 0 ? `${minutes}m ${remainingSec}s` : `${minutes}m`
+  const hours = Math.floor(minutes / 60)
+  const remainingMin = minutes % 60
+  return remainingMin > 0 ? `${hours}h ${remainingMin}m` : `${hours}h`
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// 1. QUICK PANEL — Static usage instructions
+// ═══════════════════════════════════════════════════════════════════════
+
+export function QuickPanel() {
+  return (
+    <div className="space-y-4" data-testid="gsd-surface-gsd-quick">
+      <PanelHeader
+        title="Quick Task"
+        icon={<Zap className="h-3.5 w-3.5" />}
+      />
+
+      <div className="rounded-lg border border-border/50 bg-card/50 px-4 py-4 space-y-3">
+        <p className="text-xs text-foreground">
+          Create a quick one-off task outside the current plan. Useful for small fixes, experiments, or ad-hoc work that
+          doesn&apos;t fit into the milestone structure.
+        </p>
+
+        <div className="space-y-2">
+          <h4 className="text-[11px] font-medium text-muted-foreground uppercase tracking-wide">Usage</h4>
+          <div className="rounded-md border border-border/50 bg-background/50 px-3 py-2 font-mono text-[11px] text-foreground/80">
+            /gsd quick &lt;description&gt;
+          </div>
+        </div>
+
+        <div className="space-y-2">
+          <h4 className="text-[11px] font-medium text-muted-foreground uppercase tracking-wide">Examples</h4>
+          <div className="space-y-1.5">
+            {[
+              "Fix the typo in README.md header",
+              "Add .env.example with required keys",
+              "Update the LICENSE year to 2026",
+              "Run prettier on the whole project",
+            ].map((example) => (
+              <div key={example} className="flex items-center gap-2 text-[11px]">
+                <span className="text-muted-foreground">$</span>
+                <code className="font-mono text-muted-foreground">/gsd quick {example}</code>
+              </div>
+            ))}
+          </div>
+        </div>
+
+        <div className="rounded-md border border-info/15 bg-info/5 px-3 py-2 text-[11px] text-info/90">
+          Quick tasks run as standalone units — they don&apos;t affect milestone progress, slices, or the plan. Use them
+          for work that should happen now without ceremony.
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// 2. HISTORY PANEL — Project metrics and breakdowns
+// ═══════════════════════════════════════════════════════════════════════
+
+type HistoryTab = "phase" | "slice" | "model" | "units"
+
+export function HistoryPanel() {
+  const workspace = useGSDWorkspaceState()
+  const { loadHistoryData } = useGSDWorkspaceActions()
+  const state = workspace.commandSurface.remainingCommands.history
+  const data = state.data as HistoryData | null
+  const busy = state.phase === "loading"
+  const [activeTab, setActiveTab] = useState<HistoryTab>("phase")
+
+  return (
+    <div className="space-y-4" data-testid="gsd-surface-gsd-history">
+      <PanelHeader
+        title="History & Metrics"
+        icon={<Clock className="h-3.5 w-3.5" />}
+        onRefresh={() => void loadHistoryData()}
+        refreshing={busy}
+      />
+
+      {state.error && <PanelError message={state.error} />}
+      {busy && !data && <PanelLoading label="Loading history data…" />}
+
+      {data && (
+        <>
+          {/* Totals summary */}
+          <div className="flex flex-wrap gap-2">
+            <InfoPill label="Units" value={data.totals.units} />
+            <InfoPill label="Cost" value={formatCost(data.totals.cost)} variant="warning" />
+            <InfoPill label="Duration" value={formatDuration(data.totals.duration)} />
+            <InfoPill label="Tool Calls" value={data.totals.toolCalls} />
+          </div>
+
+          {/* Tab switcher */}
+          <div className="flex gap-1 rounded-lg border border-border/50 bg-card/50 p-0.5">
+            {(["phase", "slice", "model", "units"] as const).map((tab) => (
+              <button
+                key={tab}
+                type="button"
+                onClick={() => setActiveTab(tab)}
+                className={cn(
+                  "flex-1 rounded-md px-2.5 py-1 text-[11px] font-medium capitalize transition-colors",
+                  activeTab === tab
+                    ? "bg-card text-foreground shadow-sm"
+                    : "text-muted-foreground hover:text-muted-foreground",
+                )}
+              >
+                {tab === "units" ? "Recent" : `By ${tab}`}
+              </button>
+            ))}
+          </div>
+
+          {/* By Phase */}
+          {activeTab === "phase" && data.byPhase.length > 0 && (
+            <div className="overflow-x-auto rounded-lg border border-border/50">
+              <table className="w-full text-[11px]">
+                <thead>
+                  <tr className="border-b border-border/50 bg-card/50">
+                    <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Phase</th>
+                    <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Units</th>
+                    <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Cost</th>
+                    <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Duration</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {data.byPhase.map((row: HistoryPhaseAggregate) => (
+                    <tr key={row.phase} className="border-b border-border/50 last:border-0">
+                      <td className="px-2.5 py-1.5 font-mono text-foreground/80 capitalize">{row.phase}</td>
+                      <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">{row.units}</td>
+                      <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">{formatCost(row.cost)}</td>
+                      <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">{formatDuration(row.duration)}</td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          )}
+
+          {/* By Slice */}
+          {activeTab === "slice" && data.bySlice.length > 0 && (
+            <div className="overflow-x-auto rounded-lg border border-border/50">
+              <table className="w-full text-[11px]">
+                <thead>
+                  <tr className="border-b border-border/50 bg-card/50">
+                    <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Slice</th>
+                    <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Units</th>
+                    <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Cost</th>
+                    <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Duration</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {data.bySlice.map((row: HistorySliceAggregate) => (
+                    <tr key={row.sliceId} className="border-b border-border/50 last:border-0">
+                      <td className="px-2.5 py-1.5 font-mono text-foreground/80">{row.sliceId}</td>
+                      <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">{row.units}</td>
+                      <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">{formatCost(row.cost)}</td>
+                      <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">{formatDuration(row.duration)}</td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          )}
+
+          {/* By Model */}
+          {activeTab === "model" && data.byModel.length > 0 && (
+            <div className="overflow-x-auto rounded-lg border border-border/50">
+              <table className="w-full text-[11px]">
+                <thead>
+                  <tr className="border-b border-border/50 bg-card/50">
+                    <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Model</th>
+                    <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Units</th>
+                    <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Cost</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {data.byModel.map((row: HistoryModelAggregate) => (
+                    <tr key={row.model} className="border-b border-border/50 last:border-0">
+                      <td className="px-2.5 py-1.5 font-mono text-foreground/80 truncate max-w-[180px]">{row.model}</td>
+                      <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">{row.units}</td>
+                      <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">{formatCost(row.cost)}</td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          )}
+
+          {/* Recent Units */}
+          {activeTab === "units" && (
+            <>
+              {data.units.length > 0 ? (
+                <div className="overflow-x-auto rounded-lg border border-border/50">
+                  <table className="w-full text-[11px]">
+                    <thead>
+                      <tr className="border-b border-border/50 bg-card/50">
+                        <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Type</th>
+                        <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">ID</th>
+                        <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Model</th>
+                        <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Cost</th>
+                        <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Duration</th>
+                      </tr>
+                    </thead>
+                    <tbody>
+                      {data.units.slice(0, 20).map((u, i) => (
+                        <tr key={i} className="border-b border-border/50 last:border-0">
+                          <td className="px-2.5 py-1.5 font-mono text-foreground/80">{u.type}</td>
+                          <td className="px-2.5 py-1.5 font-mono text-foreground/80 truncate max-w-[120px]">{u.id}</td>
+                          <td className="px-2.5 py-1.5 text-muted-foreground truncate max-w-[120px]">{u.model}</td>
+                          <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">{formatCost(u.cost)}</td>
+                          <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">{formatDuration(u.finishedAt - u.startedAt)}</td>
+                        </tr>
+                      ))}
+                    </tbody>
+                  </table>
+                </div>
+              ) : (
+                <PanelEmpty message="No unit history recorded yet" />
+              )}
+            </>
+          )}
+
+          {activeTab === "phase" && data.byPhase.length === 0 && <PanelEmpty message="No phase breakdown available" />}
+          {activeTab === "slice" && data.bySlice.length === 0 && <PanelEmpty message="No slice breakdown available" />}
+          {activeTab === "model" && data.byModel.length === 0 && <PanelEmpty message="No model breakdown available" />}
+        </>
+      )}
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// 3. UNDO PANEL — Last completed unit info + undo action
+// ═══════════════════════════════════════════════════════════════════════
+
+export function UndoPanel() {
+  const workspace = useGSDWorkspaceState()
+  const { loadUndoInfo, executeUndoAction } = useGSDWorkspaceActions()
+  const state = workspace.commandSurface.remainingCommands.undo
+  const data = state.data as UndoInfo | null
+  const busy = state.phase === "loading"
+  const [confirming, setConfirming] = useState(false)
+  const [executing, setExecuting] = useState(false)
+  const [result, setResult] = useState<UndoResult | null>(null)
+
+  const handleUndo = async () => {
+    setExecuting(true)
+    setResult(null)
+    try {
+      const res = await executeUndoAction()
+      setResult(res)
+      setConfirming(false)
+    } finally {
+      setExecuting(false)
+    }
+  }
+
+  return (
+    <div className="space-y-4" data-testid="gsd-surface-gsd-undo">
+      <PanelHeader
+        title="Undo Last Unit"
+        icon={<Undo2 className="h-3.5 w-3.5" />}
+        onRefresh={() => { setResult(null); setConfirming(false); void loadUndoInfo() }}
+        refreshing={busy}
+      />
+
+      {state.error && <PanelError message={state.error} />}
+      {busy && !data && <PanelLoading label="Loading undo info…" />}
+
+      {/* Result banner */}
+      {result && (
+        <div className={cn(
+          "rounded-lg border px-3 py-2.5 text-xs",
+          result.success
+            ? "border-success/20 bg-success/5 text-success"
+            : "border-destructive/20 bg-destructive/5 text-destructive",
+        )}>
+          <div className="flex items-center gap-2">
+            {result.success ? <CheckCircle2 className="h-3.5 w-3.5" /> : <XCircle className="h-3.5 w-3.5" />}
+            <span className="font-medium">{result.success ? "Undo Successful" : "Undo Failed"}</span>
+          </div>
+          <p className="mt-1 text-[11px] text-muted-foreground">{result.message}</p>
+        </div>
+      )}
+
+      {data && (
+        <>
+          {data.lastUnitType ? (
+            <>
+              {/* Last unit info */}
+              <div className="rounded-lg border border-border/50 bg-card/50 px-3 py-2.5 space-y-1.5">
+                <h4 className="text-[11px] font-medium text-muted-foreground uppercase tracking-wide">Last Completed Unit</h4>
+                <div className="grid grid-cols-2 gap-x-4 gap-y-0.5 text-[11px]">
+                  <span className="text-muted-foreground">Type</span>
+                  <span className="font-mono text-foreground/80">{data.lastUnitType}</span>
+                  <span className="text-muted-foreground">ID</span>
+                  <span className="font-mono text-foreground/80 truncate">{data.lastUnitId ?? "—"}</span>
+                  <span className="text-muted-foreground">Key</span>
+                  <span className="font-mono text-foreground/80 truncate">{data.lastUnitKey ?? "—"}</span>
+                </div>
+              </div>
+
+              <div className="flex flex-wrap gap-2">
+                <InfoPill label="Completed Units" value={data.completedCount} />
+                {data.commits.length > 0 && (
+                  <InfoPill label="Commits" value={data.commits.length} variant="info" />
+                )}
+              </div>
+
+              {/* Commit SHAs */}
+              {data.commits.length > 0 && (
+                <div className="space-y-1.5">
+                  <h4 className="text-[11px] font-medium text-muted-foreground">Associated Commits</h4>
+                  <div className="flex flex-wrap gap-1">
+                    {data.commits.map((sha) => (
+                      <Badge key={sha} variant="outline" className="text-[10px] px-1.5 py-0 font-mono">
+                        {sha.slice(0, 8)}
+                      </Badge>
+                    ))}
+                  </div>
+                </div>
+              )}
+
+              {/* Confirmation */}
+              {!confirming ? (
+                <Button
+                  type="button"
+                  variant="destructive"
+                  size="sm"
+                  onClick={() => setConfirming(true)}
+                  disabled={executing || !!result?.success}
+                  className="h-7 gap-1.5 text-xs"
+                >
+                  <RotateCcw className="h-3 w-3" />
+                  Undo Last Unit
+                </Button>
+              ) : (
+                <div className="rounded-lg border border-warning/20 bg-warning/5 px-3 py-2.5 space-y-2">
+                  <div className="flex items-center gap-2 text-xs text-warning">
+                    <AlertTriangle className="h-3.5 w-3.5" />
+                    <span className="font-medium">This will revert the last unit and its git commits.</span>
+                  </div>
+                  <div className="flex gap-2">
+                    <Button
+                      type="button"
+                      variant="destructive"
+                      size="sm"
+                      onClick={() => void handleUndo()}
+                      disabled={executing}
+                      className="h-7 gap-1.5 text-xs"
+                    >
+                      {executing ? <LoaderCircle className="h-3 w-3 animate-spin" /> : <RotateCcw className="h-3 w-3" />}
+                      Confirm Undo
+                    </Button>
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="sm"
+                      onClick={() => setConfirming(false)}
+                      disabled={executing}
+                      className="h-7 text-xs"
+                    >
+                      Cancel
+                    </Button>
+                  </div>
+                </div>
+              )}
+            </>
+          ) : (
+            <PanelEmpty message="No completed units to undo" />
+          )}
+        </>
+      )}
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// 4. STEER PANEL — Overrides display + steer message form
+// ═══════════════════════════════════════════════════════════════════════
+
+export function SteerPanel() {
+  const workspace = useGSDWorkspaceState()
+  const { loadSteerData, sendSteer } = useGSDWorkspaceActions()
+  const state = workspace.commandSurface.remainingCommands.steer
+  const data = state.data as SteerData | null
+  const busy = state.phase === "loading"
+  const [message, setMessage] = useState("")
+  const [sending, setSending] = useState(false)
+  const [sent, setSent] = useState(false)
+
+  const handleSend = async () => {
+    if (!message.trim()) return
+    setSending(true)
+    setSent(false)
+    try {
+      await sendSteer(message.trim())
+      setSent(true)
+      setMessage("")
+      // Reload overrides after steering
+      void loadSteerData()
+    } finally {
+      setSending(false)
+    }
+  }
+
+  return (
+    <div className="space-y-4" data-testid="gsd-surface-gsd-steer">
+      <PanelHeader
+        title="Steer"
+        icon={<Navigation className="h-3.5 w-3.5" />}
+        onRefresh={() => { setSent(false); void loadSteerData() }}
+        refreshing={busy}
+      />
+
+      {state.error && <PanelError message={state.error} />}
+      {busy && !data && <PanelLoading label="Loading steer data…" />}
+
+      {/* Success banner */}
+      {sent && (
+        <div className="rounded-lg border border-success/20 bg-success/5 px-3 py-2.5 text-xs text-success flex items-center gap-2">
+          <CheckCircle2 className="h-3.5 w-3.5" />
+          Steering message sent successfully.
+        </div>
+      )}
+
+      {/* Current overrides */}
+      <div className="space-y-2">
+        <h4 className="text-[11px] font-medium text-muted-foreground uppercase tracking-wide">Current Overrides</h4>
+        {data?.overridesContent ? (
+          <div className="rounded-lg border border-border/50 bg-background/50 px-3 py-2.5 text-[11px] font-mono text-foreground/80 whitespace-pre-wrap max-h-[200px] overflow-y-auto leading-relaxed">
+            {data.overridesContent}
+          </div>
+        ) : (
+          <div className="rounded-lg border border-border/50 bg-card/50 px-3 py-2.5 text-[11px] text-muted-foreground italic">
+            No active overrides
+          </div>
+        )}
+      </div>
+
+      {/* Steer message form */}
+      <div className="space-y-2">
+        <h4 className="text-[11px] font-medium text-muted-foreground uppercase tracking-wide">Send Steering Message</h4>
+        <Textarea
+          value={message}
+          onChange={(e) => setMessage(e.target.value)}
+          placeholder="Enter steering instructions for the agent…"
+          className="min-h-[80px] text-xs resize-none"
+        />
+        <Button
+          type="button"
+          variant="default"
+          size="sm"
+          onClick={() => void handleSend()}
+          disabled={sending || !message.trim()}
+          className="h-7 gap-1.5 text-xs"
+        >
+          {sending ? <LoaderCircle className="h-3 w-3 animate-spin" /> : <Navigation className="h-3 w-3" />}
+          Send
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// 5. HOOKS PANEL — Hook entries table
+// ═══════════════════════════════════════════════════════════════════════
+
+export function HooksPanel() {
+  const workspace = useGSDWorkspaceState()
+  const { loadHooksData } = useGSDWorkspaceActions()
+  const state = workspace.commandSurface.remainingCommands.hooks
+  const data = state.data as HooksData | null
+  const busy = state.phase === "loading"
+
+  return (
+    <div className="space-y-4" data-testid="gsd-surface-gsd-hooks">
+      <PanelHeader
+        title="Hooks"
+        icon={<Layers className="h-3.5 w-3.5" />}
+        status={data ? (
+          <Badge variant="outline" className="text-[10px] px-1.5 py-0">
+            {data.entries.length} {data.entries.length === 1 ? "hook" : "hooks"}
+          </Badge>
+        ) : null}
+        onRefresh={() => void loadHooksData()}
+        refreshing={busy}
+      />
+
+      {state.error && <PanelError message={state.error} />}
+      {busy && !data && <PanelLoading label="Loading hooks…" />}
+
+      {data && (
+        <>
+          {data.entries.length > 0 ? (
+            <div className="overflow-x-auto rounded-lg border border-border/50">
+              <table className="w-full text-[11px]">
+                <thead>
+                  <tr className="border-b border-border/50 bg-card/50">
+                    <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Name</th>
+                    <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Type</th>
+                    <th className="px-2.5 py-1.5 text-center font-medium text-muted-foreground">Status</th>
+                    <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Targets</th>
+                    <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Cycles</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {data.entries.map((entry: HookStatusEntry) => {
+                    const totalCycles = Object.values(entry.activeCycles).reduce((sum, n) => sum + n, 0)
+                    return (
+                      <tr key={entry.name} className="border-b border-border/50 last:border-0">
+                        <td className="px-2.5 py-1.5 font-mono text-foreground/80">{entry.name}</td>
+                        <td className="px-2.5 py-1.5">
+                          <Badge variant="outline" className="text-[10px] px-1.5 py-0">
+                            {entry.type}
+                          </Badge>
+                        </td>
+                        <td className="px-2.5 py-1.5 text-center">
+                          <Badge
+                            variant={entry.enabled ? "secondary" : "outline"}
+                            className={cn(
+                              "text-[10px] px-1.5 py-0",
+                              entry.enabled ? "border-success/30 text-success" : "text-muted-foreground",
+                            )}
+                          >
+                            {entry.enabled ? "enabled" : "disabled"}
+                          </Badge>
+                        </td>
+                        <td className="px-2.5 py-1.5 text-muted-foreground">
+                          {entry.targets.length > 0 ? entry.targets.join(", ") : "all"}
+                        </td>
+                        <td className="px-2.5 py-1.5 text-right tabular-nums text-foreground/80">
+                          {totalCycles}
+                        </td>
+                      </tr>
+                    )
+                  })}
+                </tbody>
+              </table>
+            </div>
+          ) : (
+            <PanelEmpty message="No hooks configured" />
+          )}
+
+          {/* Formatted status */}
+          {data.formattedStatus && (
+            <div className="rounded-lg border border-border/50 bg-background/50 px-3 py-2.5 text-[11px] font-mono text-muted-foreground whitespace-pre-wrap leading-relaxed">
+              {data.formattedStatus}
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// 6. INSPECT PANEL — GSD database overview
+// ═══════════════════════════════════════════════════════════════════════
+
+export function InspectPanel() {
+  const workspace = useGSDWorkspaceState()
+  const { loadInspectData } = useGSDWorkspaceActions()
+  const state = workspace.commandSurface.remainingCommands.inspect
+  const data = state.data as InspectData | null
+  const busy = state.phase === "loading"
+
+  return (
+    <div className="space-y-4" data-testid="gsd-surface-gsd-inspect">
+      <PanelHeader
+        title="Inspect Database"
+        icon={<Database className="h-3.5 w-3.5" />}
+        subtitle={data?.schemaVersion != null ? `v${data.schemaVersion}` : null}
+        onRefresh={() => void loadInspectData()}
+        refreshing={busy}
+      />
+
+      {state.error && <PanelError message={state.error} />}
+      {busy && !data && <PanelLoading label="Loading database…" />}
+
+      {data && (
+        <>
+          {/* Counts */}
+          <div className="flex flex-wrap gap-2">
+            <InfoPill label="Decisions" value={data.counts.decisions} variant="info" />
+            <InfoPill label="Requirements" value={data.counts.requirements} variant="info" />
+            <InfoPill label="Artifacts" value={data.counts.artifacts} />
+          </div>
+
+          {/* Recent decisions */}
+          {data.recentDecisions.length > 0 && (
+            <div className="space-y-2">
+              <h4 className="text-xs font-medium text-muted-foreground">Recent Decisions ({data.recentDecisions.length})</h4>
+              <div className="overflow-x-auto rounded-lg border border-border/50">
+                <table className="w-full text-[11px]">
+                  <thead>
+                    <tr className="border-b border-border/50 bg-card/50">
+                      <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">ID</th>
+                      <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Decision</th>
+                      <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Choice</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {data.recentDecisions.map((d) => (
+                      <tr key={d.id} className="border-b border-border/50 last:border-0">
+                        <td className="px-2.5 py-1.5 font-mono text-foreground/80">{d.id}</td>
+                        <td className="px-2.5 py-1.5 text-foreground/80 max-w-[200px] truncate">{d.decision}</td>
+                        <td className="px-2.5 py-1.5 text-muted-foreground max-w-[150px] truncate">{d.choice}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            </div>
+          )}
+
+          {/* Recent requirements */}
+          {data.recentRequirements.length > 0 && (
+            <div className="space-y-2">
+              <h4 className="text-xs font-medium text-muted-foreground">Recent Requirements ({data.recentRequirements.length})</h4>
+              <div className="overflow-x-auto rounded-lg border border-border/50">
+                <table className="w-full text-[11px]">
+                  <thead>
+                    <tr className="border-b border-border/50 bg-card/50">
+                      <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">ID</th>
+                      <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Status</th>
+                      <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Description</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {data.recentRequirements.map((r) => (
+                      <tr key={r.id} className="border-b border-border/50 last:border-0">
+                        <td className="px-2.5 py-1.5 font-mono text-foreground/80">{r.id}</td>
+                        <td className="px-2.5 py-1.5">
+                          <Badge
+                            variant={r.status === "active" ? "secondary" : "outline"}
+                            className={cn(
+                              "text-[10px] px-1.5 py-0",
+                              r.status === "active" && "border-success/30 text-success",
+                              r.status === "validated" && "border-info/30 text-info",
+                              r.status === "deferred" && "text-muted-foreground",
+                            )}
+                          >
+                            {r.status}
+                          </Badge>
+                        </td>
+                        <td className="px-2.5 py-1.5 text-foreground/80 max-w-[220px] truncate">{r.description}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            </div>
+          )}
+
+          {data.recentDecisions.length === 0 && data.recentRequirements.length === 0 && (
+            <PanelEmpty message="Database is empty — no decisions or requirements recorded" />
+          )}
+        </>
+      )}
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// 7. EXPORT PANEL — Format selection + download trigger
+// ═══════════════════════════════════════════════════════════════════════
+
+export function ExportPanel() {
+  const workspace = useGSDWorkspaceState()
+  const { loadExportData } = useGSDWorkspaceActions()
+  const state = workspace.commandSurface.remainingCommands.exportData
+  const data = state.data as ExportResult | null
+  const busy = state.phase === "loading"
+  const [format, setFormat] = useState<"markdown" | "json">("markdown")
+
+  const triggerDownload = (result: ExportResult) => {
+    const mimeType = result.format === "json" ? "application/json" : "text/markdown"
+    const blob = new Blob([result.content], { type: mimeType })
+    const url = URL.createObjectURL(blob)
+    const a = document.createElement("a")
+    a.href = url
+    a.download = result.filename
+    document.body.appendChild(a)
+    a.click()
+    document.body.removeChild(a)
+    URL.revokeObjectURL(url)
+  }
+
+  const handleExport = async () => {
+    const result = await loadExportData(format)
+    if (result) triggerDownload(result)
+  }
+
+  return (
+    <div className="space-y-4" data-testid="gsd-surface-gsd-export">
+      <PanelHeader
+        title="Export"
+        icon={<Download className="h-3.5 w-3.5" />}
+      />
+
+      {state.error && <PanelError message={state.error} />}
+
+      {/* Format selector */}
+      <div className="space-y-2">
+        <h4 className="text-[11px] font-medium text-muted-foreground uppercase tracking-wide">Format</h4>
+        <div className="flex gap-1 rounded-lg border border-border/50 bg-card/50 p-0.5">
+          {(["markdown", "json"] as const).map((f) => (
+            <button
+              key={f}
+              type="button"
+              onClick={() => setFormat(f)}
+              className={cn(
+                "flex-1 rounded-md px-3 py-1.5 text-[11px] font-medium capitalize transition-colors",
+                format === f
+                  ? "bg-card text-foreground shadow-sm"
+                  : "text-muted-foreground hover:text-muted-foreground",
+              )}
+            >
+              {f === "markdown" ? "Markdown" : "JSON"}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      {/* Export button */}
+      <Button
+        type="button"
+        variant="default"
+        size="sm"
+        onClick={() => void handleExport()}
+        disabled={busy}
+        className="h-7 gap-1.5 text-xs"
+      >
+        {busy ? <LoaderCircle className="h-3 w-3 animate-spin" /> : <Download className="h-3 w-3" />}
+        Generate Export
+      </Button>
+
+      {/* Download result */}
+      {data && (
+        <div className="rounded-lg border border-success/20 bg-success/5 px-3 py-2.5 space-y-2">
+          <div className="flex items-center gap-2 text-xs text-success">
+            <CheckCircle2 className="h-3.5 w-3.5" />
+            <span className="font-medium">Export Ready</span>
+          </div>
+          <div className="flex items-center justify-between gap-2">
+            <span className="text-[11px] font-mono text-muted-foreground">{data.filename}</span>
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              onClick={() => triggerDownload(data)}
+              className="h-6 gap-1 text-[10px]"
+            >
+              <Download className="h-2.5 w-2.5" />
+              Download Again
+            </Button>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// 8. CLEANUP PANEL — Branches and snapshots management
+// ═══════════════════════════════════════════════════════════════════════
+
+export function CleanupPanel() {
+  const workspace = useGSDWorkspaceState()
+  const { loadCleanupData, executeCleanupAction } = useGSDWorkspaceActions()
+  const state = workspace.commandSurface.remainingCommands.cleanup
+  const data = state.data as CleanupData | null
+  const busy = state.phase === "loading"
+  const [executing, setExecuting] = useState(false)
+  const [result, setResult] = useState<CleanupResult | null>(null)
+
+  const mergedBranches = data?.branches.filter((b: CleanupBranch) => b.merged) ?? []
+  const oldSnapshots = data?.snapshots ?? []
+
+  const handleCleanup = async (type: "branches" | "snapshots") => {
+    setExecuting(true)
+    setResult(null)
+    try {
+      const branches = type === "branches" ? mergedBranches.map((b: CleanupBranch) => b.name) : []
+      const snapshots = type === "snapshots" ? oldSnapshots.map((s: CleanupSnapshot) => s.ref) : []
+      const res = await executeCleanupAction(branches, snapshots)
+      setResult(res)
+      // Reload after cleanup
+      void loadCleanupData()
+    } finally {
+      setExecuting(false)
+    }
+  }
+
+  return (
+    <div className="space-y-4" data-testid="gsd-surface-gsd-cleanup">
+      <PanelHeader
+        title="Cleanup"
+        icon={<Trash2 className="h-3.5 w-3.5" />}
+        onRefresh={() => { setResult(null); void loadCleanupData() }}
+        refreshing={busy}
+      />
+
+      {state.error && <PanelError message={state.error} />}
+      {busy && !data && <PanelLoading label="Scanning for cleanup targets…" />}
+
+      {/* Result banner */}
+      {result && (
+        <div className="rounded-lg border border-success/20 bg-success/5 px-3 py-2.5 text-xs text-success">
+          <div className="flex items-center gap-2">
+            <CheckCircle2 className="h-3.5 w-3.5" />
+            <span className="font-medium">Cleanup Complete</span>
+          </div>
+          <p className="mt-1 text-[11px] text-muted-foreground">{result.message}</p>
+        </div>
+      )}
+
+      {data && (
+        <>
+          {/* Branches table */}
+          <div className="space-y-2">
+            <div className="flex items-center justify-between">
+              <h4 className="text-xs font-medium text-muted-foreground">Branches ({data.branches.length})</h4>
+              {mergedBranches.length > 0 && (
+                <Button
+                  type="button"
+                  variant="destructive"
+                  size="sm"
+                  onClick={() => void handleCleanup("branches")}
+                  disabled={executing}
+                  className="h-6 gap-1 text-[10px]"
+                >
+                  {executing ? <LoaderCircle className="h-2.5 w-2.5 animate-spin" /> : <Scissors className="h-2.5 w-2.5" />}
+                  Delete Merged ({mergedBranches.length})
+                </Button>
+              )}
+            </div>
+            {data.branches.length > 0 ? (
+              <div className="overflow-x-auto rounded-lg border border-border/50">
+                <table className="w-full text-[11px]">
+                  <thead>
+                    <tr className="border-b border-border/50 bg-card/50">
+                      <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Branch</th>
+                      <th className="px-2.5 py-1.5 text-center font-medium text-muted-foreground">Status</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {data.branches.map((b: CleanupBranch) => (
+                      <tr key={b.name} className="border-b border-border/50 last:border-0">
+                        <td className="px-2.5 py-1.5 font-mono text-foreground/80 truncate max-w-[250px]">
+                          <span className="flex items-center gap-1.5">
+                            <GitBranch className="h-3 w-3 text-muted-foreground shrink-0" />
+                            {b.name}
+                          </span>
+                        </td>
+                        <td className="px-2.5 py-1.5 text-center">
+                          <Badge
+                            variant={b.merged ? "secondary" : "outline"}
+                            className={cn(
+                              "text-[10px] px-1.5 py-0",
+                              b.merged ? "border-success/30 text-success" : "text-muted-foreground",
+                            )}
+                          >
+                            {b.merged ? "merged" : "active"}
+                          </Badge>
+                        </td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            ) : (
+              <PanelEmpty message="No branches to clean up" />
+            )}
+          </div>
+
+          {/* Snapshots table */}
+          <div className="space-y-2">
+            <div className="flex items-center justify-between">
+              <h4 className="text-xs font-medium text-muted-foreground">Snapshots ({data.snapshots.length})</h4>
+              {oldSnapshots.length > 0 && (
+                <Button
+                  type="button"
+                  variant="destructive"
+                  size="sm"
+                  onClick={() => void handleCleanup("snapshots")}
+                  disabled={executing}
+                  className="h-6 gap-1 text-[10px]"
+                >
+                  {executing ? <LoaderCircle className="h-2.5 w-2.5 animate-spin" /> : <Archive className="h-2.5 w-2.5" />}
+                  Prune Snapshots ({oldSnapshots.length})
+                </Button>
+              )}
+            </div>
+            {data.snapshots.length > 0 ? (
+              <div className="overflow-x-auto rounded-lg border border-border/50">
+                <table className="w-full text-[11px]">
+                  <thead>
+                    <tr className="border-b border-border/50 bg-card/50">
+                      <th className="px-2.5 py-1.5 text-left font-medium text-muted-foreground">Ref</th>
+                      <th className="px-2.5 py-1.5 text-right font-medium text-muted-foreground">Date</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {data.snapshots.map((s: CleanupSnapshot) => (
+                      <tr key={s.ref} className="border-b border-border/50 last:border-0">
+                        <td className="px-2.5 py-1.5 font-mono text-foreground/80 truncate max-w-[200px]">{s.ref}</td>
+                        <td className="px-2.5 py-1.5 text-right text-muted-foreground">{s.date}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            ) : (
+              <PanelEmpty message="No snapshots to prune" />
+            )}
+          </div>
+        </>
+      )}
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// 9. QUEUE PANEL — Milestone registry from existing workspace data
+// ═══════════════════════════════════════════════════════════════════════
+
+function sliceProgress(slices: WorkspaceSliceTarget[]): { done: number; total: number } {
+  const done = slices.filter((s) => s.done).length
+  return { done, total: slices.length }
+}
+
+export function QueuePanel() {
+  const workspace = useGSDWorkspaceState()
+  const workspaceIndex = getLiveWorkspaceIndex(workspace)
+  const milestones = workspaceIndex?.milestones ?? []
+  const active = workspaceIndex?.active
+
+  return (
+    <div className="space-y-4" data-testid="gsd-surface-gsd-queue">
+      <PanelHeader
+        title="Queue"
+        icon={<ListChecks className="h-3.5 w-3.5" />}
+        status={
+          <Badge variant="outline" className="text-[10px] px-1.5 py-0">
+            {milestones.length} {milestones.length === 1 ? "milestone" : "milestones"}
+          </Badge>
+        }
+      />
+
+      {milestones.length > 0 ? (
+        <div className="space-y-2">
+          {milestones.map((m: WorkspaceMilestoneTarget) => {
+            const isActive = active?.milestoneId === m.id
+            const progress = sliceProgress(m.slices)
+            return (
+              <div
+                key={m.id}
+                className={cn(
+                  "rounded-lg border px-3 py-2.5 space-y-1.5",
+                  isActive
+                    ? "border-info/25 bg-info/5"
+                    : "border-border/50 bg-card/50",
+                )}
+              >
+                <div className="flex items-center justify-between gap-2">
+                  <div className="flex items-center gap-2">
+                    <span className="text-xs font-mono font-medium text-foreground/80">{m.id}</span>
+                    <span className="text-xs text-foreground truncate">{m.title}</span>
+                    {isActive && (
+                      <Badge variant="secondary" className="text-[10px] px-1.5 py-0 border-info/30 text-info">
+                        active
+                      </Badge>
+                    )}
+                  </div>
+                  <span className="text-[10px] text-muted-foreground tabular-nums shrink-0">
+                    {progress.done}/{progress.total} slices
+                  </span>
+                </div>
+
+                {/* Progress bar */}
+                {progress.total > 0 && (
+                  <div className="h-1 rounded-full bg-border/50 overflow-hidden">
+                    <div
+                      className={cn(
+                        "h-full rounded-full transition-all",
+                        progress.done === progress.total ? "bg-success" : "bg-info",
+                      )}
+                      style={{ width: `${(progress.done / progress.total) * 100}%` }}
+                    />
+                  </div>
+                )}
+
+                {/* Slice list for active milestone */}
+                {isActive && m.slices.length > 0 && (
+                  <div className="space-y-0.5 pt-1">
+                    {m.slices.map((s: WorkspaceSliceTarget) => (
+                      <div key={s.id} className="flex items-center gap-2 text-[11px]">
+                        {s.done ? (
+                          <CheckCircle2 className="h-3 w-3 text-success shrink-0" />
+                        ) : (
+                          <span className={cn(
+                            "inline-block h-1.5 w-1.5 rounded-full shrink-0",
+                            active?.sliceId === s.id ? "bg-info" : "bg-border/50",
+                          )} />
+                        )}
+                        <span className="font-mono text-muted-foreground">{s.id}</span>
+                        <span className={cn(
+                          "truncate",
+                          s.done ? "text-muted-foreground line-through" : "text-foreground/80",
+                        )}>
+                          {s.title}
+                        </span>
+                        {active?.sliceId === s.id && !s.done && (
+                          <Badge variant="outline" className="text-[9px] px-1 py-0 text-info">current</Badge>
+                        )}
+                      </div>
+                    ))}
+                  </div>
+                )}
+              </div>
+            )
+          })}
+        </div>
+      ) : (
+        <PanelEmpty message="No milestones in the plan" />
+      )}
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// 10. STATUS PANEL — Current active context from workspace data
+// ═══════════════════════════════════════════════════════════════════════
+
+export function StatusPanel() {
+  const workspace = useGSDWorkspaceState()
+  const workspaceIndex = getLiveWorkspaceIndex(workspace)
+  const active = workspaceIndex?.active
+  const milestones = workspaceIndex?.milestones ?? []
+
+  const currentMilestone = milestones.find((m: WorkspaceMilestoneTarget) => m.id === active?.milestoneId)
+  const currentSlice = currentMilestone?.slices.find((s: WorkspaceSliceTarget) => s.id === active?.sliceId)
+
+  const totalSlices = milestones.reduce((sum: number, m: WorkspaceMilestoneTarget) => sum + m.slices.length, 0)
+  const doneSlices = milestones.reduce((sum: number, m: WorkspaceMilestoneTarget) => sum + m.slices.filter((s) => s.done).length, 0)
+
+  return (
+    <div className="space-y-4" data-testid="gsd-surface-gsd-status">
+      <PanelHeader
+        title="Status"
+        icon={<Terminal className="h-3.5 w-3.5" />}
+      />
+
+      {/* Active context card */}
+      <div className="rounded-lg border border-border/50 bg-card/50 px-3 py-3 space-y-2">
+        <h4 className="text-[11px] font-medium text-muted-foreground uppercase tracking-wide">Active Context</h4>
+        <div className="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1 text-[11px]">
+          <span className="text-muted-foreground">Phase</span>
+          <span className="font-mono text-foreground/80">
+            {active?.phase ? (
+              <Badge variant="secondary" className="text-[10px] px-1.5 py-0">{active.phase}</Badge>
+            ) : (
+              <span className="text-muted-foreground italic">idle</span>
+            )}
+          </span>
+
+          <span className="text-muted-foreground">Milestone</span>
+          <span className="font-mono text-foreground/80">
+            {currentMilestone ? (
+              <span>{currentMilestone.id} — {currentMilestone.title}</span>
+            ) : (
+              <span className="text-muted-foreground italic">none</span>
+            )}
+          </span>
+
+          <span className="text-muted-foreground">Slice</span>
+          <span className="font-mono text-foreground/80">
+            {currentSlice ? (
+              <span>{currentSlice.id} — {currentSlice.title}</span>
+            ) : (
+              <span className="text-muted-foreground italic">none</span>
+            )}
+          </span>
+
+          <span className="text-muted-foreground">Task</span>
+          <span className="font-mono text-foreground/80">
+            {active?.taskId ?? <span className="text-muted-foreground italic">none</span>}
+          </span>
+        </div>
+      </div>
+
+      {/* Overall progress */}
+      <div className="flex flex-wrap gap-2">
+        <InfoPill label="Milestones" value={milestones.length} />
+        <InfoPill label="Slices" value={`${doneSlices}/${totalSlices}`} variant={doneSlices === totalSlices && totalSlices > 0 ? "success" : "info"} />
+      </div>
+
+      {/* Progress bar */}
+      {totalSlices > 0 && (
+        <div className="space-y-1">
+          <div className="flex items-center justify-between text-[10px] text-muted-foreground">
+            <span>Overall Progress</span>
+            <span className="tabular-nums">{Math.round((doneSlices / totalSlices) * 100)}%</span>
+          </div>
+          <div className="h-1.5 rounded-full bg-border/50 overflow-hidden">
+            <div
+              className={cn(
+                "h-full rounded-full transition-all",
+                doneSlices === totalSlices ? "bg-success" : "bg-info",
+              )}
+              style={{ width: `${(doneSlices / totalSlices) * 100}%` }}
+            />
+          </div>
+        </div>
+      )}
+
+      {milestones.length === 0 && (
+        <PanelEmpty message="No plan loaded — run /gsd to initialize" />
+      )}
+    </div>
+  )
+}
diff --git a/web/components/sf/roadmap.tsx b/web/components/sf/roadmap.tsx
new file mode 100644
index 000000000..ebe8f0302
--- /dev/null
+++ b/web/components/sf/roadmap.tsx
@@ -0,0 +1,159 @@
+"use client"
+
+import { CheckCircle2, Circle, Play, AlertTriangle, ChevronRight } from "lucide-react"
+import { cn } from "@/lib/utils"
+import { getLiveWorkspaceIndex, useGSDWorkspaceState, type RiskLevel } from "@/lib/sf-workspace-store"
+import { getMilestoneStatus, getSliceStatus, type ItemStatus } from "@/lib/workspace-status"
+
+const StatusIcon = ({
+  status,
+  size = "default",
+}: {
+  status: ItemStatus
+  size?: "default" | "large"
+}) => {
+  const sizeClass = size === "large" ? "h-5 w-5" : "h-4 w-4"
+  if (status === "done") {
+    return <CheckCircle2 className={cn(sizeClass, "text-success")} />
+  }
+  if (status === "in-progress") {
+    return <Play className={cn(sizeClass, "text-warning")} />
+  }
+  return <Circle className={cn(sizeClass, "text-muted-foreground")} />
+}
+
+const RiskBadge = ({ risk }: { risk: RiskLevel }) => {
+  return (
+    <span
+      className={cn(
+        "inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-[10px] font-medium uppercase",
+        risk === "high" && "bg-destructive/20 text-destructive",
+        risk === "medium" && "bg-warning/20 text-warning",
+        risk === "low" && "bg-muted text-muted-foreground",
+      )}
+    >
+      {risk === "high" && <AlertTriangle className="h-2.5 w-2.5" />}
+      {risk}
+    </span>
+  )
+}
+
+export function Roadmap() {
+  const workspace = useGSDWorkspaceState()
+  const liveWorkspace = getLiveWorkspaceIndex(workspace)
+  const milestones = liveWorkspace?.milestones ?? []
+  const activeScope = liveWorkspace?.active ?? {}
+  const workspaceFreshness = workspace.live.freshness.workspace.stale ? "stale" : workspace.live.freshness.workspace.status
+
+  return (
+    <div className="flex h-full flex-col overflow-hidden">
+      <div className="border-b border-border px-6 py-3">
+        <h1 className="text-lg font-semibold">Roadmap</h1>
+        <p className="text-sm text-muted-foreground">
+          Project milestone structure with slices and dependencies
+        </p>
+        <p className="mt-1 text-xs text-muted-foreground" data-testid="roadmap-workspace-freshness">
+          Workspace freshness: {workspaceFreshness}
+        </p>
+      </div>
+
+      <div className="flex-1 overflow-y-auto p-6">
+        {workspace.bootStatus === "loading" && (
+          <div className="py-8 text-center text-sm text-muted-foreground">Loading workspace…</div>
+        )}
+
+        {workspace.bootStatus === "ready" && milestones.length === 0 && (
+          <div className="py-8 text-center text-sm text-muted-foreground">
+            No milestones found. Create a milestone with <code className="rounded bg-muted px-1.5 py-0.5 font-mono text-xs">/gsd</code> to get started.
+          </div>
+        )}
+
+        <div className="space-y-6">
+          {milestones.map((milestone) => {
+            const milestoneStatus = getMilestoneStatus(milestone, activeScope)
+            const doneSlices = milestone.slices.filter((s) => s.done).length
+            const totalTasks = milestone.slices.reduce((acc, s) => acc + s.tasks.length, 0)
+            const doneTasks = milestone.slices.reduce((acc, s) => acc + s.tasks.filter((t) => t.done).length, 0)
+
+            return (
+              <div key={milestone.id} className="rounded-md border border-border bg-card">
+                <div
+                  className={cn(
+                    "flex items-center gap-3 border-b border-border px-4 py-3",
+                    milestoneStatus === "in-progress" && "bg-accent/30",
+                  )}
+                >
+                  <StatusIcon status={milestoneStatus} size="large" />
+                  <div className="flex-1">
+                    <div className="flex items-center gap-2">
+                      <span className="font-mono text-xs text-muted-foreground">{milestone.id}</span>
+                      <ChevronRight className="h-3 w-3 text-muted-foreground" />
+                      <span className="font-semibold">{milestone.title}</span>
+                    </div>
+                  </div>
+                  <div className="text-right">
+                    <div className="text-sm font-medium">
+                      {doneSlices}/{milestone.slices.length} slices
+                    </div>
+                    <div className="text-xs text-muted-foreground">
+                      {doneTasks}/{totalTasks} tasks
+                    </div>
+                  </div>
+                </div>
+
+                <div className="divide-y divide-border">
+                  {milestone.slices.map((slice) => {
+                    const sliceStatus = getSliceStatus(milestone.id, slice, activeScope)
+                    const sliceDoneTasks = slice.tasks.filter((t) => t.done).length
+                    const sliceTotalTasks = slice.tasks.length
+
+                    return (
+                      <div
+                        key={`${milestone.id}-${slice.id}`}
+                        className={cn(
+                          "flex items-center gap-3 px-4 py-2.5",
+                          sliceStatus === "in-progress" && "bg-accent/20",
+                          sliceStatus === "pending" && "opacity-70",
+                        )}
+                      >
+                        <div className="w-4" />
+                        <StatusIcon status={sliceStatus} />
+                        <div className="flex-1">
+                          <div className="flex items-center gap-2">
+                            <span className="font-mono text-xs text-muted-foreground">{slice.id}</span>
+                            <span className="text-sm">{slice.title}</span>
+                            {slice.risk && <RiskBadge risk={slice.risk} />}
+                            {slice.depends && slice.depends.length > 0 && (
+                              <span className="text-[10px] text-muted-foreground">
+                                depends on {slice.depends.join(", ")}
+                              </span>
+                            )}
+                          </div>
+                        </div>
+                        <div className="flex items-center gap-4">
+                          <div className="w-24">
+                            <div className="h-1 w-full rounded-full bg-accent">
+                              <div
+                                className="h-full rounded-full bg-foreground/70 transition-all"
+                                style={{
+                                  width: sliceTotalTasks > 0 ? `${(sliceDoneTasks / sliceTotalTasks) * 100}%` : "0%",
+                                }}
+                              />
+                            </div>
+                          </div>
+                          <span className="w-12 text-right text-xs text-muted-foreground">
+                            {sliceDoneTasks}/{sliceTotalTasks}
+                          </span>
+                        </div>
+                      </div>
+                    )
+                  })}
+                </div>
+              </div>
+            )
+          })}
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/web/components/sf/scope-badge.tsx b/web/components/sf/scope-badge.tsx
new file mode 100644
index 000000000..127c5329c
--- /dev/null
+++ b/web/components/sf/scope-badge.tsx
@@ -0,0 +1,154 @@
+"use client"
+
+import { cn } from "@/lib/utils"
+
+/* ─── Helpers ──────────────────────────────────────────────────────────────── */
+
+type PhaseTone = "success" | "active" | "warning" | "muted" | "info"
+
+function phasePresentation(phase: string): { label: string; tone: PhaseTone } {
+  switch (phase) {
+    case "complete":
+    case "completed":
+      return { label: "Complete", tone: "success" }
+    case "executing":
+      return { label: "Executing", tone: "active" }
+    case "in-progress":
+      return { label: "In Progress", tone: "active" }
+    case "planning":
+      return { label: "Planning", tone: "info" }
+    case "pre-planning":
+      return { label: "Pre-planning", tone: "muted" }
+    case "summarizing":
+      return { label: "Summarizing", tone: "info" }
+    case "blocked":
+      return { label: "Blocked", tone: "warning" }
+    case "needs-discussion":
+      return { label: "Discussion", tone: "warning" }
+    case "replanning-slice":
+      return { label: "Replanning", tone: "info" }
+    case "completing-milestone":
+      return { label: "Completing", tone: "info" }
+    case "evaluating-gates":
+      return { label: "Evaluating Gates", tone: "info" }
+    default:
+      return { label: phase, tone: "muted" }
+  }
+}
+
+const tonePill: Record<PhaseTone, string> = {
+  success: "bg-success/15 text-success",
+  active: "bg-primary/15 text-primary",
+  warning: "bg-warning/15 text-warning",
+  info: "bg-info/15 text-info",
+  muted: "bg-muted text-muted-foreground",
+}
+
+const toneDot: Record<PhaseTone, string> = {
+  success: "bg-success",
+  active: "bg-primary",
+  warning: "bg-warning",
+  info: "bg-info",
+  muted: "bg-muted-foreground/50",
+}
+
+/**
+ * Strip leading zeros from GSD IDs: M002 → M2, S01 → S1, T03 → T3.
+ * Handles compound paths like "M001/S02/T03" → "M1/S2/T3".
+ */
+function normalizeScopeId(raw: string): string {
+  return raw.replace(/([MST])0*(\d+)/g, "$1$2")
+}
+
+/**
+ * Parse a scope label like "M002 — completed" into { scopeId, phase }.
+ * Also handles bare IDs like "M002" (from auto mode).
+ */
+function parseScopeLabel(label: string): { scopeId: string; phase: string | null } {
+  const m = label.match(/^(.+?)\s*—\s*(.+)$/)
+  if (m) return { scopeId: normalizeScopeId(m[1].trim()), phase: m[2].trim() }
+  return { scopeId: normalizeScopeId(label.trim()), phase: null }
+}
+
+/* ─── Components ───────────────────────────────────────────────────────────── */
+
+interface ScopeBadgeProps {
+  /** Raw scope label, e.g. "M002 — completed", "M001/S02/T03 — executing", or just "M002" */
+  label: string
+  /** Size variant */
+  size?: "sm" | "md"
+  className?: string
+}
+
+/**
+ * Renders a scope label as: M002 [Complete]
+ * The scope ID stays as-is (compact), phase gets a small colored pill.
+ */
+export function ScopeBadge({ label, size = "md", className }: ScopeBadgeProps) {
+  const { scopeId, phase } = parseScopeLabel(label)
+
+  if (scopeId === "Project scope pending") {
+    return <span className={cn("text-muted-foreground", sizeText(size), className)}>Scope pending…</span>
+  }
+
+  const phaseInfo = phase ? phasePresentation(phase) : null
+
+  return (
+    <span className={cn("inline-flex items-center gap-2", className)}>
+      <span className={cn("font-semibold tracking-tight", sizeValue(size))}>
+        {scopeId}
+      </span>
+      {phaseInfo && (
+        <span
+          className={cn(
+            "inline-flex shrink-0 items-center rounded-full px-2 font-medium leading-snug",
+            tonePill[phaseInfo.tone],
+            sizeText(size),
+            sizePy(size),
+          )}
+        >
+          {phaseInfo.label}
+        </span>
+      )}
+    </span>
+  )
+}
+
+function sizeText(size: "sm" | "md") {
+  return size === "sm" ? "text-[10px]" : "text-[11px]"
+}
+
+function sizeValue(size: "sm" | "md") {
+  return size === "sm" ? "text-sm" : "text-lg"
+}
+
+function sizePy(size: "sm" | "md") {
+  return size === "sm" ? "py-px" : "py-0.5"
+}
+
+/**
+ * Inline variant for the status bar — renders: ● M002 · Complete
+ */
+export function ScopeBadgeInline({ label, className }: { label: string; className?: string }) {
+  const { scopeId, phase } = parseScopeLabel(label)
+
+  if (scopeId === "Project scope pending") {
+    return <span className={cn("text-muted-foreground", className)}>Scope pending…</span>
+  }
+
+  const phaseInfo = phase ? phasePresentation(phase) : null
+  const dotColor = phaseInfo ? toneDot[phaseInfo.tone] : "bg-muted-foreground/50"
+
+  return (
+    <span className={cn("inline-flex items-center gap-1.5", className)}>
+      <span className={cn("h-1.5 w-1.5 shrink-0 rounded-full", dotColor)} />
+      <span>{scopeId}</span>
+      {phaseInfo && (
+        <>
+          <span className="text-border">·</span>
+          <span>{phaseInfo.label}</span>
+        </>
+      )}
+    </span>
+  )
+}
diff --git a/web/components/sf/settings-panels.tsx b/web/components/sf/settings-panels.tsx
new file mode 100644
index 000000000..a5fe18a74
--- /dev/null
+++ b/web/components/sf/settings-panels.tsx
@@ -0,0 +1,1240 @@
+"use client"
+
+import { useState, useEffect, useCallback } from "react"
+
+import {
+  AlertTriangle,
+  CheckCircle2,
+  Cpu,
+  DollarSign,
+  Eye,
+  EyeOff,
+  FlaskConical,
+  KeyRound,
+  LoaderCircle,
+  Radio,
+  RefreshCw,
+  Settings,
+  SlidersHorizontal,
+  Type,
+} from "lucide-react"
+
+import { Badge } from "@/components/ui/badge"
+import { Button } from "@/components/ui/button"
+import type {
+  SettingsData,
+  SettingsPatternHistory,
+  SettingsRoutingHistory,
+} from "@/lib/settings-types"
+import { cn } from "@/lib/utils"
+import {
+  formatCost,
+  formatTokens,
+  useGSDWorkspaceActions,
+  useGSDWorkspaceState,
+} from "@/lib/sf-workspace-store"
+import { useTerminalFontSize } from "@/lib/use-terminal-font-size"
+import { useEditorFontSize } from "@/lib/use-editor-font-size"
+import { authFetch } from "@/lib/auth"
+
+// ═══════════════════════════════════════════════════════════════════════
+// SHARED INFRASTRUCTURE
+// ═══════════════════════════════════════════════════════════════════════
+
+function SettingsHeader({
+  title,
+  icon,
+  subtitle,
+  onRefresh,
+  refreshing,
+}: {
+  title: string
+  icon: React.ReactNode
+  subtitle?: string | null
+  onRefresh: () => void
+  refreshing: boolean
+}) {
+  return (
+    <div className="flex items-center justify-between gap-3 pb-4">
+      <div className="flex items-center gap-2.5">
+        <span className="text-muted-foreground">{icon}</span>
+        <h3 className="text-[13px] font-semibold uppercase tracking-[0.08em] text-muted-foreground">{title}</h3>
+        {subtitle && <span className="text-[11px] text-muted-foreground">{subtitle}</span>}
+      </div>
+      <Button type="button" variant="ghost" size="sm" onClick={onRefresh} disabled={refreshing} className="h-7 gap-1.5 text-xs">
+        <RefreshCw className={cn("h-3 w-3", refreshing && "animate-spin")} />
+        Refresh
+      </Button>
+    </div>
+  )
+}
+
+function SettingsError({ message }: { message: string }) {
+  return (
+    <div className="rounded-lg border border-destructive/20 bg-destructive/5 px-3 py-2.5 text-xs text-destructive">
+      {message}
+    </div>
+  )
+}
+
+function SettingsLoading({ label }: { label: string }) {
+  return (
+    <div className="flex items-center gap-2 py-6 text-xs text-muted-foreground">
+      <LoaderCircle className="h-3.5 w-3.5 animate-spin" />
+      {label}
+    </div>
+  )
+}
+
+function SettingsEmpty({ message }: { message: string }) {
+  return (
+    <div className="rounded-lg border border-border/50 bg-card/50 px-4 py-5 text-center text-xs text-muted-foreground">
+      {message}
+    </div>
+  )
+}
+
+function Pill({ label, value, variant }: { label: string; value: string | number; variant?: "default" | "info" | "warning" | "success" }) {
+  return (
+    <div className={cn(
+      "flex items-center gap-1.5 rounded-md border px-2.5 py-1 text-xs",
+      variant === "info" && "border-info/20 bg-info/5 text-info",
+      variant === "warning" && "border-warning/20 bg-warning/5 text-warning",
+      variant === "success" && "border-success/20 bg-success/5 text-success",
+      (!variant || variant === "default") && "border-border/50 bg-card/50 text-foreground/80",
+    )}>
+      <span className="text-muted-foreground">{label}</span>
+      <span className="font-medium tabular-nums">{value}</span>
+    </div>
+  )
+}
+
+function FlagBadge({ label, enabled }: { label: string; enabled: boolean | undefined }) {
+  return (
+    <Badge
+      variant={enabled ? "secondary" : "outline"}
+      className={cn(
+        "text-[10px] px-1.5 py-0 font-mono",
+        enabled ? "border-success/30 text-success" : "text-muted-foreground",
+      )}
+    >
+      {label}: {enabled ? "on" : "off"}
+    </Badge>
+  )
+}
+
+function SkillBadgeList({ label, skills }: { label: string; skills: string[] | undefined }) {
+  if (!skills?.length) return null
+  return (
+    <div className="space-y-1">
+      <span className="text-[11px] text-muted-foreground">{label}</span>
+      <div className="flex flex-wrap gap-1">
+        {skills.map((skill) => (
+          <Badge key={skill} variant="outline" className="text-[10px] px-1.5 py-0 font-mono">
+            {skill}
+          </Badge>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+function ModelBadgeList({ models }: { models: Record<string, string> | undefined }) {
+  if (!models || Object.keys(models).length === 0) return null
+  return (
+    <div className="space-y-1">
+      <span className="text-[11px] text-muted-foreground">Phase Models</span>
+      <div className="flex flex-wrap gap-1">
+        {Object.entries(models)
+          .sort(([a], [b]) => a.localeCompare(b))
+          .map(([phase, model]) => (
+            <Badge key={phase} variant="outline" className="text-[10px] px-1.5 py-0 font-mono">
+              {phase}: {model}
+            </Badge>
+          ))}
+      </div>
+    </div>
+  )
+}
+
+function KvRow({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <div className="flex items-center justify-between gap-4 text-xs">
+      <span className="text-muted-foreground shrink-0">{label}</span>
+      <span className="text-foreground/80 text-right truncate">{children}</span>
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// HOOK: shared settings data access
+// ═══════════════════════════════════════════════════════════════════════
+
+function useSettingsData() {
+  const workspace = useGSDWorkspaceState()
+  const { loadSettingsData } = useGSDWorkspaceActions()
+  const state = workspace.commandSurface.settingsData
+  return {
+    state,
+    data: state.data as SettingsData | null,
+    busy: state.phase === "loading",
+    refresh: () => void loadSettingsData(),
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// PREFS PANEL
+// ═══════════════════════════════════════════════════════════════════════
+
+function tokenProfileVariant(profile: string | undefined): "info" | "warning" | "success" {
+  if (profile === "budget") return "warning"
+  if (profile === "quality") return "success"
+  return "info"
+}
+
+export function PrefsPanel() {
+  const { state, data, busy, refresh } = useSettingsData()
+  const prefs = data?.preferences ?? null
+
+  return (
+    <div className="space-y-4" data-testid="settings-prefs">
+      <SettingsHeader
+        title="Effective Preferences"
+        icon={<Settings className="h-3.5 w-3.5" />}
+        subtitle={prefs ? `${prefs.scope} scope` : null}
+        onRefresh={refresh}
+        refreshing={busy}
+      />
+
+      {state.error && <SettingsError message={state.error} />}
+      {busy && !data && <SettingsLoading label="Loading preferences…" />}
+
+      {data && !prefs && <SettingsEmpty message="No preferences file found" />}
+
+      {prefs && (
+        <>
+          {/* Core mode & profile */}
+          <div className="flex flex-wrap gap-2">
+            <Pill label="Mode" value={prefs.mode ?? "solo"} variant="info" />
+            <Pill label="Token Profile" value={prefs.tokenProfile ?? "balanced"} variant={tokenProfileVariant(prefs.tokenProfile)} />
+            {prefs.customInstructions?.length ? (
+              <Pill label="Custom Instructions" value={prefs.customInstructions.length} />
+            ) : null}
+          </div>
+
+          {/* Skills */}
+          <div className="space-y-2">
+            <ModelBadgeList models={prefs.models} />
+            <SkillBadgeList label="Always use" skills={prefs.alwaysUseSkills} />
+            <SkillBadgeList label="Prefer" skills={prefs.preferSkills} />
+            <SkillBadgeList label="Avoid" skills={prefs.avoidSkills} />
+            {!prefs.models || Object.keys(prefs.models).length === 0
+              ? !prefs.alwaysUseSkills?.length && !prefs.preferSkills?.length && !prefs.avoidSkills?.length && (
+                <span className="text-[11px] text-muted-foreground">No model or skill preferences configured</span>
+              )
+              : !prefs.alwaysUseSkills?.length && !prefs.preferSkills?.length && !prefs.avoidSkills?.length && (
+                <span className="text-[11px] text-muted-foreground">No skill preferences configured</span>
+              )}
+          </div>
+
+          {/* Toggles */}
+          <div className="grid grid-cols-2 gap-x-6 gap-y-1.5 rounded-lg border border-border/50 bg-card/50 px-3 py-2.5">
+            <KvRow label="Auto-Supervisor">
+              {prefs.autoSupervisor?.enabled ? (
+                <span className="text-success">
+                  on{prefs.autoSupervisor.softTimeoutMinutes != null && ` (${prefs.autoSupervisor.softTimeoutMinutes}m)`}
+                </span>
+              ) : (
+                <span className="text-muted-foreground">off</span>
+              )}
+            </KvRow>
+            <KvRow label="UAT Dispatch">
+              <span className={prefs.uatDispatch ? "text-success" : "text-muted-foreground"}>
+                {prefs.uatDispatch ? "on" : "off"}
+              </span>
+            </KvRow>
+            <KvRow label="Auto-Visualize">
+              <span className={prefs.autoVisualize ? "text-success" : "text-muted-foreground"}>
+                {prefs.autoVisualize ? "on" : "off"}
+              </span>
+            </KvRow>
+            <KvRow label="Preference Scope">
+              <span className="font-mono text-[10px]">{prefs.scope}</span>
+            </KvRow>
+          </div>
+
+          {/* Source file */}
+          <div className="text-[11px] text-muted-foreground truncate font-mono">
+            Source: {prefs.path}
+          </div>
+
+          {/* Warnings */}
+          {prefs.warnings && prefs.warnings.length > 0 && (
+            <div className="space-y-1.5">
+              <div className="flex items-center gap-1.5 text-xs text-warning">
+                <AlertTriangle className="h-3 w-3" />
+                <span className="font-medium">Warnings ({prefs.warnings.length})</span>
+              </div>
+              {prefs.warnings.map((warning, i) => (
+                <div key={i} className="rounded border border-warning/20 bg-warning/5 px-2.5 py-1.5 text-[11px] text-warning">
+                  {warning}
+                </div>
+              ))}
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// MODEL ROUTING PANEL
+// ═══════════════════════════════════════════════════════════════════════
+
+function topPatterns(history: SettingsRoutingHistory, max = 5): Array<{ name: string; total: number; pattern: SettingsPatternHistory }> {
+  return Object.entries(history.patterns)
+    .map(([name, pattern]) => {
+      const total =
+        pattern.light.success + pattern.light.fail +
+        pattern.standard.success + pattern.standard.fail +
+        pattern.heavy.success + pattern.heavy.fail
+      return { name, total, pattern }
+    })
+    .sort((a, b) => b.total - a.total)
+    .slice(0, max)
+}
+
+function TierModelRow({ tier, modelId }: { tier: string; modelId: string | undefined }) {
+  return (
+    <div className="flex items-center justify-between gap-4 text-xs">
+      <span className="text-muted-foreground capitalize">{tier}</span>
+      <span className="font-mono text-[11px] text-foreground/80 truncate max-w-[200px]">
+        {modelId ?? <span className="text-muted-foreground italic">default</span>}
+      </span>
+    </div>
+  )
+}
+
+function TierOutcomeBadge({ tier, success, fail }: { tier: string; success: number; fail: number }) {
+  const total = success + fail
+  if (total === 0) return null
+  return (
+    <Badge
+      variant="outline"
+      className={cn(
+        "text-[10px] px-1.5 py-0 font-mono",
+        fail > 0 ? "border-destructive/20 text-destructive" : "text-muted-foreground",
+      )}
+    >
+      {tier}: {success}✓{fail > 0 && <span> {fail}✗</span>}
+    </Badge>
+  )
+}
+
+export function ModelRoutingPanel() {
+  const { state, data, busy, refresh } = useSettingsData()
+  const routingConfig = data?.routingConfig ?? null
+  const routingHistory = data?.routingHistory ?? null
+
+  return (
+    <div className="space-y-4" data-testid="settings-model-routing">
+      <SettingsHeader
+        title="Model Routing"
+        icon={<Cpu className="h-3.5 w-3.5" />}
+        onRefresh={refresh}
+        refreshing={busy}
+      />
+
+      {state.error && <SettingsError message={state.error} />}
+      {busy && !data && <SettingsLoading label="Loading routing config…" />}
+
+      {data && (
+        <>
+          {/* Dynamic routing status */}
+          <div className="flex items-center gap-2">
+            <Badge
+              variant={routingConfig?.enabled ? "secondary" : "outline"}
+              className={cn(
+                "text-[10px] px-2 py-0.5",
+                routingConfig?.enabled ? "border-success/30 text-success" : "text-muted-foreground",
+              )}
+            >
+              Dynamic Routing: {routingConfig?.enabled ? "enabled" : "disabled"}
+            </Badge>
+          </div>
+
+          {/* Tier assignments */}
+          {routingConfig?.tier_models && (
+            <div className="rounded-lg border border-border/50 bg-card/50 px-3 py-2.5 space-y-1.5">
+              <h4 className="text-[11px] font-medium text-muted-foreground uppercase tracking-wide">Tier Assignments</h4>
+              <TierModelRow tier="light" modelId={routingConfig.tier_models.light} />
+              <TierModelRow tier="standard" modelId={routingConfig.tier_models.standard} />
+              <TierModelRow tier="heavy" modelId={routingConfig.tier_models.heavy} />
+            </div>
+          )}
+
+          {/* Routing flags */}
+          <div className="flex flex-wrap gap-1.5">
+            <FlagBadge label="escalate_on_failure" enabled={routingConfig?.escalate_on_failure} />
+            <FlagBadge label="budget_pressure" enabled={routingConfig?.budget_pressure} />
+            <FlagBadge label="cross_provider" enabled={routingConfig?.cross_provider} />
+            <FlagBadge label="hooks" enabled={routingConfig?.hooks} />
+          </div>
+
+          {/* Routing history */}
+          {routingHistory ? (
+            <div className="space-y-3">
+              <div className="flex flex-wrap gap-2">
+                <Pill label="Patterns" value={Object.keys(routingHistory.patterns).length} />
+                <Pill label="Feedback" value={routingHistory.feedback.length} />
+              </div>
+
+              {/* Top patterns table */}
+              {Object.keys(routingHistory.patterns).length > 0 && (
+                <div className="space-y-1.5">
+                  <h4 className="text-[11px] font-medium text-muted-foreground">Top Patterns</h4>
+                  <div className="space-y-2">
+                    {topPatterns(routingHistory).map(({ name, total, pattern }) => (
+                      <div key={name} className="rounded-lg border border-border/50 bg-card/50 px-3 py-2 space-y-1">
+                        <div className="flex items-center justify-between gap-2">
+                          <span className="text-xs font-mono text-foreground/80 truncate">{name}</span>
+                          <span className="text-[10px] text-muted-foreground tabular-nums shrink-0">{total} attempts</span>
+                        </div>
+                        <div className="flex flex-wrap gap-1">
+                          <TierOutcomeBadge tier="L" success={pattern.light.success} fail={pattern.light.fail} />
+                          <TierOutcomeBadge tier="S" success={pattern.standard.success} fail={pattern.standard.fail} />
+                          <TierOutcomeBadge tier="H" success={pattern.heavy.success} fail={pattern.heavy.fail} />
+                        </div>
+                      </div>
+                    ))}
+                  </div>
+                </div>
+              )}
+            </div>
+          ) : (
+            <SettingsEmpty message="No routing history yet" />
+          )}
+        </>
+      )}
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// BUDGET PANEL
+// ═══════════════════════════════════════════════════════════════════════
+
+function enforcementVariant(enforcement: string | undefined): "info" | "warning" | "success" {
+  if (enforcement === "halt") return "warning"
+  if (enforcement === "pause") return "info"
+  return "success"
+}
+
+function formatChars(chars: number): string {
+  if (chars >= 1_000_000) return `${(chars / 1_000_000).toFixed(1)}M`
+  if (chars >= 1_000) return `${Math.round(chars / 1_000)}K`
+  return String(chars)
+}
+
+export function BudgetPanel() {
+  const { state, data, busy, refresh } = useSettingsData()
+  const prefs = data?.preferences ?? null
+  const budget = data?.budgetAllocation ?? null
+  const totals = data?.projectTotals ?? null
+
+  return (
+    <div className="space-y-4" data-testid="settings-budget">
+      <SettingsHeader
+        title="Budget & Costs"
+        icon={<DollarSign className="h-3.5 w-3.5" />}
+        onRefresh={refresh}
+        refreshing={busy}
+      />
+
+      {state.error && <SettingsError message={state.error} />}
+      {busy && !data && <SettingsLoading label="Loading budget data…" />}
+
+      {data && (
+        <>
+          {/* Budget controls */}
+          <div className="flex flex-wrap gap-2">
+            <Pill
+              label="Ceiling"
+              value={prefs?.budgetCeiling != null ? formatCost(prefs.budgetCeiling) : "Not set"}
+              variant={prefs?.budgetCeiling != null ? "warning" : "default"}
+            />
+            <Pill
+              label="Enforcement"
+              value={prefs?.budgetEnforcement ?? "Not set"}
+              variant={prefs?.budgetEnforcement ? enforcementVariant(prefs.budgetEnforcement) : "default"}
+            />
+            <Pill
+              label="Token Profile"
+              value={prefs?.tokenProfile ?? "balanced"}
+              variant={tokenProfileVariant(prefs?.tokenProfile)}
+            />
+          </div>
+
+          {/* Context budget allocations */}
+          {budget && (
+            <div className="rounded-lg border border-border/50 bg-card/50 px-3 py-2.5 space-y-1.5">
+              <h4 className="text-[11px] font-medium text-muted-foreground uppercase tracking-wide">Context Budget Allocations</h4>
+              <KvRow label="Summary Budget">{formatChars(budget.summaryBudgetChars)} chars</KvRow>
+              <KvRow label="Inline Context">{formatChars(budget.inlineContextBudgetChars)} chars</KvRow>
+              <KvRow label="Verification">{formatChars(budget.verificationBudgetChars)} chars</KvRow>
+              <KvRow label="Task Count Range">{budget.taskCountRange.min}–{budget.taskCountRange.max}</KvRow>
+              <KvRow label="Continue Threshold">{budget.continueThresholdPercent}%</KvRow>
+            </div>
+          )}
+
+          {/* Project cost totals */}
+          {totals ? (
+            <div className="space-y-3">
+              <h4 className="text-[11px] font-medium text-muted-foreground uppercase tracking-wide">Project Cost Totals</h4>
+
+              {/* Summary pills */}
+              <div className="flex flex-wrap gap-2">
+                <Pill label="Units" value={totals.units} />
+                <Pill label="Total Cost" value={formatCost(totals.cost)} variant="warning" />
+                <Pill label="Duration" value={`${Math.round(totals.duration / 1000)}s`} />
+              </div>
+
+              {/* Token breakdown */}
+              <div className="rounded-lg border border-border/50 bg-card/50 px-3 py-2.5 space-y-1.5">
+                <h4 className="text-[11px] font-medium text-muted-foreground uppercase tracking-wide">Token Breakdown</h4>
+                <KvRow label="Input">{formatTokens(totals.tokens.input)}</KvRow>
+                <KvRow label="Output">{formatTokens(totals.tokens.output)}</KvRow>
+                <KvRow label="Cache Read">{formatTokens(totals.tokens.cacheRead)}</KvRow>
+                <KvRow label="Cache Write">{formatTokens(totals.tokens.cacheWrite)}</KvRow>
+                <KvRow label="Total">{formatTokens(totals.tokens.total)}</KvRow>
+              </div>
+
+              {/* Interaction counts */}
+              <div className="flex flex-wrap gap-2">
+                <Pill label="Tool Calls" value={totals.toolCalls} />
+                <Pill label="Assistant Msgs" value={totals.assistantMessages} />
+                <Pill label="User Msgs" value={totals.userMessages} />
+              </div>
+            </div>
+          ) : (
+            <SettingsEmpty message="No execution metrics yet" />
+          )}
+        </>
+      )}
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// REMOTE QUESTIONS PANEL (Integrations tab)
+// ═══════════════════════════════════════════════════════════════════════
+
+type RemoteChannel = "slack" | "discord" | "telegram"
+
+const CHANNEL_OPTIONS: {
+  value: RemoteChannel
+  label: string
+  description: string
+  idPlaceholder: string
+}[] = [
+  { value: "slack", label: "Slack", description: "Get pinged in a Slack channel", idPlaceholder: "Channel ID (e.g. C01ABCD2EFG)" },
+  { value: "discord", label: "Discord", description: "Get pinged in a Discord channel", idPlaceholder: "Channel ID (17–20 digit number)" },
+  { value: "telegram", label: "Telegram", description: "Get pinged via Telegram bot", idPlaceholder: "Chat ID (numeric, may start with -)" },
+]
+
+const CHANNEL_ID_PATTERNS: Record<RemoteChannel, RegExp> = {
+  slack: /^[A-Z0-9]{9,12}$/,
+  discord: /^\d{17,20}$/,
+  telegram: /^-?\d{5,20}$/,
+}
+
+interface RemoteQuestionsApiResponse {
+  config: {
+    channel: RemoteChannel
+    channelId: string
+    timeoutMinutes: number
+    pollIntervalSeconds: number
+  } | null
+  envVarSet: boolean
+  tokenSet: boolean
+  envVarName: string | null
+  status: string
+  error?: string
+}
+
+export function RemoteQuestionsPanel() {
+  const { data, busy, refresh } = useSettingsData()
+  const existingConfig = data?.preferences?.remoteQuestions ?? null
+
+  const [envVarSet, setEnvVarSet] = useState(false)
+  const [envVarName, setEnvVarName] = useState<string | null>(null)
+  const [apiLoading, setApiLoading] = useState(true)
+  const [tokenSet, setTokenSet] = useState(false)
+
+  const [channel, setChannel] = useState<RemoteChannel>("slack")
+  const [channelId, setChannelId] = useState("")
+  const [timeoutMinutes, setTimeoutMinutes] = useState(5)
+  const [pollIntervalSeconds, setPollIntervalSeconds] = useState(5)
+  const [botToken, setBotToken] = useState("")
+  const [showToken, setShowToken] = useState(false)
+  const [savingToken, setSavingToken] = useState(false)
+  const [tokenSuccess, setTokenSuccess] = useState<string | null>(null)
+
+  const [saving, setSaving] = useState(false)
+  const [deleting, setDeleting] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [success, setSuccess] = useState<string | null>(null)
+  const [isConfigured, setIsConfigured] = useState(false)
+  const [showAdvanced, setShowAdvanced] = useState(false)
+
+  const fetchApiStatus = useCallback(async () => {
+    try {
+      setApiLoading(true)
+      const res = await authFetch("/api/remote-questions", { cache: "no-store" })
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({ error: "Unknown error" }))
+        setError(body.error ?? `API error ${res.status}`)
+        return
+      }
+      const json: RemoteQuestionsApiResponse = await res.json()
+      setEnvVarSet(json.envVarSet)
+      setEnvVarName(json.envVarName)
+      setTokenSet(json.tokenSet)
+      setIsConfigured(json.status === "configured" && json.config !== null)
+      if (json.config) {
+        setChannel(json.config.channel)
+        setChannelId(json.config.channelId)
+        setTimeoutMinutes(json.config.timeoutMinutes)
+        setPollIntervalSeconds(json.config.pollIntervalSeconds)
+      }
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Failed to fetch remote questions status")
+    } finally {
+      setApiLoading(false)
+    }
+  }, [])
+
+  useEffect(() => { void fetchApiStatus() }, [fetchApiStatus])
+
+  useEffect(() => {
+    if (existingConfig?.channel) {
+      setChannel(existingConfig.channel)
+      setChannelId(existingConfig.channelId ?? "")
+      setTimeoutMinutes(existingConfig.timeoutMinutes ?? 5)
+      setPollIntervalSeconds(existingConfig.pollIntervalSeconds ?? 5)
+    }
+  }, [existingConfig])
+
+  const channelIdValid = channelId.trim().length > 0 && CHANNEL_ID_PATTERNS[channel].test(channelId.trim())
+  const canSave = channelIdValid && !saving && !deleting
+
+  useEffect(() => {
+    if (!success) return
+    const timer = setTimeout(() => setSuccess(null), 3000)
+    return () => clearTimeout(timer)
+  }, [success])
+
+  const handleSave = async () => {
+    setSaving(true)
+    setError(null)
+    setSuccess(null)
+    try {
+      const res = await authFetch("/api/remote-questions", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ channel, channelId: channelId.trim(), timeoutMinutes, pollIntervalSeconds }),
+      })
+      const json = await res.json()
+      if (!res.ok) { setError(json.error ?? `Save failed (${res.status})`); return }
+      setSuccess("Configuration saved")
+      setIsConfigured(true)
+      refresh()
+      void fetchApiStatus()
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Failed to save configuration")
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const handleDisconnect = async () => {
+    setDeleting(true)
+    setError(null)
+    setSuccess(null)
+    try {
+      const res = await authFetch("/api/remote-questions", { method: "DELETE" })
+      const json = await res.json()
+      if (!res.ok) { setError(json.error ?? `Disconnect failed (${res.status})`); return }
+      setSuccess("Channel disconnected")
+      setIsConfigured(false)
+      setChannelId("")
+      setTimeoutMinutes(5)
+      setPollIntervalSeconds(5)
+      setChannel("slack")
+      setTokenSet(false)
+      refresh()
+      void fetchApiStatus()
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Failed to disconnect channel")
+    } finally {
+      setDeleting(false)
+    }
+  }
+
+  const handleSaveToken = async () => {
+    if (!botToken.trim()) return
+    setSavingToken(true)
+    setError(null)
+    setTokenSuccess(null)
+    try {
+      const res = await authFetch("/api/remote-questions", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ channel, token: botToken.trim() }),
+      })
+      const json = await res.json()
+      if (!res.ok) { setError(json.error ?? `Token save failed (${res.status})`); return }
+      setTokenSuccess(`Token saved (${json.masked})`)
+      setTokenSet(true)
+      setBotToken("")
+      setShowToken(false)
+      void fetchApiStatus()
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Failed to save token")
+    } finally {
+      setSavingToken(false)
+    }
+  }
+
+  useEffect(() => {
+    if (!tokenSuccess) return
+    const timer = setTimeout(() => setTokenSuccess(null), 3000)
+    return () => clearTimeout(timer)
+  }, [tokenSuccess])
+
+  const derivedEnvVarName = envVarName ?? `${channel.toUpperCase()}_BOT_TOKEN`
+  const selectedChannelOption = CHANNEL_OPTIONS.find((o) => o.value === channel)!
+
+  if ((busy || apiLoading) && !data && !isConfigured) {
+    return (
+      <div className="space-y-5" data-testid="settings-remote-questions">
+        <SettingsHeader title="Integrations" icon={<Radio className="h-3.5 w-3.5" />} subtitle="Remote notifications" onRefresh={() => { refresh(); void fetchApiStatus() }} refreshing />
+        <SettingsLoading label="Loading integration status…" />
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-5" data-testid="settings-remote-questions">
+      <SettingsHeader
+        title="Integrations"
+        icon={<Radio className="h-3.5 w-3.5" />}
+        subtitle="Remote notifications"
+        onRefresh={() => { refresh(); void fetchApiStatus() }}
+        refreshing={busy || apiLoading}
+      />
+
+      {/* Intro */}
+      <p className="text-xs leading-relaxed text-muted-foreground">
+        Connect a chat channel so the agent pings you when it needs input
+        instead of waiting silently.
+      </p>
+
+      {/* Feedback banners */}
+      {error && <SettingsError message={error} />}
+      {success && (
+        <div className="flex items-center gap-2.5 rounded-xl border border-success/15 bg-success/[0.04] px-4 py-3 text-sm text-muted-foreground">
+          <CheckCircle2 className="h-4 w-4 shrink-0 text-success" />
+          {success}
+        </div>
+      )}
+
+      {/* ── Connected state banner ───────────────────────────────── */}
+      {isConfigured && (
+        <div className="rounded-xl border border-success/15 bg-success/[0.04] px-4 py-4">
+          <div className="flex items-start justify-between gap-3">
+            <div className="flex items-center gap-3">
+              <div className="flex h-9 w-9 items-center justify-center rounded-lg border border-success/20 bg-success/10">
+                <CheckCircle2 className="h-4.5 w-4.5 text-success" />
+              </div>
+              <div>
+                <div className="text-sm font-medium text-foreground">
+                  Connected to {selectedChannelOption.label}
+                </div>
+                <div className="mt-0.5 font-mono text-[11px] text-muted-foreground">
+                  {channelId}
+                </div>
+              </div>
+            </div>
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              onClick={() => void handleDisconnect()}
+              disabled={deleting}
+              className="h-7 text-xs text-destructive/70 hover:text-destructive"
+            >
+              {deleting ? <LoaderCircle className="h-3 w-3 animate-spin" /> : "Disconnect"}
+            </Button>
+          </div>
+          <div className="mt-3 flex gap-4 border-t border-success/10 pt-3 text-[11px] text-muted-foreground">
+            <span>Timeout: {timeoutMinutes}m</span>
+            <span>Poll: {pollIntervalSeconds}s</span>
+          </div>
+        </div>
+      )}
+
+      {/* ── Channel picker (card-based) ──────────────────────────── */}
+      <div className="space-y-2">
+        <div className="text-xs font-medium text-muted-foreground">
+          {isConfigured ? "Switch channel" : "Choose a channel"}
+        </div>
+        <div className="grid grid-cols-3 gap-2">
+          {CHANNEL_OPTIONS.map((opt) => (
+            <button
+              key={opt.value}
+              type="button"
+              onClick={() => {
+                setChannel(opt.value)
+                setError(null)
+              }}
+              disabled={saving}
+              className={cn(
+                "rounded-xl border px-3 py-3 text-left transition-all duration-200",
+                "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                "active:scale-[0.97]",
+                channel === opt.value
+                  ? "border-foreground/30 bg-foreground/[0.06]"
+                  : "border-border/50 bg-card/50 hover:border-foreground/15 hover:bg-card/50",
+              )}
+            >
+              <div className="text-sm font-medium text-foreground">{opt.label}</div>
+              <div className="mt-0.5 text-[11px] text-muted-foreground">{opt.description}</div>
+            </button>
+          ))}
+        </div>
+      </div>
+
+      {/* ── Channel ID input ─────────────────────────────────────── */}
+      <div className="space-y-2">
+        <div className="text-xs font-medium text-muted-foreground">Channel ID</div>
+        <input
+          type="text"
+          value={channelId}
+          onChange={(e) => { setChannelId(e.target.value); if (error) setError(null) }}
+          placeholder={selectedChannelOption.idPlaceholder}
+          disabled={saving}
+          className={cn(
+            "w-full rounded-xl border bg-card/50 px-4 py-2.5 font-mono text-sm text-foreground",
+            "placeholder:text-muted-foreground",
+            "focus:outline-none focus:ring-2 focus:ring-ring focus:border-transparent",
+            "transition-colors",
+            channelId.trim().length > 0 && !CHANNEL_ID_PATTERNS[channel].test(channelId.trim())
+              ? "border-destructive/40"
+              : "border-border/50",
+          )}
+          onKeyDown={(e) => { if (e.key === "Enter" && canSave) void handleSave() }}
+        />
+        {channelId.trim().length > 0 && !CHANNEL_ID_PATTERNS[channel].test(channelId.trim()) && (
+          <p className="text-[11px] text-destructive/70">
+            Doesn't match the expected format for {selectedChannelOption.label}
+          </p>
+        )}
+      </div>
+
+      {/* ── Advanced (collapsed by default) ──────────────────────── */}
+      <button
+        type="button"
+        onClick={() => setShowAdvanced((v) => !v)}
+        className="flex items-center gap-1.5 text-[11px] text-muted-foreground hover:text-muted-foreground transition-colors"
+      >
+        <svg
+          className={cn("h-3 w-3 transition-transform", showAdvanced && "rotate-90")}
+          viewBox="0 0 16 16"
+          fill="currentColor"
+        >
+          <path d="M6 4l4 4-4 4" />
+        </svg>
+        Advanced settings
+      </button>
+
+      {showAdvanced && (
+        <div className="grid grid-cols-2 gap-3 pl-4">
+          <div className="space-y-1.5">
+            <label className="text-[11px] text-muted-foreground" htmlFor="rq-timeout">
+              Timeout (min)
+            </label>
+            <input
+              id="rq-timeout"
+              type="number"
+              min={1}
+              max={30}
+              value={timeoutMinutes}
+              onChange={(e) => setTimeoutMinutes(Math.max(1, Math.min(30, Number(e.target.value) || 1)))}
+              className="w-full rounded-lg border border-border/50 bg-card/50 px-3 py-2 text-xs text-foreground tabular-nums focus:outline-none focus:ring-2 focus:ring-ring"
+            />
+          </div>
+          <div className="space-y-1.5">
+            <label className="text-[11px] text-muted-foreground" htmlFor="rq-poll">
+              Poll interval (sec)
+            </label>
+            <input
+              id="rq-poll"
+              type="number"
+              min={2}
+              max={30}
+              value={pollIntervalSeconds}
+              onChange={(e) => setPollIntervalSeconds(Math.max(2, Math.min(30, Number(e.target.value) || 2)))}
+              className="w-full rounded-lg border border-border/50 bg-card/50 px-3 py-2 text-xs text-foreground tabular-nums focus:outline-none focus:ring-2 focus:ring-ring"
+            />
+          </div>
+        </div>
+      )}
+
+      {/* ── Save button ──────────────────────────────────────────── */}
+      {channelId.trim().length > 0 && (
+        <Button
+          type="button"
+          onClick={() => void handleSave()}
+          disabled={!canSave}
+          className="gap-2 transition-transform active:scale-[0.96]"
+        >
+          {saving ? (
+            <LoaderCircle className="h-4 w-4 animate-spin" />
+          ) : (
+            <CheckCircle2 className="h-4 w-4" />
+          )}
+          {isConfigured ? "Update connection" : "Save & connect"}
+        </Button>
+      )}
+
+      {/* ── Bot token ─────────────────────────────────────────── */}
+      <div className="space-y-3">
+        <div className="text-xs font-medium text-muted-foreground">Bot token</div>
+
+        {tokenSuccess && (
+          <div className="flex items-center gap-2.5 rounded-xl border border-success/15 bg-success/[0.04] px-4 py-2.5 text-xs text-muted-foreground">
+            <CheckCircle2 className="h-3.5 w-3.5 shrink-0 text-success" />
+            {tokenSuccess}
+          </div>
+        )}
+
+        {tokenSet && !tokenSuccess && (
+          <div className="flex items-center gap-2.5 rounded-xl border border-success/15 bg-success/[0.04] px-4 py-2.5 text-xs text-muted-foreground">
+            <CheckCircle2 className="h-3.5 w-3.5 shrink-0 text-success" />
+            <span className="font-mono text-[11px]">{derivedEnvVarName}</span> is configured
+          </div>
+        )}
+
+        {!tokenSet && (
+          <div className="flex items-center gap-2.5 rounded-xl border border-warning/15 bg-warning/[0.04] px-4 py-2.5 text-xs text-muted-foreground">
+            <AlertTriangle className="h-3.5 w-3.5 shrink-0 text-warning" />
+            <span><span className="font-mono text-[11px]">{derivedEnvVarName}</span> not configured</span>
+          </div>
+        )}
+
+        <div className="flex gap-2">
+          <div className="relative flex-1">
+            <input
+              type={showToken ? "text" : "password"}
+              value={botToken}
+              onChange={(e) => setBotToken(e.target.value)}
+              placeholder={`Paste your ${selectedChannelOption.label} bot token`}
+              disabled={savingToken}
+              className={cn(
+                "w-full rounded-xl border border-border/50 bg-card/50 pl-4 pr-10 py-2.5 font-mono text-sm text-foreground",
+                "placeholder:text-muted-foreground",
+                "focus:outline-none focus:ring-2 focus:ring-ring focus:border-transparent",
+                "transition-colors",
+              )}
+              onKeyDown={(e) => { if (e.key === "Enter" && botToken.trim()) void handleSaveToken() }}
+            />
+            <button
+              type="button"
+              onClick={() => setShowToken((v) => !v)}
+              className="absolute right-3 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-muted-foreground transition-colors"
+            >
+              {showToken ? <EyeOff className="h-3.5 w-3.5" /> : <Eye className="h-3.5 w-3.5" />}
+            </button>
+          </div>
+          <Button
+            type="button"
+            size="sm"
+            onClick={() => void handleSaveToken()}
+            disabled={!botToken.trim() || savingToken}
+            className="h-[42px] gap-1.5 px-4"
+          >
+            {savingToken ? <LoaderCircle className="h-3.5 w-3.5 animate-spin" /> : <KeyRound className="h-3.5 w-3.5" />}
+            Save
+          </Button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// GENERAL PANEL (font sizes)
+// ═══════════════════════════════════════════════════════════════════════
+
+const TERMINAL_SIZE_PRESETS = [11, 12, 13, 14, 15, 16] as const
+const EDITOR_SIZE_PRESETS = [11, 12, 13, 14, 15, 16] as const
+
+function FontSizeControl({
+  label,
+  description,
+  presets,
+  defaultSize,
+  currentSize,
+  onChange,
+  previewFont,
+}: {
+  label: string
+  description: string
+  presets: readonly number[]
+  defaultSize: number
+  currentSize: number
+  onChange: (size: number) => void
+  previewFont: "mono" | "sans"
+}) {
+  return (
+    <div className="rounded-lg border border-border/50 bg-card/50 px-3 py-3 space-y-3">
+      <div>
+        <div className="text-xs font-medium text-foreground">{label}</div>
+        <div className="text-[11px] text-muted-foreground mt-0.5">{description}</div>
+      </div>
+
+      <div className="flex flex-wrap gap-1.5">
+        {presets.map((size) => (
+          <button
+            key={size}
+            type="button"
+            onClick={() => onChange(size)}
+            className={cn(
+              "rounded-md border px-3 py-1.5 text-xs font-medium tabular-nums transition-colors",
+              currentSize === size
+                ? "border-foreground/30 bg-foreground/10 text-foreground shadow-sm"
+                : "border-border/50 bg-card/50 text-muted-foreground hover:border-foreground/20 hover:text-foreground",
+            )}
+          >
+            {size}px
+            {size === defaultSize && (
+              <span className="ml-1 text-[10px] text-muted-foreground">(default)</span>
+            )}
+          </button>
+        ))}
+      </div>
+
+      <div
+        className={cn(
+          "mt-2 rounded-md border border-border/50 bg-terminal px-3 py-2 text-foreground/80",
+          previewFont === "mono" ? "font-mono" : "font-sans",
+        )}
+        style={{ fontSize: `${currentSize}px`, lineHeight: 1.35 }}
+      >
+        The quick brown fox jumps over the lazy dog
+      </div>
+    </div>
+  )
+}
+
+export function GeneralPanel() {
+  const [terminalFontSize, setTerminalFontSize] = useTerminalFontSize()
+  const [editorFontSize, setEditorFontSize] = useEditorFontSize()
+
+  return (
+    <div className="space-y-5" data-testid="settings-general">
+      <SettingsHeader
+        title="General"
+        icon={<SlidersHorizontal className="h-3.5 w-3.5" />}
+        subtitle="Appearance & behavior"
+        onRefresh={() => {}}
+        refreshing={false}
+      />
+
+      <FontSizeControl
+        label="Terminal font size"
+        description="Applies to all terminals and the chat mode interface"
+        presets={TERMINAL_SIZE_PRESETS}
+        defaultSize={13}
+        currentSize={terminalFontSize}
+        onChange={setTerminalFontSize}
+        previewFont="mono"
+      />
+
+      <FontSizeControl
+        label="Code font size"
+        description="Applies to the file viewer and code editor"
+        presets={EDITOR_SIZE_PRESETS}
+        defaultSize={14}
+        currentSize={editorFontSize}
+        onChange={setEditorFontSize}
+        previewFont="mono"
+      />
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// EXPERIMENTAL PANEL
+// ═══════════════════════════════════════════════════════════════════════
+
+interface ExperimentalFlag {
+  key: string
+  label: string
+  description: string
+  warning?: string
+}
+
+const EXPERIMENTAL_FLAGS: ExperimentalFlag[] = [
+  {
+    key: "rtk",
+    label: "RTK Shell Compression",
+    description:
+      "Wraps shell commands through the RTK binary to reduce token usage during command execution. RTK is downloaded automatically on first use.",
+    warning: "Experimental — may change or be removed without notice.",
+  },
+]
+
+export function ExperimentalPanel() {
+  const { state, data, busy, refresh } = useSettingsData()
+  const prefs = data?.preferences ?? null
+
+  const [flags, setFlags] = useState<Record<string, boolean>>({})
+  const [saving, setSaving] = useState<Record<string, boolean>>({})
+  const [saveError, setSaveError] = useState<string | null>(null)
+
+  // Trigger a settings load if data hasn't been fetched yet (e.g. navigating
+  // directly to the Experimental tab without going through gsd-prefs first).
+  useEffect(() => {
+    if (!data && !busy && state.phase === "idle") {
+      refresh()
+    }
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Sync local state from loaded prefs
+  useEffect(() => {
+    if (!prefs) return
+    setFlags({ rtk: prefs.experimental?.rtk === true })
+  }, [prefs])
+
+  async function toggle(flagKey: string, next: boolean) {
+    setSaving((s) => ({ ...s, [flagKey]: true }))
+    setSaveError(null)
+    try {
+      const res = await authFetch("/api/experimental", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ flag: flagKey, enabled: next }),
+      })
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({})) as { error?: string }
+        throw new Error(body.error ?? `HTTP ${res.status}`)
+      }
+      setFlags((f) => ({ ...f, [flagKey]: next }))
+      // Refresh settings data so PrefsPanel reflects the change
+      refresh()
+    } catch (err) {
+      setSaveError(err instanceof Error ? err.message : String(err))
+    } finally {
+      setSaving((s) => ({ ...s, [flagKey]: false }))
+    }
+  }
+
+  return (
+    <div className="space-y-4" data-testid="settings-experimental">
+      <SettingsHeader
+        title="Experimental"
+        icon={<FlaskConical className="h-3.5 w-3.5" />}
+        subtitle="Opt-in features — may change without notice"
+        onRefresh={refresh}
+        refreshing={busy}
+      />
+
+      {state.error && <SettingsError message={state.error} />}
+      {saveError && <SettingsError message={saveError} />}
+      {busy && !data && <SettingsLoading label="Loading preferences…" />}
+
+      <div className="space-y-3">
+        {EXPERIMENTAL_FLAGS.map((flag) => {
+          const enabled = flags[flag.key] ?? false
+          const isSaving = saving[flag.key] ?? false
+
+          return (
+            <div
+              key={flag.key}
+              className="rounded-lg border border-border/50 bg-card/50 px-3 py-3 space-y-2"
+            >
+              <div className="flex items-start justify-between gap-3">
+                <div className="min-w-0 flex-1 space-y-1">
+                  <div className="flex items-center gap-2">
+                    <span className="text-xs font-medium text-foreground">{flag.label}</span>
+                    <span
+                      className={cn(
+                        "rounded-full px-1.5 py-0.5 text-[10px] font-medium",
+                        enabled
+                          ? "bg-success/10 text-success"
+                          : "bg-muted text-muted-foreground",
+                      )}
+                    >
+                      {enabled ? "on" : "off"}
+                    </span>
+                  </div>
+                  <p className="text-[11px] text-muted-foreground leading-relaxed">
+                    {flag.description}
+                  </p>
+                  {flag.warning && (
+                    <div className="flex items-center gap-1 text-[10px] text-warning">
+                      <AlertTriangle className="h-3 w-3 shrink-0" />
+                      <span>{flag.warning}</span>
+                    </div>
+                  )}
+                </div>
+                <button
+                  onClick={() => toggle(flag.key, !enabled)}
+                  disabled={isSaving || busy || !data}
+                  className={cn(
+                    "shrink-0 relative inline-flex h-5 w-9 items-center rounded-full transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50 disabled:cursor-not-allowed",
+                    enabled ? "bg-success" : "bg-muted-foreground/30",
+                  )}
+                  role="switch"
+                  aria-checked={enabled}
+                  aria-label={`Toggle ${flag.label}`}
+                >
+                  <span
+                    className={cn(
+                      "inline-block h-3.5 w-3.5 rounded-full bg-white shadow-sm transition-transform",
+                      enabled ? "translate-x-4" : "translate-x-0.5",
+                    )}
+                  />
+                  {isSaving && (
+                    <span className="absolute inset-0 flex items-center justify-center">
+                      <LoaderCircle className="h-3 w-3 animate-spin text-white" />
+                    </span>
+                  )}
+                </button>
+              </div>
+            </div>
+          )
+        })}
+      </div>
+
+      {data && (
+        <p className="text-[11px] text-muted-foreground">
+          Changes are written to{" "}
+          <span className="font-mono">{prefs?.path ?? "~/.gsd/PREFERENCES.md"}</span>
+          {" "}and take effect on the next session.
+        </p>
+      )}
+    </div>
+  )
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// LEGACY EXPORTS
+// ═══════════════════════════════════════════════════════════════════════
+
+// Legacy exports for backward compatibility with gsd-prefs mega-scroll
+export const TerminalSizePanel = GeneralPanel
+export const EditorSizePanel = () => null
diff --git a/web/components/sf/shell-terminal.tsx b/web/components/sf/shell-terminal.tsx
new file mode 100644
index 000000000..c60b92ceb
--- /dev/null
+++ b/web/components/sf/shell-terminal.tsx
@@ -0,0 +1,743 @@
+"use client"
+
+import { useEffect, useRef, useCallback, useState } from "react"
+import { useTheme } from "next-themes"
+import { Plus, X, TerminalSquare, Loader2, ImagePlus } from "lucide-react"
+import { cn } from "@/lib/utils"
+import { validateImageFile } from "@/lib/image-utils"
+import { filterInitialGsdHeader } from "@/lib/initial-gsd-header-filter"
+import { buildProjectAbsoluteUrl, buildProjectPath } from "@/lib/project-url"
+import { authFetch, appendAuthParam } from "@/lib/auth"
+import { getXtermOptions, getXtermTheme } from "@/lib/xterm-theme"
+import "@xterm/xterm/css/xterm.css"
+
+type XTerminal = import("@xterm/xterm").Terminal
+type XFitAddon = import("@xterm/addon-fit").FitAddon
+
+const MIN_TERMINAL_ATTACH_WIDTH = 180
+const MIN_TERMINAL_ATTACH_HEIGHT = 120
+const MIN_TERMINAL_ATTACH_COLS = 20
+const MIN_TERMINAL_ATTACH_ROWS = 8
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+interface TerminalTab {
+  id: string
+  label: string
+  connected: boolean
+}
+
+interface ShellTerminalProps {
+  className?: string
+  command?: string
+  commandArgs?: string[]
+  sessionPrefix?: string
+  hideSidebar?: boolean
+  fontSize?: number
+  hideInitialGsdHeader?: boolean
+  projectCwd?: string
+}
+
+function getRenderableTerminalSize(container: HTMLDivElement | null, terminal: XTerminal | null): { cols: number; rows: number } | null {
+  if (!container || !terminal) return null
+
+  const rect = container.getBoundingClientRect()
+  if (rect.width < MIN_TERMINAL_ATTACH_WIDTH || rect.height < MIN_TERMINAL_ATTACH_HEIGHT) {
+    return null
+  }
+
+  if (terminal.cols < MIN_TERMINAL_ATTACH_COLS || terminal.rows < MIN_TERMINAL_ATTACH_ROWS) {
+    return null
+  }
+
+  return { cols: terminal.cols, rows: terminal.rows }
+}
+
+async function settleTerminalLayout(
+  container: HTMLDivElement | null,
+  terminal: XTerminal | null,
+  fitAddon: XFitAddon | null,
+  isDisposed: () => boolean,
+): Promise<{ cols: number; rows: number } | null> {
+  if (typeof document !== "undefined" && "fonts" in document) {
+    try {
+      await Promise.race([
+        document.fonts.ready,
+        new Promise<void>((resolve) => setTimeout(resolve, 1000)),
+      ])
+    } catch {
+      // Ignore font loading failures and fall through to repeated fit attempts.
+    }
+  }
+
+  for (let attempt = 0; attempt < 12; attempt++) {
+    if (isDisposed()) return null
+
+    await new Promise<void>((resolve) => {
+      requestAnimationFrame(() => resolve())
+    })
+
+    if (isDisposed()) return null
+
+    try {
+      fitAddon?.fit()
+    } catch {
+      /* hidden or detached */
+    }
+
+    const size = getRenderableTerminalSize(container, terminal)
+    if (size) {
+      return size
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 50))
+  }
+
+  return getRenderableTerminalSize(container, terminal)
+}
+
+function deriveCommandLabel(command?: string): string {
+  if (!command?.trim()) return "zsh"
+  const token = command.trim().split(/\s+/)[0] || command
+  const normalized = token.replace(/\\/g, "/")
+  const parts = normalized.split("/")
+  return parts[parts.length - 1] || token
+}
+
+// ─── Single terminal instance (internal) ──────────────────────────────────────
+
+interface TerminalInstanceProps {
+  sessionId: string
+  visible: boolean
+  command?: string
+  commandArgs?: string[]
+  isDark: boolean
+  fontSize?: number
+  hideInitialGsdHeader?: boolean
+  projectCwd?: string
+  onConnectionChange: (connected: boolean) => void
+}
+
+function TerminalInstance({
+  sessionId,
+  visible,
+  command,
+  commandArgs,
+  isDark,
+  fontSize,
+  hideInitialGsdHeader = false,
+  projectCwd,
+  onConnectionChange,
+}: TerminalInstanceProps) {
+  const containerRef = useRef<HTMLDivElement>(null)
+  const termRef = useRef<XTerminal | null>(null)
+  const fitAddonRef = useRef<XFitAddon | null>(null)
+  const eventSourceRef = useRef<EventSource | null>(null)
+  const inputQueueRef = useRef<string[]>([])
+  const flushingRef = useRef(false)
+  const resizeTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const onConnectionChangeRef = useRef(onConnectionChange)
+  const initialHeaderSettledRef = useRef(!hideInitialGsdHeader)
+  const initialHeaderBufferRef = useRef("")
+  const commandArgsKey = (commandArgs ?? []).join("\u0000")
+  const [hasOutput, setHasOutput] = useState(false)
+
+  const sendResize = useCallback(
+    (cols: number, rows: number) => {
+      if (resizeTimeoutRef.current) clearTimeout(resizeTimeoutRef.current)
+      resizeTimeoutRef.current = setTimeout(() => {
+        void authFetch(buildProjectPath("/api/terminal/resize", projectCwd), {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ id: sessionId, cols, rows }),
+        })
+      }, 100)
+    },
+    [projectCwd, sessionId],
+  )
+
+  const flushInputQueue = useCallback(async () => {
+    if (flushingRef.current) return
+    flushingRef.current = true
+    while (inputQueueRef.current.length > 0) {
+      const data = inputQueueRef.current.shift()!
+      try {
+        await authFetch(buildProjectPath("/api/terminal/input", projectCwd), {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ id: sessionId, data }),
+        })
+      } catch {
+        inputQueueRef.current.unshift(data)
+        break
+      }
+    }
+    flushingRef.current = false
+  }, [projectCwd, sessionId])
+
+  const sendInput = useCallback(
+    (data: string) => {
+      inputQueueRef.current.push(data)
+      void flushInputQueue()
+    },
+    [flushInputQueue],
+  )
+
+  useEffect(() => {
+    onConnectionChangeRef.current = onConnectionChange
+  }, [onConnectionChange])
+
+  useEffect(() => {
+    initialHeaderSettledRef.current = !hideInitialGsdHeader
+    initialHeaderBufferRef.current = ""
+  }, [hideInitialGsdHeader, sessionId])
+
+  // Update xterm theme when isDark changes
+  useEffect(() => {
+    if (termRef.current) {
+      termRef.current.options.theme = getXtermTheme(isDark)
+    }
+  }, [isDark])
+
+  // Update xterm font size when fontSize changes
+  useEffect(() => {
+    if (termRef.current) {
+      termRef.current.options.fontSize = fontSize ?? 13
+      try {
+        fitAddonRef.current?.fit()
+        if (termRef.current) {
+          sendResize(termRef.current.cols, termRef.current.rows)
+        }
+      } catch {
+        /* not visible yet */
+      }
+    }
+  }, [fontSize, sendResize])
+
+  // Re-fit when visibility changes
+  useEffect(() => {
+    if (visible && fitAddonRef.current && termRef.current) {
+      // Small delay to let the DOM settle
+      const t = setTimeout(() => {
+        try {
+          fitAddonRef.current?.fit()
+          if (termRef.current) {
+            sendResize(termRef.current.cols, termRef.current.rows)
+          }
+        } catch {
+          /* not visible yet */
+        }
+      }, 50)
+      return () => clearTimeout(t)
+    }
+  }, [visible, sendResize])
+
+  useEffect(() => {
+    if (!containerRef.current) return
+
+    let disposed = false
+    let terminal: XTerminal | null = null
+    let fitAddon: XFitAddon | null = null
+    let resizeObserver: ResizeObserver | null = null
+
+    const init = async () => {
+      const [{ Terminal }, { FitAddon }] = await Promise.all([
+        import("@xterm/xterm"),
+        import("@xterm/addon-fit"),
+      ])
+
+      if (disposed) return
+
+      terminal = new Terminal(getXtermOptions(isDark, fontSize))
+      fitAddon = new FitAddon()
+      terminal.loadAddon(fitAddon)
+      terminal.open(containerRef.current!)
+
+      termRef.current = terminal
+      fitAddonRef.current = fitAddon
+
+      await settleTerminalLayout(containerRef.current, terminal, fitAddon, () => disposed)
+      if (disposed) return
+
+      terminal.onData((data) => sendInput(data))
+      terminal.onBinary((data) => sendInput(data))
+
+      // SSE stream
+      const streamUrl = buildProjectAbsoluteUrl(
+        "/api/terminal/stream",
+        window.location.origin,
+        projectCwd,
+      )
+      streamUrl.searchParams.set("id", sessionId)
+      if (command) streamUrl.searchParams.set("command", command)
+      for (const arg of commandArgs ?? []) {
+        streamUrl.searchParams.append("arg", arg)
+      }
+      const es = new EventSource(appendAuthParam(streamUrl.toString()))
+      eventSourceRef.current = es
+
+      es.onmessage = (event) => {
+        try {
+          const msg = JSON.parse(event.data) as {
+            type: string
+            data?: string
+          }
+          if (msg.type === "connected") {
+            onConnectionChangeRef.current(true)
+            void settleTerminalLayout(containerRef.current, terminal, fitAddon, () => disposed).then((size) => {
+              if (!size) return
+              sendResize(size.cols, size.rows)
+            })
+          } else if (msg.type === "output" && msg.data) {
+            let output = msg.data
+
+            if (hideInitialGsdHeader && !initialHeaderSettledRef.current) {
+              initialHeaderBufferRef.current += output
+              const filtered = filterInitialGsdHeader(initialHeaderBufferRef.current)
+
+              if (filtered.status === "needs-more") {
+                return
+              }
+
+              initialHeaderSettledRef.current = true
+              initialHeaderBufferRef.current = ""
+              output = filtered.text
+            }
+
+            if (output) {
+              terminal?.write(output)
+              setHasOutput(true)
+            }
+          }
+        } catch {
+          /* malformed */
+        }
+      }
+
+      es.onerror = () => onConnectionChangeRef.current(false)
+
+      // Resize observer
+      resizeObserver = new ResizeObserver(() => {
+        if (disposed) return
+        try {
+          fitAddon?.fit()
+          if (terminal) sendResize(terminal.cols, terminal.rows)
+        } catch {
+          /* not visible */
+        }
+      })
+      resizeObserver.observe(containerRef.current!)
+    }
+
+    void init()
+
+    return () => {
+      disposed = true
+      if (resizeTimeoutRef.current) clearTimeout(resizeTimeoutRef.current)
+      eventSourceRef.current?.close()
+      eventSourceRef.current = null
+      resizeObserver?.disconnect()
+      terminal?.dispose()
+      termRef.current = null
+      fitAddonRef.current = null
+    }
+  }, [sessionId, command, commandArgs, commandArgsKey, fontSize, hideInitialGsdHeader, isDark, projectCwd, sendInput, sendResize])
+
+  // Focus on click
+  const wrapperRef = useRef<HTMLDivElement>(null)
+  const handleClick = useCallback(() => {
+    termRef.current?.focus()
+  }, [])
+
+  // Shift+Enter → newline (native DOM, capture phase)
+  // xterm.js sends \r for both Enter and Shift+Enter. The pi TUI editor
+  // recognizes \n (LF) as "insert newline".
+  useEffect(() => {
+    const el = wrapperRef.current
+    if (!el) return
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Enter" && e.shiftKey && !e.ctrlKey && !e.altKey && !e.metaKey) {
+        e.preventDefault()
+        e.stopPropagation()
+        sendInput("\n")
+      }
+    }
+
+    el.addEventListener("keydown", onKeyDown, true)
+    return () => el.removeEventListener("keydown", onKeyDown, true)
+  }, [sendInput])
+
+  // Auto-focus when this tab becomes visible
+  useEffect(() => {
+    if (visible) {
+      // Small delay to let layout settle
+      const t = setTimeout(() => termRef.current?.focus(), 80)
+      return () => clearTimeout(t)
+    }
+  }, [visible])
+
+  return (
+    <div
+      ref={wrapperRef}
+      className={cn("relative h-full w-full bg-terminal", !visible && "hidden")}
+      onClick={handleClick}
+    >
+      {/* Loading overlay — visible until first output arrives */}
+      {!hasOutput && (
+        <div className="absolute inset-0 z-10 flex flex-col items-center justify-center gap-3 bg-terminal">
+          <Loader2 className="h-5 w-5 animate-spin text-muted-foreground" />
+          <span className="text-xs text-muted-foreground">
+            {command ? "Starting GSD…" : "Connecting…"}
+          </span>
+        </div>
+      )}
+      <div
+        ref={containerRef}
+        className="h-full w-full"
+        style={{ padding: "8px 4px 4px 8px" }}
+      />
+    </div>
+  )
+}
+
+// ─── Image upload helpers ─────────────────────────────────────────────────────
+
+const ALLOWED_IMAGE_TYPES = new Set([
+  "image/jpeg",
+  "image/png",
+  "image/gif",
+  "image/webp",
+])
+
+/**
+ * Upload an image file to the server's temp directory and inject the `@filepath`
+ * text into the PTY session's stdin.
+ *
+ * Observability:
+ * - console.warn on client-side validation failure
+ * - console.error on upload or inject failure
+ */
+async function uploadAndInjectImage(file: File, sessionId: string, projectCwd?: string): Promise<void> {
+  // Client-side validation
+  const validation = validateImageFile(file)
+  if (!validation.valid) {
+    console.warn("[terminal-upload] validation failed:", validation.error)
+    return
+  }
+
+  // Upload to temp dir
+  const formData = new FormData()
+  formData.append("file", file)
+
+  let uploadPath: string
+  try {
+    const res = await authFetch(buildProjectPath("/api/terminal/upload", projectCwd), {
+      method: "POST",
+      body: formData,
+    })
+    const data = await res.json() as { ok?: boolean; path?: string; error?: string }
+    if (!res.ok || !data.path) {
+      console.error("[terminal-upload] upload failed:", data.error ?? `HTTP ${res.status}`)
+      return
+    }
+    uploadPath = data.path
+  } catch (err) {
+    console.error("[terminal-upload] upload request failed:", err)
+    return
+  }
+
+  // Inject @filepath into PTY stdin
+  try {
+    const res = await authFetch(buildProjectPath("/api/terminal/input", projectCwd), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ id: sessionId, data: `@${uploadPath} ` }),
+    })
+    if (!res.ok) {
+      const data = await res.json().catch(() => ({})) as { error?: string }
+      console.error("[terminal-upload] inject failed:", data.error ?? `HTTP ${res.status}`)
+    }
+  } catch (err) {
+    console.error("[terminal-upload] inject request failed:", err)
+  }
+}
+
+// ─── Multi-instance terminal panel ────────────────────────────────────────────
+
+/**
+ * Derive a session ID that is scoped to the project path.  This ensures
+ * that switching projects creates a separate PTY session per project, and
+ * switching back reconnects to the *same* server-side PTY instead of
+ * spawning a new one (the server's getOrCreateSession returns the existing
+ * live session when the ID matches).
+ */
+function deriveProjectScopedSessionId(
+  projectCwd: string | undefined,
+  sessionPrefix?: string,
+  command?: string,
+): string {
+  const base = sessionPrefix ?? (command ? "gsd-default" : "default")
+  if (!projectCwd) return base
+  return `${base}:${projectCwd}`
+}
+
+export function ShellTerminal({
+  className,
+  command,
+  commandArgs,
+  sessionPrefix,
+  hideSidebar = false,
+  fontSize,
+  hideInitialGsdHeader = false,
+  projectCwd,
+}: ShellTerminalProps) {
+  const { resolvedTheme } = useTheme()
+  const isDark = resolvedTheme !== "light"
+  const defaultId = deriveProjectScopedSessionId(projectCwd, sessionPrefix, command)
+  const commandLabel = deriveCommandLabel(command)
+  const [tabs, setTabs] = useState<TerminalTab[]>([
+    { id: defaultId, label: commandLabel, connected: false },
+  ])
+  const [activeTabId, setActiveTabId] = useState(defaultId)
+  const [isDragOver, setIsDragOver] = useState(false)
+  const terminalAreaRef = useRef<HTMLDivElement>(null)
+
+  // When the project changes, the defaultId changes.  Reset tabs so the
+  // terminal reconnects to the project-scoped PTY session on the server.
+  // The server's getOrCreateSession will return the existing live session
+  // when the session ID matches, preserving terminal state.
+  const prevDefaultIdRef = useRef(defaultId)
+  useEffect(() => {
+    if (prevDefaultIdRef.current !== defaultId) {
+      prevDefaultIdRef.current = defaultId
+      setTabs([{ id: defaultId, label: commandLabel, connected: false }])
+      setActiveTabId(defaultId)
+    }
+  }, [defaultId, commandLabel])
+
+  // ── Drag-and-drop handlers (native DOM, capture phase) ──────────────────
+  // React synthetic events don't reliably fire through xterm's internal DOM.
+  // Native capture-phase listeners intercept before xterm can swallow them —
+  // same pattern used for paste below.
+
+  useEffect(() => {
+    const el = terminalAreaRef.current
+    if (!el) return
+
+    let counter = 0
+
+    const onDragEnter = (e: DragEvent) => {
+      e.preventDefault()
+      e.stopPropagation()
+      counter += 1
+      if (counter === 1) setIsDragOver(true)
+    }
+
+    const onDragOver = (e: DragEvent) => {
+      e.preventDefault()
+      e.stopPropagation()
+    }
+
+    const onDragLeave = (e: DragEvent) => {
+      e.preventDefault()
+      e.stopPropagation()
+      counter -= 1
+      if (counter <= 0) {
+        counter = 0
+        setIsDragOver(false)
+      }
+    }
+
+    const onDrop = (e: DragEvent) => {
+      e.preventDefault()
+      e.stopPropagation()
+      counter = 0
+      setIsDragOver(false)
+
+      if (!activeTabId) return
+      const files = Array.from(e.dataTransfer?.files ?? [])
+      const imageFile = files.find((f) => ALLOWED_IMAGE_TYPES.has(f.type))
+      if (imageFile) {
+        void uploadAndInjectImage(imageFile, activeTabId, projectCwd)
+      }
+    }
+
+    el.addEventListener("dragenter", onDragEnter, true)
+    el.addEventListener("dragover", onDragOver, true)
+    el.addEventListener("dragleave", onDragLeave, true)
+    el.addEventListener("drop", onDrop, true)
+    return () => {
+      el.removeEventListener("dragenter", onDragEnter, true)
+      el.removeEventListener("dragover", onDragOver, true)
+      el.removeEventListener("dragleave", onDragLeave, true)
+      el.removeEventListener("drop", onDrop, true)
+    }
+  }, [activeTabId, projectCwd])
+
+  // ── Paste handler for images ──────────────────────────────────────────────
+
+  useEffect(() => {
+    const el = terminalAreaRef.current
+    if (!el) return
+
+    const handlePaste = (e: ClipboardEvent) => {
+      if (!e.clipboardData) return
+      const files = Array.from(e.clipboardData.files)
+      const imageFile = files.find((f) => ALLOWED_IMAGE_TYPES.has(f.type))
+      if (imageFile) {
+        e.preventDefault()
+        e.stopPropagation()
+        if (activeTabId) {
+          void uploadAndInjectImage(imageFile, activeTabId, projectCwd)
+        }
+      }
+      // If no image files, don't prevent default — let xterm.js handle text paste
+    }
+
+    el.addEventListener("paste", handlePaste, true) // capture phase to fire before xterm
+    return () => el.removeEventListener("paste", handlePaste, true)
+  }, [activeTabId, projectCwd])
+
+  const createTab = useCallback(async () => {
+    try {
+      const res = await authFetch(buildProjectPath("/api/terminal/sessions", projectCwd), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(command ? { command } : {}),
+      })
+      const data = (await res.json()) as { id: string }
+      const newTab: TerminalTab = {
+        id: data.id,
+        label: commandLabel,
+        connected: false,
+      }
+      setTabs((prev) => [...prev, newTab])
+      setActiveTabId(data.id)
+    } catch {
+      /* network error */
+    }
+  }, [command, commandLabel, projectCwd])
+
+  const closeTab = useCallback(
+    (id: string) => {
+      // Don't close the last tab
+      if (tabs.length <= 1) return
+      const deleteUrl = buildProjectAbsoluteUrl("/api/terminal/sessions", window.location.origin, projectCwd)
+      deleteUrl.searchParams.set("id", id)
+      void authFetch(deleteUrl.toString(), {
+        method: "DELETE",
+      })
+      const remaining = tabs.filter((t) => t.id !== id)
+      setTabs(remaining)
+      if (activeTabId === id) {
+        setActiveTabId(remaining[remaining.length - 1]?.id ?? defaultId)
+      }
+    },
+    [tabs, activeTabId, defaultId, projectCwd],
+  )
+
+  const updateConnection = useCallback(
+    (id: string, connected: boolean) => {
+      setTabs((prev) =>
+        prev.map((t) => (t.id === id ? { ...t, connected } : t)),
+      )
+    },
+    [],
+  )
+
+  return (
+    <div className={cn("flex bg-terminal", className)}>
+      {/* Terminal area — receives drag/drop and paste for images */}
+      <div
+        ref={terminalAreaRef}
+        className="relative flex-1 min-w-0"
+      >
+        {tabs.map((tab) => (
+          <TerminalInstance
+            key={tab.id}
+            sessionId={tab.id}
+            visible={tab.id === activeTabId}
+            command={command}
+            commandArgs={tab.id === defaultId ? commandArgs : undefined}
+            isDark={isDark}
+            fontSize={fontSize}
+            hideInitialGsdHeader={hideInitialGsdHeader}
+            projectCwd={projectCwd}
+            onConnectionChange={(c) => updateConnection(tab.id, c)}
+          />
+        ))}
+
+        {/* Drop overlay */}
+        {isDragOver && (
+          <div className="absolute inset-0 z-20 flex flex-col items-center justify-center gap-2 bg-background backdrop-blur-sm border-2 border-dashed border-primary rounded-md pointer-events-none">
+            <ImagePlus className="h-8 w-8 text-primary" />
+            <span className="text-sm font-medium text-primary">Drop image here</span>
+          </div>
+        )}
+      </div>
+
+      {!hideSidebar && (
+        <div className="flex w-[34px] flex-shrink-0 flex-col border-l border-border/50 bg-terminal">
+          {/* New terminal button */}
+          <button
+            onClick={createTab}
+            className="flex h-[30px] w-full items-center justify-center text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
+            title="New terminal"
+          >
+            <Plus className="h-3 w-3" />
+          </button>
+
+          <div className="h-px bg-border/50" />
+
+          {/* Tab list */}
+          <div className="flex-1 overflow-y-auto">
+            {tabs.map((tab, index) => (
+              <button
+                key={tab.id}
+                onClick={() => setActiveTabId(tab.id)}
+                className={cn(
+                  "group relative flex h-[30px] w-full items-center justify-center transition-colors",
+                  tab.id === activeTabId
+                    ? "bg-accent text-accent-foreground"
+                    : "text-muted-foreground hover:bg-accent/50 hover:text-accent-foreground",
+                )}
+                title={`${tab.label} ${index + 1}`}
+              >
+                {/* Active indicator bar */}
+                {tab.id === activeTabId && (
+                  <div className="absolute left-0 top-1.5 bottom-1.5 w-[2px] rounded-full bg-muted-foreground" />
+                )}
+
+                <div className="relative flex items-center">
+                  <TerminalSquare className="h-3 w-3" />
+                  {/* Connection dot */}
+                  <span
+                    className={cn(
+                      "absolute -bottom-0.5 -right-0.5 h-1.5 w-1.5 rounded-full border border-terminal",
+                      tab.connected ? "bg-success" : "bg-muted-foreground/40",
+                    )}
+                  />
+                </div>
+
+                {/* Close button — shows on hover as small badge in corner */}
+                {tabs.length > 1 && (
+                  <button
+                    onClick={(e) => {
+                      e.stopPropagation()
+                      closeTab(tab.id)
+                    }}
+                    className="absolute -right-0.5 -top-0.5 z-10 hidden h-3.5 w-3.5 items-center justify-center rounded-full bg-accent text-muted-foreground hover:bg-destructive/20 hover:text-destructive group-hover:flex"
+                    title="Kill terminal"
+                  >
+                    <X className="h-2 w-2" />
+                  </button>
+                )}
+              </button>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
diff --git a/web/components/sf/sidebar.tsx b/web/components/sf/sidebar.tsx
new file mode 100644
index 000000000..357aa163c
--- /dev/null
+++ b/web/components/sf/sidebar.tsx
@@ -0,0 +1,798 @@
+"use client"
+
+import { useMemo, useState, useSyncExternalStore } from "react"
+import {
+  ChevronRight,
+  ChevronDown,
+  CheckCircle2,
+  Circle,
+  Play,
+  Folder,
+  FileText,
+  GitBranch,
+  Settings,
+  LayoutDashboard,
+  Map as MapIcon,
+  Activity,
+  BarChart3,
+  Columns2,
+  MessagesSquare,
+  LifeBuoy,
+  LogOut,
+  FolderKanban,
+  Loader2,
+  Milestone,
+  SkipForward,
+  Monitor,
+  Sun,
+  Moon,
+  PanelRightClose,
+  PanelRightOpen,
+} from "lucide-react"
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog"
+import { Button } from "@/components/ui/button"
+import { cn } from "@/lib/utils"
+import { useTheme } from "next-themes"
+import {
+  getCurrentScopeLabel,
+  getLiveWorkspaceIndex,
+  getLiveAutoDashboard,
+  useGSDWorkspaceState,
+  useGSDWorkspaceActions,
+  buildPromptCommand,
+} from "@/lib/sf-workspace-store"
+import { getMilestoneStatus, getSliceStatus, getTaskStatus, type ItemStatus } from "@/lib/workspace-status"
+import { deriveWorkflowAction } from "@/lib/workflow-actions"
+import { executeWorkflowActionInPowerMode } from "@/lib/workflow-action-execution"
+import { useProjectStoreManager } from "@/lib/project-store-manager"
+import { Skeleton } from "@/components/ui/skeleton"
+import { authFetch } from "@/lib/auth"
+
+const StatusIcon = ({ status }: { status: ItemStatus }) => {
+  if (status === "done") {
+    return <CheckCircle2 className="h-4 w-4 shrink-0 text-success" />
+  }
+  if (status === "in-progress") {
+    return <Play className="h-4 w-4 shrink-0 text-warning" />
+  }
+  return <Circle className="h-4 w-4 shrink-0 text-muted-foreground" />
+}
+
+/* ─── Nav Rail (left icon bar) ─── */
+
+interface NavRailProps {
+  activeView: string
+  onViewChange: (view: string) => void
+  isConnecting?: boolean
+}
+
+export function NavRail({ activeView, onViewChange, isConnecting = false }: NavRailProps) {
+  const { openCommandSurface } = useGSDWorkspaceActions()
+  const manager = useProjectStoreManager()
+  const activeProjectCwd = useSyncExternalStore(manager.subscribe, manager.getSnapshot, manager.getSnapshot)
+  const [exitDialogOpen, setExitDialogOpen] = useState(false)
+  const { theme, setTheme } = useTheme()
+
+  const cycleTheme = () => {
+    if (theme === "system") setTheme("light")
+    else if (theme === "light") setTheme("dark")
+    else setTheme("system")
+  }
+
+  const themeIcon = theme === "light" ? Sun : theme === "dark" ? Moon : Monitor
+  const themeLabel = theme === "light" ? "Light" : theme === "dark" ? "Dark" : "System"
+  const ThemeIcon = themeIcon
+
+  const navItems = [
+    { id: "dashboard", label: "Dashboard", icon: LayoutDashboard },
+    { id: "power", label: "Power Mode", icon: Columns2 },
+    { id: "chat", label: "Chat", icon: MessagesSquare },
+    { id: "roadmap", label: "Roadmap", icon: MapIcon },
+    { id: "files", label: "Files", icon: Folder },
+    { id: "activity", label: "Activity", icon: Activity },
+    { id: "visualize", label: "Visualize", icon: BarChart3 },
+  ]
+
+  return (
+    <div className="flex w-12 flex-col items-center gap-1 border-r border-border bg-sidebar py-3">
+      {navItems.map((item) => (
+        <button
+          key={item.id}
+          onClick={() => onViewChange(item.id)}
+          disabled={isConnecting}
+          className={cn(
+            "flex h-10 w-10 items-center justify-center rounded-md transition-colors",
+            isConnecting
+              ? "cursor-not-allowed text-muted-foreground/50"
+              : activeView === item.id
+                ? "bg-accent text-foreground"
+                : "text-muted-foreground hover:bg-accent/50 hover:text-foreground",
+          )}
+          title={isConnecting ? "Connecting…" : item.label}
+        >
+          <item.icon className="h-5 w-5" />
+        </button>
+      ))}
+      <div className="mt-auto flex flex-col gap-1">
+        <button
+          onClick={() => window.dispatchEvent(new CustomEvent("gsd:open-projects"))}
+          disabled={isConnecting}
+          className={cn(
+            "flex h-10 w-10 items-center justify-center rounded-md transition-colors",
+            isConnecting
+              ? "cursor-not-allowed text-muted-foreground/50"
+              : "text-muted-foreground hover:bg-accent/50 hover:text-foreground",
+          )}
+          title={isConnecting ? "Connecting…" : "Projects"}
+        >
+          <FolderKanban className="h-5 w-5" />
+        </button>
+        <button
+          className={cn(
+            "flex h-10 w-10 items-center justify-center rounded-md text-muted-foreground transition-colors",
+            isConnecting
+              ? "cursor-not-allowed opacity-30"
+              : "hover:bg-accent/50 hover:text-foreground",
+          )}
+          title="Git"
+          disabled={isConnecting}
+          onClick={() => !isConnecting && openCommandSurface("git", { source: "sidebar" })}
+          data-testid="sidebar-git-button"
+        >
+          <GitBranch className="h-5 w-5" />
+        </button>
+        <button
+          className={cn(
+            "flex h-10 w-10 items-center justify-center rounded-md text-muted-foreground transition-colors",
+            isConnecting
+              ? "cursor-not-allowed opacity-30"
+              : "hover:bg-accent/50 hover:text-foreground",
+          )}
+          title="Settings"
+          disabled={isConnecting}
+          onClick={() => !isConnecting && openCommandSurface("settings", { source: "sidebar" })}
+          data-testid="sidebar-settings-button"
+        >
+          <Settings className="h-5 w-5" />
+        </button>
+        <button
+          className={cn(
+            "flex h-10 w-10 items-center justify-center rounded-md text-muted-foreground transition-colors",
+            isConnecting
+              ? "cursor-not-allowed opacity-30"
+              : "hover:bg-accent/50 hover:text-foreground",
+          )}
+          title={`Theme: ${themeLabel}`}
+          disabled={isConnecting}
+          onClick={() => !isConnecting && cycleTheme()}
+          data-testid="sidebar-theme-toggle"
+        >
+          <ThemeIcon className="h-5 w-5" />
+        </button>
+        <button
+          className={cn(
+            "flex h-10 w-10 items-center justify-center rounded-md text-muted-foreground transition-colors",
+            isConnecting
+              ? "cursor-not-allowed opacity-30"
+              : "hover:bg-destructive/15 hover:text-destructive",
+          )}
+          title="Exit"
+          disabled={isConnecting}
+          onClick={() => !isConnecting && setExitDialogOpen(true)}
+          data-testid="sidebar-signoff-button"
+        >
+          <LogOut className="h-5 w-5" />
+        </button>
+        <ExitDialog
+          open={exitDialogOpen}
+          onOpenChange={setExitDialogOpen}
+          projectCount={manager.getProjectCount()}
+          activeProjectCwd={activeProjectCwd}
+          onCloseProject={(cwd) => {
+            manager.closeProject(cwd)
+            onViewChange("dashboard")
+            setExitDialogOpen(false)
+          }}
+          onStopServer={async () => {
+            await authFetch("/api/shutdown", { method: "POST" }).catch(() => {})
+            setTimeout(() => {
+              try { window.close() } catch { /* ignore */ }
+              setTimeout(() => { window.location.href = "about:blank" }, 300)
+            }, 400)
+          }}
+        />
+      </div>
+    </div>
+  )
+}
+
+/* ─── Exit Dialog (multi-project aware) ─── */
+
+function ExitDialog({
+  open,
+  onOpenChange,
+  projectCount,
+  activeProjectCwd,
+  onCloseProject,
+  onStopServer,
+}: {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  projectCount: number
+  activeProjectCwd: string | null
+  onCloseProject: (cwd: string) => void
+  onStopServer: () => void
+}) {
+  const hasMultipleProjects = projectCount > 1
+  const projectName = activeProjectCwd ? activeProjectCwd.split("/").pop() ?? activeProjectCwd : null
+
+  if (!hasMultipleProjects) {
+    // Single project — simple stop server dialog
+    return (
+      <Dialog open={open} onOpenChange={onOpenChange}>
+        <DialogContent className="sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Stop the GSD web server?</DialogTitle>
+            <DialogDescription>
+              This will shut down the server process and close this tab. Run{" "}
+              <code className="rounded bg-muted px-1 py-0.5 font-mono text-xs">gsd --web</code> again to restart.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <Button variant="ghost" onClick={() => onOpenChange(false)}>
+              Cancel
+            </Button>
+            <Button
+              variant="destructive"
+              onClick={onStopServer}
+            >
+              Stop server
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    )
+  }
+
+  // Multiple projects — offer close project vs stop server
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>Close project or stop server?</DialogTitle>
+          <DialogDescription>
+            You have {projectCount} projects open. You can close just the current project or stop the entire server.
+          </DialogDescription>
+        </DialogHeader>
+        <div className="flex flex-col gap-2 py-2">
+          {activeProjectCwd && (
+            <Button
+              variant="outline"
+              className="h-auto justify-start gap-3 px-4 py-3 text-left"
+              onClick={() => onCloseProject(activeProjectCwd)}
+            >
+              <FolderKanban className="h-4 w-4 shrink-0 text-muted-foreground" />
+              <div className="min-w-0">
+                <div className="text-sm font-medium">Close {projectName}</div>
+                <div className="text-xs text-muted-foreground">
+                  Disconnect this project and switch to another
+                </div>
+              </div>
+            </Button>
+          )}
+          <Button
+            variant="outline"
+            className="h-auto justify-start gap-3 px-4 py-3 text-left border-destructive/30 hover:bg-destructive/10 hover:text-destructive"
+            onClick={onStopServer}
+          >
+            <LogOut className="h-4 w-4 shrink-0" />
+            <div className="min-w-0">
+              <div className="text-sm font-medium">Stop server</div>
+              <div className="text-xs text-muted-foreground">
+                Shut down all {projectCount} projects and close the tab
+              </div>
+            </div>
+          </Button>
+        </div>
+        <DialogFooter>
+          <Button variant="ghost" onClick={() => onOpenChange(false)}>
+            Cancel
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+/* ─── Milestone Explorer (right sidebar) ─── */
+
+export function MilestoneExplorer({ isConnecting = false, width, onCollapse }: { isConnecting?: boolean; width?: number; onCollapse?: () => void }) {
+  const workspace = useGSDWorkspaceState()
+  const { openCommandSurface, setCommandSurfaceSection, sendCommand } = useGSDWorkspaceActions()
+  const [expandedMilestones, setExpandedMilestones] = useState<string[]>([])
+  const [expandedSlices, setExpandedSlices] = useState<string[]>([])
+
+  const liveWorkspace = getLiveWorkspaceIndex(workspace)
+  const milestones = useMemo(() => liveWorkspace?.milestones ?? [], [liveWorkspace?.milestones])
+  const activeScope = liveWorkspace?.active
+  const auto = getLiveAutoDashboard(workspace)
+  const recoverySummary = workspace.live.recoverySummary
+  const validationCount = liveWorkspace?.validationIssues.length ?? 0
+  const currentScopeLabel = getCurrentScopeLabel(liveWorkspace)
+  const projectCwd = workspace.boot?.project.cwd ?? null
+  const bridge = workspace.boot?.bridge ?? null
+
+  const openTaskFile = (absolutePath: string | undefined) => {
+    if (!absolutePath || !projectCwd) return
+    const gsdPrefix = `${projectCwd}/.gsd/`
+    if (!absolutePath.startsWith(gsdPrefix)) return
+    const relativePath = absolutePath.slice(gsdPrefix.length)
+    window.dispatchEvent(new CustomEvent("gsd:open-file", { detail: { root: "gsd", path: relativePath } }))
+  }
+
+  const workflowAction = deriveWorkflowAction({
+    phase: liveWorkspace?.active.phase ?? "pre-planning",
+    autoActive: auto?.active ?? false,
+    autoPaused: auto?.paused ?? false,
+    onboardingLocked: workspace.boot?.onboarding.locked ?? false,
+    commandInFlight: workspace.commandInFlight,
+    bootStatus: workspace.bootStatus,
+    hasMilestones: milestones.length > 0,
+    projectDetectionKind: workspace.boot?.projectDetection?.kind ?? null,
+  })
+
+  const handleCommand = (command: string) => {
+    executeWorkflowActionInPowerMode({
+      dispatch: () => sendCommand(buildPromptCommand(command, bridge)),
+    })
+  }
+
+  const handlePrimaryAction = () => {
+    if (!workflowAction.primary) return
+    handleCommand(workflowAction.primary.command)
+  }
+
+  const handleOpenRecovery = () => {
+    openCommandSurface("settings", { source: "sidebar" })
+    setCommandSurfaceSection("recovery")
+  }
+
+  const effectiveExpandedMilestones =
+    activeScope?.milestoneId && !expandedMilestones.includes(activeScope.milestoneId)
+      ? [...expandedMilestones, activeScope.milestoneId]
+      : expandedMilestones
+
+  const effectiveExpandedSlices =
+    activeScope?.milestoneId && activeScope.sliceId
+      ? (() => {
+          const sliceKey = `${activeScope.milestoneId}-${activeScope.sliceId}`
+          return expandedSlices.includes(sliceKey) ? expandedSlices : [...expandedSlices, sliceKey]
+        })()
+      : expandedSlices
+
+  const milestoneStatus = new Map(
+    milestones.map((milestone) => [milestone.id, getMilestoneStatus(milestone, activeScope ?? {})]),
+  )
+
+  const toggleMilestone = (id: string) => {
+    setExpandedMilestones((prev) =>
+      prev.includes(id) ? prev.filter((entry) => entry !== id) : [...prev, id],
+    )
+  }
+
+  const toggleSlice = (id: string) => {
+    setExpandedSlices((prev) =>
+      prev.includes(id) ? prev.filter((entry) => entry !== id) : [...prev, id],
+    )
+  }
+
+  return (
+    <div className="flex flex-col bg-sidebar" style={{ width: width ?? 256, flexShrink: 0 }}>
+      {isConnecting && (
+        <div className="flex-1 overflow-y-auto px-1.5 py-1">
+          <div className="px-2 py-1.5">
+            <span className="text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
+              Milestones
+            </span>
+          </div>
+          <div className="space-y-0.5 px-1">
+            {[1, 2].map((m) => (
+              <div key={m}>
+                <div className="flex items-center gap-1.5 px-2 py-1.5">
+                  <Skeleton className="h-4 w-4 shrink-0 rounded" />
+                  <Skeleton className="h-4 w-4 shrink-0 rounded-full" />
+                  <Skeleton className={cn("h-4", m === 1 ? "w-40" : "w-32")} />
+                </div>
+                {m === 1 && (
+                  <div className="ml-4 space-y-0.5">
+                    {[1, 2, 3].map((s) => (
+                      <div key={s} className="flex items-center gap-1.5 px-2 py-1.5">
+                        <Skeleton className="h-4 w-4 shrink-0 rounded" />
+                        <Skeleton className="h-4 w-4 shrink-0 rounded-full" />
+                        <Skeleton className={cn("h-3.5", s === 1 ? "w-32" : s === 2 ? "w-28" : "w-24")} />
+                      </div>
+                    ))}
+                  </div>
+                )}
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+
+      {!isConnecting && (
+        <div className="flex-1 overflow-y-auto px-1.5 py-1">
+          <div className="flex items-start justify-between px-2 py-1.5">
+            <div className="min-w-0">
+              <span className="text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
+                Milestones
+              </span>
+              <div className="mt-1 text-xs text-foreground" data-testid="sidebar-current-scope">
+                {currentScopeLabel}
+              </div>
+            </div>
+            {onCollapse && (
+              <button
+                onClick={onCollapse}
+                className="flex h-6 w-6 shrink-0 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
+                title="Collapse sidebar"
+              >
+                <PanelRightClose className="h-3.5 w-3.5" />
+              </button>
+            )}
+          </div>
+
+          {workspace.bootStatus === "error" && milestones.length === 0 && (
+            <div className="px-3 py-2 text-xs text-destructive">Workspace boot failed before the explorer could load.</div>
+          )}
+
+          {workspace.bootStatus === "ready" && milestones.length === 0 && (
+            <div className="px-3 py-2 text-xs text-muted-foreground">No milestones found for this project.</div>
+          )}
+
+          {milestones.map((milestone) => {
+            const milestoneOpen = effectiveExpandedMilestones.includes(milestone.id)
+            const milestoneActive = activeScope?.milestoneId === milestone.id
+            const status = milestoneStatus.get(milestone.id) ?? "pending"
+
+            return (
+              <div key={milestone.id}>
+                <button
+                  onClick={() => toggleMilestone(milestone.id)}
+                  className={cn(
+                    "flex w-full items-center gap-1.5 px-2 py-1.5 text-sm transition-colors hover:bg-accent/50",
+                    milestoneActive && "bg-accent/30",
+                  )}
+                >
+                  {milestoneOpen ? (
+                    <ChevronDown className="h-4 w-4 shrink-0 text-muted-foreground" />
+                  ) : (
+                    <ChevronRight className="h-4 w-4 shrink-0 text-muted-foreground" />
+                  )}
+                  <StatusIcon status={status} />
+                  <span className={cn("truncate", status === "pending" && "text-muted-foreground")}>
+                    {milestone.id}: {milestone.title}
+                  </span>
+                </button>
+
+                {milestoneOpen && (
+                  <div className="ml-4">
+                    {milestone.slices.map((slice) => {
+                      const sliceKey = `${milestone.id}-${slice.id}`
+                      const sliceOpen = effectiveExpandedSlices.includes(sliceKey)
+                      const sliceStatus = getSliceStatus(milestone.id, slice, activeScope ?? {})
+                      const sliceActive = activeScope?.milestoneId === milestone.id && activeScope.sliceId === slice.id
+
+                      return (
+                        <div key={sliceKey}>
+                          <button
+                            onClick={() => toggleSlice(sliceKey)}
+                            className={cn(
+                              "flex w-full items-center gap-1.5 px-2 py-1.5 text-sm transition-colors hover:bg-accent/50",
+                              sliceActive && "bg-accent/20",
+                            )}
+                          >
+                            {sliceOpen ? (
+                              <ChevronDown className="h-4 w-4 shrink-0 text-muted-foreground" />
+                            ) : (
+                              <ChevronRight className="h-4 w-4 shrink-0 text-muted-foreground" />
+                            )}
+                            <StatusIcon status={sliceStatus} />
+                            <span className={cn("truncate text-[13px]", sliceStatus === "pending" && "text-muted-foreground")}>
+                              {slice.id}: {slice.title}
+                            </span>
+                          </button>
+
+                          {sliceOpen && (
+                            <div className="ml-5">
+                              {slice.branch && (
+                                <div className="px-2 py-0.5 text-[10px] uppercase tracking-wider text-muted-foreground">
+                                  {slice.branch}
+                                </div>
+                              )}
+                              {slice.tasks.map((task) => {
+                                const taskStatus = getTaskStatus(milestone.id, slice.id, task, activeScope ?? {})
+                                const hasFile = !!(task.planPath || task.summaryPath)
+                                return (
+                                  <button
+                                    key={`${sliceKey}-${task.id}`}
+                                    type="button"
+                                    onClick={() => openTaskFile(task.summaryPath ?? task.planPath)}
+                                    disabled={!hasFile}
+                                    className={cn(
+                                      "flex w-full items-center gap-1.5 px-2 py-1 text-xs transition-colors",
+                                      hasFile ? "cursor-pointer hover:bg-accent/50" : "cursor-default opacity-70",
+                                      activeScope?.taskId === task.id && sliceActive && "bg-accent/10",
+                                    )}
+                                  >
+                                    <FileText className="h-4 w-4 shrink-0 text-muted-foreground" />
+                                    <StatusIcon status={taskStatus} />
+                                    <span className={cn("truncate text-left", taskStatus === "pending" && "text-muted-foreground")}>
+                                      {task.id}: {task.title}
+                                    </span>
+                                  </button>
+                                )
+                              })}
+                            </div>
+                          )}
+                        </div>
+                      )
+                    })}
+                  </div>
+                )}
+              </div>
+            )
+          })}
+        </div>
+      )}
+
+      {/* Sticky action footer */}
+      {!isConnecting && (
+        <div className="border-t border-border px-3 py-2.5">
+          <div className="flex items-center justify-between gap-2 rounded-md border border-border bg-background px-3 py-2 text-xs">
+            <div className="min-w-0">
+              <div className="font-medium text-foreground" data-testid="sidebar-validation-count">
+                {validationCount} validation issue{validationCount === 1 ? "" : "s"}
+              </div>
+              <div className="truncate text-muted-foreground">{recoverySummary.label}</div>
+            </div>
+            <button
+              type="button"
+              onClick={handleOpenRecovery}
+              className="inline-flex h-8 shrink-0 items-center gap-1.5 rounded-md border border-border bg-card px-2.5 text-[11px] font-medium text-foreground transition-colors hover:bg-accent"
+              data-testid="sidebar-recovery-summary-entrypoint"
+            >
+              <LifeBuoy className="h-3.5 w-3.5" />
+              Recovery
+            </button>
+          </div>
+        </div>
+      )}
+
+      {!isConnecting && workflowAction.primary && (
+        <div className="border-t border-border px-3 py-2.5">
+          <div className="flex items-center gap-2">
+            <button
+              onClick={handlePrimaryAction}
+              disabled={workflowAction.disabled}
+              className={cn(
+                "inline-flex h-9 flex-1 items-center justify-center gap-2 rounded-md px-3 text-sm font-medium transition-colors",
+                workflowAction.primary.variant === "destructive"
+                  ? "bg-destructive text-destructive-foreground hover:bg-destructive/90"
+                  : "bg-primary text-primary-foreground hover:bg-primary/90",
+                workflowAction.disabled && "cursor-not-allowed opacity-50",
+              )}
+              title={workflowAction.disabledReason}
+            >
+              {workspace.commandInFlight ? (
+                <Loader2 className="h-3.5 w-3.5 animate-spin" />
+              ) : workflowAction.isNewMilestone ? (
+                <Milestone className="h-3.5 w-3.5" />
+              ) : (
+                <Play className="h-3.5 w-3.5" />
+              )}
+              {workflowAction.primary.label}
+            </button>
+            {workflowAction.secondaries.map((action) => (
+              <button
+                key={action.command}
+                onClick={() => handleCommand(action.command)}
+                disabled={workflowAction.disabled}
+                className={cn(
+                  "inline-flex h-9 w-9 shrink-0 items-center justify-center rounded-md border border-border bg-background transition-colors hover:bg-accent",
+                  workflowAction.disabled && "cursor-not-allowed opacity-50",
+                )}
+                title={action.label}
+              >
+                <SkipForward className="h-3.5 w-3.5" />
+              </button>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+/* ─── Collapsed Milestone Sidebar (icon-only rail) ─── */
+
+export function CollapsedMilestoneSidebar({ onExpand }: { onExpand: () => void }) {
+  const workspace = useGSDWorkspaceState()
+  const { sendCommand } = useGSDWorkspaceActions()
+
+  const liveWorkspace = getLiveWorkspaceIndex(workspace)
+  const milestones = liveWorkspace?.milestones ?? []
+  const auto = getLiveAutoDashboard(workspace)
+  const bridge = workspace.boot?.bridge ?? null
+
+  const workflowAction = deriveWorkflowAction({
+    phase: liveWorkspace?.active.phase ?? "pre-planning",
+    autoActive: auto?.active ?? false,
+    autoPaused: auto?.paused ?? false,
+    onboardingLocked: workspace.boot?.onboarding.locked ?? false,
+    commandInFlight: workspace.commandInFlight,
+    bootStatus: workspace.bootStatus,
+    hasMilestones: milestones.length > 0,
+    projectDetectionKind: workspace.boot?.projectDetection?.kind ?? null,
+  })
+
+  const handleCommand = (command: string) => {
+    executeWorkflowActionInPowerMode({
+      dispatch: () => sendCommand(buildPromptCommand(command, bridge)),
+    })
+  }
+
+  const handlePrimaryAction = () => {
+    if (!workflowAction.primary) return
+    handleCommand(workflowAction.primary.command)
+  }
+
+  return (
+    <div className="flex h-full w-10 flex-col items-center border-l border-border bg-sidebar py-3">
+      <button
+        onClick={onExpand}
+        className="flex h-8 w-8 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
+        title="Expand milestone sidebar"
+      >
+        <PanelRightOpen className="h-4 w-4" />
+      </button>
+
+      {workflowAction.primary && (
+        <div className="mt-auto pb-0.5">
+          <button
+            onClick={handlePrimaryAction}
+            disabled={workflowAction.disabled}
+            className={cn(
+              "flex h-8 w-8 items-center justify-center rounded-md transition-colors",
+              workflowAction.primary.variant === "destructive"
+                ? "bg-destructive text-destructive-foreground hover:bg-destructive/90"
+                : "bg-primary text-primary-foreground hover:bg-primary/90",
+              workflowAction.disabled && "cursor-not-allowed opacity-50",
+            )}
+            title={workflowAction.disabledReason ?? workflowAction.primary.label}
+          >
+            {workspace.commandInFlight ? (
+              <Loader2 className="h-4 w-4 animate-spin" />
+            ) : workflowAction.isNewMilestone ? (
+              <Milestone className="h-4 w-4" />
+            ) : (
+              <Play className="h-4 w-4" />
+            )}
+          </button>
+        </div>
+      )}
+    </div>
+  )
+}
+
+/* ─── Legacy Sidebar export (back-compat) ─── */
+
+interface SidebarProps {
+  activeView: string
+  onViewChange: (view: string) => void
+  isConnecting?: boolean
+  mobile?: boolean
+}
+
+export function Sidebar({ activeView, onViewChange, isConnecting = false, mobile = false }: SidebarProps) {
+  if (mobile) {
+    return <MobileNavPanel activeView={activeView} onViewChange={onViewChange} isConnecting={isConnecting} />
+  }
+  return (
+    <div className="flex h-full">
+      <NavRail activeView={activeView} onViewChange={onViewChange} isConnecting={isConnecting} />
+    </div>
+  )
+}
+
+/* ─── Mobile Nav Panel (full-width labels for touch) ─── */
+
+function MobileNavPanel({ activeView, onViewChange, isConnecting = false }: NavRailProps) {
+  const { openCommandSurface } = useGSDWorkspaceActions()
+  const { theme, setTheme } = useTheme()
+
+  const cycleTheme = () => {
+    if (theme === "system") setTheme("light")
+    else if (theme === "light") setTheme("dark")
+    else setTheme("system")
+  }
+
+  const themeLabel = theme === "light" ? "Light" : theme === "dark" ? "Dark" : "System"
+  const ThemeIcon = theme === "light" ? Sun : theme === "dark" ? Moon : Monitor
+
+  const navItems = [
+    { id: "dashboard", label: "Dashboard", icon: LayoutDashboard },
+    { id: "power", label: "Power Mode", icon: Columns2 },
+    { id: "chat", label: "Chat", icon: MessagesSquare },
+    { id: "roadmap", label: "Roadmap", icon: MapIcon },
+    { id: "files", label: "Files", icon: Folder },
+    { id: "activity", label: "Activity", icon: Activity },
+    { id: "visualize", label: "Visualize", icon: BarChart3 },
+  ]
+
+  return (
+    <div className="flex h-full flex-col bg-sidebar pt-14" data-testid="mobile-nav-panel">
+      <div className="flex-1 overflow-y-auto px-2 py-2">
+        {navItems.map((item) => (
+          <button
+            key={item.id}
+            onClick={() => onViewChange(item.id)}
+            disabled={isConnecting}
+            className={cn(
+              "flex w-full items-center gap-3 rounded-md px-3 py-3 text-sm font-medium transition-colors min-h-[44px]",
+              isConnecting
+                ? "cursor-not-allowed text-muted-foreground/50"
+                : activeView === item.id
+                  ? "bg-accent text-foreground"
+                  : "text-muted-foreground hover:bg-accent/50 hover:text-foreground",
+            )}
+          >
+            <item.icon className="h-5 w-5 shrink-0" />
+            {item.label}
+          </button>
+        ))}
+      </div>
+      <div className="border-t border-border px-2 py-2 space-y-1">
+        <button
+          onClick={() => window.dispatchEvent(new CustomEvent("gsd:open-projects"))}
+          disabled={isConnecting}
+          className="flex w-full items-center gap-3 rounded-md px-3 py-3 text-sm text-muted-foreground hover:bg-accent/50 hover:text-foreground transition-colors min-h-[44px]"
+        >
+          <FolderKanban className="h-5 w-5 shrink-0" />
+          Projects
+        </button>
+        <button
+          onClick={() => !isConnecting && openCommandSurface("git", { source: "sidebar" })}
+          disabled={isConnecting}
+          className="flex w-full items-center gap-3 rounded-md px-3 py-3 text-sm text-muted-foreground hover:bg-accent/50 hover:text-foreground transition-colors min-h-[44px]"
+        >
+          <GitBranch className="h-5 w-5 shrink-0" />
+          Git
+        </button>
+        <button
+          onClick={() => !isConnecting && openCommandSurface("settings", { source: "sidebar" })}
+          disabled={isConnecting}
+          className="flex w-full items-center gap-3 rounded-md px-3 py-3 text-sm text-muted-foreground hover:bg-accent/50 hover:text-foreground transition-colors min-h-[44px]"
+        >
+          <Settings className="h-5 w-5 shrink-0" />
+          Settings
+        </button>
+        <button
+          onClick={() => !isConnecting && cycleTheme()}
+          disabled={isConnecting}
+          className="flex w-full items-center gap-3 rounded-md px-3 py-3 text-sm text-muted-foreground hover:bg-accent/50 hover:text-foreground transition-colors min-h-[44px]"
+        >
+          <ThemeIcon className="h-5 w-5 shrink-0" />
+          Theme: {themeLabel}
+        </button>
+      </div>
+    </div>
+  )
+}
diff --git a/web/components/sf/status-bar.tsx b/web/components/sf/status-bar.tsx
new file mode 100644
index 000000000..2a0cab91b
--- /dev/null
+++ b/web/components/sf/status-bar.tsx
@@ -0,0 +1,163 @@
+"use client"
+
+import { useEffect, useState, useCallback } from "react"
+import { GitBranch, Cpu, DollarSign, Clock, Zap, AlertTriangle, Wifi, Info, LifeBuoy } from "lucide-react"
+import { cn } from "@/lib/utils"
+import { Skeleton } from "@/components/ui/skeleton"
+import {
+  buildProjectUrl,
+  getCurrentBranch,
+  getCurrentScopeLabel,
+  getLiveAutoDashboard,
+  getLiveWorkspaceIndex,
+  getModelLabel,
+  getStatusPresentation,
+  getVisibleWorkspaceError,
+  useGSDWorkspaceState,
+} from "@/lib/sf-workspace-store"
+import {
+  formatCost as formatProjectCost,
+  formatDuration as formatProjectDuration,
+  formatTokenCount,
+  type ProjectTotals,
+} from "@/lib/visualizer-types"
+import { ScopeBadgeInline } from "@/components/sf/scope-badge"
+import { authFetch } from "@/lib/auth"
+
+function toneClass(tone: ReturnType<typeof getStatusPresentation>["tone"]): string {
+  switch (tone) {
+    case "success":
+      return "text-success"
+    case "warning":
+      return "text-warning"
+    case "danger":
+      return "text-destructive"
+    default:
+      return "text-muted-foreground"
+  }
+}
+
+export function StatusBar() {
+  const workspace = useGSDWorkspaceState()
+  const status = getStatusPresentation(workspace)
+  const liveWorkspace = getLiveWorkspaceIndex(workspace)
+  const auto = getLiveAutoDashboard(workspace)
+  const branch = getCurrentBranch(liveWorkspace) ?? "project scope"
+  const model = getModelLabel(workspace.boot?.bridge)
+  const unitLabel = auto?.currentUnit?.id ?? getCurrentScopeLabel(liveWorkspace)
+  const visibleError = getVisibleWorkspaceError(workspace)
+  const titleOverride = workspace.titleOverride?.trim() || null
+  const statusTexts = workspace.statusTexts
+  const recoverySummary = workspace.live.recoverySummary
+  const validationCount = getLiveWorkspaceIndex(workspace)?.validationIssues.length ?? 0
+  const statusTextEntries = Object.entries(statusTexts)
+  const latestStatusText = statusTextEntries.length > 0 ? statusTextEntries[statusTextEntries.length - 1][1] : null
+  const isConnecting = workspace.bootStatus === "idle" || workspace.bootStatus === "loading"
+  const projectCwd = workspace.boot?.project.cwd
+
+  // ── Project-level totals from visualizer API ──
+  const [projectTotals, setProjectTotals] = useState<ProjectTotals | null>(null)
+
+  const fetchProjectTotals = useCallback(async () => {
+    try {
+      const resp = await authFetch(buildProjectUrl("/api/visualizer", projectCwd))
+      if (!resp.ok) return
+      const json = await resp.json()
+      if (json.totals) setProjectTotals(json.totals)
+    } catch {
+      // Silently ignore — status bar is non-critical
+    }
+  }, [projectCwd])
+
+  useEffect(() => {
+    const timeout = window.setTimeout(() => {
+      void fetchProjectTotals()
+    }, 0)
+    const interval = window.setInterval(() => {
+      void fetchProjectTotals()
+    }, 30_000)
+    return () => {
+      window.clearTimeout(timeout)
+      window.clearInterval(interval)
+    }
+  }, [fetchProjectTotals])
+
+  return (
+    <div className="flex h-7 items-center justify-between border-t border-border bg-card px-2 md:px-3 text-[10px] md:text-xs">
+      <div className="flex min-w-0 items-center gap-2 md:gap-4">
+        <div className={`flex items-center gap-1.5 ${toneClass(status.tone)}`}>
+          <Wifi className="h-3 w-3" />
+          <span>{status.label}</span>
+        </div>
+        <div className="hidden sm:flex items-center gap-1.5 text-muted-foreground">
+          <GitBranch className="h-3 w-3" />
+          {isConnecting ? (
+            <Skeleton className="h-3 w-20" />
+          ) : (
+            <span className="font-mono">{branch}</span>
+          )}
+        </div>
+        <div className="hidden lg:flex items-center gap-1.5 text-muted-foreground">
+          <Cpu className="h-3 w-3" />
+          {isConnecting ? (
+            <Skeleton className="h-3 w-24" />
+          ) : (
+            <span className="font-mono">{model}</span>
+          )}
+        </div>
+        {!isConnecting && (
+          <div className="hidden max-w-xs items-center gap-1.5 truncate text-muted-foreground xl:flex" data-testid="status-bar-retry-compaction">
+            <LifeBuoy className="h-3 w-3 shrink-0" />
+            <span className="truncate">
+              {recoverySummary.retryInProgress ? `Retry ${Math.max(1, recoverySummary.retryAttempt)}` : recoverySummary.isCompacting ? "Compacting" : recoverySummary.freshness}
+            </span>
+          </div>
+        )}
+        {!isConnecting && (
+          <div
+            className={cn("hidden items-center gap-1.5 xl:flex", validationCount > 0 ? "text-warning" : "text-muted-foreground")}
+            data-testid="status-bar-validation-count"
+          >
+            <AlertTriangle className="h-3 w-3 shrink-0" />
+            <span>{validationCount} issue{validationCount === 1 ? "" : "s"}</span>
+          </div>
+        )}
+        {!isConnecting && visibleError && (
+          <div className="hidden max-w-sm items-center gap-1.5 truncate text-destructive lg:flex" data-testid="status-bar-error">
+            <AlertTriangle className="h-3 w-3 shrink-0" />
+            <span className="truncate">{visibleError}</span>
+          </div>
+        )}
+        {!isConnecting && titleOverride && (
+          <div className="hidden max-w-xs items-center gap-1.5 truncate text-foreground/80 xl:flex" data-testid="status-bar-title-override">
+            <Info className="h-3 w-3 shrink-0" />
+            <span className="truncate" title={titleOverride}>{titleOverride}</span>
+          </div>
+        )}
+        {!isConnecting && latestStatusText && !visibleError && (
+          <div className="hidden max-w-xs items-center gap-1.5 truncate text-muted-foreground lg:flex" data-testid="status-bar-extension-status">
+            <Info className="h-3 w-3 shrink-0" />
+            <span className="truncate">{latestStatusText}</span>
+          </div>
+        )}
+      </div>
+      <div className="flex min-w-0 items-center gap-2 md:gap-4">
+        <div className="hidden sm:flex items-center gap-1.5 text-muted-foreground">
+          <Clock className="h-3 w-3" />
+          {isConnecting ? <Skeleton className="h-3 w-8" /> : <span>{formatProjectDuration(projectTotals?.duration ?? auto?.elapsed ?? 0)}</span>}
+        </div>
+        <div className="hidden sm:flex items-center gap-1.5 text-muted-foreground">
+          <Zap className="h-3 w-3" />
+          {isConnecting ? <Skeleton className="h-3 w-6" /> : <span>{formatTokenCount(projectTotals?.tokens.total ?? auto?.totalTokens ?? 0)}</span>}
+        </div>
+        <div className="flex items-center gap-1.5 text-muted-foreground">
+          <DollarSign className="h-3 w-3" />
+          {isConnecting ? <Skeleton className="h-3 w-10" /> : <span>{formatProjectCost(projectTotals?.cost ?? auto?.totalCost ?? 0)}</span>}
+        </div>
+        <span className="hidden sm:inline max-w-[20rem] truncate text-muted-foreground" data-testid="status-bar-unit">
+          {isConnecting ? <Skeleton className="inline-block h-3 w-28 align-middle" /> : <ScopeBadgeInline label={unitLabel} />}
+        </span>
+      </div>
+    </div>
+  )
+}
diff --git a/web/components/sf/tempCodeRunnerFile.tsx b/web/components/sf/tempCodeRunnerFile.tsx
new file mode 100644
index 000000000..637f4b60e
--- /dev/null
+++ b/web/components/sf/tempCodeRunnerFile.tsx
@@ -0,0 +1,784 @@
+"use client"
+
+import { useEffect, useRef, useCallback, useState } from "react"
+import { useTheme } from "next-themes"
+import { Plus, X, TerminalSquare, Loader2, ImagePlus } from "lucide-react"
+import { cn } from "@/lib/utils"
+import { validateImageFile } from "@/lib/image-utils"
+import { filterInitialGsdHeader } from "@/lib/initial-gsd-header-filter"
+import { buildProjectAbsoluteUrl, buildProjectPath } from "@/lib/project-url"
+import { authFetch, appendAuthParam } from "@/lib/auth"
+import "@xterm/xterm/css/xterm.css"
+
+type XTerminal = import("@xterm/xterm").Terminal
+type XFitAddon = import("@xterm/addon-fit").FitAddon
+
+const MIN_TERMINAL_ATTACH_WIDTH = 180
+const MIN_TERMINAL_ATTACH_HEIGHT = 120
+const MIN_TERMINAL_ATTACH_COLS = 20
+const MIN_TERMINAL_ATTACH_ROWS = 8
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+interface TerminalTab {
+  id: string
+  label: string
+  connected: boolean
+}
+
+interface ShellTerminalProps {
+  className?: string
+  command?: string
+  commandArgs?: string[]
+  sessionPrefix?: string
+  hideSidebar?: boolean
+  fontSize?: number
+  hideInitialGsdHeader?: boolean
+  projectCwd?: string
+}
+
+// ─── xterm themes ─────────────────────────────────────────────────────────────
+
+const XTERM_DARK_THEME = {
+  background: "#0a0a0a",
+  foreground: "#e4e4e7",
+  cursor: "#e4e4e7",
+  cursorAccent: "#0a0a0a",
+  selectionBackground: "#27272a",
+  selectionForeground: "#e4e4e7",
+  black: "#18181b",
+  red: "#ef4444",
+  green: "#22c55e",
+  yellow: "#eab308",
+  blue: "#3b82f6",
+  magenta: "#a855f7",
+  cyan: "#06b6d4",
+  white: "#e4e4e7",
+  brightBlack: "#52525b",
+  brightRed: "#f87171",
+  brightGreen: "#4ade80",
+  brightYellow: "#facc15",
+  brightBlue: "#60a5fa",
+  brightMagenta: "#c084fc",
+  brightCyan: "#22d3ee",
+  brightWhite: "#fafafa",
+} as const
+
+const XTERM_LIGHT_THEME = {
+  background: "#f5f5f5",
+  foreground: "#1a1a1a",
+  cursor: "#1a1a1a",
+  cursorAccent: "#f5f5f5",
+  selectionBackground: "#d4d4d8",
+  selectionForeground: "#1a1a1a",
+  black: "#1a1a1a",
+  red: "#dc2626",
+  green: "#16a34a",
+  yellow: "#ca8a04",
+  blue: "#2563eb",
+  magenta: "#9333ea",
+  cyan: "#0891b2",
+  white: "#e4e4e7",
+  brightBlack: "#71717a",
+  brightRed: "#ef4444",
+  brightGreen: "#22c55e",
+  brightYellow: "#eab308",
+  brightBlue: "#3b82f6",
+  brightMagenta: "#a855f7",
+  brightCyan: "#06b6d4",
+  brightWhite: "#fafafa",
+} as const
+
+function getXtermTheme(isDark: boolean) {
+  return isDark ? XTERM_DARK_THEME : XTERM_LIGHT_THEME
+}
+
+function getXtermOptions(isDark: boolean, fontSize?: number) {
+  return {
+    cursorBlink: true,
+    cursorStyle: "bar" as const,
+    fontSize: fontSize ?? 13,
+    fontFamily:
+      "'SF Mono', 'Cascadia Code', 'Fira Code', Menlo, Monaco, 'Courier New', monospace",
+    lineHeight: 1.35,
+    letterSpacing: 0,
+    theme: getXtermTheme(isDark),
+    allowProposedApi: true,
+    scrollback: 10000,
+    convertEol: false,
+  }
+}
+
+function getRenderableTerminalSize(container: HTMLDivElement | null, terminal: XTerminal | null): { cols: number; rows: number } | null {
+  if (!container || !terminal) return null
+
+  const rect = container.getBoundingClientRect()
+  if (rect.width < MIN_TERMINAL_ATTACH_WIDTH || rect.height < MIN_TERMINAL_ATTACH_HEIGHT) {
+    return null
+  }
+
+  if (terminal.cols < MIN_TERMINAL_ATTACH_COLS || terminal.rows < MIN_TERMINAL_ATTACH_ROWS) {
+    return null
+  }
+
+  return { cols: terminal.cols, rows: terminal.rows }
+}
+
+async function settleTerminalLayout(
+  container: HTMLDivElement | null,
+  terminal: XTerminal | null,
+  fitAddon: XFitAddon | null,
+  isDisposed: () => boolean,
+): Promise<{ cols: number; rows: number } | null> {
+  if (typeof document !== "undefined" && "fonts" in document) {
+    try {
+      await Promise.race([
+        document.fonts.ready,
+        new Promise<void>((resolve) => setTimeout(resolve, 1000)),
+      ])
+    } catch {
+      // Ignore font loading failures and fall through to repeated fit attempts.
+    }
+  }
+
+  for (let attempt = 0; attempt < 12; attempt++) {
+    if (isDisposed()) return null
+
+    await new Promise<void>((resolve) => {
+      requestAnimationFrame(() => resolve())
+    })
+
+    if (isDisposed()) return null
+
+    try {
+      fitAddon?.fit()
+    } catch {
+      /* hidden or detached */
+    }
+
+    const size = getRenderableTerminalSize(container, terminal)
+    if (size) {
+      return size
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 50))
+  }
+
+  return getRenderableTerminalSize(container, terminal)
+}
+
+function deriveCommandLabel(command?: string): string {
+  if (!command?.trim()) return "zsh"
+  const token = command.trim().split(/\s+/)[0] || command
+  const normalized = token.replace(/\\/g, "/")
+  const parts = normalized.split("/")
+  return parts[parts.length - 1] || token
+}
+
+// ─── Single terminal instance (internal) ──────────────────────────────────────
+
+interface TerminalInstanceProps {
+  sessionId: string
+  visible: boolean
+  command?: string
+  commandArgs?: string[]
+  isDark: boolean
+  fontSize?: number
+  hideInitialGsdHeader?: boolean
+  projectCwd?: string
+  onConnectionChange: (connected: boolean) => void
+}
+
+function TerminalInstance({
+  sessionId,
+  visible,
+  command,
+  commandArgs,
+  isDark,
+  fontSize,
+  hideInitialGsdHeader = false,
+  projectCwd,
+  onConnectionChange,
+}: TerminalInstanceProps) {
+  const containerRef = useRef<HTMLDivElement>(null)
+  const termRef = useRef<XTerminal | null>(null)
+  const fitAddonRef = useRef<XFitAddon | null>(null)
+  const eventSourceRef = useRef<EventSource | null>(null)
+  const inputQueueRef = useRef<string[]>([])
+  const flushingRef = useRef(false)
+  const resizeTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const onConnectionChangeRef = useRef(onConnectionChange)
+  const initialHeaderSettledRef = useRef(!hideInitialGsdHeader)
+  const initialHeaderBufferRef = useRef("")
+  const commandArgsKey = (commandArgs ?? []).join("\u0000")
+  const [hasOutput, setHasOutput] = useState(false)
+
+  const sendResize = useCallback(
+    (cols: number, rows: number) => {
+      if (resizeTimeoutRef.current) clearTimeout(resizeTimeoutRef.current)
+      resizeTimeoutRef.current = setTimeout(() => {
+        void authFetch(buildProjectPath("/api/terminal/resize", projectCwd), {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ id: sessionId, cols, rows }),
+        })
+      }, 100)
+    },
+    [projectCwd, sessionId],
+  )
+
+  const flushInputQueue = useCallback(async () => {
+    if (flushingRef.current) return
+    flushingRef.current = true
+    while (inputQueueRef.current.length > 0) {
+      const data = inputQueueRef.current.shift()!
+      try {
+        await authFetch(buildProjectPath("/api/terminal/input", projectCwd), {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ id: sessionId, data }),
+        })
+      } catch {
+        inputQueueRef.current.unshift(data)
+        break
+      }
+    }
+    flushingRef.current = false
+  }, [projectCwd, sessionId])
+
+  const sendInput = useCallback(
+    (data: string) => {
+      inputQueueRef.current.push(data)
+      void flushInputQueue()
+    },
+    [flushInputQueue],
+  )
+
+  useEffect(() => {
+    onConnectionChangeRef.current = onConnectionChange
+  }, [onConnectionChange])
+
+  useEffect(() => {
+    initialHeaderSettledRef.current = !hideInitialGsdHeader
+    initialHeaderBufferRef.current = ""
+  }, [hideInitialGsdHeader, sessionId])
+
+  // Update xterm theme when isDark changes
+  useEffect(() => {
+    if (termRef.current) {
+      termRef.current.options.theme = getXtermTheme(isDark)
+    }
+  }, [isDark])
+
+  // Update xterm font size when fontSize changes
+  useEffect(() => {
+    if (termRef.current) {
+      termRef.current.options.fontSize = fontSize ?? 13
+      try {
+        fitAddonRef.current?.fit()
+        if (termRef.current) {
+          sendResize(termRef.current.cols, termRef.current.rows)
+        }
+      } catch {
+        /* not visible yet */
+      }
+    }
+  }, [fontSize, sendResize])
+
+  // Re-fit when visibility changes
+  useEffect(() => {
+    if (visible && fitAddonRef.current && termRef.current) {
+      // Small delay to let the DOM settle
+      const t = setTimeout(() => {
+        try {
+          fitAddonRef.current?.fit()
+          if (termRef.current) {
+            sendResize(termRef.current.cols, termRef.current.rows)
+          }
+        } catch {
+          /* not visible yet */
+        }
+      }, 50)
+      return () => clearTimeout(t)
+    }
+  }, [visible, sendResize])
+
+  useEffect(() => {
+    if (!containerRef.current) return
+
+    let disposed = false
+    let terminal: XTerminal | null = null
+    let fitAddon: XFitAddon | null = null
+    let resizeObserver: ResizeObserver | null = null
+
+    const init = async () => {
+      const [{ Terminal }, { FitAddon }] = await Promise.all([
+        import("@xterm/xterm"),
+        import("@xterm/addon-fit"),
+      ])
+
+      if (disposed) return
+
+      terminal = new Terminal(getXtermOptions(isDark, fontSize))
+      fitAddon = new FitAddon()
+      terminal.loadAddon(fitAddon)
+      terminal.open(containerRef.current!)
+
+      termRef.current = terminal
+      fitAddonRef.current = fitAddon
+
+      await settleTerminalLayout(containerRef.current, terminal, fitAddon, () => disposed)
+      if (disposed) return
+
+      terminal.onData((data) => sendInput(data))
+      terminal.onBinary((data) => sendInput(data))
+
+      // SSE stream
+      const streamUrl = buildProjectAbsoluteUrl(
+        "/api/terminal/stream",
+        window.location.origin,
+        projectCwd,
+      )
+      streamUrl.searchParams.set("id", sessionId)
+      if (command) streamUrl.searchParams.set("command", command)
+      for (const arg of commandArgs ?? []) {
+        streamUrl.searchParams.append("arg", arg)
+      }
+      const es = new EventSource(appendAuthParam(streamUrl.toString()))
+      eventSourceRef.current = es
+
+      es.onmessage = (event) => {
+        try {
+          const msg = JSON.parse(event.data) as {
+            type: string
+            data?: string
+          }
+          if (msg.type === "connected") {
+            onConnectionChangeRef.current(true)
+            void settleTerminalLayout(containerRef.current, terminal, fitAddon, () => disposed).then((size) => {
+              if (!size) return
+              sendResize(size.cols, size.rows)
+            })
+          } else if (msg.type === "output" && msg.data) {
+            let output = msg.data
+
+            if (hideInitialGsdHeader && !initialHeaderSettledRef.current) {
+              initialHeaderBufferRef.current += output
+              const filtered = filterInitialGsdHeader(initialHeaderBufferRef.current)
+
+              if (filtered.status === "needs-more") {
+                return
+              }
+
+              initialHeaderSettledRef.current = true
+              initialHeaderBufferRef.current = ""
+              output = filtered.text
+            }
+
+            if (output) {
+              terminal?.write(output)
+              setHasOutput(true)
+            }
+          }
+        } catch {
+          /* malformed */
+        }
+      }
+
+      es.onerror = () => onConnectionChangeRef.current(false)
+
+      // Resize observer
+      resizeObserver = new ResizeObserver(() => {
+        if (disposed) return
+        try {
+          fitAddon?.fit()
+          if (terminal) sendResize(terminal.cols, terminal.rows)
+        } catch {
+          /* not visible */
+        }
+      })
+      resizeObserver.observe(containerRef.current!)
+    }
+
+    void init()
+
+    return () => {
+      disposed = true
+      if (resizeTimeoutRef.current) clearTimeout(resizeTimeoutRef.current)
+      eventSourceRef.current?.close()
+      eventSourceRef.current = null
+      resizeObserver?.disconnect()
+      terminal?.dispose()
+      termRef.current = null
+      fitAddonRef.current = null
+    }
+  }, [sessionId, command, commandArgs, commandArgsKey, fontSize, hideInitialGsdHeader, isDark, projectCwd, sendInput, sendResize])
+
+  // Focus on click
+  const wrapperRef = useRef<HTMLDivElement>(null)
+  const handleClick = useCallback(() => {
+    termRef.current?.focus()
+  }, [])
+
+  // Shift+Enter → newline (native DOM, capture phase)
+  // xterm.js sends \r for both Enter and Shift+Enter. The pi TUI editor
+  // recognizes \n (LF) as "insert newline".
+  useEffect(() => {
+    const el = wrapperRef.current
+    if (!el) return
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Enter" && e.shiftKey && !e.ctrlKey && !e.altKey && !e.metaKey) {
+        e.preventDefault()
+        e.stopPropagation()
+        sendInput("\n")
+      }
+    }
+
+    el.addEventListener("keydown", onKeyDown, true)
+    return () => el.removeEventListener("keydown", onKeyDown, true)
+  }, [sendInput])
+
+  // Auto-focus when this tab becomes visible
+  useEffect(() => {
+    if (visible) {
+      // Small delay to let layout settle
+      const t = setTimeout(() => termRef.current?.focus(), 80)
+      return () => clearTimeout(t)
+    }
+  }, [visible])
+
+  return (
+    <div
+      ref={wrapperRef}
+      className={cn("relative h-full w-full bg-terminal", !visible && "hidden")}
+      onClick={handleClick}
+    >
+      {/* Loading overlay — visible until first output arrives */}
+      {!hasOutput && (
+        <div className="absolute inset-0 z-10 flex flex-col items-center justify-center gap-3 bg-terminal">
+          <Loader2 className="h-5 w-5 animate-spin text-muted-foreground" />
+          <span className="text-xs text-muted-foreground">
+            {command ? "Starting GSD…" : "Connecting…"}
+          </span>
+        </div>
+      )}
+      <div
+        ref={containerRef}
+        className="h-full w-full"
+        style={{ padding: "8px 4px 4px 8px" }}
+      />
+    </div>
+  )
+}
+
+// ─── Image upload helpers ─────────────────────────────────────────────────────
+
+const ALLOWED_IMAGE_TYPES = new Set([
+  "image/jpeg",
+  "image/png",
+  "image/gif",
+  "image/webp",
+])
+
+/**
+ * Upload an image file to the server's temp directory and inject the `@filepath`
+ * text into the PTY session's stdin.
+ *
+ * Observability:
+ * - console.warn on client-side validation failure
+ * - console.error on upload or inject failure
+ */
+async function uploadAndInjectImage(file: File, sessionId: string, projectCwd?: string): Promise<void> {
+  // Client-side validation
+  const validation = validateImageFile(file)
+  if (!validation.valid) {
+    console.warn("[terminal-upload] validation failed:", validation.error)
+    return
+  }
+
+  // Upload to temp dir
+  const formData = new FormData()
+  formData.append("file", file)
+
+  let uploadPath: string
+  try {
+    const res = await authFetch(buildProjectPath("/api/terminal/upload", projectCwd), {
+      method: "POST",
+      body: formData,
+    })
+    const data = await res.json() as { ok?: boolean; path?: string; error?: string }
+    if (!res.ok || !data.path) {
+      console.error("[terminal-upload] upload failed:", data.error ?? `HTTP ${res.status}`)
+      return
+    }
+    uploadPath = data.path
+  } catch (err) {
+    console.error("[terminal-upload] upload request failed:", err)
+    return
+  }
+
+  // Inject @filepath into PTY stdin
+  try {
+    const res = await authFetch(buildProjectPath("/api/terminal/input", projectCwd), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ id: sessionId, data: `@${uploadPath} ` }),
+    })
+    if (!res.ok) {
+      const data = await res.json().catch(() => ({})) as { error?: string }
+      console.error("[terminal-upload] inject failed:", data.error ?? `HTTP ${res.status}`)
+    }
+  } catch (err) {
+    console.error("[terminal-upload] inject request failed:", err)
+  }
+}
+
+// ─── Multi-instance terminal panel ────────────────────────────────────────────
+
+export function ShellTerminal({
+  className,
+  command,
+  commandArgs,
+  sessionPrefix,
+  hideSidebar = false,
+  fontSize,
+  hideInitialGsdHeader = false,
+  projectCwd,
+}: ShellTerminalProps) {
+  const { resolvedTheme } = useTheme()
+  const isDark = resolvedTheme !== "light"
+  const defaultId = sessionPrefix ?? (command ? "gsd-default" : "default")
+  const commandLabel = deriveCommandLabel(command)
+  const [tabs, setTabs] = useState<TerminalTab[]>([
+    { id: defaultId, label: commandLabel, connected: false },
+  ])
+  const [activeTabId, setActiveTabId] = useState(defaultId)
+  const [isDragOver, setIsDragOver] = useState(false)
+  const terminalAreaRef = useRef<HTMLDivElement>(null)
+
+  // ── Drag-and-drop handlers (native DOM, capture phase) ──────────────────
+  // React synthetic events don't reliably fire through xterm's internal DOM.
+  // Native capture-phase listeners intercept before xterm can swallow them —
+  // same pattern used for paste below.
+
+  useEffect(() => {
+    const el = terminalAreaRef.current
+    if (!el) return
+
+    let counter = 0
+
+    const onDragEnter = (e: DragEvent) => {
+      e.preventDefault()
+      e.stopPropagation()
+      counter += 1
+      if (counter === 1) setIsDragOver(true)
+    }
+
+    const onDragOver = (e: DragEvent) => {
+      e.preventDefault()
+      e.stopPropagation()
+    }
+
+    const onDragLeave = (e: DragEvent) => {
+      e.preventDefault()
+      e.stopPropagation()
+      counter -= 1
+      if (counter <= 0) {
+        counter = 0
+        setIsDragOver(false)
+      }
+    }
+
+    const onDrop = (e: DragEvent) => {
+      e.preventDefault()
+      e.stopPropagation()
+      counter = 0
+      setIsDragOver(false)
+
+      if (!activeTabId) return
+      const files = Array.from(e.dataTransfer?.files ?? [])
+      const imageFile = files.find((f) => ALLOWED_IMAGE_TYPES.has(f.type))
+      if (imageFile) {
+        void uploadAndInjectImage(imageFile, activeTabId, projectCwd)
+      }
+    }
+
+    el.addEventListener("dragenter", onDragEnter, true)
+    el.addEventListener("dragover", onDragOver, true)
+    el.addEventListener("dragleave", onDragLeave, true)
+    el.addEventListener("drop", onDrop, true)
+    return () => {
+      el.removeEventListener("dragenter", onDragEnter, true)
+      el.removeEventListener("dragover", onDragOver, true)
+      el.removeEventListener("dragleave", onDragLeave, true)
+      el.removeEventListener("drop", onDrop, true)
+    }
+  }, [activeTabId, projectCwd])
+
+  // ── Paste handler for images ──────────────────────────────────────────────
+
+  useEffect(() => {
+    const el = terminalAreaRef.current
+    if (!el) return
+
+    const handlePaste = (e: ClipboardEvent) => {
+      if (!e.clipboardData) return
+      const files = Array.from(e.clipboardData.files)
+      const imageFile = files.find((f) => ALLOWED_IMAGE_TYPES.has(f.type))
+      if (imageFile) {
+        e.preventDefault()
+        e.stopPropagation()
+        if (activeTabId) {
+          void uploadAndInjectImage(imageFile, activeTabId, projectCwd)
+        }
+      }
+      // If no image files, don't prevent default — let xterm.js handle text paste
+    }
+
+    el.addEventListener("paste", handlePaste, true) // capture phase to fire before xterm
+    return () => el.removeEventListener("paste", handlePaste, true)
+  }, [activeTabId, projectCwd])
+
+  const createTab = useCallback(async () => {
+    try {
+      const res = await authFetch(buildProjectPath("/api/terminal/sessions", projectCwd), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(command ? { command } : {}),
+      })
+      const data = (await res.json()) as { id: string }
+      const newTab: TerminalTab = {
+        id: data.id,
+        label: commandLabel,
+        connected: false,
+      }
+      setTabs((prev) => [...prev, newTab])
+      setActiveTabId(data.id)
+    } catch {
+      /* network error */
+    }
+  }, [command, commandLabel, projectCwd])
+
+  const closeTab = useCallback(
+    (id: string) => {
+      // Don't close the last tab
+      if (tabs.length <= 1) return
+      const deleteUrl = buildProjectAbsoluteUrl("/api/terminal/sessions", window.location.origin, projectCwd)
+      deleteUrl.searchParams.set("id", id)
+      void authFetch(deleteUrl.toString(), {
+        method: "DELETE",
+      })
+      const remaining = tabs.filter((t) => t.id !== id)
+      setTabs(remaining)
+      if (activeTabId === id) {
+        setActiveTabId(remaining[remaining.length - 1]?.id ?? defaultId)
+      }
+    },
+    [tabs, activeTabId, defaultId, projectCwd],
+  )
+
+  const updateConnection = useCallback(
+    (id: string, connected: boolean) => {
+      setTabs((prev) =>
+        prev.map((t) => (t.id === id ? { ...t, connected } : t)),
+      )
+    },
+    [],
+  )
+
+  return (
+    <div className={cn("flex bg-terminal", className)}>
+      {/* Terminal area — receives drag/drop and paste for images */}
+      <div
+        ref={terminalAreaRef}
+        className="relative flex-1 min-w-0"
+      >
+        {tabs.map((tab) => (
+          <TerminalInstance
+            key={tab.id}
+            sessionId={tab.id}
+            visible={tab.id === activeTabId}
+            command={command}
+            commandArgs={tab.id === defaultId ? commandArgs : undefined}
+            isDark={isDark}
+            fontSize={fontSize}
+            hideInitialGsdHeader={hideInitialGsdHeader}
+            projectCwd={projectCwd}
+            onConnectionChange={(c) => updateConnection(tab.id, c)}
+          />
+        ))}
+
+        {/* Drop overlay */}
+        {isDragOver && (
+          <div className="absolute inset-0 z-20 flex flex-col items-center justify-center gap-2 bg-background/80 backdrop-blur-sm border-2 border-dashed border-primary rounded-md pointer-events-none">
+            <ImagePlus className="h-8 w-8 text-primary" />
+            <span className="text-sm font-medium text-primary">Drop image here</span>
+          </div>
+        )}
+      </div>
+
+      {!hideSidebar && (
+        <div className="flex w-[34px] flex-shrink-0 flex-col border-l border-border/40 bg-terminal">
+          {/* New terminal button */}
+          <button
+            onClick={createTab}
+            className="flex h-[30px] w-full items-center justify-center text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
+            title="New terminal"
+          >
+            <Plus className="h-3 w-3" />
+          </button>
+
+          <div className="h-px bg-border/40" />
+
+          {/* Tab list */}
+          <div className="flex-1 overflow-y-auto">
+            {tabs.map((tab, index) => (
+              <button
+                key={tab.id}
+                onClick={() => setActiveTabId(tab.id)}
+                className={cn(
+                  "group relative flex h-[30px] w-full items-center justify-center transition-colors",
+                  tab.id === activeTabId
+                    ? "bg-accent text-accent-foreground"
+                    : "text-muted-foreground hover:bg-accent/50 hover:text-accent-foreground",
+                )}
+                title={`${tab.label} ${index + 1}`}
+              >
+                {/* Active indicator bar */}
+                {tab.id === activeTabId && (
+                  <div className="absolute left-0 top-1.5 bottom-1.5 w-[2px] rounded-full bg-muted-foreground" />
+                )}
+
+                <div className="relative flex items-center">
+                  <TerminalSquare className="h-3 w-3" />
+                  {/* Connection dot */}
+                  <span
+                    className={cn(
+                      "absolute -bottom-0.5 -right-0.5 h-1.5 w-1.5 rounded-full border border-terminal",
+                      tab.connected ? "bg-success" : "bg-muted-foreground/40",
+                    )}
+                  />
+                </div>
+
+                {/* Close button — shows on hover as small badge in corner */}
+                {tabs.length > 1 && (
+                  <button
+                    onClick={(e) => {
+                      e.stopPropagation()
+                      closeTab(tab.id)
+                    }}
+                    className="absolute -right-0.5 -top-0.5 z-10 hidden h-3.5 w-3.5 items-center justify-center rounded-full bg-accent text-muted-foreground hover:bg-destructive/20 hover:text-destructive group-hover:flex"
+                    title="Kill terminal"
+                  >
+                    <X className="h-2 w-2" />
+                  </button>
+                )}
+              </button>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
diff --git a/web/components/sf/terminal.tsx b/web/components/sf/terminal.tsx
new file mode 100644
index 000000000..e2a23af6c
--- /dev/null
+++ b/web/components/sf/terminal.tsx
@@ -0,0 +1,345 @@
+"use client"
+
+import { useEffect, useRef, useState } from "react"
+import { Compass, Loader2, OctagonX, Wrench } from "lucide-react"
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import {
+  getOnboardingPresentation,
+  getSessionLabelFromBridge,
+  getStatusPresentation,
+  useGSDWorkspaceActions,
+  useGSDWorkspaceState,
+} from "@/lib/sf-workspace-store"
+
+interface TerminalProps {
+  className?: string
+}
+
+type InputMode = "prompt" | "follow_up" | "steer"
+type WidgetPlacement = "aboveEditor" | "belowEditor"
+
+const MAX_VISIBLE_WIDGET_LINES = 6
+
+function getInputMode(state: ReturnType<typeof useGSDWorkspaceState>): InputMode {
+  const session = state.boot?.bridge.sessionState
+  if (!session) return "prompt"
+  if (session.isStreaming) return "follow_up"
+  return "prompt"
+}
+
+function inputModePlaceholder(mode: InputMode, state: ReturnType<typeof useGSDWorkspaceState>): string {
+  if (state.bootStatus === "loading") return "Loading workspace…"
+  if (state.bootStatus === "error") return "Workspace boot failed — check the visible error state"
+  if (state.commandInFlight) return `Sending ${state.commandInFlight}…`
+  if (state.boot?.onboarding.locked) {
+    return getOnboardingPresentation(state).detail
+  }
+  switch (mode) {
+    case "steer":
+      return "Type a steering message to redirect the agent…"
+    case "follow_up":
+      return "Agent is active — type a follow-up or /state"
+    case "prompt":
+      return "Type a prompt, /state, /new, or /clear"
+  }
+}
+
+function inputModeLabel(mode: InputMode): string {
+  switch (mode) {
+    case "steer":
+      return "steer"
+    case "follow_up":
+      return "follow-up"
+    case "prompt":
+      return "$"
+  }
+}
+
+function getWidgetsForPlacement(
+  widgetContents: Record<string, { lines: string[] | undefined; placement?: WidgetPlacement }>,
+  placement: WidgetPlacement,
+): Array<{ key: string; placement: WidgetPlacement; visibleLines: string[]; hiddenLineCount: number; fullText: string }> {
+  return Object.entries(widgetContents)
+    .filter(([, widget]) => {
+      const widgetPlacement = widget.placement ?? "aboveEditor"
+      return widgetPlacement === placement && Array.isArray(widget.lines) && widget.lines.length > 0
+    })
+    .sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey))
+    .map(([key, widget]) => {
+      const lines = widget.lines ?? []
+      return {
+        key,
+        placement,
+        visibleLines: lines.slice(0, MAX_VISIBLE_WIDGET_LINES),
+        hiddenLineCount: Math.max(0, lines.length - MAX_VISIBLE_WIDGET_LINES),
+        fullText: lines.join("\n"),
+      }
+    })
+}
+
+function TerminalWidgetBand({
+  placement,
+  widgets,
+}: {
+  placement: WidgetPlacement
+  widgets: Array<{ key: string; placement: WidgetPlacement; visibleLines: string[]; hiddenLineCount: number; fullText: string }>
+}) {
+  if (widgets.length === 0) return null
+
+  return (
+    <div
+      className="border-t border-border/50 bg-card/50 px-4 py-2"
+      data-testid={placement === "aboveEditor" ? "terminal-widgets-above-editor" : "terminal-widgets-below-editor"}
+    >
+      <div className="space-y-2">
+        {widgets.map((widget) => (
+          <div
+            key={`${widget.placement}:${widget.key}`}
+            className="rounded-md border border-border bg-background/50 px-3 py-2"
+            data-testid="terminal-widget"
+            data-widget-key={widget.key}
+            data-widget-placement={widget.placement}
+            title={widget.fullText}
+          >
+            <div className="mb-1 flex items-center justify-between gap-2 text-[10px] uppercase tracking-[0.2em] text-muted-foreground">
+              <span className="truncate">{widget.key}</span>
+              <span>{widget.placement === "aboveEditor" ? "Above editor" : "Below editor"}</span>
+            </div>
+            <div className="space-y-1 text-xs text-foreground">
+              {widget.visibleLines.map((line, index) => (
+                <div key={`${widget.key}:${index}`} className="whitespace-pre-wrap break-words">
+                  {line}
+                </div>
+              ))}
+              {widget.hiddenLineCount > 0 && (
+                <div className="text-[11px] text-muted-foreground" data-testid="terminal-widget-overflow">
+                  +{widget.hiddenLineCount} more line{widget.hiddenLineCount === 1 ? "" : "s"}
+                </div>
+              )}
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+export function Terminal({ className }: TerminalProps) {
+  const workspace = useGSDWorkspaceState()
+  const { submitInput, sendAbort, sendSteer, consumeEditorTextBuffer } = useGSDWorkspaceActions()
+  const [input, setInput] = useState("")
+  const [steerMode, setSteerMode] = useState(false)
+  const bottomRef = useRef<HTMLDivElement>(null)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  const autoMode = getInputMode(workspace)
+  const isStreaming = Boolean(workspace.boot?.bridge.sessionState?.isStreaming)
+  const inputMode: InputMode = steerMode && isStreaming ? "steer" : autoMode
+  const widgetsAboveEditor = getWidgetsForPlacement(workspace.widgetContents, "aboveEditor")
+  const widgetsBelowEditor = getWidgetsForPlacement(workspace.widgetContents, "belowEditor")
+
+  useEffect(() => {
+    if (workspace.editorTextBuffer === null) return
+    const buffer = workspace.editorTextBuffer
+    const updateTimer = window.setTimeout(() => {
+      setInput(buffer)
+      consumeEditorTextBuffer()
+      inputRef.current?.focus()
+    }, 0)
+    return () => window.clearTimeout(updateTimer)
+  }, [consumeEditorTextBuffer, workspace.editorTextBuffer])
+
+  useEffect(() => {
+    bottomRef.current?.scrollIntoView({ behavior: "smooth" })
+  }, [workspace.terminalLines, workspace.streamingAssistantText, workspace.liveTranscript])
+
+  const status = getStatusPresentation(workspace)
+  const sessionLabel = getSessionLabelFromBridge(workspace.boot?.bridge)
+  const isInputDisabled =
+    workspace.bootStatus !== "ready" ||
+    workspace.commandInFlight === "refresh" ||
+    Boolean(workspace.boot?.onboarding.locked)
+
+  const handleSubmit = async (event: React.FormEvent) => {
+    event.preventDefault()
+    const trimmed = input.trim()
+    if (!trimmed) return
+
+    if (inputMode === "steer") {
+      await sendSteer(trimmed)
+      setInput("")
+      setSteerMode(false)
+      return
+    }
+
+    await submitInput(trimmed)
+    setInput("")
+  }
+
+  return (
+    <div
+      className={cn("flex flex-col bg-terminal font-mono text-sm", className)}
+      onClick={() => inputRef.current?.focus()}
+    >
+      {/* Terminal header */}
+      <div className="flex items-center justify-between border-b border-border/50 px-4 py-2 text-[11px] text-muted-foreground">
+        <div className="min-w-0 flex items-center gap-2 truncate">
+          <span data-testid="terminal-session-banner">
+            {sessionLabel || "Waiting for live session…"}
+          </span>
+          {/* Active tool execution badge */}
+          {workspace.activeToolExecution && (
+            <span
+              className="inline-flex items-center gap-1 rounded-full border border-foreground/15 bg-accent/60 px-2 py-0.5 text-[10px] font-medium text-foreground/80"
+              data-testid="terminal-tool-badge"
+            >
+              <Wrench className="h-3 w-3" />
+              {workspace.activeToolExecution.name}
+            </span>
+          )}
+        </div>
+        <div className="flex items-center gap-2">
+          {/* Abort button */}
+          {isStreaming && (
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-6 gap-1 px-2 text-[11px] text-destructive hover:bg-destructive/10 hover:text-destructive"
+              onClick={(e) => {
+                e.stopPropagation()
+                void sendAbort()
+              }}
+              disabled={workspace.commandInFlight === "abort"}
+              data-testid="terminal-abort-button"
+            >
+              <OctagonX className="h-3 w-3" />
+              Abort
+            </Button>
+          )}
+          <span
+            className={cn(
+              "h-2 w-2 rounded-full",
+              status.tone === "success"
+                ? "bg-success"
+                : status.tone === "warning"
+                  ? "bg-warning"
+                  : status.tone === "danger"
+                    ? "bg-destructive"
+                    : "bg-muted-foreground/60",
+              status.tone === "success" && "animate-pulse",
+            )}
+          />
+          <span>{status.label}</span>
+        </div>
+      </div>
+
+      {/* Terminal lines + streaming content */}
+      <div className="flex-1 overflow-y-auto p-4">
+        {workspace.terminalLines.map((line) => (
+          <div key={line.id} className="flex" data-testid="terminal-line">
+            <span className="mr-2 select-none text-muted-foreground">{line.timestamp}</span>
+            <span
+              className={cn(
+                "whitespace-pre-wrap",
+                line.type === "input" && "text-foreground before:content-['$_'] before:text-muted-foreground",
+                line.type === "output" && "text-terminal-foreground",
+                line.type === "system" && "text-muted-foreground",
+                line.type === "success" && "text-success",
+                line.type === "error" && "text-destructive",
+              )}
+            >
+              {line.content}
+            </span>
+          </div>
+        ))}
+
+        {/* Completed transcript blocks from previous turns */}
+        {workspace.liveTranscript.length > 0 && (
+          <div className="mt-2 space-y-2" data-testid="terminal-transcript">
+            {workspace.liveTranscript.map((block, i) => (
+              <div
+                key={`transcript-${i}`}
+                className="whitespace-pre-wrap rounded border border-border/50 bg-accent/20 px-3 py-2 text-foreground"
+              >
+                {block}
+              </div>
+            ))}
+          </div>
+        )}
+
+        {/* Live streaming assistant text */}
+        {workspace.streamingAssistantText && (
+          <div className="mt-2" data-testid="terminal-streaming-text">
+            <div className="whitespace-pre-wrap rounded border border-foreground/10 bg-foreground/[0.03] px-3 py-2 text-foreground">
+              {workspace.streamingAssistantText}
+              <span className="ml-0.5 inline-block h-4 w-1.5 animate-pulse bg-foreground/60" />
+            </div>
+          </div>
+        )}
+
+        {/* Streaming indicator when active but no text yet */}
+        {isStreaming && !workspace.streamingAssistantText && !workspace.activeToolExecution && (
+          <div className="mt-2 flex items-center gap-2 text-xs text-muted-foreground">
+            <Loader2 className="h-3 w-3 animate-spin" />
+            Agent is thinking…
+          </div>
+        )}
+
+        <div ref={bottomRef} />
+      </div>
+
+      <TerminalWidgetBand placement="aboveEditor" widgets={widgetsAboveEditor} />
+
+      {/* Input area with steer toggle */}
+      <form onSubmit={handleSubmit} className="flex items-center gap-2 border-t border-border/50 px-4 py-2">
+        {/* Steer toggle — only visible when agent is streaming */}
+        {isStreaming && (
+          <Button
+            type="button"
+            variant={steerMode ? "default" : "ghost"}
+            size="sm"
+            className={cn(
+              "h-6 gap-1 px-2 text-[11px]",
+              steerMode
+                ? "bg-foreground text-background"
+                : "text-muted-foreground hover:text-foreground",
+            )}
+            onClick={(e) => {
+              e.stopPropagation()
+              setSteerMode(!steerMode)
+            }}
+            data-testid="terminal-steer-toggle"
+          >
+            <Compass className="h-3 w-3" />
+            Steer
+          </Button>
+        )}
+        <span
+          className={cn(
+            "text-muted-foreground",
+            inputMode === "steer" && "font-semibold text-foreground",
+          )}
+        >
+          {inputModeLabel(inputMode)}
+        </span>
+        <input
+          ref={inputRef}
+          type="text"
+          value={input}
+          onChange={(event) => setInput(event.target.value)}
+          className="flex-1 bg-transparent text-foreground outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:text-muted-foreground"
+          placeholder={inputModePlaceholder(inputMode, workspace)}
+          disabled={isInputDisabled}
+          data-testid="terminal-command-input"
+          autoFocus
+        />
+        {workspace.commandInFlight && (
+          <span className="text-xs text-muted-foreground">{workspace.commandInFlight}…</span>
+        )}
+      </form>
+
+      <TerminalWidgetBand placement="belowEditor" widgets={widgetsBelowEditor} />
+    </div>
+  )
+}
diff --git a/web/components/sf/update-banner.tsx b/web/components/sf/update-banner.tsx
new file mode 100644
index 000000000..fb45d8084
--- /dev/null
+++ b/web/components/sf/update-banner.tsx
@@ -0,0 +1,179 @@
+"use client"
+
+import { useState, useEffect, useRef, useCallback } from "react"
+import { cn } from "@/lib/utils"
+import { authFetch } from "@/lib/auth"
+
+interface UpdateInfo {
+  currentVersion: string
+  latestVersion: string
+  updateAvailable: boolean
+  updateStatus: string
+  targetVersion?: string
+  error?: string
+}
+
+const POLL_INTERVAL = 3000
+
+export function UpdateBanner() {
+  const [info, setInfo] = useState<UpdateInfo | null>(null)
+  const [triggering, setTriggering] = useState(false)
+  const [dismissed, setDismissed] = useState(false)
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null)
+
+  const fetchStatus = useCallback(async () => {
+    try {
+      const res = await authFetch("/api/update")
+      if (!res.ok) return
+      const data: UpdateInfo = await res.json()
+      setInfo(data)
+    } catch {
+      // Network error — silently ignore, banner stays in last known state
+    }
+  }, [])
+
+  // Initial fetch on mount
+  useEffect(() => {
+    void fetchStatus()
+  }, [fetchStatus])
+
+  // Polling while update is running
+  useEffect(() => {
+    if (info?.updateStatus === "running") {
+      intervalRef.current = setInterval(() => void fetchStatus(), POLL_INTERVAL)
+    }
+    return () => {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current)
+        intervalRef.current = null
+      }
+    }
+  }, [info?.updateStatus, fetchStatus])
+
+  const handleUpdate = async () => {
+    setTriggering(true)
+    try {
+      const res = await authFetch("/api/update", { method: "POST" })
+      if (res.ok || res.status === 202) {
+        // Immediately poll to pick up the "running" status
+        await fetchStatus()
+      } else if (res.status === 409) {
+        // Already running — just refresh status
+        await fetchStatus()
+      }
+    } catch {
+      // Network error during trigger
+    } finally {
+      setTriggering(false)
+    }
+  }
+
+  // Don't render until we have data, or if no update is available and status is idle
+  if (!info) return null
+  if (!info.updateAvailable && info.updateStatus === "idle") return null
+  if (dismissed) return null
+
+  const isRunning = info.updateStatus === "running"
+  const isSuccess = info.updateStatus === "success"
+  const isError = info.updateStatus === "error"
+  const targetLabel = info.targetVersion ?? info.latestVersion
+
+  return (
+    <div
+      data-testid="update-banner"
+      className={cn(
+        "flex items-center gap-3 border-b px-4 py-2 text-xs",
+        isSuccess && "border-success/20 bg-success/10 text-success",
+        isError && "border-destructive/20 bg-destructive/10 text-destructive",
+        !isSuccess && !isError && "border-warning/20 bg-warning/10 text-warning",
+      )}
+    >
+      {isSuccess ? (
+        <span className="flex-1" data-testid="update-banner-message">
+          Update complete — restart GSD to use v{targetLabel}
+        </span>
+      ) : isError ? (
+        <>
+          <span className="flex-1" data-testid="update-banner-message">
+            Update failed{info.error ? `: ${info.error}` : ""}
+          </span>
+          <button
+            onClick={() => void handleUpdate()}
+            disabled={triggering}
+            className={cn(
+              "flex-shrink-0 rounded border border-destructive/30 bg-background px-2 py-0.5 text-xs font-medium text-destructive transition-colors hover:bg-destructive/10",
+              triggering && "cursor-not-allowed opacity-50",
+            )}
+            data-testid="update-banner-retry"
+          >
+            Retry
+          </button>
+        </>
+      ) : (
+        <>
+          <span className="flex-1" data-testid="update-banner-message">
+            {isRunning ? (
+              <span className="flex items-center gap-2">
+                <Spinner />
+                Updating to v{targetLabel}…
+              </span>
+            ) : (
+              <>
+                Update available: v{info.currentVersion} → v{info.latestVersion}
+              </>
+            )}
+          </span>
+          {!isRunning && (
+            <button
+              onClick={() => void handleUpdate()}
+              disabled={triggering}
+              className={cn(
+                "flex-shrink-0 rounded border border-warning/30 bg-background px-2 py-0.5 text-xs font-medium text-warning transition-colors hover:bg-warning/10",
+                triggering && "cursor-not-allowed opacity-50",
+              )}
+              data-testid="update-banner-action"
+            >
+              Update
+            </button>
+          )}
+        </>
+      )}
+      <button
+        onClick={() => setDismissed(true)}
+        aria-label="Dismiss update banner"
+        className="flex-shrink-0 rounded p-0.5 opacity-50 transition-opacity hover:opacity-100"
+        data-testid="update-banner-dismiss"
+      >
+        <svg xmlns="http://www.w3.org/2000/svg" className="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+          <line x1="18" y1="6" x2="6" y2="18" />
+          <line x1="6" y1="6" x2="18" y2="18" />
+        </svg>
+      </button>
+    </div>
+  )
+}
+
+function Spinner() {
+  return (
+    <svg
+      className="h-3 w-3 animate-spin"
+      xmlns="http://www.w3.org/2000/svg"
+      fill="none"
+      viewBox="0 0 24 24"
+    >
+      <circle
+        className="opacity-25"
+        cx="12"
+        cy="12"
+        r="10"
+        stroke="currentColor"
+        strokeWidth="4"
+      />
+      <path
+        className="opacity-75"
+        fill="currentColor"
+        d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
+      />
+    </svg>
+  )
+}
diff --git a/web/components/sf/visualizer-view.tsx b/web/components/sf/visualizer-view.tsx
new file mode 100644
index 000000000..f265f7500
--- /dev/null
+++ b/web/components/sf/visualizer-view.tsx
@@ -0,0 +1,1306 @@
+"use client"
+
+import { useEffect, useState, useCallback } from "react"
+import * as TabsPrimitive from "@radix-ui/react-tabs"
+import {
+  CheckCircle2,
+  Circle,
+  Play,
+  AlertTriangle,
+  Clock,
+  Download,
+  Activity,
+  GitBranch,
+  ArrowRight,
+  BarChart3,
+  FileText,
+  FileJson,
+  Loader2,
+  Layers,
+  Bot,
+  RotateCcw,
+  ChevronRight,
+  AlertCircle,
+} from "lucide-react"
+import { cn } from "@/lib/utils"
+import { useGSDWorkspaceState, buildProjectUrl } from "@/lib/sf-workspace-store"
+import type {
+  VisualizerData,
+  VisualizerSlice,
+  VisualizerTask,
+  ProjectTotals,
+} from "@/lib/visualizer-types"
+import {
+  formatCost,
+  formatTokenCount,
+  formatDuration,
+} from "@/lib/visualizer-types"
+import { authFetch } from "@/lib/auth"
+
+// ─── Design Tokens ────────────────────────────────────────────────────────────
+
+// Tab definitions — single source of truth
+const TABS = [
+  { value: "progress", label: "Progress",     Icon: Layers    },
+  { value: "deps",     label: "Dependencies", Icon: GitBranch },
+  { value: "metrics",  label: "Metrics",      Icon: BarChart3 },
+  { value: "timeline", label: "Timeline",     Icon: Clock     },
+  { value: "agent",    label: "Agent",        Icon: Bot       },
+  { value: "changes",  label: "Changes",      Icon: Activity  },
+  { value: "export",   label: "Export",       Icon: Download  },
+] as const
+
+type TabValue = (typeof TABS)[number]["value"]
+
+// ─── Shared Primitives ────────────────────────────────────────────────────────
+
+function statusIcon(status: "complete" | "active" | "pending" | "done") {
+  switch (status) {
+    case "complete":
+    case "done":
+      return <CheckCircle2 className="h-4 w-4 shrink-0 text-success" />
+    case "active":
+      return <Play className="h-4 w-4 shrink-0 text-info" />
+    case "pending":
+      return <Circle className="h-4 w-4 shrink-0 text-muted-foreground/50" />
+  }
+}
+
+function taskStatusIcon(task: VisualizerTask) {
+  if (task.done)   return statusIcon("done")
+  if (task.active) return statusIcon("active")
+  return statusIcon("pending")
+}
+
+function RiskBadge({ risk }: { risk: string }) {
+  const color =
+    risk === "high"
+      ? "bg-destructive/15 text-destructive border-destructive/25 ring-destructive/10"
+      : risk === "medium"
+        ? "bg-warning/15 text-warning border-warning/25 ring-warning/10"
+        : "bg-success/15 text-success border-success/25 ring-success/10"
+  return (
+    <span
+      className={cn(
+        "inline-flex items-center rounded border px-2 py-0.5 text-[11px] font-semibold uppercase tracking-widest",
+        color,
+      )}
+    >
+      {risk}
+    </span>
+  )
+}
+
+function formatRelative(isoDate: string): string {
+  const diff = Date.now() - new Date(isoDate).getTime()
+  if (diff < 60_000) return "just now"
+  const min = Math.floor(diff / 60_000)
+  if (min < 60) return `${min}m ago`
+  const hr = Math.floor(min / 60)
+  if (hr < 24) return `${hr}h ago`
+  return `${Math.floor(hr / 24)}d ago`
+}
+
+function formatTime(ts: number): string {
+  const d = new Date(ts)
+  return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`
+}
+
+/** Prominent section label with left accent bar */
+function SectionLabel({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="flex items-center gap-2.5">
+      <div className="h-3.5 w-0.5 rounded-full bg-foreground/25" />
+      <h3 className="text-xs font-semibold uppercase tracking-widest text-muted-foreground">
+        {children}
+      </h3>
+    </div>
+  )
+}
+
+/** Large empty state with icon */
+function EmptyState({ message, icon: Icon = AlertCircle }: { message: string; icon?: React.ComponentType<{ className?: string }> }) {
+  return (
+    <div className="flex flex-col items-center justify-center gap-4 rounded-xl border border-dashed border-border py-16 text-center">
+      <div className="rounded-full border border-border bg-muted/50 p-4">
+        <Icon className="h-6 w-6 text-muted-foreground" />
+      </div>
+      <p className="text-sm font-medium text-muted-foreground">{message}</p>
+    </div>
+  )
+}
+
+/** Metric card — key number with label */
+function StatCard({
+  label,
+  value,
+  sub,
+  accent,
+}: {
+  label: string
+  value: string
+  sub?: string
+  accent?: "sky" | "emerald" | "amber" | "default"
+}) {
+  const accentClasses = {
+    sky:     "from-info/8 border-info/20",
+    emerald: "from-success/8 border-success/20",
+    amber:   "from-warning/8 border-warning/20",
+    default: "from-transparent border-border",
+  }[accent ?? "default"]
+
+  return (
+    <div className={cn(
+      "relative overflow-hidden rounded-xl border bg-gradient-to-br to-transparent p-5",
+      accentClasses,
+    )}>
+      <p className="text-xs font-semibold uppercase tracking-widest text-muted-foreground">
+        {label}
+      </p>
+      <p className="mt-2 text-2xl font-bold tabular-nums leading-none tracking-tight">
+        {value}
+      </p>
+      {sub && (
+        <p className="mt-1.5 text-xs text-muted-foreground">{sub}</p>
+      )}
+    </div>
+  )
+}
+
+/** Horizontal progress bar with label */
+function ProgressBar({
+  value,
+  max,
+  color = "sky",
+  animated = false,
+}: {
+  value: number
+  max: number
+  color?: "sky" | "emerald" | "amber"
+  animated?: boolean
+}) {
+  const pct = max > 0 ? Math.max(1, (value / max) * 100) : 0
+  const barColor = { sky: "bg-info", emerald: "bg-success", amber: "bg-warning" }[color]
+  return (
+    <div className="h-2 w-full overflow-hidden rounded-full bg-muted">
+      <div
+        className={cn("h-full rounded-full transition-all duration-700", barColor, animated && "animate-pulse")}
+        style={{ width: `${pct}%` }}
+      />
+    </div>
+  )
+}
+
+// ─── Progress Tab ─────────────────────────────────────────────────────────────
+
+function ProgressTab({ data }: { data: VisualizerData }) {
+  if (data.milestones.length === 0) {
+    return <EmptyState message="No milestones defined yet." icon={Layers} />
+  }
+
+  const allSlices = data.milestones.flatMap((m) => m.slices)
+  const riskCounts = { low: 0, medium: 0, high: 0 }
+  for (const sl of allSlices) {
+    if (sl.risk === "high") riskCounts.high++
+    else if (sl.risk === "medium") riskCounts.medium++
+    else riskCounts.low++
+  }
+
+  return (
+    <div className="space-y-6">
+      {/* Risk Heatmap */}
+      {allSlices.length > 0 && (
+        <div className="rounded-xl border border-border bg-card p-6">
+          <SectionLabel>Risk Heatmap</SectionLabel>
+          <div className="mt-5 space-y-3">
+            {data.milestones
+              .filter((m) => m.slices.length > 0)
+              .map((ms) => (
+                <div key={ms.id} className="flex items-center gap-4">
+                  <span className="w-16 shrink-0 font-mono text-xs font-medium text-muted-foreground">
+                    {ms.id}
+                  </span>
+                  <div className="flex flex-wrap gap-1.5">
+                    {ms.slices.map((sl) => (
+                      <div
+                        key={sl.id}
+                        title={`${sl.id}: ${sl.title} (${sl.risk})`}
+                        className={cn(
+                          "h-6 w-6 rounded cursor-default transition-transform hover:scale-125",
+                          sl.risk === "high"
+                            ? "bg-destructive"
+                            : sl.risk === "medium"
+                              ? "bg-warning"
+                              : "bg-success",
+                        )}
+                      />
+                    ))}
+                  </div>
+                </div>
+              ))}
+          </div>
+          <div className="mt-5 flex items-center gap-5 text-xs text-muted-foreground">
+            <span className="flex items-center gap-2">
+              <span className="h-3 w-3 rounded-sm bg-success" />
+              Low ({riskCounts.low})
+            </span>
+            <span className="flex items-center gap-2">
+              <span className="h-3 w-3 rounded-sm bg-warning" />
+              Medium ({riskCounts.medium})
+            </span>
+            <span className="flex items-center gap-2">
+              <span className="h-3 w-3 rounded-sm bg-destructive" />
+              High ({riskCounts.high})
+            </span>
+          </div>
+        </div>
+      )}
+
+      {/* Milestone tree */}
+      <div className="space-y-4">
+        {data.milestones.map((ms) => (
+          <div key={ms.id} className="overflow-hidden rounded-xl border border-border bg-card">
+            {/* Milestone header */}
+            <div className="flex items-center justify-between border-b border-border bg-muted/50 px-5 py-4">
+              <div className="flex items-center gap-3">
+                {statusIcon(ms.status)}
+                <span className="font-mono text-xs font-semibold text-muted-foreground">{ms.id}</span>
+                <span className="text-sm font-semibold">{ms.title}</span>
+              </div>
+              <span
+                className={cn(
+                  "rounded-md px-2.5 py-1 text-xs font-semibold uppercase tracking-wider",
+                  ms.status === "complete"
+                    ? "bg-success/15 text-success"
+                    : ms.status === "active"
+                      ? "bg-info/15 text-info"
+                      : "bg-muted text-muted-foreground",
+                )}
+              >
+                {ms.status}
+              </span>
+            </div>
+
+            {ms.status === "pending" && ms.dependsOn.length > 0 && (
+              <div className="px-5 py-2.5 text-xs text-muted-foreground border-b border-border/50">
+                Depends on {ms.dependsOn.join(", ")}
+              </div>
+            )}
+
+            {/* Slices */}
+            {ms.slices.length > 0 && (
+              <div className="divide-y divide-border/50">
+                {ms.slices.map((sl) => {
+                  const doneTasks = sl.tasks.filter((t) => t.done).length
+                  const slStatus = sl.done ? "done" : sl.active ? "active" : "pending"
+                  return (
+                    <div key={sl.id} className="px-5 py-4">
+                      <div className="flex items-center gap-3">
+                        {statusIcon(slStatus)}
+                        <span className="font-mono text-xs font-medium text-muted-foreground">{sl.id}</span>
+                        <span className="min-w-0 flex-1 truncate text-sm font-medium">{sl.title}</span>
+                        <div className="flex shrink-0 items-center gap-2.5">
+                          {sl.depends.length > 0 && (
+                            <span className="text-xs text-muted-foreground">
+                              deps: {sl.depends.join(", ")}
+                            </span>
+                          )}
+                          {sl.tasks.length > 0 && (
+                            <span className="font-mono text-xs font-medium text-muted-foreground">
+                              {doneTasks}/{sl.tasks.length}
+                            </span>
+                          )}
+                          <RiskBadge risk={sl.risk} />
+                        </div>
+                      </div>
+
+                      {/* Tasks — only shown for active or partially-done slices */}
+                      {(sl.active || sl.tasks.some((t) => t.active)) && sl.tasks.length > 0 && (
+                        <div className="ml-7 mt-3 space-y-1">
+                          {sl.tasks.map((task) => (
+                            <div
+                              key={task.id}
+                              className={cn(
+                                "flex items-center gap-2.5 rounded-lg px-3 py-2 transition-colors",
+                                task.active
+                                  ? "bg-info/8 border border-info/20"
+                                  : "hover:bg-muted/50",
+                              )}
+                            >
+                              {taskStatusIcon(task)}
+                              <span className="font-mono text-xs font-medium text-muted-foreground">{task.id}</span>
+                              <span
+                                className={cn(
+                                  "text-sm",
+                                  task.done && "text-muted-foreground line-through",
+                                  task.active && "font-semibold text-info",
+                                  !task.done && !task.active && "text-muted-foreground",
+                                )}
+                              >
+                                {task.title}
+                              </span>
+                              {task.active && (
+                                <span className="ml-auto rounded-md bg-info/15 px-2 py-0.5 text-[11px] font-bold uppercase tracking-wider text-info">
+                                  running
+                                </span>
+                              )}
+                            </div>
+                          ))}
+                        </div>
+                      )}
+                    </div>
+                  )
+                })}
+              </div>
+            )}
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+// ─── Deps Tab ─────────────────────────────────────────────────────────────────
+
+function DepsTab({ data }: { data: VisualizerData }) {
+  const cp = data.criticalPath
+  const activeMs = data.milestones.find((m) => m.status === "active")
+  const milestoneDeps = data.milestones.filter((m) => m.dependsOn.length > 0)
+
+  return (
+    <div className="space-y-6">
+      {/* Milestone Dependencies */}
+      <div className="rounded-xl border border-border bg-card p-6">
+        <SectionLabel>Milestone Dependencies</SectionLabel>
+        <div className="mt-5">
+          {milestoneDeps.length === 0 ? (
+            <p className="text-sm text-muted-foreground">No milestone dependencies configured.</p>
+          ) : (
+            <div className="flex flex-col gap-3">
+              {milestoneDeps.flatMap((ms) =>
+                ms.dependsOn.map((dep) => (
+                  <div key={`${dep}-${ms.id}`} className="flex items-center gap-3">
+                    <span className="rounded-lg border border-info/25 bg-info/10 px-3 py-1.5 font-mono text-sm font-semibold text-info">
+                      {dep}
+                    </span>
+                    <ArrowRight className="h-4 w-4 text-muted-foreground" />
+                    <span className="rounded-lg border border-border bg-muted/50 px-3 py-1.5 font-mono text-sm font-medium">
+                      {ms.id}
+                    </span>
+                    <span className="text-sm text-muted-foreground">{ms.title}</span>
+                  </div>
+                )),
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+
+      {/* Slice Dependencies */}
+      <div className="rounded-xl border border-border bg-card p-6">
+        <SectionLabel>Slice Dependencies — Active Milestone</SectionLabel>
+        <div className="mt-5">
+          {!activeMs ? (
+            <p className="text-sm text-muted-foreground">No active milestone.</p>
+          ) : (
+            (() => {
+              const slDeps = activeMs.slices.filter((s) => s.depends.length > 0)
+              if (slDeps.length === 0)
+                return <p className="text-sm text-muted-foreground">No slice dependencies in {activeMs.id}.</p>
+              return (
+                <div className="flex flex-col gap-3">
+                  {slDeps.flatMap((sl) =>
+                    sl.depends.map((dep) => (
+                      <div key={`${dep}-${sl.id}`} className="flex items-center gap-3">
+                        <span className="rounded-lg border border-info/25 bg-info/10 px-3 py-1.5 font-mono text-sm font-semibold text-info">
+                          {dep}
+                        </span>
+                        <ArrowRight className="h-4 w-4 text-muted-foreground" />
+                        <span className="rounded-lg border border-border bg-muted/50 px-3 py-1.5 font-mono text-sm font-medium">
+                          {sl.id}
+                        </span>
+                        <span className="text-sm text-muted-foreground">{sl.title}</span>
+                      </div>
+                    )),
+                  )}
+                </div>
+              )
+            })()
+          )}
+        </div>
+      </div>
+
+      {/* Critical Path */}
+      <div className="rounded-xl border border-border bg-card p-6">
+        <SectionLabel>Critical Path</SectionLabel>
+        <div className="mt-5">
+          {cp.milestonePath.length === 0 ? (
+            <p className="text-sm text-muted-foreground">No critical path data.</p>
+          ) : (
+            <div className="space-y-7">
+              {/* Milestone chain */}
+              <div>
+                <p className="mb-3 text-xs font-semibold uppercase tracking-widest text-muted-foreground">
+                  Milestone Chain
+                </p>
+                <div className="flex flex-wrap items-center gap-2">
+                  {cp.milestonePath.map((id, i) => (
+                    <span key={id} className="flex items-center gap-2">
+                      <span className="rounded-lg border border-destructive/30 bg-destructive/10 px-3 py-1.5 font-mono text-sm font-bold text-destructive">
+                        {id}
+                      </span>
+                      {i < cp.milestonePath.length - 1 && (
+                        <ChevronRight className="h-4 w-4 text-muted-foreground" />
+                      )}
+                    </span>
+                  ))}
+                </div>
+              </div>
+
+              {/* Milestone slack */}
+              {Object.keys(cp.milestoneSlack).length > 0 && (
+                <div>
+                  <p className="mb-3 text-xs font-semibold uppercase tracking-widest text-muted-foreground">
+                    Milestone Slack
+                  </p>
+                  <div className="flex flex-col gap-2">
+                    {data.milestones
+                      .filter((m) => !cp.milestonePath.includes(m.id))
+                      .map((m) => (
+                        <div key={m.id} className="flex items-center gap-4 rounded-lg bg-muted/50 px-4 py-2.5">
+                          <span className="w-16 font-mono text-sm font-semibold">{m.id}</span>
+                          <span className="text-sm text-muted-foreground">{m.title}</span>
+                          <span className="ml-auto font-mono text-xs text-muted-foreground">
+                            slack: {cp.milestoneSlack[m.id] ?? 0}
+                          </span>
+                        </div>
+                      ))}
+                  </div>
+                </div>
+              )}
+
+              {/* Slice critical path */}
+              {cp.slicePath.length > 0 && (
+                <div>
+                  <p className="mb-3 text-xs font-semibold uppercase tracking-widest text-muted-foreground">
+                    Slice Critical Path
+                  </p>
+                  <div className="flex flex-wrap items-center gap-2">
+                    {cp.slicePath.map((id, i) => (
+                      <span key={id} className="flex items-center gap-2">
+                        <span className="rounded-lg border border-warning/30 bg-warning/10 px-3 py-1.5 font-mono text-sm font-semibold text-warning">
+                          {id}
+                        </span>
+                        {i < cp.slicePath.length - 1 && (
+                          <ChevronRight className="h-4 w-4 text-muted-foreground" />
+                        )}
+                      </span>
+                    ))}
+                  </div>
+                  {/* Bottleneck warnings */}
+                  {activeMs && (
+                    <div className="mt-3 space-y-2">
+                      {cp.slicePath
+                        .map((sid) => activeMs.slices.find((s) => s.id === sid))
+                        .filter(
+                          (sl): sl is VisualizerSlice => sl != null && !sl.done && !sl.active,
+                        )
+                        .map((sl) => (
+                          <div
+                            key={sl.id}
+                            className="flex items-center gap-2.5 rounded-lg border border-warning/20 bg-warning/8 px-4 py-2.5 text-sm text-warning"
+                          >
+                            <AlertTriangle className="h-4 w-4 shrink-0" />
+                            <span className="font-mono font-semibold">{sl.id}</span>
+                            <span>is on the critical path but not yet started</span>
+                          </div>
+                        ))}
+                    </div>
+                  )}
+                </div>
+              )}
+
+              {/* Slice slack */}
+              {Object.keys(cp.sliceSlack).length > 0 && (
+                <div>
+                  <p className="mb-3 text-xs font-semibold uppercase tracking-widest text-muted-foreground">
+                    Slice Slack
+                  </p>
+                  <div className="flex flex-wrap gap-2">
+                    {Object.entries(cp.sliceSlack).map(([id, slack]) => (
+                      <span
+                        key={id}
+                        className="rounded-lg border border-border bg-muted/50 px-3 py-1.5 font-mono text-xs text-muted-foreground"
+                      >
+                        {id}: {slack}
+                      </span>
+                    ))}
+                  </div>
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// ─── Metrics Tab ──────────────────────────────────────────────────────────────
+
+function MetricsTab({ data }: { data: VisualizerData }) {
+  if (!data.totals) {
+    return <EmptyState message="No metrics data available." icon={BarChart3} />
+  }
+
+  const totals = data.totals
+
+  return (
+    <div className="space-y-6">
+      {/* Summary stats */}
+      <div className="grid grid-cols-2 gap-4 sm:grid-cols-4">
+        <StatCard label="Execution Units" value={String(totals.units)} accent="default" />
+        <StatCard label="Total Cost"    value={formatCost(totals.cost)}          accent="emerald" />
+        <StatCard label="Duration"      value={formatDuration(totals.duration)}  accent="sky" />
+        <StatCard
+          label="Total Tokens"
+          value={formatTokenCount(totals.tokens.total)}
+          sub={`${formatTokenCount(totals.tokens.input)} in · ${formatTokenCount(totals.tokens.output)} out`}
+          accent="amber"
+        />
+      </div>
+
+      {/* By Phase */}
+      {data.byPhase.length > 0 && (
+        <div className="rounded-xl border border-border bg-card p-6">
+          <SectionLabel>Cost by Phase</SectionLabel>
+          <div className="mt-5 space-y-5">
+            {data.byPhase.map((phase) => {
+              const pct = totals.cost > 0 ? (phase.cost / totals.cost) * 100 : 0
+              return (
+                <div key={phase.phase}>
+                  <div className="mb-2 flex items-center justify-between">
+                    <span className="text-sm font-semibold">{phase.phase}</span>
+                    <div className="flex items-center gap-4 text-xs text-muted-foreground">
+                      <span className="font-mono font-medium text-foreground">{formatCost(phase.cost)}</span>
+                      <span>{pct.toFixed(1)}%</span>
+                      <span>{formatTokenCount(phase.tokens.total)} tok</span>
+                      <span>{phase.units} units</span>
+                    </div>
+                  </div>
+                  <ProgressBar value={pct} max={100} color="sky" />
+                </div>
+              )
+            })}
+          </div>
+        </div>
+      )}
+
+      {/* By Model */}
+      {data.byModel.length > 0 && (
+        <div className="rounded-xl border border-border bg-card p-6">
+          <SectionLabel>Cost by Model</SectionLabel>
+          <div className="mt-5 space-y-5">
+            {data.byModel.map((model) => {
+              const pct = totals.cost > 0 ? (model.cost / totals.cost) * 100 : 0
+              return (
+                <div key={model.model}>
+                  <div className="mb-2 flex items-center justify-between">
+                    <span className="font-mono text-sm font-medium">{model.model}</span>
+                    <div className="flex items-center gap-4 text-xs text-muted-foreground">
+                      <span className="font-mono font-medium text-foreground">{formatCost(model.cost)}</span>
+                      <span>{pct.toFixed(1)}%</span>
+                      <span>{formatTokenCount(model.tokens.total)} tok</span>
+                      <span>{model.units} units</span>
+                    </div>
+                  </div>
+                  <ProgressBar value={pct} max={100} color="emerald" />
+                </div>
+              )
+            })}
+          </div>
+        </div>
+      )}
+
+      {/* By Slice */}
+      {data.bySlice.length > 0 && (
+        <div className="rounded-xl border border-border bg-card p-6">
+          <SectionLabel>Cost by Slice</SectionLabel>
+          <div className="mt-5 overflow-x-auto">
+            <table className="w-full text-sm">
+              <thead>
+                <tr className="border-b border-border text-left text-xs font-semibold uppercase tracking-widest text-muted-foreground">
+                  <th className="pb-3 pr-5">Slice</th>
+                  <th className="pb-3 pr-5 text-right">Units</th>
+                  <th className="pb-3 pr-5 text-right">Cost</th>
+                  <th className="pb-3 pr-5 text-right">Duration</th>
+                  <th className="pb-3 text-right">Tokens</th>
+                </tr>
+              </thead>
+              <tbody className="divide-y divide-border/50">
+                {data.bySlice.map((sl) => (
+                  <tr key={sl.sliceId} className="transition-colors hover:bg-muted/50">
+                    <td className="py-3 pr-5 font-mono text-xs font-semibold">{sl.sliceId}</td>
+                    <td className="py-3 pr-5 text-right tabular-nums text-muted-foreground">{sl.units}</td>
+                    <td className="py-3 pr-5 text-right tabular-nums font-medium">{formatCost(sl.cost)}</td>
+                    <td className="py-3 pr-5 text-right tabular-nums text-muted-foreground">{formatDuration(sl.duration)}</td>
+                    <td className="py-3 text-right tabular-nums text-muted-foreground">{formatTokenCount(sl.tokens.total)}</td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        </div>
+      )}
+
+      {/* Projections */}
+      {data.bySlice.length >= 2 && <ProjectionsSection data={data} totals={totals} />}
+    </div>
+  )
+}
+
+function ProjectionsSection({
+  data,
+  totals,
+}: {
+  data: VisualizerData
+  totals: ProjectTotals
+}) {
+  const sliceLevelEntries = data.bySlice.filter((s) => s.sliceId.includes("/"))
+  if (sliceLevelEntries.length < 2) return null
+
+  const totalSliceCost = sliceLevelEntries.reduce((sum, s) => sum + s.cost, 0)
+  const avgCostPerSlice = totalSliceCost / sliceLevelEntries.length
+  const projectedRemaining = avgCostPerSlice * data.remainingSliceCount
+  const projectedTotal = totals.cost + projectedRemaining
+  const burnRate = totals.duration > 0 ? totals.cost / (totals.duration / 3_600_000) : 0
+
+  return (
+    <div className="rounded-xl border border-border bg-card p-6">
+      <SectionLabel>Projections</SectionLabel>
+      <div className="mt-5 grid grid-cols-2 gap-4 sm:grid-cols-4">
+        <StatCard label="Avg / Slice"        value={formatCost(avgCostPerSlice)} />
+        <StatCard
+          label="Projected Remaining"
+          value={formatCost(projectedRemaining)}
+          sub={`${data.remainingSliceCount} slices left`}
+        />
+        <StatCard label="Projected Total" value={formatCost(projectedTotal)} />
+        {burnRate > 0 && (
+          <StatCard label="Burn Rate" value={`${formatCost(burnRate)}/hr`} />
+        )}
+      </div>
+      {projectedTotal > 2 * totals.cost && data.remainingSliceCount > 0 && (
+        <div className="mt-4 flex items-center gap-2.5 rounded-lg border border-warning/20 bg-warning/8 px-4 py-3 text-sm text-warning">
+          <AlertTriangle className="h-4 w-4 shrink-0" />
+          Projected total {formatCost(projectedTotal)} exceeds 2× current spend
+        </div>
+      )}
+    </div>
+  )
+}
+
+// ─── Timeline Tab ─────────────────────────────────────────────────────────────
+
+function TimelineTab({ data }: { data: VisualizerData }) {
+  const sorted = [...data.units].sort((a, b) => a.startedAt - b.startedAt)
+  const recent = sorted.slice(-30)
+  const hasRunningUnit = recent.some((u) => !u.finishedAt || u.finishedAt === 0)
+  const [runningNow, setRunningNow] = useState(() => Date.now())
+
+  useEffect(() => {
+    if (!hasRunningUnit) return
+    const interval = window.setInterval(() => {
+      setRunningNow(Date.now())
+    }, 1000)
+    return () => window.clearInterval(interval)
+  }, [hasRunningUnit])
+
+  const referenceNow = hasRunningUnit ? runningNow : 0
+  const durationForUnit = useCallback(
+    (unit: VisualizerData["units"][number]) => (unit.finishedAt || referenceNow) - unit.startedAt,
+    [referenceNow],
+  )
+
+  if (data.units.length === 0) {
+    return <EmptyState message="No execution history yet." icon={Clock} />
+  }
+
+  const maxDuration = Math.max(...recent.map(durationForUnit), 1)
+
+  return (
+    <div className="space-y-4">
+      <div className="overflow-hidden rounded-xl border border-border bg-card">
+        {/* Header */}
+        <div className="border-b border-border bg-muted/50 px-6 py-4">
+          <SectionLabel>Execution Timeline</SectionLabel>
+          <p className="mt-1.5 text-xs text-muted-foreground">
+            Showing {recent.length} of {data.units.length} units — most recent first
+          </p>
+        </div>
+
+        {/* Column headers */}
+        <div className="grid grid-cols-[3.5rem_1.5rem_5rem_8rem_1fr_4.5rem_5rem] items-center gap-3 border-b border-border/50 px-6 py-2.5 text-xs font-semibold uppercase tracking-widest text-muted-foreground">
+          <span>Time</span>
+          <span />
+          <span>Type</span>
+          <span>ID</span>
+          <span>Duration</span>
+          <span className="text-right">Time</span>
+          <span className="text-right">Cost</span>
+        </div>
+
+        <div className="divide-y divide-border/40">
+          {[...recent].reverse().map((unit, i) => {
+            const duration = durationForUnit(unit)
+            const pct = (duration / maxDuration) * 100
+            const isRunning = !unit.finishedAt || unit.finishedAt === 0
+            return (
+              <div
+                key={`${unit.id}-${unit.startedAt}-${i}`}
+                className="grid grid-cols-[3.5rem_1.5rem_5rem_8rem_1fr_4.5rem_5rem] items-center gap-3 px-6 py-3.5 transition-colors hover:bg-muted/50"
+              >
+                <span className="font-mono text-xs text-muted-foreground">
+                  {formatTime(unit.startedAt)}
+                </span>
+                {isRunning ? (
+                  <Play className="h-3.5 w-3.5 shrink-0 text-info" />
+                ) : (
+                  <CheckCircle2 className="h-3.5 w-3.5 shrink-0 text-success" />
+                )}
+                <span className="truncate text-xs font-medium">{unit.type}</span>
+                <span className="truncate font-mono text-xs text-muted-foreground">{unit.id}</span>
+                <div className="hidden sm:block">
+                  <ProgressBar
+                    value={pct}
+                    max={100}
+                    color="sky"
+                    animated={isRunning}
+                  />
+                </div>
+                <span className="text-right font-mono text-xs tabular-nums text-muted-foreground">
+                  {formatDuration(duration)}
+                </span>
+                <span className="text-right font-mono text-xs tabular-nums font-medium">
+                  {formatCost(unit.cost)}
+                </span>
+              </div>
+            )
+          })}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// ─── Agent Tab ────────────────────────────────────────────────────────────────
+
+function AgentTab({ data }: { data: VisualizerData }) {
+  const activity = data.agentActivity
+
+  if (!activity) {
+    return <EmptyState message="No agent activity data available." icon={Bot} />
+  }
+
+  const completed = activity.completedUnits
+  const total = Math.max(completed, activity.totalSlices)
+  const pct = total > 0 ? Math.min(100, Math.round((completed / total) * 100)) : 0
+
+  return (
+    <div className="space-y-6">
+      {/* Status card */}
+      <div className="rounded-xl border border-border bg-card p-6">
+        <div className="flex items-center justify-between">
+          <div className="flex items-center gap-4">
+            <div className={cn(
+              "relative flex h-10 w-10 items-center justify-center rounded-full",
+              activity.active
+                ? "bg-success/15"
+                : "bg-muted",
+            )}>
+              {activity.active && (
+                <div className="absolute inset-0 animate-ping rounded-full bg-success/20" />
+              )}
+              <div className={cn(
+                "h-3 w-3 rounded-full",
+                activity.active ? "bg-success" : "bg-muted-foreground/30",
+              )} />
+            </div>
+            <div>
+              <p className="text-xl font-bold">{activity.active ? "Active" : "Idle"}</p>
+              <p className="text-sm text-muted-foreground">
+                {activity.active ? "Agent is running" : "Waiting for next task"}
+              </p>
+            </div>
+          </div>
+          {activity.active && (
+            <div className="text-right">
+              <p className="font-mono text-lg font-bold">{formatDuration(activity.elapsed)}</p>
+              <p className="text-xs text-muted-foreground">elapsed</p>
+            </div>
+          )}
+        </div>
+
+        {activity.currentUnit && (
+          <div className="mt-5 flex items-center gap-3 rounded-xl border border-info/20 bg-info/8 px-5 py-3.5">
+            <Play className="h-4 w-4 shrink-0 text-info" />
+            <div>
+              <p className="text-xs text-muted-foreground">Currently executing</p>
+              <p className="mt-0.5 font-mono text-sm font-semibold text-info">
+                {activity.currentUnit.type} — {activity.currentUnit.id}
+              </p>
+            </div>
+          </div>
+        )}
+      </div>
+
+      {/* Completion progress */}
+      {total > 0 && (
+        <div className="rounded-xl border border-border bg-card p-6">
+          <div className="mb-4 flex items-center justify-between">
+            <SectionLabel>Completion Progress</SectionLabel>
+            <span className="font-mono text-sm text-muted-foreground">
+              {completed} / {total} slices
+            </span>
+          </div>
+          <ProgressBar value={completed} max={total} color="emerald" />
+          <div className="mt-3 flex items-center justify-between text-xs text-muted-foreground">
+            <span>{pct}% complete</span>
+            <span>{total - completed} remaining</span>
+          </div>
+        </div>
+      )}
+
+      {/* Stats grid */}
+      <div className="grid grid-cols-2 gap-4 sm:grid-cols-4">
+        <StatCard
+          label="Completion Rate"
+          value={activity.completionRate > 0 ? `${activity.completionRate.toFixed(1)}/hr` : "—"}
+          accent="sky"
+        />
+        <StatCard label="Session Cost"   value={formatCost(activity.sessionCost)}               accent="emerald" />
+        <StatCard label="Session Tokens" value={formatTokenCount(activity.sessionTokens)}        accent="amber" />
+        <StatCard label="Completed"      value={String(activity.completedUnits)}                 />
+      </div>
+
+      {/* Recent units */}
+      {data.units.filter((u) => u.finishedAt > 0).length > 0 && (
+        <div className="overflow-hidden rounded-xl border border-border bg-card">
+          <div className="border-b border-border bg-muted/50 px-6 py-4">
+            <SectionLabel>Recent Completed Units</SectionLabel>
+          </div>
+          <div className="divide-y divide-border/40">
+            {data.units
+              .filter((u) => u.finishedAt > 0)
+              .slice(-5)
+              .reverse()
+              .map((u, i) => (
+                <div key={`${u.id}-${i}`} className="flex items-center gap-4 px-6 py-4 transition-colors hover:bg-muted/50">
+                  <span className="w-12 font-mono text-xs text-muted-foreground">{formatTime(u.startedAt)}</span>
+                  <CheckCircle2 className="h-4 w-4 shrink-0 text-success" />
+                  <span className="flex-1 truncate text-sm font-medium">{u.type}</span>
+                  <span className="font-mono text-xs text-muted-foreground">{u.id}</span>
+                  <span className="font-mono text-xs tabular-nums text-muted-foreground">{formatDuration(u.finishedAt - u.startedAt)}</span>
+                  <span className="font-mono text-xs tabular-nums font-semibold">{formatCost(u.cost)}</span>
+                </div>
+              ))}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+// ─── Changes Tab ──────────────────────────────────────────────────────────────
+
+function ChangesTab({ data }: { data: VisualizerData }) {
+  const entries = data.changelog.entries
+
+  if (entries.length === 0) {
+    return <EmptyState message="No completed slices yet." icon={Activity} />
+  }
+
+  const sorted = [...entries].reverse()
+
+  return (
+    <div className="space-y-4">
+      {sorted.map((entry, i) => (
+        <div key={`${entry.milestoneId}-${entry.sliceId}-${i}`} className="overflow-hidden rounded-xl border border-border bg-card">
+          {/* Header */}
+          <div className="flex items-center justify-between border-b border-border bg-muted/50 px-6 py-4">
+            <div className="flex items-center gap-3">
+              <CheckCircle2 className="h-4 w-4 shrink-0 text-success" />
+              <span className="font-mono text-xs font-bold text-success">
+                {entry.milestoneId}/{entry.sliceId}
+              </span>
+              <span className="text-sm font-semibold">{entry.title}</span>
+            </div>
+            {entry.completedAt && (
+              <span className="text-xs text-muted-foreground">{formatRelative(entry.completedAt)}</span>
+            )}
+          </div>
+
+          <div className="px-6 py-5 space-y-5">
+            {/* One-liner */}
+            {entry.oneLiner && (
+              <p className="text-sm text-muted-foreground italic leading-relaxed border-l-2 border-muted pl-4">
+                &ldquo;{entry.oneLiner}&rdquo;
+              </p>
+            )}
+
+            {/* Files modified */}
+            {entry.filesModified.length > 0 && (
+              <div>
+                <p className="mb-3 text-xs font-semibold uppercase tracking-widest text-muted-foreground">
+                  Files Modified
+                </p>
+                <div className="space-y-2">
+                  {entry.filesModified.map((f, fi) => (
+                    <div key={fi} className="flex items-start gap-3 rounded-lg bg-muted/50 px-4 py-2.5">
+                      <CheckCircle2 className="mt-0.5 h-3.5 w-3.5 shrink-0 text-success/70" />
+                      <span className="font-mono text-xs font-medium text-muted-foreground">{f.path}</span>
+                      {f.description && (
+                        <span className="ml-1 text-xs text-muted-foreground">— {f.description}</span>
+                      )}
+                    </div>
+                  ))}
+                </div>
+              </div>
+            )}
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+// ─── Export Tab ───────────────────────────────────────────────────────────────
+
+function ExportTab({ data }: { data: VisualizerData }) {
+  const downloadBlob = useCallback(
+    (content: string, filename: string, mimeType: string) => {
+      const blob = new Blob([content], { type: mimeType })
+      const url = URL.createObjectURL(blob)
+      const a = document.createElement("a")
+      a.href = url
+      a.download = filename
+      document.body.appendChild(a)
+      a.click()
+      document.body.removeChild(a)
+      URL.revokeObjectURL(url)
+    },
+    [],
+  )
+
+  const generateMarkdown = useCallback(() => {
+    const lines: string[] = []
+    lines.push("# GSD Workflow Report")
+    lines.push("")
+    lines.push(`Generated: ${new Date().toISOString()}`)
+    lines.push(`Phase: ${data.phase}`)
+    lines.push("")
+    lines.push("## Milestones")
+    lines.push("")
+    for (const ms of data.milestones) {
+      const icon = ms.status === "complete" ? "✓" : ms.status === "active" ? "▸" : "○"
+      lines.push(`### ${icon} ${ms.id}: ${ms.title} (${ms.status})`)
+      if (ms.dependsOn.length > 0) lines.push(`Depends on: ${ms.dependsOn.join(", ")}`)
+      lines.push("")
+      for (const sl of ms.slices) {
+        const slIcon = sl.done ? "✓" : sl.active ? "▸" : "○"
+        lines.push(`- ${slIcon} **${sl.id}**: ${sl.title} [risk: ${sl.risk}]`)
+        for (const t of sl.tasks) {
+          const tIcon = t.done ? "✓" : t.active ? "▸" : "○"
+          lines.push(`  - ${tIcon} ${t.id}: ${t.title}`)
+        }
+      }
+      lines.push("")
+    }
+    if (data.totals) {
+      lines.push("## Metrics Summary")
+      lines.push("")
+      lines.push(`| Metric | Value |`)
+      lines.push(`|--------|-------|`)
+      lines.push(`| Units | ${data.totals.units} |`)
+      lines.push(`| Total Cost | ${formatCost(data.totals.cost)} |`)
+      lines.push(`| Duration | ${formatDuration(data.totals.duration)} |`)
+      lines.push(`| Tokens | ${formatTokenCount(data.totals.tokens.total)} |`)
+      lines.push("")
+    }
+    if (data.criticalPath.milestonePath.length > 0) {
+      lines.push("## Critical Path")
+      lines.push("")
+      lines.push(`Milestone: ${data.criticalPath.milestonePath.join(" → ")}`)
+      if (data.criticalPath.slicePath.length > 0) {
+        lines.push(`Slice: ${data.criticalPath.slicePath.join(" → ")}`)
+      }
+      lines.push("")
+    }
+    if (data.changelog.entries.length > 0) {
+      lines.push("## Changelog")
+      lines.push("")
+      for (const entry of data.changelog.entries) {
+        lines.push(`### ${entry.milestoneId}/${entry.sliceId}: ${entry.title}`)
+        if (entry.oneLiner) lines.push(`> ${entry.oneLiner}`)
+        if (entry.filesModified.length > 0) {
+          lines.push("Files:")
+          for (const f of entry.filesModified) lines.push(`- \`${f.path}\` — ${f.description}`)
+        }
+        if (entry.completedAt) lines.push(`Completed: ${entry.completedAt}`)
+        lines.push("")
+      }
+    }
+    return lines.join("\n")
+  }, [data])
+
+  const handleMarkdown = () => downloadBlob(generateMarkdown(), "gsd-report.md", "text/markdown")
+  const handleJSON = () => downloadBlob(JSON.stringify(data, null, 2), "gsd-report.json", "application/json")
+
+  return (
+    <div className="space-y-6">
+      <div className="rounded-xl border border-border bg-card p-6">
+        <SectionLabel>Export Project Data</SectionLabel>
+        <p className="mt-3 text-sm leading-relaxed text-muted-foreground">
+          Download the current visualizer data as a structured report. Markdown includes
+          milestones, metrics, critical path, and changelog in a readable format.
+          JSON contains the full raw data payload.
+        </p>
+
+        <div className="mt-7 grid gap-4 sm:grid-cols-2">
+          <button
+            onClick={handleMarkdown}
+            className="group flex items-center gap-5 rounded-xl border border-border bg-muted/50 p-5 text-left transition-all hover:border-info/40 hover:bg-info/5"
+          >
+            <div className="rounded-xl border border-info/20 bg-info/10 p-4 transition-colors group-hover:bg-info/15">
+              <FileText className="h-6 w-6 text-info" />
+            </div>
+            <div className="flex-1">
+              <p className="text-sm font-semibold transition-colors group-hover:text-info">Download Markdown</p>
+              <p className="mt-1 text-xs text-muted-foreground">Human-readable report with tables and structure</p>
+            </div>
+            <Download className="h-4 w-4 shrink-0 text-muted-foreground/0 transition-all group-hover:text-info/70" />
+          </button>
+
+          <button
+            onClick={handleJSON}
+            className="group flex items-center gap-5 rounded-xl border border-border bg-muted/50 p-5 text-left transition-all hover:border-success/40 hover:bg-success/5"
+          >
+            <div className="rounded-xl border border-success/20 bg-success/10 p-4 transition-colors group-hover:bg-success/15">
+              <FileJson className="h-6 w-6 text-success" />
+            </div>
+            <div className="flex-1">
+              <p className="text-sm font-semibold transition-colors group-hover:text-success">Download JSON</p>
+              <p className="mt-1 text-xs text-muted-foreground">Full raw data payload for tooling</p>
+            </div>
+            <Download className="h-4 w-4 shrink-0 text-muted-foreground/0 transition-all group-hover:text-success/70" />
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// ─── Custom Tab Bar ────────────────────────────────────────────────────────────
+
+function VisualizerTabs({
+  defaultValue,
+  children,
+}: {
+  defaultValue: TabValue
+  children: React.ReactNode
+}) {
+  return (
+    <TabsPrimitive.Root defaultValue={defaultValue} className="flex h-full flex-col overflow-hidden">
+      {children}
+    </TabsPrimitive.Root>
+  )
+}
+
+function VisualizerTabList() {
+  return (
+    <TabsPrimitive.List className="flex shrink-0 justify-center border-b border-border bg-background px-6">
+      {TABS.map(({ value, label, Icon }) => (
+        <TabsPrimitive.Trigger
+          key={value}
+          value={value}
+          className={cn(
+            // Base
+            "group relative flex items-center gap-2 px-4 py-3.5 text-sm font-medium outline-none",
+            "text-muted-foreground transition-colors duration-150",
+            // Hover
+            "hover:text-foreground",
+            // Active (selected) — text
+            "data-[state=active]:text-foreground",
+            // Focus visible
+            "focus-visible:text-foreground",
+            // Disabled
+            "disabled:pointer-events-none disabled:opacity-40",
+          )}
+        >
+          {/* Active bottom border indicator */}
+          <span
+            className={cn(
+              "pointer-events-none absolute bottom-0 left-0 right-0 h-0.5 rounded-t-full",
+              "bg-foreground opacity-0 transition-opacity duration-150",
+              "group-data-[state=active]:opacity-100",
+            )}
+          />
+
+          {/* Hover background */}
+          <span className="absolute inset-x-0 inset-y-1.5 rounded-lg bg-muted/0 transition-colors duration-150 group-hover:bg-muted group-data-[state=active]:bg-transparent" />
+
+          {/* Icon */}
+          <Icon className="relative h-4 w-4 shrink-0 transition-colors duration-150 text-muted-foreground group-hover:text-muted-foreground group-data-[state=active]:text-foreground" />
+
+          {/* Label */}
+          <span className="relative">{label}</span>
+        </TabsPrimitive.Trigger>
+      ))}
+    </TabsPrimitive.List>
+  )
+}
+
+// ─── Main Component ───────────────────────────────────────────────────────────
+
+export function VisualizerView() {
+  const workspace = useGSDWorkspaceState()
+  const projectCwd = workspace.boot?.project.cwd
+  const [data, setData] = useState<VisualizerData | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  const fetchData = useCallback(async () => {
+    try {
+      const resp = await authFetch(buildProjectUrl("/api/visualizer", projectCwd))
+      if (!resp.ok) {
+        const body = await resp.json().catch(() => ({ error: "Unknown error" }))
+        throw new Error(body.error || `HTTP ${resp.status}`)
+      }
+      const json: VisualizerData = await resp.json()
+      setData(json)
+      setError(null)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to fetch visualizer data")
+    } finally {
+      setLoading(false)
+    }
+  }, [projectCwd])
+
+  useEffect(() => {
+    fetchData()
+    const interval = setInterval(fetchData, 10_000)
+    return () => clearInterval(interval)
+  }, [fetchData])
+
+  // Loading
+  if (loading && !data) {
+    return (
+      <div className="flex h-full items-center justify-center">
+        <div className="flex flex-col items-center gap-4">
+          <Loader2 className="h-7 w-7 animate-spin text-muted-foreground" />
+          <p className="text-sm text-muted-foreground">Loading visualizer data…</p>
+        </div>
+      </div>
+    )
+  }
+
+  // Error (no cached data)
+  if (error && !data) {
+    return (
+      <div className="flex h-full items-center justify-center">
+        <div className="flex flex-col items-center gap-4 text-center">
+          <div className="rounded-full border border-warning/20 bg-warning/10 p-4">
+            <AlertTriangle className="h-6 w-6 text-warning" />
+          </div>
+          <div>
+            <p className="text-sm font-semibold">Failed to load visualizer</p>
+            <p className="mt-1.5 max-w-sm text-xs text-muted-foreground">{error}</p>
+          </div>
+          <button
+            onClick={fetchData}
+            className="mt-1 inline-flex items-center gap-2 rounded-lg border border-border bg-card px-4 py-2 text-sm font-medium transition-colors hover:bg-accent"
+          >
+            <RotateCcw className="h-3.5 w-3.5" />
+            Retry
+          </button>
+        </div>
+      </div>
+    )
+  }
+
+  if (!data) return null
+
+  return (
+    <div className="flex h-full flex-col overflow-hidden">
+      {/* Header */}
+      <div className="flex shrink-0 items-center justify-between border-b border-border px-7 py-5">
+        <div>
+          <h1 className="text-xl font-bold tracking-tight">Workflow Visualizer</h1>
+          <div className="mt-1.5 flex items-center gap-3 text-sm text-muted-foreground">
+            <span>
+              Phase:{" "}
+              <span className={cn(
+                "inline-flex items-center rounded-md px-2 py-0.5 text-xs font-semibold uppercase tracking-wider",
+                data.phase === "complete"
+                  ? "bg-success/15 text-success"
+                  : data.phase === "active" || data.phase === "running"
+                    ? "bg-info/15 text-info"
+                    : "bg-muted text-muted-foreground",
+              )}>
+                {data.phase}
+              </span>
+            </span>
+            {data.remainingSliceCount > 0 && (
+              <>
+                <span className="text-border">·</span>
+                <span>
+                  {data.remainingSliceCount} slice{data.remainingSliceCount !== 1 ? "s" : ""} remaining
+                </span>
+              </>
+            )}
+            {error && (
+              <>
+                <span className="text-border">·</span>
+                <span className="flex items-center gap-1 text-warning">
+                  <AlertTriangle className="h-3 w-3" />
+                  Stale — {error}
+                </span>
+              </>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {/* Tabs */}
+      <VisualizerTabs defaultValue="progress">
+        <VisualizerTabList />
+
+        <div className="flex-1 overflow-y-auto">
+          <div className="mx-auto max-w-5xl px-7 py-7">
+            <TabsPrimitive.Content value="progress" className="outline-none">
+              <ProgressTab data={data} />
+            </TabsPrimitive.Content>
+            <TabsPrimitive.Content value="deps" className="outline-none">
+              <DepsTab data={data} />
+            </TabsPrimitive.Content>
+            <TabsPrimitive.Content value="metrics" className="outline-none">
+              <MetricsTab data={data} />
+            </TabsPrimitive.Content>
+            <TabsPrimitive.Content value="timeline" className="outline-none">
+              <TimelineTab data={data} />
+            </TabsPrimitive.Content>
+            <TabsPrimitive.Content value="agent" className="outline-none">
+              <AgentTab data={data} />
+            </TabsPrimitive.Content>
+            <TabsPrimitive.Content value="changes" className="outline-none">
+              <ChangesTab data={data} />
+            </TabsPrimitive.Content>
+            <TabsPrimitive.Content value="export" className="outline-none">
+              <ExportTab data={data} />
+            </TabsPrimitive.Content>
+          </div>
+        </div>
+      </VisualizerTabs>
+    </div>
+  )
+}
diff --git a/web/lib/sf-workspace-store.tsx b/web/lib/sf-workspace-store.tsx
new file mode 100644
index 000000000..388386aab
--- /dev/null
+++ b/web/lib/sf-workspace-store.tsx
@@ -0,0 +1,5406 @@
+"use client"
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react"
+import {
+  dispatchBrowserSlashCommand,
+  getBrowserSlashCommandTerminalNotice,
+  SF_HELP_TEXT,
+  type BrowserSlashCommandDispatchResult,
+  type BrowserSlashCommandSurface,
+} from "./browser-slash-command-dispatch"
+import {
+  applyCommandSurfaceActionResult,
+  closeCommandSurfaceState,
+  createInitialCommandSurfaceState,
+  openCommandSurfaceState,
+  selectCommandSurfaceStateTarget,
+  setCommandSurfacePending,
+  setCommandSurfaceSection,
+  type CommandSurfaceCompactionResult,
+  type CommandSurfaceDiagnosticsPhaseState,
+  type CommandSurfaceDoctorState,
+  type CommandSurfaceForkMessage,
+  type CommandSurfaceGitSummaryState,
+  type CommandSurfaceModelOption,
+  type CommandSurfaceRecoveryState,
+  type CommandSurfaceSection,
+  type CommandSurfaceSessionBrowserState,
+  type CommandSurfaceSessionStats,
+  type CommandSurfaceTarget,
+  type CommandSurfaceThinkingLevel,
+  type CommandSurfaceKnowledgeCapturesState,
+  type WorkspaceCommandSurfaceState,
+  type WorkspaceRecoveryDiagnostics,
+  type WorkspaceRecoverySummary,
+} from "./command-surface-contract"
+import type { DoctorFixResult, DoctorReport, ForensicReport, SkillHealthReport } from "./diagnostics-types"
+import type { KnowledgeData, CapturesData, CaptureResolveRequest, CaptureResolveResult } from "./knowledge-captures-types"
+import type { SettingsData } from "./settings-types"
+import type {
+  HistoryData,
+  InspectData,
+  HooksData,
+  ExportResult,
+  UndoInfo,
+  UndoResult,
+  CleanupData,
+  CleanupResult,
+  SteerData,
+} from "./remaining-command-types"
+import { isGitSummaryResponse, type GitSummaryResponse } from "./git-summary-contract"
+import type { PendingImage } from "./image-utils"
+import type { ChatMessage } from "./pty-chat-parser"
+import type {
+  SessionBrowserNameFilter,
+  SessionBrowserResponse,
+  SessionBrowserSession,
+  SessionBrowserSortMode,
+  SessionManageResponse,
+} from "./session-browser-contract"
+import { authFetch, appendAuthParam } from "./auth"
+import { ContextualTips } from "../../packages/pi-coding-agent/src/core/contextual-tips.ts"
+
+export type WorkspaceStatus = "idle" | "loading" | "ready" | "error" | "unauthenticated"
+export type WorkspaceConnectionState =
+  | "idle"
+  | "connecting"
+  | "connected"
+  | "reconnecting"
+  | "disconnected"
+  | "error"
+export type TerminalLineType = "input" | "output" | "system" | "success" | "error"
+export type BridgePhase = "idle" | "starting" | "ready" | "failed"
+export type WorkspaceStatusTone = "muted" | "info" | "success" | "warning" | "danger"
+
+export interface WorkspaceModelRef {
+  id?: string
+  provider?: string
+  providerId?: string
+}
+
+export interface BridgeLastError {
+  message: string
+  at: string
+  phase: BridgePhase
+  afterSessionAttachment: boolean
+  commandType?: string
+}
+
+export interface WorkspaceSessionState {
+  model?: WorkspaceModelRef
+  thinkingLevel: string
+  isStreaming: boolean
+  isCompacting: boolean
+  steeringMode: "all" | "one-at-a-time"
+  followUpMode: "all" | "one-at-a-time"
+  sessionFile?: string
+  sessionId: string
+  sessionName?: string
+  autoCompactionEnabled: boolean
+  autoRetryEnabled: boolean
+  retryInProgress: boolean
+  retryAttempt: number
+  messageCount: number
+  pendingMessageCount: number
+}
+
+export interface BridgeRuntimeSnapshot {
+  phase: BridgePhase
+  projectCwd: string
+  projectSessionsDir: string
+  packageRoot: string
+  startedAt: string | null
+  updatedAt: string
+  connectionCount: number
+  lastCommandType: string | null
+  activeSessionId: string | null
+  activeSessionFile: string | null
+  sessionState: WorkspaceSessionState | null
+  lastError: BridgeLastError | null
+}
+
+export type { WorkspaceTaskTarget, RiskLevel, WorkspaceSliceTarget, WorkspaceMilestoneTarget } from "./workspace-types.js"
+
+export interface WorkspaceScopeTarget {
+  scope: string
+  label: string
+  kind: "project" | "milestone" | "slice" | "task"
+}
+
+export interface WorkspaceValidationIssue {
+  message?: string
+  [key: string]: unknown
+}
+
+export interface WorkspaceIndex {
+  milestones: WorkspaceMilestoneTarget[]
+  active: {
+    milestoneId?: string
+    sliceId?: string
+    taskId?: string
+    phase: string
+  }
+  scopes: WorkspaceScopeTarget[]
+  validationIssues: WorkspaceValidationIssue[]
+}
+
+export interface RtkSessionSavings {
+  commands: number
+  inputTokens: number
+  outputTokens: number
+  savedTokens: number
+  savingsPct: number
+  totalTimeMs: number
+  avgTimeMs: number
+  updatedAt: string
+}
+
+export interface AutoDashboardData {
+  active: boolean
+  paused: boolean
+  stepMode: boolean
+  startTime: number
+  elapsed: number
+  currentUnit: { type: string; id: string; startedAt: number } | null
+  completedUnits: { type: string; id: string; startedAt: number; finishedAt: number }[]
+  basePath: string
+  totalCost: number
+  totalTokens: number
+  rtkSavings?: RtkSessionSavings | null
+  /** Whether RTK is enabled via experimental.rtk preference. False when not opted in. */
+  rtkEnabled?: boolean
+}
+
+export interface BootResumableSession {
+  id: string
+  path: string
+  cwd: string
+  name?: string
+  createdAt: string
+  modifiedAt: string
+  messageCount: number
+  isActive: boolean
+}
+
+export interface WorkspaceOnboardingProviderState {
+  id: string
+  label: string
+  required: true
+  recommended: boolean
+  configured: boolean
+  configuredVia: "auth_file" | "environment" | "runtime" | null
+  supports: {
+    apiKey: boolean
+    oauth: boolean
+    oauthAvailable: boolean
+    usesCallbackServer: boolean
+  }
+}
+
+export interface WorkspaceOnboardingOptionalSectionState {
+  id: string
+  label: string
+  blocking: false
+  skippable: true
+  configured: boolean
+  configuredItems: string[]
+}
+
+export interface WorkspaceOnboardingValidationResult {
+  status: "succeeded" | "failed"
+  providerId: string
+  method: "api_key" | "oauth"
+  checkedAt: string
+  message: string
+  persisted: boolean
+}
+
+export interface WorkspaceOnboardingFlowState {
+  flowId: string
+  providerId: string
+  providerLabel: string
+  status: "idle" | "running" | "awaiting_browser_auth" | "awaiting_input" | "succeeded" | "failed" | "cancelled"
+  updatedAt: string
+  auth: {
+    url: string
+    instructions?: string
+  } | null
+  prompt: {
+    kind: "text" | "manual_code"
+    message: string
+    placeholder?: string
+    allowEmpty?: boolean
+  } | null
+  progress: string[]
+  error: string | null
+}
+
+export interface WorkspaceOnboardingBridgeAuthRefreshState {
+  phase: "idle" | "pending" | "succeeded" | "failed"
+  strategy: "restart" | null
+  startedAt: string | null
+  completedAt: string | null
+  error: string | null
+}
+
+export interface WorkspaceOnboardingState {
+  status: "blocked" | "ready"
+  locked: boolean
+  lockReason: "required_setup" | "bridge_refresh_pending" | "bridge_refresh_failed" | null
+  required: {
+    blocking: true
+    skippable: false
+    satisfied: boolean
+    satisfiedBy: { providerId: string; source: "auth_file" | "environment" | "runtime" } | null
+    providers: WorkspaceOnboardingProviderState[]
+  }
+  optional: {
+    blocking: false
+    skippable: true
+    sections: WorkspaceOnboardingOptionalSectionState[]
+  }
+  lastValidation: WorkspaceOnboardingValidationResult | null
+  activeFlow: WorkspaceOnboardingFlowState | null
+  bridgeAuthRefresh: WorkspaceOnboardingBridgeAuthRefreshState
+}
+
+// ─── Project Detection ──────────────────────────────────────────────────────
+
+export type ProjectDetectionKind =
+  | "active-sf"
+  | "empty-sf"
+  | "v1-legacy"
+  | "brownfield"
+  | "blank"
+
+export interface ProjectDetectionSignals {
+
+  hasGsdFolder: boolean
+  hasPlanningFolder: boolean
+  hasGitRepo: boolean
+  hasPackageJson: boolean
+  isMonorepo?: boolean
+  fileCount: number
+}
+
+export interface ProjectDetection {
+  kind: ProjectDetectionKind
+  signals: ProjectDetectionSignals
+}
+
+// ─── Boot Payload ───────────────────────────────────────────────────────────
+
+export interface WorkspaceBootPayload {
+  project: {
+    cwd: string
+    sessionsDir: string
+    packageRoot: string
+  }
+  workspace: WorkspaceIndex
+  auto: AutoDashboardData
+  onboarding: WorkspaceOnboardingState
+  onboardingNeeded: boolean
+  resumableSessions: BootResumableSession[]
+  bridge: BridgeRuntimeSnapshot
+  projectDetection?: ProjectDetection
+}
+
+export interface BridgeStatusEvent {
+  type: "bridge_status"
+  bridge: BridgeRuntimeSnapshot
+}
+
+export type LiveStateInvalidationDomain = "auto" | "workspace" | "recovery" | "resumable_sessions"
+export type LiveStateInvalidationSource = "bridge_event" | "rpc_command" | "session_manage"
+export type LiveStateInvalidationReason =
+  | "agent_end"
+  | "turn_end"
+  | "auto_retry_start"
+  | "auto_retry_end"
+  | "auto_compaction_start"
+  | "auto_compaction_end"
+  | "new_session"
+  | "switch_session"
+  | "fork"
+  | "set_session_name"
+
+export interface LiveStateInvalidationEvent {
+  type: "live_state_invalidation"
+  at: string
+  reason: LiveStateInvalidationReason
+  source: LiveStateInvalidationSource
+  domains: LiveStateInvalidationDomain[]
+  workspaceIndexCacheInvalidated: boolean
+}
+
+export type WorkspaceFreshnessStatus = "idle" | "fresh" | "refreshing" | "stale" | "error"
+
+export interface WorkspaceFreshnessBucket {
+  status: WorkspaceFreshnessStatus
+  stale: boolean
+  reloadCount: number
+  lastRequestedAt: string | null
+  lastSuccessAt: string | null
+  lastFailureAt: string | null
+  lastFailure: string | null
+  invalidatedAt: string | null
+  invalidationReason: LiveStateInvalidationReason | null
+  invalidationSource: LiveStateInvalidationSource | null
+}
+
+export interface WorkspaceLiveFreshnessState {
+  auto: WorkspaceFreshnessBucket
+  workspace: WorkspaceFreshnessBucket
+  recovery: WorkspaceFreshnessBucket
+  resumableSessions: WorkspaceFreshnessBucket
+  gitSummary: WorkspaceFreshnessBucket
+  sessionBrowser: WorkspaceFreshnessBucket
+  sessionStats: WorkspaceFreshnessBucket
+}
+
+export interface WorkspaceLiveState {
+  auto: AutoDashboardData | null
+  workspace: WorkspaceIndex | null
+  resumableSessions: BootResumableSession[]
+  recoverySummary: WorkspaceRecoverySummary
+  freshness: WorkspaceLiveFreshnessState
+  softBootRefreshCount: number
+  targetedRefreshCount: number
+}
+
+// Discriminated union for extension UI requests — matches the authoritative
+// RpcExtensionUIRequest from rpc-types.ts. Blocking methods queue in pendingUiRequests;
+// fire-and-forget methods update state maps directly.
+export type ExtensionUiRequestEvent =
+  | { type: "extension_ui_request"; id: string; method: "select"; title: string; options: string[]; timeout?: number; allowMultiple?: boolean }
+  | { type: "extension_ui_request"; id: string; method: "confirm"; title: string; message: string; timeout?: number }
+  | { type: "extension_ui_request"; id: string; method: "input"; title: string; placeholder?: string; timeout?: number }
+  | { type: "extension_ui_request"; id: string; method: "editor"; title: string; prefill?: string }
+  | { type: "extension_ui_request"; id: string; method: "notify"; message: string; notifyType?: "info" | "warning" | "error" }
+  | { type: "extension_ui_request"; id: string; method: "setStatus"; statusKey: string; statusText: string | undefined }
+  | { type: "extension_ui_request"; id: string; method: "setWidget"; widgetKey: string; widgetLines: string[] | undefined; widgetPlacement?: "aboveEditor" | "belowEditor" }
+  | { type: "extension_ui_request"; id: string; method: "setTitle"; title: string }
+  | { type: "extension_ui_request"; id: string; method: "set_editor_text"; text: string }
+
+export interface ExtensionErrorEvent {
+  type: "extension_error"
+  extensionPath?: string
+  event?: string
+  error: string
+}
+
+export interface MessageUpdateEvent {
+  type: "message_update"
+  assistantMessageEvent?: {
+    type: string
+    delta?: string
+    [key: string]: unknown
+  }
+  [key: string]: unknown
+}
+
+export interface ToolExecutionStartEvent {
+  type: "tool_execution_start"
+  toolCallId: string
+  toolName: string
+  [key: string]: unknown
+}
+
+export interface ToolExecutionUpdateEvent {
+  type: "tool_execution_update"
+  toolCallId: string
+  toolName: string
+  partialResult?: {
+    content?: Array<{ type: string; text?: string }>
+    details?: Record<string, unknown>
+    isError?: boolean
+  }
+  [key: string]: unknown
+}
+
+export interface ToolExecutionEndEvent {
+  type: "tool_execution_end"
+  toolCallId: string
+  toolName: string
+  isError?: boolean
+  [key: string]: unknown
+}
+
+export interface AgentEndEvent {
+  type: "agent_end"
+  [key: string]: unknown
+}
+
+export interface TurnEndEvent {
+  type: "turn_end"
+  [key: string]: unknown
+}
+
+export type WorkspaceEvent =
+  | BridgeStatusEvent
+  | LiveStateInvalidationEvent
+  | ExtensionUiRequestEvent
+  | ExtensionErrorEvent
+  | MessageUpdateEvent
+  | ToolExecutionStartEvent
+  | ToolExecutionUpdateEvent
+  | ToolExecutionEndEvent
+  | AgentEndEvent
+  | TurnEndEvent
+  | ({ type: Exclude<string, "bridge_status" | "live_state_invalidation" | "extension_ui_request" | "extension_error" | "message_update" | "tool_execution_start" | "tool_execution_update" | "tool_execution_end" | "agent_end" | "turn_end">; [key: string]: unknown } & Record<string, unknown>)
+
+export function isWorkspaceEvent(value: unknown): value is WorkspaceEvent {
+  return value !== null && typeof value === "object" && typeof (value as Record<string, unknown>).type === "string"
+}
+
+export interface WorkspaceCommandResponse {
+  type: "response"
+  command: string
+  success: boolean
+  error?: string
+  data?: unknown
+  id?: string
+  code?: string
+  details?: {
+    reason?: "required_setup" | "bridge_refresh_pending" | "bridge_refresh_failed"
+    onboarding?: Partial<WorkspaceOnboardingState>
+  }
+}
+
+export interface WorkspaceBridgeCommand {
+  type: string
+  [key: string]: unknown
+}
+
+export interface WorkspaceTerminalLine {
+  id: string
+  type: TerminalLineType
+  content: string
+  timestamp: string
+}
+
+export type WorkspaceOnboardingRequestState =
+  | "idle"
+  | "refreshing"
+  | "saving_api_key"
+  | "starting_provider_flow"
+  | "submitting_provider_flow_input"
+  | "cancelling_provider_flow"
+  | "logging_out_provider"
+
+// A blocking UI request that needs user response before the agent can continue.
+// The `method` field discriminates the payload shape.
+export type PendingUiRequest = Extract<
+  ExtensionUiRequestEvent,
+  { method: "select" | "confirm" | "input" | "editor" }
+>
+
+export interface ActiveToolExecution {
+  id: string
+  name: string
+  args?: Record<string, unknown>
+  result?: {
+    content?: Array<{ type: string; text?: string }>
+    details?: Record<string, unknown>
+    isError?: boolean
+  }
+}
+
+/** Completed tool execution with result — kept for chat rendering */
+export interface CompletedToolExecution {
+  id: string
+  name: string
+  args: Record<string, unknown>
+  result?: {
+    content?: Array<{ type: string; text?: string }>
+    details?: Record<string, unknown>
+    isError?: boolean
+  }
+}
+
+/**
+ * A chronologically-ordered segment within a single assistant turn.
+ * The sequence `thinking → text → tool → thinking → text → tool …`
+ * is captured as separate segments so the chat UI can render them
+ * in the correct interleaved order.
+ */
+export type TurnSegment =
+  | { kind: "thinking"; content: string }
+  | { kind: "text"; content: string }
+  | { kind: "tool"; tool: CompletedToolExecution }
+
+export interface WidgetContent {
+  lines: string[] | undefined
+  placement?: "aboveEditor" | "belowEditor"
+}
+
+export interface WorkspaceStoreState {
+  bootStatus: WorkspaceStatus
+  connectionState: WorkspaceConnectionState
+  boot: WorkspaceBootPayload | null
+  live: WorkspaceLiveState
+  terminalLines: WorkspaceTerminalLine[]
+  lastClientError: string | null
+  lastBridgeError: BridgeLastError | null
+  sessionAttached: boolean
+  lastEventType: string | null
+  commandInFlight: string | null
+  lastSlashCommandOutcome: BrowserSlashCommandDispatchResult | null
+  commandSurface: WorkspaceCommandSurfaceState
+  onboardingRequestState: WorkspaceOnboardingRequestState
+  onboardingRequestProviderId: string | null
+  // Live interaction state
+  pendingUiRequests: PendingUiRequest[]
+  streamingAssistantText: string
+  streamingThinkingText: string
+  liveTranscript: string[]
+  /** Thinking text for each liveTranscript block (parallel array — same length) */
+  liveThinkingTranscript: string[]
+  completedToolExecutions: CompletedToolExecution[]
+  activeToolExecution: ActiveToolExecution | null
+  /**
+   * Ordered segments within the current streaming turn.
+   * Captures the chronological sequence: thinking → text → tool → thinking → text → ...
+   * Flushed to `completedTurnSegments` on turn boundary.
+   */
+  currentTurnSegments: TurnSegment[]
+  /**
+   * Segment history for completed turns. Each entry is a full turn's segments.
+   * Parallel to `liveTranscript` (same index = same turn).
+   */
+  completedTurnSegments: TurnSegment[][]
+  /** User messages in chat — persisted in store so they survive component unmount/remount */
+  chatUserMessages: ChatMessage[]
+  statusTexts: Record<string, string>
+  widgetContents: Record<string, WidgetContent>
+  titleOverride: string | null
+  editorTextBuffer: string | null
+}
+
+const MAX_TERMINAL_LINES = 250
+export const MAX_TRANSCRIPT_BLOCKS = 100
+export const COMMAND_TIMEOUT_MS = 90_000
+export const VISIBILITY_REFRESH_THRESHOLD_MS = 30_000
+const IMPLEMENTED_BROWSER_COMMAND_SURFACES = new Set<BrowserSlashCommandSurface>([
+  "settings",
+  "model",
+  "thinking",
+  "git",
+  "resume",
+  "name",
+  "fork",
+  "compact",
+  "login",
+  "logout",
+  "session",
+  "export",
+  // SF subcommand surfaces (S02)
+  "sf-status",
+  "sf-visualize",
+  "sf-forensics",
+  "sf-doctor",
+  "sf-skill-health",
+  "sf-knowledge",
+  "sf-capture",
+  "sf-triage",
+  "sf-quick",
+  "sf-history",
+  "sf-undo",
+  "sf-inspect",
+  "sf-prefs",
+  "sf-config",
+  "sf-hooks",
+  "sf-mode",
+  "sf-steer",
+  "sf-export",
+  "sf-cleanup",
+  "sf-queue",
+])
+
+function timestampLabel(date = new Date()): string {
+  return date.toLocaleTimeString("en-US", {
+    hour12: false,
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  })
+}
+
+function createTerminalLine(type: TerminalLineType, content: string): WorkspaceTerminalLine {
+  return {
+    id: `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+    type,
+    content,
+    timestamp: timestampLabel(),
+  }
+}
+
+function withTerminalLine(lines: WorkspaceTerminalLine[], line: WorkspaceTerminalLine): WorkspaceTerminalLine[] {
+  return [...lines, line].slice(-MAX_TERMINAL_LINES)
+}
+
+function hasAttachedSession(bridge: BridgeRuntimeSnapshot | null | undefined): boolean {
+  return Boolean(bridge?.activeSessionId || bridge?.sessionState?.sessionId)
+}
+
+function normalizeClientError(error: unknown): string {
+  if (error instanceof Error) return error.message
+  return String(error)
+}
+
+function getCommandInputLabel(command: WorkspaceBridgeCommand): string {
+  return typeof command.message === "string" ? command.message : `/${command.type}`
+}
+
+function summarizeBridgeStatus(bridge: BridgeRuntimeSnapshot): { type: TerminalLineType; message: string } {
+  if (bridge.phase === "failed") {
+    return {
+      type: "error",
+      message: `Bridge failed${bridge.lastError?.message ? ` — ${bridge.lastError.message}` : ""}`,
+    }
+  }
+
+  if (bridge.phase === "starting") {
+    return {
+      type: "system",
+      message: "Bridge starting for the current project…",
+    }
+  }
+
+  if (bridge.phase === "ready") {
+    const sessionLabel = getSessionLabelFromBridge(bridge)
+    return {
+      type: "success",
+      message: sessionLabel
+        ? `Live bridge ready — attached to ${sessionLabel}`
+        : "Live bridge ready — session attachment pending",
+    }
+  }
+
+  return {
+    type: "system",
+    message: "Bridge idle",
+  }
+}
+
+function summarizeEvent(event: WorkspaceEvent): { type: TerminalLineType; message: string } | null {
+  switch (event.type) {
+    case "bridge_status":
+      return summarizeBridgeStatus((event as BridgeStatusEvent).bridge)
+    case "live_state_invalidation":
+      return {
+        type: "system",
+        message: `[Live] Refreshing ${Array.isArray(event.domains) ? event.domains.join(", ") : "state"} after ${String(event.reason).replaceAll("_", " ")}`,
+      }
+    case "agent_start":
+      return { type: "system", message: "[Agent] Run started" }
+    case "agent_end":
+      return { type: "success", message: "[Agent] Run finished" }
+    case "turn_start":
+      return { type: "system", message: "[Agent] Turn started" }
+    case "turn_end":
+      return { type: "success", message: "[Agent] Turn complete" }
+    case "tool_execution_start":
+      return {
+        type: "output",
+        message: `[Tool] ${typeof event.toolName === "string" ? event.toolName : "tool"} started`,
+      }
+    case "tool_execution_update":
+      return null
+    case "tool_execution_end":
+      return {
+        type: event.isError ? "error" : "success",
+        message: `[Tool] ${typeof event.toolName === "string" ? event.toolName : "tool"} ${event.isError ? "failed" : "completed"}`,
+      }
+    case "auto_compaction_start":
+      return { type: "system", message: "[Auto] Compaction started" }
+    case "auto_compaction_end":
+      return {
+        type: event.aborted ? "error" : "success",
+        message: event.aborted ? "[Auto] Compaction aborted" : "[Auto] Compaction finished",
+      }
+    case "auto_retry_start":
+      return {
+        type: "system",
+        message: `[Auto] Retry ${String(event.attempt)}/${String(event.maxAttempts)} scheduled`,
+      }
+    case "auto_retry_end":
+      return {
+        type: event.success ? "success" : "error",
+        message: event.success ? "[Auto] Retry recovered the run" : "[Auto] Retry exhausted",
+      }
+    case "extension_ui_request": {
+      const uiEvent = event as ExtensionUiRequestEvent
+      const detail =
+        "title" in uiEvent && typeof uiEvent.title === "string" && uiEvent.title.trim().length > 0
+          ? uiEvent.title
+          : "message" in uiEvent && typeof uiEvent.message === "string" && uiEvent.message.trim().length > 0
+            ? uiEvent.message
+            : uiEvent.method
+      return {
+        type: ("notifyType" in uiEvent && uiEvent.notifyType === "error") ? "error" : "system",
+        message: `[UI] ${detail}`,
+      }
+    }
+    case "extension_error":
+      return { type: "error", message: `[Extension] ${event.error}` }
+    default:
+      return null
+  }
+}
+
+type OnboardingApiPayload = {
+  onboarding?: WorkspaceOnboardingState
+  error?: string
+}
+
+const ACTIVE_ONBOARDING_FLOW_STATUSES = new Set<WorkspaceOnboardingFlowState["status"]>([
+  "running",
+  "awaiting_browser_auth",
+  "awaiting_input",
+])
+
+const TERMINAL_ONBOARDING_FLOW_STATUSES = new Set<WorkspaceOnboardingFlowState["status"]>([
+  "succeeded",
+  "failed",
+  "cancelled",
+])
+
+function findOnboardingProviderLabel(onboarding: WorkspaceOnboardingState, providerId: string): string {
+  return onboarding.required.providers.find((provider) => provider.id === providerId)?.label ?? providerId
+}
+
+function mergeOnboardingState(
+  current: WorkspaceOnboardingState,
+  patch: Partial<WorkspaceOnboardingState>,
+): WorkspaceOnboardingState {
+  return {
+    ...current,
+    ...patch,
+    required: {
+      ...current.required,
+      ...(patch.required ?? {}),
+      providers: patch.required?.providers ?? current.required.providers,
+    },
+    optional: {
+      ...current.optional,
+      ...(patch.optional ?? {}),
+      sections: patch.optional?.sections ?? current.optional.sections,
+    },
+    bridgeAuthRefresh: {
+      ...current.bridgeAuthRefresh,
+      ...(patch.bridgeAuthRefresh ?? {}),
+    },
+  }
+}
+
+function cloneBootWithBridge(
+  boot: WorkspaceBootPayload | null,
+  bridge: BridgeRuntimeSnapshot,
+): WorkspaceBootPayload | null {
+  if (!boot) return null
+  const nextBoot = {
+    ...boot,
+    bridge,
+  }
+
+  return {
+    ...nextBoot,
+    resumableSessions: overlayLiveBridgeSessionState(nextBoot.resumableSessions, nextBoot),
+  }
+}
+
+function patchBootSessionState(
+  boot: WorkspaceBootPayload | null,
+  patch: Partial<WorkspaceSessionState>,
+): WorkspaceBootPayload | null {
+  if (!boot?.bridge.sessionState) return boot
+
+  return cloneBootWithBridge(boot, {
+    ...boot.bridge,
+    sessionState: {
+      ...boot.bridge.sessionState,
+      ...patch,
+    },
+  })
+}
+
+function patchBootSessionName(
+  boot: WorkspaceBootPayload | null,
+  sessionPath: string,
+  name: string,
+): WorkspaceBootPayload | null {
+  if (!boot) return null
+
+  const isActiveSession = getLiveActiveSessionPath(boot) === sessionPath
+  const nextBridge =
+    isActiveSession && boot.bridge.sessionState
+      ? {
+          ...boot.bridge,
+          sessionState: {
+            ...boot.bridge.sessionState,
+            sessionName: name,
+          },
+        }
+      : boot.bridge
+
+  const nextBoot = {
+    ...boot,
+    bridge: nextBridge,
+  }
+
+  return {
+    ...nextBoot,
+    resumableSessions: overlayLiveBridgeSessionState(
+      nextBoot.resumableSessions.map((session) =>
+        session.path === sessionPath
+          ? {
+              ...session,
+              name,
+            }
+          : session,
+      ),
+      nextBoot,
+    ),
+  }
+}
+
+function patchBootActiveSession(
+  boot: WorkspaceBootPayload | null,
+  sessionPath: string,
+  sessionName?: string,
+): WorkspaceBootPayload | null {
+  if (!boot) return null
+
+  const selectedSession = boot.resumableSessions.find((session) => session.path === sessionPath)
+  const nextBridge = {
+    ...boot.bridge,
+    activeSessionFile: sessionPath,
+    activeSessionId: selectedSession?.id ?? boot.bridge.activeSessionId,
+    sessionState: boot.bridge.sessionState
+      ? {
+          ...boot.bridge.sessionState,
+          sessionFile: sessionPath,
+          sessionId: selectedSession?.id ?? boot.bridge.sessionState.sessionId,
+          sessionName: sessionName ?? selectedSession?.name ?? boot.bridge.sessionState.sessionName,
+        }
+      : boot.bridge.sessionState,
+  }
+
+  const nextBoot = {
+    ...boot,
+    bridge: nextBridge,
+  }
+
+  return {
+    ...nextBoot,
+    resumableSessions: overlayLiveBridgeSessionState(
+      nextBoot.resumableSessions.map((session) => ({
+        ...session,
+        isActive: session.path === sessionPath,
+      })),
+      nextBoot,
+    ),
+  }
+}
+
+function cloneBootWithOnboarding(
+  boot: WorkspaceBootPayload | null,
+  onboarding: WorkspaceOnboardingState,
+): WorkspaceBootPayload | null {
+  if (!boot) return null
+  return {
+    ...boot,
+    onboarding,
+    onboardingNeeded: onboarding.locked,
+  }
+}
+
+function cloneBootWithPartialOnboarding(
+  boot: WorkspaceBootPayload | null,
+  onboarding: Partial<WorkspaceOnboardingState>,
+): WorkspaceBootPayload | null {
+  if (!boot) return null
+  return cloneBootWithOnboarding(boot, mergeOnboardingState(boot.onboarding, onboarding))
+}
+
+function summarizeOnboardingState(onboarding: WorkspaceOnboardingState): { type: TerminalLineType; message: string } | null {
+  if (onboarding.bridgeAuthRefresh.phase === "failed") {
+    return {
+      type: "error",
+      message: onboarding.bridgeAuthRefresh.error
+        ? `Bridge auth refresh failed — ${onboarding.bridgeAuthRefresh.error}`
+        : "Bridge auth refresh failed after setup",
+    }
+  }
+
+  if (onboarding.bridgeAuthRefresh.phase === "pending") {
+    return {
+      type: "system",
+      message: "Credentials saved — refreshing bridge auth before the workspace unlocks…",
+    }
+  }
+
+  if (onboarding.lastValidation?.status === "failed") {
+    return {
+      type: "error",
+      message: `Credential validation failed — ${onboarding.lastValidation.message}`,
+    }
+  }
+
+  if (!onboarding.locked && onboarding.lastValidation?.status === "succeeded") {
+    return {
+      type: "success",
+      message: `${findOnboardingProviderLabel(onboarding, onboarding.lastValidation.providerId)} is ready — workspace unlocked`,
+    }
+  }
+
+  if (onboarding.activeFlow?.status === "awaiting_browser_auth") {
+    return {
+      type: "system",
+      message: `${onboarding.activeFlow.providerLabel} sign-in is waiting for browser confirmation`,
+    }
+  }
+
+  if (onboarding.activeFlow?.status === "awaiting_input") {
+    return {
+      type: "system",
+      message: `${onboarding.activeFlow.providerLabel} sign-in needs one more input step`,
+    }
+  }
+
+  if (onboarding.activeFlow?.status === "cancelled") {
+    return {
+      type: "system",
+      message: `${onboarding.activeFlow.providerLabel} sign-in was cancelled`,
+    }
+  }
+
+  if (onboarding.activeFlow?.status === "failed") {
+    return {
+      type: "error",
+      message: onboarding.activeFlow.error
+        ? `${onboarding.activeFlow.providerLabel} sign-in failed — ${onboarding.activeFlow.error}`
+        : `${onboarding.activeFlow.providerLabel} sign-in failed`,
+    }
+  }
+
+  if (onboarding.lockReason === "required_setup") {
+    return {
+      type: "system",
+      message: "Onboarding is still required before model-backed prompts will run",
+    }
+  }
+
+  return null
+}
+
+function bootSeedLines(boot: WorkspaceBootPayload): WorkspaceTerminalLine[] {
+  const lines = [
+    createTerminalLine("system", `SF web workspace attached to ${boot.project.cwd}`),
+    createTerminalLine("system", `Workspace scope: ${getCurrentScopeLabel(boot.workspace)}`),
+  ]
+
+  const bridgeSummary = summarizeBridgeStatus(boot.bridge)
+  lines.push(createTerminalLine(bridgeSummary.type, bridgeSummary.message))
+
+  if (boot.bridge.lastError) {
+    lines.push(createTerminalLine("error", `Bridge error: ${boot.bridge.lastError.message}`))
+  }
+
+  const onboardingSummary = summarizeOnboardingState(boot.onboarding)
+  if (onboardingSummary) {
+    lines.push(createTerminalLine(onboardingSummary.type, onboardingSummary.message))
+  }
+
+  return lines
+}
+
+function responseToLine(response: WorkspaceCommandResponse): WorkspaceTerminalLine {
+  if (!response.success) {
+    return createTerminalLine("error", `Command failed (${response.command}) — ${response.error ?? "unknown error"}`)
+  }
+
+  switch (response.command) {
+    case "get_state":
+      return createTerminalLine("success", "Session state refreshed")
+    case "new_session":
+      return createTerminalLine("success", "Started a new session")
+    case "prompt":
+      return createTerminalLine("success", "Prompt accepted by the live bridge")
+    case "follow_up":
+      return createTerminalLine("success", "Follow-up queued on the live bridge")
+    default:
+      return createTerminalLine("success", `Command accepted (${response.command})`)
+  }
+}
+
+export function shortenPath(path: string | undefined, segmentCount = 3): string {
+  if (!path) return "—"
+  const parts = path.split(/[\\/]/).filter(Boolean)
+  if (parts.length <= segmentCount) {
+    return path.startsWith("/") ? `/${parts.join("/")}` : parts.join("/")
+  }
+  const tail = parts.slice(-segmentCount).join("/")
+  return `…/${tail}`
+}
+
+export function getProjectDisplayName(path: string | undefined): string {
+  if (!path) return "Current project"
+  const parts = path.split(/[\\/]/).filter(Boolean)
+  return parts.at(-1) || path
+}
+
+export function formatDuration(ms: number): string {
+  if (!ms || ms < 1000) return "0m"
+  const totalMinutes = Math.floor(ms / 60_000)
+  const hours = Math.floor(totalMinutes / 60)
+  const minutes = totalMinutes % 60
+  if (hours > 0) return `${hours}h ${minutes}m`
+  return `${minutes}m`
+}
+
+export function formatTokens(tokens: number): string {
+  if (!Number.isFinite(tokens) || tokens <= 0) return "0"
+  if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`
+  if (tokens >= 1_000) return `${Math.round(tokens / 1_000)}K`
+  return String(Math.round(tokens))
+}
+
+export function formatCost(cost: number): string {
+  if (!Number.isFinite(cost) || cost <= 0) return "$0.00"
+  return `$${cost.toFixed(2)}`
+}
+
+export function getCurrentScopeLabel(workspace: WorkspaceIndex | null | undefined): string {
+  if (!workspace) return "Project scope pending"
+  const scope = [workspace.active.milestoneId, workspace.active.sliceId, workspace.active.taskId]
+    .filter(Boolean)
+    .join("/")
+  return scope ? `${scope} — ${workspace.active.phase}` : `project — ${workspace.active.phase}`
+}
+
+export function getCurrentBranch(workspace: WorkspaceIndex | null | undefined): string | null {
+  if (!workspace?.active.milestoneId || !workspace.active.sliceId) {
+    return null
+  }
+
+  const milestone = workspace.milestones.find((entry) => entry.id === workspace.active.milestoneId)
+  const slice = milestone?.slices.find((entry) => entry.id === workspace.active.sliceId)
+  return slice?.branch ?? null
+}
+
+export function getCurrentSlice(workspace: WorkspaceIndex | null | undefined): WorkspaceSliceTarget | null {
+  if (!workspace?.active.milestoneId || !workspace.active.sliceId) return null
+  const milestone = workspace.milestones.find((entry) => entry.id === workspace.active.milestoneId)
+  return milestone?.slices.find((entry) => entry.id === workspace.active.sliceId) ?? null
+}
+
+export function getSessionLabelFromBridge(bridge: BridgeRuntimeSnapshot | null | undefined): string | null {
+  if (!bridge?.sessionState && !bridge?.activeSessionId) return null
+  const sessionName = bridge.sessionState?.sessionName?.trim()
+  if (sessionName) return sessionName
+  if (bridge.activeSessionId) return `session ${bridge.activeSessionId}`
+  return bridge.sessionState?.sessionId ?? null
+}
+
+export function getModelLabel(bridge: BridgeRuntimeSnapshot | null | undefined): string {
+  const model = bridge?.sessionState?.model
+  if (!model) return "model pending"
+  return model.id || model.providerId || model.provider || "model pending"
+}
+
+function getCurrentModelSelection(
+  bridge: BridgeRuntimeSnapshot | null | undefined,
+): { provider?: string; modelId?: string } | null {
+  const model = bridge?.sessionState?.model
+  if (!model) return null
+  return {
+    provider: model.provider ?? model.providerId,
+    modelId: model.id,
+  }
+}
+
+function getPreferredOnboardingProviderId(onboarding: WorkspaceOnboardingState | null | undefined): string | null {
+  if (!onboarding) return null
+  if (onboarding.required.satisfiedBy?.providerId) {
+    return onboarding.required.satisfiedBy.providerId
+  }
+
+  const recommended = onboarding.required.providers.find((provider) => !provider.configured && provider.recommended)
+  if (recommended) return recommended.id
+
+  const firstUnconfigured = onboarding.required.providers.find((provider) => !provider.configured)
+  if (firstUnconfigured) return firstUnconfigured.id
+
+  return onboarding.required.providers[0]?.id ?? null
+}
+
+function normalizeAvailableModels(
+  payload: unknown,
+  currentModel: { provider?: string; modelId?: string } | null,
+): CommandSurfaceModelOption[] {
+  const models =
+    payload &&
+    typeof payload === "object" &&
+    "models" in payload &&
+    Array.isArray((payload as { models?: unknown[] }).models)
+      ? (payload as { models: Array<Record<string, unknown>> }).models
+      : []
+
+  const results: CommandSurfaceModelOption[] = []
+  for (const model of models) {
+    const provider =
+      typeof model.provider === "string"
+        ? model.provider
+        : typeof model.providerId === "string"
+          ? model.providerId
+          : undefined
+    const modelId = typeof model.id === "string" ? model.id : undefined
+    if (!provider || !modelId) continue
+    results.push({
+      provider,
+      modelId,
+      name: typeof model.name === "string" ? model.name : undefined,
+      reasoning: Boolean(model.reasoning),
+      isCurrent: provider === currentModel?.provider && modelId === currentModel?.modelId,
+    })
+  }
+  return results
+    .sort((left, right) => Number(right.isCurrent) - Number(left.isCurrent) || left.provider.localeCompare(right.provider) || left.modelId.localeCompare(right.modelId))
+}
+
+function normalizeSessionStats(payload: unknown): CommandSurfaceSessionStats | null {
+  if (!payload || typeof payload !== "object") return null
+  const stats = payload as Partial<CommandSurfaceSessionStats>
+  if (typeof stats.sessionId !== "string") return null
+
+  return {
+    sessionFile: typeof stats.sessionFile === "string" ? stats.sessionFile : undefined,
+    sessionId: stats.sessionId,
+    userMessages: Number(stats.userMessages ?? 0),
+    assistantMessages: Number(stats.assistantMessages ?? 0),
+    toolCalls: Number(stats.toolCalls ?? 0),
+    toolResults: Number(stats.toolResults ?? 0),
+    totalMessages: Number(stats.totalMessages ?? 0),
+    tokens: {
+      input: Number(stats.tokens?.input ?? 0),
+      output: Number(stats.tokens?.output ?? 0),
+      cacheRead: Number(stats.tokens?.cacheRead ?? 0),
+      cacheWrite: Number(stats.tokens?.cacheWrite ?? 0),
+      total: Number(stats.tokens?.total ?? 0),
+    },
+    cost: Number(stats.cost ?? 0),
+  }
+}
+
+function normalizeForkMessages(payload: unknown): CommandSurfaceForkMessage[] {
+  const messages =
+    payload &&
+    typeof payload === "object" &&
+    "messages" in payload &&
+    Array.isArray((payload as { messages?: unknown[] }).messages)
+      ? (payload as { messages: Array<Record<string, unknown>> }).messages
+      : []
+
+  return messages
+    .map((message) => {
+      const entryId = typeof message.entryId === "string" ? message.entryId : undefined
+      const text = typeof message.text === "string" ? message.text : undefined
+      if (!entryId || !text) return null
+      return { entryId, text } satisfies CommandSurfaceForkMessage
+    })
+    .filter((message): message is CommandSurfaceForkMessage => message !== null)
+}
+
+function normalizeCompactionResult(payload: unknown): CommandSurfaceCompactionResult | null {
+  if (!payload || typeof payload !== "object") return null
+  const result = payload as Partial<CommandSurfaceCompactionResult>
+  if (typeof result.summary !== "string" || typeof result.firstKeptEntryId !== "string") return null
+
+  return {
+    summary: result.summary,
+    firstKeptEntryId: result.firstKeptEntryId,
+    tokensBefore: Number(result.tokensBefore ?? 0),
+    details: result.details,
+  }
+}
+
+function normalizeGitSummaryPayload(payload: unknown): GitSummaryResponse | null {
+  return isGitSummaryResponse(payload) ? payload : null
+}
+
+function normalizeGitSummaryError(
+  current: CommandSurfaceGitSummaryState,
+  message: string,
+): CommandSurfaceGitSummaryState {
+  return {
+    ...current,
+    pending: false,
+    loaded: false,
+    error: message,
+  }
+}
+
+function normalizeRecoveryDiagnosticsPayload(payload: unknown): WorkspaceRecoveryDiagnostics | null {
+  if (!payload || typeof payload !== "object") return null
+
+  const candidate = payload as Partial<WorkspaceRecoveryDiagnostics>
+  if (candidate.status !== "ready" && candidate.status !== "unavailable") return null
+  if (typeof candidate.loadedAt !== "string") return null
+  if (!candidate.project || typeof candidate.project.cwd !== "string") return null
+  if (!candidate.summary || typeof candidate.summary.label !== "string" || typeof candidate.summary.detail !== "string") return null
+  if (!candidate.bridge || typeof candidate.bridge.phase !== "string") return null
+  if (!candidate.validation || typeof candidate.validation.total !== "number") return null
+  if (!candidate.doctor || typeof candidate.doctor.total !== "number") return null
+  if (!candidate.interruptedRun || typeof candidate.interruptedRun.available !== "boolean") return null
+  if (!candidate.actions || !Array.isArray(candidate.actions.browser) || !Array.isArray(candidate.actions.commands)) return null
+
+  return candidate as WorkspaceRecoveryDiagnostics
+}
+
+function createRecoveryStateFromDiagnostics(diagnostics: WorkspaceRecoveryDiagnostics): CommandSurfaceRecoveryState {
+  return {
+    phase: diagnostics.status === "ready" ? "ready" : "unavailable",
+    pending: false,
+    loaded: true,
+    stale: false,
+    diagnostics,
+    error: null,
+    lastLoadedAt: diagnostics.loadedAt,
+    lastInvalidatedAt: null,
+    lastFailureAt: null,
+  }
+}
+
+function markRecoveryStatePending(current: CommandSurfaceRecoveryState): CommandSurfaceRecoveryState {
+  return {
+    ...current,
+    pending: true,
+    error: null,
+    phase: current.loaded ? current.phase : "loading",
+  }
+}
+
+function markRecoveryStateInvalidated(current: CommandSurfaceRecoveryState): CommandSurfaceRecoveryState {
+  if (!current.loaded && !current.error) return current
+  return {
+    ...current,
+    stale: true,
+    lastInvalidatedAt: new Date().toISOString(),
+  }
+}
+
+function markRecoveryStateFailure(current: CommandSurfaceRecoveryState, message: string): CommandSurfaceRecoveryState {
+  return {
+    ...current,
+    phase: "error",
+    pending: false,
+    stale: true,
+    error: message,
+    lastFailureAt: new Date().toISOString(),
+  }
+}
+
+function normalizeSessionBrowserPayload(payload: unknown): CommandSurfaceSessionBrowserState | null {
+  if (!payload || typeof payload !== "object") return null
+
+  const response = payload as Partial<SessionBrowserResponse>
+  const project = response.project
+  const query = response.query
+  if (!project || !query || !Array.isArray(response.sessions)) return null
+  if (project.scope !== "current_project") return null
+  if (typeof project.cwd !== "string" || typeof project.sessionsDir !== "string") return null
+  if (typeof query.query !== "string" || typeof query.sortMode !== "string" || typeof query.nameFilter !== "string") return null
+
+  const sessions = response.sessions.filter((session): session is SessionBrowserSession => {
+    return (
+      typeof session?.id === "string" &&
+      typeof session?.path === "string" &&
+      typeof session?.cwd === "string" &&
+      typeof session?.createdAt === "string" &&
+      typeof session?.modifiedAt === "string" &&
+      typeof session?.messageCount === "number" &&
+      typeof session?.firstMessage === "string" &&
+      typeof session?.isActive === "boolean" &&
+      typeof session?.depth === "number" &&
+      typeof session?.isLastInThread === "boolean" &&
+      Array.isArray(session?.ancestorHasNextSibling)
+    )
+  })
+
+  return {
+    scope: project.scope,
+    projectCwd: project.cwd,
+    projectSessionsDir: project.sessionsDir,
+    activeSessionPath: typeof project.activeSessionPath === "string" ? project.activeSessionPath : null,
+    query: query.query,
+    sortMode: query.sortMode as SessionBrowserSortMode,
+    nameFilter: query.nameFilter as SessionBrowserNameFilter,
+    totalSessions: Number(response.totalSessions ?? sessions.length),
+    returnedSessions: Number(response.returnedSessions ?? sessions.length),
+    sessions,
+    loaded: true,
+    error: null,
+  }
+}
+
+function getLiveActiveSessionPath(boot: WorkspaceBootPayload | null): string | null {
+  return boot?.bridge.activeSessionFile ?? boot?.bridge.sessionState?.sessionFile ?? null
+}
+
+function getLiveActiveSessionName(boot: WorkspaceBootPayload | null): string | undefined {
+  const value = boot?.bridge.sessionState?.sessionName?.trim()
+  return value ? value : undefined
+}
+
+function overlayLiveBridgeSessionState<T extends { path: string; isActive: boolean; name?: string }>(
+  sessions: T[],
+  boot: WorkspaceBootPayload | null,
+): T[] {
+  const activeSessionPath = getLiveActiveSessionPath(boot)
+  const activeSessionName = getLiveActiveSessionName(boot)
+
+  return sessions.map((session) => {
+    const isActive = activeSessionPath ? session.path === activeSessionPath : session.isActive
+    return {
+      ...session,
+      isActive,
+      ...(isActive && activeSessionName ? { name: activeSessionName } : {}),
+    }
+  })
+}
+
+function syncSessionBrowserStateWithBridge(
+  sessionBrowser: CommandSurfaceSessionBrowserState,
+  boot: WorkspaceBootPayload | null,
+): CommandSurfaceSessionBrowserState {
+  return {
+    ...sessionBrowser,
+    activeSessionPath: getLiveActiveSessionPath(boot),
+    sessions: overlayLiveBridgeSessionState(sessionBrowser.sessions, boot),
+  }
+}
+
+function patchSessionBrowserSession(
+  sessionBrowser: CommandSurfaceSessionBrowserState,
+  sessionPath: string,
+  patch: Partial<Pick<SessionBrowserSession, "name" | "isActive">>,
+): CommandSurfaceSessionBrowserState {
+  return {
+    ...sessionBrowser,
+    activeSessionPath: patch.isActive ? sessionPath : sessionBrowser.activeSessionPath,
+    sessions: sessionBrowser.sessions.map((session) =>
+      session.path === sessionPath
+        ? {
+            ...session,
+            ...patch,
+          }
+        : patch.isActive
+          ? {
+              ...session,
+              isActive: false,
+            }
+          : session,
+    ),
+  }
+}
+
+function describeSessionPath(sessionPath: string, boot: WorkspaceBootPayload | null): string {
+  const knownSession = boot?.resumableSessions.find((session) => session.path === sessionPath)
+  if (knownSession?.name?.trim()) return knownSession.name.trim()
+  if (knownSession?.id) return knownSession.id
+  return shortenPath(sessionPath)
+}
+
+export interface WorkspaceOnboardingPresentation {
+  phase:
+    | "loading"
+    | "locked"
+    | "validating"
+    | "running_flow"
+    | "awaiting_browser_auth"
+    | "awaiting_input"
+    | "refreshing"
+    | "failure"
+    | "ready"
+  label: string
+  detail: string
+  tone: WorkspaceStatusTone
+}
+
+export function getOnboardingPresentation(
+  state: Pick<WorkspaceStoreState, "bootStatus" | "boot" | "onboardingRequestState">,
+): WorkspaceOnboardingPresentation {
+  if (state.bootStatus === "loading" || !state.boot) {
+    return {
+      phase: "loading",
+      label: "Loading setup state",
+      detail: "Resolving the current project, bridge, and onboarding contract…",
+      tone: "info",
+    }
+  }
+
+  const onboarding = state.boot.onboarding
+  if (onboarding.activeFlow?.status === "awaiting_browser_auth") {
+    return {
+      phase: "awaiting_browser_auth",
+      label: "Continue sign-in in your browser",
+      detail: `${onboarding.activeFlow.providerLabel} is waiting for browser confirmation before the workspace can unlock.`,
+      tone: "info",
+    }
+  }
+
+  if (onboarding.activeFlow?.status === "awaiting_input") {
+    return {
+      phase: "awaiting_input",
+      label: "One more sign-in step is required",
+      detail: onboarding.activeFlow.prompt?.message ?? `${onboarding.activeFlow.providerLabel} needs one more input step.`,
+      tone: "info",
+    }
+  }
+
+  if (onboarding.lockReason === "bridge_refresh_pending") {
+    return {
+      phase: "refreshing",
+      label: "Refreshing bridge auth",
+      detail: "Credentials validated. The live bridge is restarting onto the new auth view before the shell unlocks.",
+      tone: "info",
+    }
+  }
+
+  if (onboarding.lockReason === "bridge_refresh_failed") {
+    return {
+      phase: "failure",
+      label: "Setup completed, but the shell is still locked",
+      detail: onboarding.bridgeAuthRefresh.error ?? "The bridge could not reload auth after setup.",
+      tone: "danger",
+    }
+  }
+
+  if (onboarding.lastValidation?.status === "failed") {
+    return {
+      phase: "failure",
+      label: "Credential validation failed",
+      detail: onboarding.lastValidation.message,
+      tone: "danger",
+    }
+  }
+
+  if (state.onboardingRequestState === "saving_api_key") {
+    return {
+      phase: "validating",
+      label: "Validating credentials",
+      detail: "Checking the provider key and saving it only if validation succeeds.",
+      tone: "info",
+    }
+  }
+
+  if (state.onboardingRequestState === "starting_provider_flow" || state.onboardingRequestState === "submitting_provider_flow_input") {
+    return {
+      phase: "running_flow",
+      label: "Advancing provider sign-in",
+      detail: "The onboarding flow is running and will update here as soon as the next step is ready.",
+      tone: "info",
+    }
+  }
+
+  if (onboarding.locked) {
+    return {
+      phase: "locked",
+      label: "Required setup needed",
+      detail: "Choose a required provider, validate it here, and the workspace will unlock without restarting the host.",
+      tone: "warning",
+    }
+  }
+
+  return {
+    phase: "ready",
+    label: "Workspace unlocked",
+    detail:
+      onboarding.lastValidation?.status === "succeeded"
+        ? `${findOnboardingProviderLabel(onboarding, onboarding.lastValidation.providerId)} is ready and the workspace is live.`
+        : "Required setup is satisfied and the shell is ready for live commands.",
+    tone: "success",
+  }
+}
+
+export function getVisibleWorkspaceError(
+  state: Pick<WorkspaceStoreState, "boot" | "lastBridgeError" | "lastClientError">,
+): string | null {
+  const onboarding = state.boot?.onboarding
+  if (onboarding?.bridgeAuthRefresh.phase === "failed" && onboarding.bridgeAuthRefresh.error) {
+    return onboarding.bridgeAuthRefresh.error
+  }
+  if (onboarding?.lastValidation?.status === "failed") {
+    return onboarding.lastValidation.message
+  }
+  return state.lastBridgeError?.message ?? state.lastClientError
+}
+
+export function getStatusPresentation(
+  state: Pick<WorkspaceStoreState, "bootStatus" | "connectionState" | "boot" | "onboardingRequestState">,
+): {
+  label: string
+  tone: WorkspaceStatusTone
+} {
+  if (state.bootStatus === "loading") {
+    return { label: "Loading workspace", tone: "info" }
+  }
+
+  if (state.bootStatus === "error") {
+    return { label: "Boot failed", tone: "danger" }
+  }
+
+  const onboardingPresentation = getOnboardingPresentation(state)
+  if (onboardingPresentation.phase !== "ready") {
+    return {
+      label: onboardingPresentation.label,
+      tone: onboardingPresentation.tone,
+    }
+  }
+
+  if (state.boot?.bridge.phase === "failed") {
+    return { label: "Bridge failed", tone: "danger" }
+  }
+
+  switch (state.connectionState) {
+    case "connected":
+      return { label: "Bridge connected", tone: "success" }
+    case "connecting":
+      return { label: "Connecting stream", tone: "info" }
+    case "reconnecting":
+      return { label: "Reconnecting stream", tone: "warning" }
+    case "disconnected":
+      return { label: "Stream disconnected", tone: "warning" }
+    case "error":
+      return { label: "Stream error", tone: "danger" }
+    default:
+      return { label: "Workspace idle", tone: "muted" }
+  }
+}
+
+function createFreshnessBucket(): WorkspaceFreshnessBucket {
+  return {
+    status: "idle",
+    stale: false,
+    reloadCount: 0,
+    lastRequestedAt: null,
+    lastSuccessAt: null,
+    lastFailureAt: null,
+    lastFailure: null,
+    invalidatedAt: null,
+    invalidationReason: null,
+    invalidationSource: null,
+  }
+}
+
+function createInitialRecoverySummary(): WorkspaceRecoverySummary {
+  return {
+    visible: false,
+    tone: "healthy",
+    label: "Recovery summary pending",
+    detail: "Waiting for the first live workspace snapshot.",
+    validationCount: 0,
+    retryInProgress: false,
+    retryAttempt: 0,
+    autoRetryEnabled: false,
+    isCompacting: false,
+    currentUnitId: null,
+    freshness: "idle",
+    entrypointLabel: "Inspect recovery",
+    lastError: null,
+  }
+}
+
+function createInitialWorkspaceLiveFreshnessState(): WorkspaceLiveFreshnessState {
+  return {
+    auto: createFreshnessBucket(),
+    workspace: createFreshnessBucket(),
+    recovery: createFreshnessBucket(),
+    resumableSessions: createFreshnessBucket(),
+    gitSummary: createFreshnessBucket(),
+    sessionBrowser: createFreshnessBucket(),
+    sessionStats: createFreshnessBucket(),
+  }
+}
+
+function createInitialWorkspaceLiveState(): WorkspaceLiveState {
+  return {
+    auto: null,
+    workspace: null,
+    resumableSessions: [],
+    recoverySummary: createInitialRecoverySummary(),
+    freshness: createInitialWorkspaceLiveFreshnessState(),
+    softBootRefreshCount: 0,
+    targetedRefreshCount: 0,
+  }
+}
+
+function withFreshnessRequested(bucket: WorkspaceFreshnessBucket): WorkspaceFreshnessBucket {
+  return {
+    ...bucket,
+    status: "refreshing",
+    lastRequestedAt: new Date().toISOString(),
+    lastFailure: null,
+  }
+}
+
+function withFreshnessInvalidated(
+  bucket: WorkspaceFreshnessBucket,
+  reason: LiveStateInvalidationReason,
+  source: LiveStateInvalidationSource,
+): WorkspaceFreshnessBucket {
+  return {
+    ...bucket,
+    status: bucket.lastSuccessAt ? "stale" : bucket.status,
+    stale: true,
+    invalidatedAt: new Date().toISOString(),
+    invalidationReason: reason,
+    invalidationSource: source,
+  }
+}
+
+function withFreshnessSucceeded(bucket: WorkspaceFreshnessBucket): WorkspaceFreshnessBucket {
+  return {
+    ...bucket,
+    status: "fresh",
+    stale: false,
+    reloadCount: bucket.reloadCount + 1,
+    lastSuccessAt: new Date().toISOString(),
+    lastFailureAt: null,
+    lastFailure: null,
+  }
+}
+
+function withFreshnessFailed(bucket: WorkspaceFreshnessBucket, error: string): WorkspaceFreshnessBucket {
+  return {
+    ...bucket,
+    status: "error",
+    stale: true,
+    lastFailureAt: new Date().toISOString(),
+    lastFailure: error,
+  }
+}
+
+export function getLiveWorkspaceIndex(
+  state: Pick<WorkspaceStoreState, "boot" | "live">,
+): WorkspaceIndex | null {
+  return state.live.workspace ?? state.boot?.workspace ?? null
+}
+
+export function getLiveAutoDashboard(
+  state: Pick<WorkspaceStoreState, "boot" | "live">,
+): AutoDashboardData | null {
+  return state.live.auto ?? state.boot?.auto ?? null
+}
+
+export function getLiveResumableSessions(
+  state: Pick<WorkspaceStoreState, "boot" | "live">,
+): BootResumableSession[] {
+  return state.live.resumableSessions.length > 0 ? state.live.resumableSessions : state.boot?.resumableSessions ?? []
+}
+
+export function createWorkspaceRecoverySummary(state: Pick<WorkspaceStoreState, "boot" | "live">): WorkspaceRecoverySummary {
+  const bridge = state.boot?.bridge ?? null
+  const workspace = getLiveWorkspaceIndex(state)
+  const auto = getLiveAutoDashboard(state)
+  const validationCount = workspace?.validationIssues.length ?? 0
+  const retryInProgress = Boolean(bridge?.sessionState?.retryInProgress)
+  const retryAttempt = bridge?.sessionState?.retryAttempt ?? 0
+  const autoRetryEnabled = Boolean(bridge?.sessionState?.autoRetryEnabled)
+  const isCompacting = Boolean(bridge?.sessionState?.isCompacting)
+  const freshnessBucket = state.live.freshness.recovery
+  const freshness =
+    freshnessBucket.status === "error"
+      ? "error"
+      : freshnessBucket.stale
+        ? "stale"
+        : freshnessBucket.lastSuccessAt
+          ? "fresh"
+          : "idle"
+  const lastError = bridge?.lastError
+    ? {
+        message: bridge.lastError.message,
+        phase: bridge.lastError.phase,
+        at: bridge.lastError.at,
+      }
+    : null
+
+  let tone: WorkspaceRecoverySummary["tone"] = "healthy"
+  let label = "Recovery summary healthy"
+  let detail = "No retry, compaction, bridge, or validation recovery signals are active."
+
+  if (!workspace && !auto && !bridge) {
+    return createInitialRecoverySummary()
+  }
+
+  if (lastError || freshness === "error") {
+    tone = "danger"
+    label = "Recovery attention required"
+    detail = lastError?.message ?? freshnessBucket.lastFailure ?? "A targeted live refresh failed."
+  } else if (validationCount > 0) {
+    tone = "warning"
+    label = `Recovery summary: ${validationCount} validation issue${validationCount === 1 ? "" : "s"}`
+    detail = "Workspace validation surfaced issues that may need doctor or audit follow-up."
+  } else if (retryInProgress) {
+    tone = "warning"
+    label = `Recovery retry active (attempt ${Math.max(1, retryAttempt)})`
+    detail = "The live bridge is retrying the current unit after a transient failure."
+  } else if (isCompacting) {
+    tone = "warning"
+    label = "Recovery compaction active"
+    detail = "The live session is compacting context before continuing."
+  } else if (freshness === "stale") {
+    tone = "warning"
+    label = "Recovery summary stale"
+    detail = freshnessBucket.invalidationReason
+      ? `Waiting for a targeted refresh after ${freshnessBucket.invalidationReason.replaceAll("_", " ")}.`
+      : "Waiting for the next targeted refresh."
+  }
+
+  return {
+    visible: true,
+    tone,
+    label,
+    detail,
+    validationCount,
+    retryInProgress,
+    retryAttempt,
+    autoRetryEnabled,
+    isCompacting,
+    currentUnitId: auto?.currentUnit?.id ?? null,
+    freshness,
+    entrypointLabel: tone === "danger" || tone === "warning" ? "Inspect recovery" : "Review recovery",
+    lastError,
+  }
+}
+
+function applyBootToLiveState(
+  current: WorkspaceLiveState,
+  boot: WorkspaceBootPayload,
+  options: { soft?: boolean } = {},
+): WorkspaceLiveState {
+  const next: WorkspaceLiveState = {
+    ...current,
+    auto: boot.auto,
+    workspace: boot.workspace,
+    resumableSessions: boot.resumableSessions,
+    freshness: {
+      ...current.freshness,
+      auto: withFreshnessSucceeded(current.freshness.auto),
+      workspace: withFreshnessSucceeded(current.freshness.workspace),
+      recovery: withFreshnessSucceeded(current.freshness.recovery),
+      resumableSessions: withFreshnessSucceeded(current.freshness.resumableSessions),
+    },
+    softBootRefreshCount: current.softBootRefreshCount + (options.soft ? 1 : 0),
+  }
+
+  next.recoverySummary = createWorkspaceRecoverySummary({ boot, live: next })
+  return next
+}
+
+function createInitialState(): WorkspaceStoreState {
+  return {
+    bootStatus: "idle",
+    connectionState: "idle",
+    boot: null,
+    live: createInitialWorkspaceLiveState(),
+    terminalLines: [createTerminalLine("system", "Preparing the live SF workspace…")],
+    lastClientError: null,
+    lastBridgeError: null,
+    sessionAttached: false,
+    lastEventType: null,
+    commandInFlight: null,
+    lastSlashCommandOutcome: null,
+    commandSurface: createInitialCommandSurfaceState(),
+    onboardingRequestState: "idle",
+    onboardingRequestProviderId: null,
+    // Live interaction state
+    pendingUiRequests: [],
+    streamingAssistantText: "",
+    streamingThinkingText: "",
+    liveTranscript: [],
+    liveThinkingTranscript: [],
+    completedToolExecutions: [],
+    activeToolExecution: null,
+    currentTurnSegments: [],
+    completedTurnSegments: [],
+    chatUserMessages: [],
+    statusTexts: {},
+    widgetContents: {},
+    titleOverride: null,
+    editorTextBuffer: null,
+  }
+}
+
+export function buildProjectUrl(path: string, projectCwd?: string): string {
+  if (!projectCwd) return path
+  const url = new URL(path, "http://localhost")
+  url.searchParams.set("project", projectCwd)
+  return url.pathname + url.search
+}
+
+export class SFWorkspaceStore {
+  constructor(private readonly projectCwd?: string) {}
+
+  private buildUrl(path: string): string {
+    return buildProjectUrl(path, this.projectCwd)
+  }
+
+  private state = createInitialState()
+  private readonly listeners = new Set<() => void>()
+  private readonly contextualTips = new ContextualTips()
+  private bootPromise: Promise<void> | null = null
+  private eventSource: EventSource | null = null
+  private onboardingPollTimer: ReturnType<typeof setInterval> | null = null
+  private started = false
+  private disposed = false
+  private lastBridgeDigest: string | null = null
+  private lastStreamState: WorkspaceConnectionState = "idle"
+  private commandTimeoutTimer: ReturnType<typeof setTimeout> | null = null
+  private lastBootRefreshAt = 0
+  private visibilityHandler: (() => void) | null = null
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  getSnapshot = (): WorkspaceStoreState => this.state
+
+  start = (): void => {
+    if (this.started || this.disposed) return
+    this.started = true
+
+    if (typeof document !== "undefined") {
+      this.visibilityHandler = () => {
+        if (document.visibilityState === "visible" && Date.now() - this.lastBootRefreshAt >= VISIBILITY_REFRESH_THRESHOLD_MS) {
+          void this.refreshBoot({ soft: true })
+        }
+      }
+      document.addEventListener("visibilitychange", this.visibilityHandler)
+    }
+
+    void this.refreshBoot()
+  }
+
+  dispose = (): void => {
+    this.disposed = true
+    this.started = false
+    this.stopOnboardingPoller()
+    this.closeEventStream()
+    this.clearCommandTimeout()
+    if (this.visibilityHandler && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.visibilityHandler)
+      this.visibilityHandler = null
+    }
+  }
+
+  disconnectSSE = (): void => {
+    this.closeEventStream()
+  }
+
+  reconnectSSE = (): void => {
+    if (this.disposed) return
+    this.ensureEventStream()
+    void this.refreshBoot({ soft: true })
+  }
+
+  clearTerminalLines = (): void => {
+    const replacement = this.state.boot ? bootSeedLines(this.state.boot) : [createTerminalLine("system", "Terminal cleared")]
+    this.patchState({ terminalLines: replacement })
+  }
+
+  consumeEditorTextBuffer = (): string | null => {
+    const next = this.state.editorTextBuffer
+    if (next !== null) {
+      this.patchState({ editorTextBuffer: null })
+    }
+    return next
+  }
+
+  openCommandSurface = (
+    surface: BrowserSlashCommandSurface,
+    options: { source?: "slash" | "sidebar" | "surface"; args?: string; selectedTarget?: CommandSurfaceTarget | null } = {},
+  ): void => {
+    const resumableSessions = getLiveResumableSessions(this.state)
+    this.patchState({
+      commandSurface: openCommandSurfaceState(this.state.commandSurface, {
+        surface,
+        source: options.source ?? "surface",
+        args: options.args ?? "",
+        selectedTarget: options.selectedTarget,
+        onboardingLocked: this.state.boot?.onboarding.locked,
+        currentModel: getCurrentModelSelection(this.state.boot?.bridge),
+        currentThinkingLevel: this.state.boot?.bridge.sessionState?.thinkingLevel ?? null,
+        preferredProviderId: getPreferredOnboardingProviderId(this.state.boot?.onboarding),
+        resumableSessions: resumableSessions.map((session) => ({
+          id: session.id,
+          path: session.path,
+          name: session.name,
+          isActive: session.isActive,
+        })),
+        currentSessionPath: this.state.boot?.bridge.activeSessionFile ?? this.state.boot?.bridge.sessionState?.sessionFile ?? null,
+        currentSessionName: this.state.boot?.bridge.sessionState?.sessionName ?? null,
+        projectCwd: this.state.boot?.project.cwd ?? null,
+        projectSessionsDir: this.state.boot?.project.sessionsDir ?? null,
+      }),
+    })
+  }
+
+  closeCommandSurface = (): void => {
+    this.patchState({
+      commandSurface: closeCommandSurfaceState(this.state.commandSurface),
+    })
+  }
+
+  setCommandSurfaceSection = (section: CommandSurfaceSection): void => {
+    const resumableSessions = getLiveResumableSessions(this.state)
+    this.patchState({
+      commandSurface: setCommandSurfaceSection(this.state.commandSurface, section, {
+        onboardingLocked: this.state.boot?.onboarding.locked,
+        currentModel: getCurrentModelSelection(this.state.boot?.bridge),
+        currentThinkingLevel: this.state.boot?.bridge.sessionState?.thinkingLevel ?? null,
+        preferredProviderId: getPreferredOnboardingProviderId(this.state.boot?.onboarding),
+        resumableSessions: resumableSessions.map((session) => ({
+          id: session.id,
+          path: session.path,
+          name: session.name,
+          isActive: session.isActive,
+        })),
+        currentSessionPath: this.state.boot?.bridge.activeSessionFile ?? this.state.boot?.bridge.sessionState?.sessionFile ?? null,
+        currentSessionName: this.state.boot?.bridge.sessionState?.sessionName ?? null,
+        projectCwd: this.state.boot?.project.cwd ?? null,
+        projectSessionsDir: this.state.boot?.project.sessionsDir ?? null,
+      }),
+    })
+  }
+
+  selectCommandSurfaceTarget = (target: CommandSurfaceTarget): void => {
+    this.patchState({
+      commandSurface: selectCommandSurfaceStateTarget(this.state.commandSurface, target),
+    })
+  }
+
+  loadGitSummary = async (): Promise<GitSummaryResponse | null> => {
+    const requestedGitSummary: CommandSurfaceGitSummaryState = {
+      ...this.state.commandSurface.gitSummary,
+      pending: true,
+      error: null,
+    }
+
+    const requestedLive: WorkspaceLiveState = {
+      ...this.state.live,
+      freshness: {
+        ...this.state.live.freshness,
+        gitSummary: withFreshnessRequested(this.state.live.freshness.gitSummary),
+      },
+    }
+
+    this.patchState({
+      live: {
+        ...requestedLive,
+        recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: requestedLive }),
+      },
+      commandSurface: setCommandSurfacePending(
+        {
+          ...this.state.commandSurface,
+          gitSummary: requestedGitSummary,
+        },
+        "load_git_summary",
+      ),
+    })
+
+    try {
+      const response = await authFetch(this.buildUrl("/api/git"), {
+        method: "GET",
+        cache: "no-store",
+        headers: {
+          Accept: "application/json",
+        },
+      })
+
+      const payload = await response.json().catch(() => null)
+      const normalizedGitSummary = normalizeGitSummaryPayload(payload)
+      if (!response.ok || !normalizedGitSummary) {
+        const message =
+          payload && typeof payload === "object" && "error" in payload && typeof payload.error === "string"
+            ? payload.error
+            : `Current-project git summary failed with ${response.status}`
+        const failedGitSummary = normalizeGitSummaryError(requestedGitSummary, message)
+        const failedLive: WorkspaceLiveState = {
+          ...this.state.live,
+          freshness: {
+            ...this.state.live.freshness,
+            gitSummary: withFreshnessFailed(this.state.live.freshness.gitSummary, message),
+          },
+        }
+        this.patchState({
+          live: {
+            ...failedLive,
+            recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: failedLive }),
+          },
+          commandSurface: applyCommandSurfaceActionResult(
+            {
+              ...this.state.commandSurface,
+              gitSummary: failedGitSummary,
+            },
+            {
+              action: "load_git_summary",
+              success: false,
+              message,
+              gitSummary: failedGitSummary,
+            },
+          ),
+        })
+        return null
+      }
+
+      const gitSummary: CommandSurfaceGitSummaryState = {
+        pending: false,
+        loaded: true,
+        result: normalizedGitSummary,
+        error: null,
+      }
+
+      const nextLive: WorkspaceLiveState = {
+        ...this.state.live,
+        freshness: {
+          ...this.state.live.freshness,
+          gitSummary: withFreshnessSucceeded(this.state.live.freshness.gitSummary),
+        },
+      }
+
+      this.patchState({
+        live: {
+          ...nextLive,
+          recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: nextLive }),
+        },
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "load_git_summary",
+          success: true,
+          message: "",
+          gitSummary,
+        }),
+      })
+
+      return normalizedGitSummary
+    } catch (error) {
+      const message = normalizeClientError(error)
+      const failedGitSummary = normalizeGitSummaryError(requestedGitSummary, message)
+      const failedLive: WorkspaceLiveState = {
+        ...this.state.live,
+        freshness: {
+          ...this.state.live.freshness,
+          gitSummary: withFreshnessFailed(this.state.live.freshness.gitSummary, message),
+        },
+      }
+      this.patchState({
+        live: {
+          ...failedLive,
+          recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: failedLive }),
+        },
+        commandSurface: applyCommandSurfaceActionResult(
+          {
+            ...this.state.commandSurface,
+            gitSummary: failedGitSummary,
+          },
+          {
+            action: "load_git_summary",
+            success: false,
+            message,
+            gitSummary: failedGitSummary,
+          },
+        ),
+      })
+      return null
+    }
+  }
+
+  loadRecoveryDiagnostics = async (): Promise<WorkspaceRecoveryDiagnostics | null> => {
+    const requestedRecovery = markRecoveryStatePending(this.state.commandSurface.recovery)
+    const requestedLive: WorkspaceLiveState = {
+      ...this.state.live,
+      freshness: {
+        ...this.state.live.freshness,
+        recovery: withFreshnessRequested(this.state.live.freshness.recovery),
+      },
+    }
+
+    this.patchState({
+      live: {
+        ...requestedLive,
+        recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: requestedLive }),
+      },
+      commandSurface: setCommandSurfacePending(
+        {
+          ...this.state.commandSurface,
+          recovery: requestedRecovery,
+        },
+        "load_recovery_diagnostics",
+      ),
+    })
+
+    try {
+      const response = await authFetch(this.buildUrl("/api/recovery"), {
+        method: "GET",
+        cache: "no-store",
+        headers: {
+          Accept: "application/json",
+        },
+      })
+
+      const payload = await response.json().catch(() => null)
+      const diagnostics = normalizeRecoveryDiagnosticsPayload(payload)
+      if (!response.ok || !diagnostics) {
+        const message =
+          payload && typeof payload === "object" && "error" in payload && typeof payload.error === "string"
+            ? payload.error
+            : `Recovery diagnostics failed with ${response.status}`
+        const failedRecovery = markRecoveryStateFailure(requestedRecovery, message)
+        const failedLive: WorkspaceLiveState = {
+          ...this.state.live,
+          freshness: {
+            ...this.state.live.freshness,
+            recovery: withFreshnessFailed(this.state.live.freshness.recovery, message),
+          },
+        }
+        this.patchState({
+          lastClientError: message,
+          live: {
+            ...failedLive,
+            recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: failedLive }),
+          },
+          commandSurface: applyCommandSurfaceActionResult(
+            {
+              ...this.state.commandSurface,
+              recovery: failedRecovery,
+            },
+            {
+              action: "load_recovery_diagnostics",
+              success: false,
+              message,
+              recovery: failedRecovery,
+            },
+          ),
+        })
+        return null
+      }
+
+      const recovery = {
+        ...createRecoveryStateFromDiagnostics(diagnostics),
+        lastInvalidatedAt: this.state.commandSurface.recovery.lastInvalidatedAt,
+      }
+      const nextLive: WorkspaceLiveState = {
+        ...this.state.live,
+        freshness: {
+          ...this.state.live.freshness,
+          recovery: withFreshnessSucceeded(this.state.live.freshness.recovery),
+        },
+      }
+
+      this.patchState({
+        lastClientError: null,
+        live: {
+          ...nextLive,
+          recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: nextLive }),
+        },
+        commandSurface: applyCommandSurfaceActionResult(
+          {
+            ...this.state.commandSurface,
+            recovery,
+          },
+          {
+            action: "load_recovery_diagnostics",
+            success: true,
+            message:
+              diagnostics.status === "ready"
+                ? "Recovery diagnostics refreshed"
+                : "Recovery diagnostics are currently unavailable",
+            recovery,
+          },
+        ),
+      })
+
+      return diagnostics
+    } catch (error) {
+      const message = normalizeClientError(error)
+      const failedRecovery = markRecoveryStateFailure(requestedRecovery, message)
+      const failedLive: WorkspaceLiveState = {
+        ...this.state.live,
+        freshness: {
+          ...this.state.live.freshness,
+          recovery: withFreshnessFailed(this.state.live.freshness.recovery, message),
+        },
+      }
+      this.patchState({
+        lastClientError: message,
+        live: {
+          ...failedLive,
+          recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: failedLive }),
+        },
+        commandSurface: applyCommandSurfaceActionResult(
+          {
+            ...this.state.commandSurface,
+            recovery: failedRecovery,
+          },
+          {
+            action: "load_recovery_diagnostics",
+            success: false,
+            message,
+            recovery: failedRecovery,
+          },
+        ),
+      })
+      return null
+    }
+  }
+
+  // ─── Diagnostics panel fetch methods ────────────────────────────────────────
+
+  private patchDiagnosticsPhaseState<K extends "forensics" | "skillHealth">(
+    key: K,
+    patch: Partial<CommandSurfaceDiagnosticsPhaseState<K extends "forensics" ? ForensicReport : SkillHealthReport>>,
+  ): void {
+    this.patchState({
+      commandSurface: {
+        ...this.state.commandSurface,
+        diagnostics: {
+          ...this.state.commandSurface.diagnostics,
+          [key]: { ...this.state.commandSurface.diagnostics[key], ...patch },
+        },
+      },
+    })
+  }
+
+  private patchDoctorState(patch: Partial<CommandSurfaceDoctorState>): void {
+    this.patchState({
+      commandSurface: {
+        ...this.state.commandSurface,
+        diagnostics: {
+          ...this.state.commandSurface.diagnostics,
+          doctor: { ...this.state.commandSurface.diagnostics.doctor, ...patch },
+        },
+      },
+    })
+  }
+
+  private patchKnowledgeCapturesState(patch: Partial<CommandSurfaceKnowledgeCapturesState>): void {
+    this.patchState({
+      commandSurface: {
+        ...this.state.commandSurface,
+        knowledgeCaptures: { ...this.state.commandSurface.knowledgeCaptures, ...patch },
+      },
+    })
+  }
+
+  private patchKnowledgeCapturesPhaseState<K extends "knowledge" | "captures">(
+    key: K,
+    patch: Partial<CommandSurfaceDiagnosticsPhaseState<K extends "knowledge" ? KnowledgeData : CapturesData>>,
+  ): void {
+    this.patchState({
+      commandSurface: {
+        ...this.state.commandSurface,
+        knowledgeCaptures: {
+          ...this.state.commandSurface.knowledgeCaptures,
+          [key]: { ...this.state.commandSurface.knowledgeCaptures[key], ...patch },
+        },
+      },
+    })
+  }
+
+  private patchSettingsPhaseState(patch: Partial<CommandSurfaceDiagnosticsPhaseState<SettingsData>>): void {
+    this.patchState({
+      commandSurface: {
+        ...this.state.commandSurface,
+        settingsData: { ...this.state.commandSurface.settingsData, ...patch },
+      },
+    })
+  }
+
+  private patchRemainingCommandsPhaseState<
+    K extends keyof import("./command-surface-contract").CommandSurfaceRemainingState,
+  >(
+    key: K,
+    patch: Partial<CommandSurfaceDiagnosticsPhaseState<import("./command-surface-contract").CommandSurfaceRemainingState[K] extends CommandSurfaceDiagnosticsPhaseState<infer T> ? T : never>>,
+  ): void {
+    this.patchState({
+      commandSurface: {
+        ...this.state.commandSurface,
+        remainingCommands: {
+          ...this.state.commandSurface.remainingCommands,
+          [key]: { ...this.state.commandSurface.remainingCommands[key], ...patch },
+        },
+      },
+    })
+  }
+
+  loadForensicsDiagnostics = async (): Promise<ForensicReport | null> => {
+    this.patchDiagnosticsPhaseState("forensics", { phase: "loading", error: null })
+    try {
+      const response = await authFetch(this.buildUrl("/api/forensics"), { method: "GET", cache: "no-store", headers: { Accept: "application/json" } })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Forensics request failed with ${response.status}`
+        this.patchDiagnosticsPhaseState("forensics", { phase: "error", error: message })
+        return null
+      }
+      this.patchDiagnosticsPhaseState("forensics", { phase: "loaded", data: payload as ForensicReport, lastLoadedAt: new Date().toISOString() })
+      return payload as ForensicReport
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchDiagnosticsPhaseState("forensics", { phase: "error", error: message })
+      return null
+    }
+  }
+
+  loadDoctorDiagnostics = async (scope?: string): Promise<DoctorReport | null> => {
+    this.patchDoctorState({ phase: "loading", error: null })
+    try {
+      const url = scope ? `/api/doctor?scope=${encodeURIComponent(scope)}` : "/api/doctor"
+      const response = await authFetch(url, { method: "GET", cache: "no-store", headers: { Accept: "application/json" } })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Doctor request failed with ${response.status}`
+        this.patchDoctorState({ phase: "error", error: message })
+        return null
+      }
+      this.patchDoctorState({ phase: "loaded", data: payload as DoctorReport, lastLoadedAt: new Date().toISOString() })
+      return payload as DoctorReport
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchDoctorState({ phase: "error", error: message })
+      return null
+    }
+  }
+
+  applyDoctorFixes = async (scope?: string): Promise<DoctorFixResult | null> => {
+    this.patchDoctorState({ fixPending: true, lastFixError: null, lastFixResult: null })
+    try {
+      const response = await authFetch(this.buildUrl("/api/doctor"), {
+        method: "POST",
+        cache: "no-store",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify(scope ? { scope } : {}),
+      })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Doctor fix request failed with ${response.status}`
+        this.patchDoctorState({ fixPending: false, lastFixError: message })
+        return null
+      }
+      const fixResult = payload as DoctorFixResult
+      this.patchDoctorState({ fixPending: false, lastFixResult: fixResult })
+      // Reload doctor data after applying fixes so the issue list refreshes
+      void this.loadDoctorDiagnostics(scope)
+      return fixResult
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchDoctorState({ fixPending: false, lastFixError: message })
+      return null
+    }
+  }
+
+  loadSkillHealthDiagnostics = async (): Promise<SkillHealthReport | null> => {
+    this.patchDiagnosticsPhaseState("skillHealth", { phase: "loading", error: null })
+    try {
+      const response = await authFetch(this.buildUrl("/api/skill-health"), { method: "GET", cache: "no-store", headers: { Accept: "application/json" } })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Skill health request failed with ${response.status}`
+        this.patchDiagnosticsPhaseState("skillHealth", { phase: "error", error: message })
+        return null
+      }
+      this.patchDiagnosticsPhaseState("skillHealth", { phase: "loaded", data: payload as SkillHealthReport, lastLoadedAt: new Date().toISOString() })
+      return payload as SkillHealthReport
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchDiagnosticsPhaseState("skillHealth", { phase: "error", error: message })
+      return null
+    }
+  }
+
+  loadKnowledgeData = async (): Promise<KnowledgeData | null> => {
+    this.patchKnowledgeCapturesPhaseState("knowledge", { phase: "loading", error: null })
+    try {
+      const response = await authFetch(this.buildUrl("/api/knowledge"), { method: "GET", cache: "no-store", headers: { Accept: "application/json" } })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Knowledge request failed with ${response.status}`
+        this.patchKnowledgeCapturesPhaseState("knowledge", { phase: "error", error: message })
+        return null
+      }
+      this.patchKnowledgeCapturesPhaseState("knowledge", { phase: "loaded", data: payload as KnowledgeData, lastLoadedAt: new Date().toISOString() })
+      return payload as KnowledgeData
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchKnowledgeCapturesPhaseState("knowledge", { phase: "error", error: message })
+      return null
+    }
+  }
+
+  loadCapturesData = async (): Promise<CapturesData | null> => {
+    this.patchKnowledgeCapturesPhaseState("captures", { phase: "loading", error: null })
+    try {
+      const response = await authFetch(this.buildUrl("/api/captures"), { method: "GET", cache: "no-store", headers: { Accept: "application/json" } })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Captures request failed with ${response.status}`
+        this.patchKnowledgeCapturesPhaseState("captures", { phase: "error", error: message })
+        return null
+      }
+      this.patchKnowledgeCapturesPhaseState("captures", { phase: "loaded", data: payload as CapturesData, lastLoadedAt: new Date().toISOString() })
+      return payload as CapturesData
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchKnowledgeCapturesPhaseState("captures", { phase: "error", error: message })
+      return null
+    }
+  }
+
+  loadSettingsData = async (): Promise<SettingsData | null> => {
+    this.patchSettingsPhaseState({ phase: "loading", error: null })
+    try {
+      const response = await authFetch(this.buildUrl("/api/settings-data"), { method: "GET", cache: "no-store", headers: { Accept: "application/json" } })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Settings request failed with ${response.status}`
+        this.patchSettingsPhaseState({ phase: "error", error: message })
+        return null
+      }
+      this.patchSettingsPhaseState({ phase: "loaded", data: payload as SettingsData, lastLoadedAt: new Date().toISOString() })
+      return payload as SettingsData
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchSettingsPhaseState({ phase: "error", error: message })
+      return null
+    }
+  }
+
+  // ─── Remaining command surface load/mutation methods ──────────────────────────
+
+  loadHistoryData = async (): Promise<HistoryData | null> => {
+    this.patchRemainingCommandsPhaseState("history", { phase: "loading", error: null })
+    try {
+      const response = await authFetch(this.buildUrl("/api/history"), { method: "GET", cache: "no-store", headers: { Accept: "application/json" } })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `History request failed with ${response.status}`
+        this.patchRemainingCommandsPhaseState("history", { phase: "error", error: message })
+        return null
+      }
+      this.patchRemainingCommandsPhaseState("history", { phase: "loaded", data: payload as HistoryData, lastLoadedAt: new Date().toISOString() })
+      return payload as HistoryData
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchRemainingCommandsPhaseState("history", { phase: "error", error: message })
+      return null
+    }
+  }
+
+  loadInspectData = async (): Promise<InspectData | null> => {
+    this.patchRemainingCommandsPhaseState("inspect", { phase: "loading", error: null })
+    try {
+      const response = await authFetch(this.buildUrl("/api/inspect"), { method: "GET", cache: "no-store", headers: { Accept: "application/json" } })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Inspect request failed with ${response.status}`
+        this.patchRemainingCommandsPhaseState("inspect", { phase: "error", error: message })
+        return null
+      }
+      this.patchRemainingCommandsPhaseState("inspect", { phase: "loaded", data: payload as InspectData, lastLoadedAt: new Date().toISOString() })
+      return payload as InspectData
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchRemainingCommandsPhaseState("inspect", { phase: "error", error: message })
+      return null
+    }
+  }
+
+  loadHooksData = async (): Promise<HooksData | null> => {
+    this.patchRemainingCommandsPhaseState("hooks", { phase: "loading", error: null })
+    try {
+      const response = await authFetch(this.buildUrl("/api/hooks"), { method: "GET", cache: "no-store", headers: { Accept: "application/json" } })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Hooks request failed with ${response.status}`
+        this.patchRemainingCommandsPhaseState("hooks", { phase: "error", error: message })
+        return null
+      }
+      this.patchRemainingCommandsPhaseState("hooks", { phase: "loaded", data: payload as HooksData, lastLoadedAt: new Date().toISOString() })
+      return payload as HooksData
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchRemainingCommandsPhaseState("hooks", { phase: "error", error: message })
+      return null
+    }
+  }
+
+  loadExportData = async (format?: "markdown" | "json"): Promise<ExportResult | null> => {
+    this.patchRemainingCommandsPhaseState("exportData", { phase: "loading", error: null })
+    try {
+      const url = format ? `/api/export-data?format=${encodeURIComponent(format)}` : "/api/export-data"
+      const response = await authFetch(url, { method: "GET", cache: "no-store", headers: { Accept: "application/json" } })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Export request failed with ${response.status}`
+        this.patchRemainingCommandsPhaseState("exportData", { phase: "error", error: message })
+        return null
+      }
+      this.patchRemainingCommandsPhaseState("exportData", { phase: "loaded", data: payload as ExportResult, lastLoadedAt: new Date().toISOString() })
+      return payload as ExportResult
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchRemainingCommandsPhaseState("exportData", { phase: "error", error: message })
+      return null
+    }
+  }
+
+  loadUndoInfo = async (): Promise<UndoInfo | null> => {
+    this.patchRemainingCommandsPhaseState("undo", { phase: "loading", error: null })
+    try {
+      const response = await authFetch(this.buildUrl("/api/undo"), { method: "GET", cache: "no-store", headers: { Accept: "application/json" } })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Undo info request failed with ${response.status}`
+        this.patchRemainingCommandsPhaseState("undo", { phase: "error", error: message })
+        return null
+      }
+      this.patchRemainingCommandsPhaseState("undo", { phase: "loaded", data: payload as UndoInfo, lastLoadedAt: new Date().toISOString() })
+      return payload as UndoInfo
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchRemainingCommandsPhaseState("undo", { phase: "error", error: message })
+      return null
+    }
+  }
+
+  loadCleanupData = async (): Promise<CleanupData | null> => {
+    this.patchRemainingCommandsPhaseState("cleanup", { phase: "loading", error: null })
+    try {
+      const response = await authFetch(this.buildUrl("/api/cleanup"), { method: "GET", cache: "no-store", headers: { Accept: "application/json" } })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Cleanup data request failed with ${response.status}`
+        this.patchRemainingCommandsPhaseState("cleanup", { phase: "error", error: message })
+        return null
+      }
+      this.patchRemainingCommandsPhaseState("cleanup", { phase: "loaded", data: payload as CleanupData, lastLoadedAt: new Date().toISOString() })
+      return payload as CleanupData
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchRemainingCommandsPhaseState("cleanup", { phase: "error", error: message })
+      return null
+    }
+  }
+
+  loadSteerData = async (): Promise<SteerData | null> => {
+    this.patchRemainingCommandsPhaseState("steer", { phase: "loading", error: null })
+    try {
+      const response = await authFetch(this.buildUrl("/api/steer"), { method: "GET", cache: "no-store", headers: { Accept: "application/json" } })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Steer data request failed with ${response.status}`
+        this.patchRemainingCommandsPhaseState("steer", { phase: "error", error: message })
+        return null
+      }
+      this.patchRemainingCommandsPhaseState("steer", { phase: "loaded", data: payload as SteerData, lastLoadedAt: new Date().toISOString() })
+      return payload as SteerData
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchRemainingCommandsPhaseState("steer", { phase: "error", error: message })
+      return null
+    }
+  }
+
+  executeUndoAction = async (): Promise<UndoResult | null> => {
+    try {
+      const response = await authFetch(this.buildUrl("/api/undo"), {
+        method: "POST",
+        cache: "no-store",
+        headers: { Accept: "application/json" },
+      })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Undo action failed with ${response.status}`
+        return { success: false, message }
+      }
+      // Reload undo info after executing
+      void this.loadUndoInfo()
+      return payload as UndoResult
+    } catch (error) {
+      const message = normalizeClientError(error)
+      return { success: false, message }
+    }
+  }
+
+  executeCleanupAction = async (branches: string[], snapshots: string[]): Promise<CleanupResult | null> => {
+    try {
+      const response = await authFetch(this.buildUrl("/api/cleanup"), {
+        method: "POST",
+        cache: "no-store",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({ branches, snapshots }),
+      })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Cleanup action failed with ${response.status}`
+        return { deletedBranches: 0, prunedSnapshots: 0, message }
+      }
+      // Reload cleanup data after executing
+      void this.loadCleanupData()
+      return payload as CleanupResult
+    } catch (error) {
+      const message = normalizeClientError(error)
+      return { deletedBranches: 0, prunedSnapshots: 0, message }
+    }
+  }
+
+  resolveCaptureAction = async (request: CaptureResolveRequest): Promise<CaptureResolveResult | null> => {
+    this.patchKnowledgeCapturesState({ resolveRequest: { pending: true, lastError: null, lastResult: null } })
+    try {
+      const response = await authFetch(this.buildUrl("/api/captures"), {
+        method: "POST",
+        cache: "no-store",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify(request),
+      })
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload) {
+        const message = payload?.error ?? `Capture resolve failed with ${response.status}`
+        this.patchKnowledgeCapturesState({ resolveRequest: { pending: false, lastError: message, lastResult: null } })
+        return null
+      }
+      const result = payload as CaptureResolveResult
+      this.patchKnowledgeCapturesState({ resolveRequest: { pending: false, lastError: null, lastResult: result } })
+      // Auto-reload captures after successful resolve
+      void this.loadCapturesData()
+      return result
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchKnowledgeCapturesState({ resolveRequest: { pending: false, lastError: message, lastResult: null } })
+      return null
+    }
+  }
+
+  updateSessionBrowserState = (
+    patch: Partial<Pick<CommandSurfaceSessionBrowserState, "query" | "sortMode" | "nameFilter">>,
+  ): void => {
+    this.patchState({
+      commandSurface: {
+        ...this.state.commandSurface,
+        sessionBrowser: {
+          ...this.state.commandSurface.sessionBrowser,
+          ...patch,
+          error: null,
+        },
+        lastError: null,
+        lastResult: null,
+      },
+    })
+  }
+
+  loadSessionBrowser = async (
+    overrides: Partial<Pick<CommandSurfaceSessionBrowserState, "query" | "sortMode" | "nameFilter">> = {},
+  ): Promise<CommandSurfaceSessionBrowserState | null> => {
+    const requestedSessionBrowser = {
+      ...this.state.commandSurface.sessionBrowser,
+      ...overrides,
+      error: null,
+    }
+
+    const requestedLive: WorkspaceLiveState = {
+      ...this.state.live,
+      freshness: {
+        ...this.state.live.freshness,
+        sessionBrowser: withFreshnessRequested(this.state.live.freshness.sessionBrowser),
+      },
+    }
+
+    this.patchState({
+      live: {
+        ...requestedLive,
+        recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: requestedLive }),
+      },
+      commandSurface: setCommandSurfacePending(
+        {
+          ...this.state.commandSurface,
+          sessionBrowser: requestedSessionBrowser,
+        },
+        "load_session_browser",
+      ),
+    })
+
+    const params = new URLSearchParams()
+    if (requestedSessionBrowser.query.trim()) {
+      params.set("query", requestedSessionBrowser.query.trim())
+    }
+    params.set("sortMode", requestedSessionBrowser.sortMode)
+    params.set("nameFilter", requestedSessionBrowser.nameFilter)
+
+    try {
+      const response = await authFetch(this.buildUrl(`/api/session/browser?${params.toString()}`), {
+        method: "GET",
+        cache: "no-store",
+        headers: {
+          Accept: "application/json",
+        },
+      })
+
+      const payload = await response.json().catch(() => null)
+      const normalizedSessionBrowser = normalizeSessionBrowserPayload(payload)
+      if (!response.ok || !normalizedSessionBrowser) {
+        const message =
+          payload && typeof payload === "object" && "error" in payload && typeof payload.error === "string"
+            ? payload.error
+            : `Current-project session browser failed with ${response.status}`
+        const failedSessionBrowser = {
+          ...requestedSessionBrowser,
+          error: message,
+        }
+        const failedLive: WorkspaceLiveState = {
+          ...this.state.live,
+          freshness: {
+            ...this.state.live.freshness,
+            sessionBrowser: withFreshnessFailed(this.state.live.freshness.sessionBrowser, message),
+          },
+        }
+        this.patchState({
+          live: {
+            ...failedLive,
+            recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: failedLive }),
+          },
+          commandSurface: applyCommandSurfaceActionResult(
+            {
+              ...this.state.commandSurface,
+              sessionBrowser: failedSessionBrowser,
+            },
+            {
+              action: "load_session_browser",
+              success: false,
+              message,
+              sessionBrowser: failedSessionBrowser,
+            },
+          ),
+        })
+        return null
+      }
+
+      const sessionBrowser = syncSessionBrowserStateWithBridge(normalizedSessionBrowser, this.state.boot)
+      const currentTarget = this.state.commandSurface.selectedTarget
+      const defaultResumePath = sessionBrowser.sessions.find((session) => !session.isActive)?.path ?? sessionBrowser.sessions[0]?.path
+      const defaultRenameSession =
+        sessionBrowser.sessions.find((session) => session.path === sessionBrowser.activeSessionPath) ?? sessionBrowser.sessions[0]
+
+      let selectedTarget = currentTarget
+      if (currentTarget?.kind === "resume" || this.state.commandSurface.section === "resume") {
+        const visiblePath =
+          currentTarget?.kind === "resume" && currentTarget.sessionPath && sessionBrowser.sessions.some((session) => session.path === currentTarget.sessionPath)
+            ? currentTarget.sessionPath
+            : defaultResumePath
+        selectedTarget = { kind: "resume", sessionPath: visiblePath }
+      } else if (currentTarget?.kind === "name" || this.state.commandSurface.section === "name") {
+        const visibleSession =
+          currentTarget?.kind === "name" && currentTarget.sessionPath
+            ? sessionBrowser.sessions.find((session) => session.path === currentTarget.sessionPath) ?? defaultRenameSession
+            : defaultRenameSession
+        selectedTarget = {
+          kind: "name",
+          sessionPath: visibleSession?.path,
+          name:
+            currentTarget?.kind === "name" && currentTarget.sessionPath === visibleSession?.path
+              ? currentTarget.name
+              : visibleSession?.name ?? "",
+        }
+      }
+
+      const nextLive: WorkspaceLiveState = {
+        ...this.state.live,
+        freshness: {
+          ...this.state.live.freshness,
+          sessionBrowser: withFreshnessSucceeded(this.state.live.freshness.sessionBrowser),
+        },
+      }
+
+      this.patchState({
+        live: {
+          ...nextLive,
+          recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: nextLive }),
+        },
+        commandSurface: applyCommandSurfaceActionResult(
+          {
+            ...this.state.commandSurface,
+            sessionBrowser,
+          },
+          {
+            action: "load_session_browser",
+            success: true,
+            message: "",
+            selectedTarget,
+            sessionBrowser,
+          },
+        ),
+      })
+
+      return sessionBrowser
+    } catch (error) {
+      const message = normalizeClientError(error)
+      const failedSessionBrowser = {
+        ...requestedSessionBrowser,
+        error: message,
+      }
+      const failedLive: WorkspaceLiveState = {
+        ...this.state.live,
+        freshness: {
+          ...this.state.live.freshness,
+          sessionBrowser: withFreshnessFailed(this.state.live.freshness.sessionBrowser, message),
+        },
+      }
+      this.patchState({
+        live: {
+          ...failedLive,
+          recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: failedLive }),
+        },
+        commandSurface: applyCommandSurfaceActionResult(
+          {
+            ...this.state.commandSurface,
+            sessionBrowser: failedSessionBrowser,
+          },
+          {
+            action: "load_session_browser",
+            success: false,
+            message,
+            sessionBrowser: failedSessionBrowser,
+          },
+        ),
+      })
+      return null
+    }
+  }
+
+  renameSessionFromSurface = async (sessionPath: string, name?: string): Promise<SessionManageResponse | null> => {
+    const currentTarget = this.state.commandSurface.selectedTarget
+    const requestedName = name ?? (currentTarget?.kind === "name" ? currentTarget.name : "")
+    const trimmedName = requestedName.trim()
+    const selectedTarget: CommandSurfaceTarget = { kind: "name", sessionPath, name: requestedName }
+
+    if (!trimmedName) {
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "rename_session",
+          success: false,
+          message: "Session name cannot be empty",
+          selectedTarget,
+        }),
+      })
+      return null
+    }
+
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "rename_session", selectedTarget),
+    })
+
+    try {
+      const response = await authFetch(this.buildUrl("/api/session/manage"), {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+        },
+        body: JSON.stringify({
+          action: "rename",
+          sessionPath,
+          name: trimmedName,
+        }),
+      })
+
+      const payload = await response.json().catch(() => null)
+      if (!response.ok || !payload || typeof payload !== "object" || payload.success !== true) {
+        const message =
+          payload && typeof payload === "object" && "error" in payload && typeof payload.error === "string"
+            ? payload.error
+            : `Session rename failed with ${response.status}`
+        this.patchState({
+          commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+            action: "rename_session",
+            success: false,
+            message,
+            selectedTarget,
+          }),
+        })
+        return null
+      }
+
+      const result = payload as SessionManageResponse & { success: true }
+      const nextBoot = patchBootSessionName(this.state.boot, result.sessionPath, result.name)
+      const nextSessionBrowser = syncSessionBrowserStateWithBridge(
+        patchSessionBrowserSession(this.state.commandSurface.sessionBrowser, result.sessionPath, {
+          name: result.name,
+          ...(result.isActiveSession ? { isActive: true } : {}),
+        }),
+        nextBoot,
+      )
+      const nextSelectedTarget: CommandSurfaceTarget = {
+        kind: "name",
+        sessionPath: result.sessionPath,
+        name: result.name,
+      }
+      const nextLiveBase: WorkspaceLiveState = {
+        ...this.state.live,
+        resumableSessions: overlayLiveBridgeSessionState(
+          getLiveResumableSessions(this.state).map((session) =>
+            session.path === result.sessionPath
+              ? {
+                  ...session,
+                  name: result.name,
+                }
+              : session,
+          ),
+          nextBoot,
+        ),
+      }
+
+      this.patchState({
+        ...(nextBoot ? { boot: nextBoot } : {}),
+        live: {
+          ...nextLiveBase,
+          recoverySummary: createWorkspaceRecoverySummary({ boot: nextBoot, live: nextLiveBase }),
+        },
+        commandSurface: applyCommandSurfaceActionResult(
+          {
+            ...this.state.commandSurface,
+            sessionBrowser: nextSessionBrowser,
+          },
+          {
+            action: "rename_session",
+            success: true,
+            message: `Session name set: ${result.name}`,
+            selectedTarget: nextSelectedTarget,
+            sessionBrowser: nextSessionBrowser,
+          },
+        ),
+      })
+
+      return result
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "rename_session",
+          success: false,
+          message,
+          selectedTarget,
+        }),
+      })
+      return null
+    }
+  }
+
+  loadAvailableModels = async (): Promise<CommandSurfaceModelOption[]> => {
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "loading_models"),
+    })
+
+    const response = await this.sendCommand(
+      { type: "get_available_models" },
+      { appendInputLine: false, appendResponseLine: false },
+    )
+
+    if (!response || response.success === false) {
+      const message = response?.error ?? this.state.lastClientError ?? "Unknown error"
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "loading_models",
+          success: false,
+          message: `Couldn't load models — ${message}`,
+        }),
+      })
+      return []
+    }
+
+    const availableModels = normalizeAvailableModels(response.data, getCurrentModelSelection(this.state.boot?.bridge))
+    const currentTarget = this.state.commandSurface.selectedTarget
+    const selectedTarget =
+      currentTarget?.kind === "model"
+        ? currentTarget
+        : availableModels[0]
+          ? { kind: "model" as const, provider: availableModels[0].provider, modelId: availableModels[0].modelId }
+          : currentTarget
+
+    this.patchState({
+      commandSurface: {
+        ...this.state.commandSurface,
+        pendingAction: null,
+        lastError: null,
+        availableModels,
+        selectedTarget: selectedTarget ?? null,
+      },
+    })
+
+    return availableModels
+  }
+
+  applyModelSelection = async (provider: string, modelId: string): Promise<WorkspaceCommandResponse | null> => {
+    const selectedTarget: CommandSurfaceTarget = { kind: "model", provider, modelId }
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "set_model", selectedTarget),
+    })
+
+    const response = await this.sendCommand(
+      { type: "set_model", provider, modelId },
+      { appendInputLine: false, appendResponseLine: false },
+    )
+
+    if (!response || response.success === false) {
+      const message = response?.error ?? this.state.lastClientError ?? "Unknown error"
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "set_model",
+          success: false,
+          message,
+          selectedTarget,
+        }),
+      })
+      return response
+    }
+
+    const nextBridge = this.state.boot?.bridge.sessionState
+      ? {
+          ...this.state.boot.bridge,
+          sessionState: {
+            ...this.state.boot.bridge.sessionState,
+            model: response.data as WorkspaceModelRef,
+          },
+        }
+      : null
+
+    const nextAvailableModels = this.state.commandSurface.availableModels.map((model) => ({
+      ...model,
+      isCurrent: model.provider === provider && model.modelId === modelId,
+    }))
+
+    this.patchState({
+      ...(nextBridge && this.state.boot ? { boot: cloneBootWithBridge(this.state.boot, nextBridge) } : {}),
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "set_model",
+        success: true,
+        message: `Model set to ${provider}/${modelId}`,
+        selectedTarget,
+        availableModels: nextAvailableModels,
+      }),
+    })
+
+    return response
+  }
+
+  applyThinkingLevel = async (level: CommandSurfaceThinkingLevel): Promise<WorkspaceCommandResponse | null> => {
+    const selectedTarget: CommandSurfaceTarget = { kind: "thinking", level }
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "set_thinking_level", selectedTarget),
+    })
+
+    const response = await this.sendCommand(
+      { type: "set_thinking_level", level },
+      { appendInputLine: false, appendResponseLine: false },
+    )
+
+    if (!response || response.success === false) {
+      const message = response?.error ?? this.state.lastClientError ?? "Unknown error"
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "set_thinking_level",
+          success: false,
+          message,
+          selectedTarget,
+        }),
+      })
+      return response
+    }
+
+    const nextBridge = this.state.boot?.bridge.sessionState
+      ? {
+          ...this.state.boot.bridge,
+          sessionState: {
+            ...this.state.boot.bridge.sessionState,
+            thinkingLevel: level,
+          },
+        }
+      : null
+
+    this.patchState({
+      ...(nextBridge && this.state.boot ? { boot: cloneBootWithBridge(this.state.boot, nextBridge) } : {}),
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "set_thinking_level",
+        success: true,
+        message: `Thinking level set to ${level}`,
+        selectedTarget,
+      }),
+    })
+
+    return response
+  }
+
+  setSteeringModeFromSurface = async (
+    mode: WorkspaceSessionState["steeringMode"],
+  ): Promise<WorkspaceCommandResponse | null> => {
+    const selectedTarget = this.state.commandSurface.selectedTarget
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "set_steering_mode", selectedTarget),
+    })
+
+    const response = await this.sendCommand(
+      { type: "set_steering_mode", mode },
+      { appendInputLine: false, appendResponseLine: false },
+    )
+
+    if (!response || response.success === false) {
+      const message = response?.error ?? this.state.lastClientError ?? "Unknown error"
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "set_steering_mode",
+          success: false,
+          message,
+          selectedTarget,
+        }),
+      })
+      return response
+    }
+
+    const nextBoot = patchBootSessionState(this.state.boot, { steeringMode: mode })
+    this.patchState({
+      ...(nextBoot ? { boot: nextBoot } : {}),
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "set_steering_mode",
+        success: true,
+        message: `Steering mode set to ${mode}`,
+        selectedTarget,
+      }),
+    })
+
+    return response
+  }
+
+  setFollowUpModeFromSurface = async (
+    mode: WorkspaceSessionState["followUpMode"],
+  ): Promise<WorkspaceCommandResponse | null> => {
+    const selectedTarget = this.state.commandSurface.selectedTarget
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "set_follow_up_mode", selectedTarget),
+    })
+
+    const response = await this.sendCommand(
+      { type: "set_follow_up_mode", mode },
+      { appendInputLine: false, appendResponseLine: false },
+    )
+
+    if (!response || response.success === false) {
+      const message = response?.error ?? this.state.lastClientError ?? "Unknown error"
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "set_follow_up_mode",
+          success: false,
+          message,
+          selectedTarget,
+        }),
+      })
+      return response
+    }
+
+    const nextBoot = patchBootSessionState(this.state.boot, { followUpMode: mode })
+    this.patchState({
+      ...(nextBoot ? { boot: nextBoot } : {}),
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "set_follow_up_mode",
+        success: true,
+        message: `Follow-up mode set to ${mode}`,
+        selectedTarget,
+      }),
+    })
+
+    return response
+  }
+
+  setAutoCompactionFromSurface = async (enabled: boolean): Promise<WorkspaceCommandResponse | null> => {
+    const selectedTarget = this.state.commandSurface.selectedTarget
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "set_auto_compaction", selectedTarget),
+    })
+
+    const response = await this.sendCommand(
+      { type: "set_auto_compaction", enabled },
+      { appendInputLine: false, appendResponseLine: false },
+    )
+
+    if (!response || response.success === false) {
+      const message = response?.error ?? this.state.lastClientError ?? "Unknown error"
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "set_auto_compaction",
+          success: false,
+          message,
+          selectedTarget,
+        }),
+      })
+      return response
+    }
+
+    const nextBoot = patchBootSessionState(this.state.boot, { autoCompactionEnabled: enabled })
+    this.patchState({
+      ...(nextBoot ? { boot: nextBoot } : {}),
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "set_auto_compaction",
+        success: true,
+        message: `Auto-compaction ${enabled ? "enabled" : "disabled"}`,
+        selectedTarget,
+      }),
+    })
+
+    return response
+  }
+
+  setAutoRetryFromSurface = async (enabled: boolean): Promise<WorkspaceCommandResponse | null> => {
+    const selectedTarget = this.state.commandSurface.selectedTarget
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "set_auto_retry", selectedTarget),
+    })
+
+    const response = await this.sendCommand(
+      { type: "set_auto_retry", enabled },
+      { appendInputLine: false, appendResponseLine: false },
+    )
+
+    if (!response || response.success === false) {
+      const message = response?.error ?? this.state.lastClientError ?? "Unknown error"
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "set_auto_retry",
+          success: false,
+          message,
+          selectedTarget,
+        }),
+      })
+      return response
+    }
+
+    const nextBoot = patchBootSessionState(this.state.boot, { autoRetryEnabled: enabled })
+    this.patchState({
+      ...(nextBoot ? { boot: nextBoot } : {}),
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "set_auto_retry",
+        success: true,
+        message: `Auto-retry ${enabled ? "enabled" : "disabled"}`,
+        selectedTarget,
+      }),
+    })
+
+    return response
+  }
+
+  abortRetryFromSurface = async (): Promise<WorkspaceCommandResponse | null> => {
+    const selectedTarget = this.state.commandSurface.selectedTarget
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "abort_retry", selectedTarget),
+    })
+
+    const response = await this.sendCommand(
+      { type: "abort_retry" },
+      { appendInputLine: false, appendResponseLine: false },
+    )
+
+    if (!response || response.success === false) {
+      const message = response?.error ?? this.state.lastClientError ?? "Unknown error"
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "abort_retry",
+          success: false,
+          message,
+          selectedTarget,
+        }),
+      })
+      return response
+    }
+
+    this.patchState({
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "abort_retry",
+        success: true,
+        message: "Retry cancellation requested. Live retry state will update when the bridge confirms the abort.",
+        selectedTarget,
+      }),
+    })
+
+    return response
+  }
+
+  switchSessionFromSurface = async (sessionPath: string): Promise<WorkspaceCommandResponse | null> => {
+    const selectedTarget: CommandSurfaceTarget = { kind: "resume", sessionPath }
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "switch_session", selectedTarget),
+    })
+
+    const response = await this.sendCommand(
+      { type: "switch_session", sessionPath },
+      { appendInputLine: false, appendResponseLine: false },
+    )
+
+    if (!response || response.success === false) {
+      const message = response?.error ?? this.state.lastClientError ?? "Unknown error"
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "switch_session",
+          success: false,
+          message,
+          selectedTarget,
+        }),
+      })
+      return response
+    }
+
+    if (response.data && typeof response.data === "object" && "cancelled" in response.data && response.data.cancelled) {
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "switch_session",
+          success: false,
+          message: "Session switch was cancelled before the browser changed sessions.",
+          selectedTarget,
+        }),
+      })
+      return response
+    }
+
+    const nextSessionName =
+      this.state.commandSurface.sessionBrowser.sessions.find((session) => session.path === sessionPath)?.name ??
+      this.state.boot?.resumableSessions.find((session) => session.path === sessionPath)?.name
+    const nextBoot = patchBootActiveSession(this.state.boot, sessionPath, nextSessionName)
+    const nextSessionBrowser = syncSessionBrowserStateWithBridge(
+      patchSessionBrowserSession(this.state.commandSurface.sessionBrowser, sessionPath, {
+        isActive: true,
+        ...(nextSessionName ? { name: nextSessionName } : {}),
+      }),
+      nextBoot,
+    )
+
+    const nextLiveBase: WorkspaceLiveState = {
+      ...this.state.live,
+      resumableSessions: overlayLiveBridgeSessionState(
+        getLiveResumableSessions(this.state).map((session) => ({
+          ...session,
+          isActive: session.path === sessionPath,
+          ...(session.path === sessionPath && nextSessionName ? { name: nextSessionName } : {}),
+        })),
+        nextBoot,
+      ),
+    }
+
+    this.patchState({
+      ...(nextBoot ? { boot: nextBoot } : {}),
+      live: {
+        ...nextLiveBase,
+        recoverySummary: createWorkspaceRecoverySummary({ boot: nextBoot, live: nextLiveBase }),
+      },
+      commandSurface: applyCommandSurfaceActionResult(
+        {
+          ...this.state.commandSurface,
+          sessionBrowser: nextSessionBrowser,
+        },
+        {
+          action: "switch_session",
+          success: true,
+          message: `Switched to ${describeSessionPath(sessionPath, nextBoot ?? this.state.boot)}`,
+          selectedTarget,
+          sessionBrowser: nextSessionBrowser,
+        },
+      ),
+    })
+
+    return response
+  }
+
+  loadSessionStats = async (): Promise<CommandSurfaceSessionStats | null> => {
+    const requestedLive: WorkspaceLiveState = {
+      ...this.state.live,
+      freshness: {
+        ...this.state.live.freshness,
+        sessionStats: withFreshnessRequested(this.state.live.freshness.sessionStats),
+      },
+    }
+
+    this.patchState({
+      live: {
+        ...requestedLive,
+        recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: requestedLive }),
+      },
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "load_session_stats"),
+    })
+
+    const response = await this.sendCommand(
+      { type: "get_session_stats" },
+      { appendInputLine: false, appendResponseLine: false },
+    )
+
+    if (!response || response.success === false) {
+      const message = response?.error ?? this.state.lastClientError ?? "Unknown error"
+      const failedLive: WorkspaceLiveState = {
+        ...this.state.live,
+        freshness: {
+          ...this.state.live.freshness,
+          sessionStats: withFreshnessFailed(this.state.live.freshness.sessionStats, message),
+        },
+      }
+      this.patchState({
+        live: {
+          ...failedLive,
+          recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: failedLive }),
+        },
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "load_session_stats",
+          success: false,
+          message: `Couldn't load session details — ${message}`,
+          sessionStats: null,
+        }),
+      })
+      return null
+    }
+
+    const sessionStats = normalizeSessionStats(response.data)
+    if (!sessionStats) {
+      const message = "Session details response was missing the expected fields."
+      const failedLive: WorkspaceLiveState = {
+        ...this.state.live,
+        freshness: {
+          ...this.state.live.freshness,
+          sessionStats: withFreshnessFailed(this.state.live.freshness.sessionStats, message),
+        },
+      }
+      this.patchState({
+        live: {
+          ...failedLive,
+          recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: failedLive }),
+        },
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "load_session_stats",
+          success: false,
+          message,
+          sessionStats: null,
+        }),
+      })
+      return null
+    }
+
+    const nextLive: WorkspaceLiveState = {
+      ...this.state.live,
+      freshness: {
+        ...this.state.live.freshness,
+        sessionStats: withFreshnessSucceeded(this.state.live.freshness.sessionStats),
+      },
+    }
+
+    this.patchState({
+      live: {
+        ...nextLive,
+        recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: nextLive }),
+      },
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "load_session_stats",
+        success: true,
+        message: `Loaded session details for ${sessionStats.sessionId}`,
+        sessionStats,
+      }),
+    })
+
+    return sessionStats
+  }
+
+  exportSessionFromSurface = async (outputPath?: string): Promise<WorkspaceCommandResponse | null> => {
+    const normalizedOutputPath = outputPath?.trim() || undefined
+    const selectedTarget: CommandSurfaceTarget = { kind: "session", outputPath: normalizedOutputPath }
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "export_html", selectedTarget),
+    })
+
+    const response = await this.sendCommand(
+      normalizedOutputPath ? { type: "export_html", outputPath: normalizedOutputPath } : { type: "export_html" },
+      { appendInputLine: false, appendResponseLine: false },
+    )
+
+    if (!response || response.success === false) {
+      const message = response?.error ?? this.state.lastClientError ?? "Unknown error"
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "export_html",
+          success: false,
+          message: `Couldn't export this session — ${message}`,
+          selectedTarget,
+        }),
+      })
+      return response
+    }
+
+    const exportedPath =
+      response.data && typeof response.data === "object" && "path" in response.data && typeof response.data.path === "string"
+        ? response.data.path
+        : "the generated file"
+
+    this.patchState({
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "export_html",
+        success: true,
+        message: `Session exported to ${exportedPath}`,
+        selectedTarget,
+      }),
+    })
+
+    return response
+  }
+
+  loadForkMessages = async (): Promise<CommandSurfaceForkMessage[]> => {
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "load_fork_messages"),
+    })
+
+    const response = await this.sendCommand(
+      { type: "get_fork_messages" },
+      { appendInputLine: false, appendResponseLine: false },
+    )
+
+    if (!response || response.success === false) {
+      const message = response?.error ?? this.state.lastClientError ?? "Unknown error"
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "load_fork_messages",
+          success: false,
+          message: `Couldn't load fork points — ${message}`,
+          forkMessages: [],
+        }),
+      })
+      return []
+    }
+
+    const forkMessages = normalizeForkMessages(response.data)
+    const currentTarget = this.state.commandSurface.selectedTarget
+    const selectedTarget =
+      currentTarget?.kind === "fork" && currentTarget.entryId
+        ? currentTarget
+        : forkMessages[0]
+          ? { kind: "fork" as const, entryId: forkMessages[0].entryId }
+          : currentTarget
+
+    this.patchState({
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "load_fork_messages",
+        success: true,
+        message: forkMessages.length > 0 ? `Loaded ${forkMessages.length} fork points.` : "No fork points are available yet.",
+        selectedTarget: selectedTarget ?? null,
+        forkMessages,
+      }),
+    })
+
+    return forkMessages
+  }
+
+  forkSessionFromSurface = async (entryId: string): Promise<WorkspaceCommandResponse | null> => {
+    const selectedTarget: CommandSurfaceTarget = { kind: "fork", entryId }
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "fork_session", selectedTarget),
+    })
+
+    const response = await this.sendCommand(
+      { type: "fork", entryId },
+      { appendInputLine: false, appendResponseLine: false },
+    )
+
+    if (!response || response.success === false) {
+      const message = response?.error ?? this.state.lastClientError ?? "Unknown error"
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "fork_session",
+          success: false,
+          message: `Couldn't create a fork — ${message}`,
+          selectedTarget,
+        }),
+      })
+      return response
+    }
+
+    if (response.data && typeof response.data === "object" && "cancelled" in response.data && response.data.cancelled) {
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "fork_session",
+          success: false,
+          message: "Fork creation was cancelled before a new session was created.",
+          selectedTarget,
+        }),
+      })
+      return response
+    }
+
+    const sourceText =
+      response.data && typeof response.data === "object" && "text" in response.data && typeof response.data.text === "string"
+        ? response.data.text.trim()
+        : ""
+
+    this.patchState({
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "fork_session",
+        success: true,
+        message: sourceText ? `Forked from “${sourceText.slice(0, 120)}${sourceText.length > 120 ? "…" : ""}”` : "Created a forked session.",
+        selectedTarget,
+      }),
+    })
+
+    return response
+  }
+
+  compactSessionFromSurface = async (customInstructions?: string): Promise<WorkspaceCommandResponse | null> => {
+    const normalizedInstructions = customInstructions?.trim() ?? ""
+    const selectedTarget: CommandSurfaceTarget = { kind: "compact", customInstructions: normalizedInstructions }
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "compact_session", selectedTarget),
+    })
+
+    const response = await this.sendCommand(
+      normalizedInstructions ? { type: "compact", customInstructions: normalizedInstructions } : { type: "compact" },
+      { appendInputLine: false, appendResponseLine: false },
+    )
+
+    if (!response || response.success === false) {
+      const message = response?.error ?? this.state.lastClientError ?? "Unknown error"
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "compact_session",
+          success: false,
+          message: `Couldn't compact the session — ${message}`,
+          selectedTarget,
+          lastCompaction: null,
+        }),
+      })
+      return response
+    }
+
+    const compactionResult = normalizeCompactionResult(response.data)
+    if (!compactionResult) {
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "compact_session",
+          success: false,
+          message: "Compaction finished but the browser could not read the compaction result.",
+          selectedTarget,
+          lastCompaction: null,
+        }),
+      })
+      return response
+    }
+
+    this.patchState({
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "compact_session",
+        success: true,
+        message: `Compacted ${compactionResult.tokensBefore.toLocaleString()} tokens into a fresh summary${normalizedInstructions ? " with custom instructions" : ""}.`,
+        selectedTarget,
+        lastCompaction: compactionResult,
+      }),
+    })
+
+    return response
+  }
+
+  saveApiKeyFromSurface = async (providerId: string, apiKey: string): Promise<WorkspaceOnboardingState | null> => {
+    const selectedTarget: CommandSurfaceTarget = { kind: "auth", providerId, intent: "manage" }
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "save_api_key", selectedTarget),
+    })
+
+    const onboarding = await this.saveApiKey(providerId, apiKey)
+    const providerLabel = onboarding ? findOnboardingProviderLabel(onboarding, providerId) : providerId
+
+    if (!onboarding) {
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "save_api_key",
+          success: false,
+          message: this.state.lastClientError ?? `${providerLabel} setup failed`,
+          selectedTarget,
+        }),
+      })
+      return null
+    }
+
+    if (onboarding.lastValidation?.status === "failed") {
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "save_api_key",
+          success: false,
+          message: onboarding.lastValidation.message,
+          selectedTarget,
+        }),
+      })
+      return onboarding
+    }
+
+    if (onboarding.bridgeAuthRefresh.phase === "failed") {
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "save_api_key",
+          success: false,
+          message: onboarding.bridgeAuthRefresh.error ?? `${providerLabel} credentials validated but bridge auth refresh failed`,
+          selectedTarget,
+        }),
+      })
+      return onboarding
+    }
+
+    this.patchState({
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "save_api_key",
+        success: true,
+        message: `${providerLabel} credentials validated and saved.`,
+        selectedTarget,
+      }),
+    })
+
+    return onboarding
+  }
+
+  startProviderFlowFromSurface = async (providerId: string): Promise<WorkspaceOnboardingState | null> => {
+    const selectedTarget: CommandSurfaceTarget = { kind: "auth", providerId, intent: "login" }
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "start_provider_flow", selectedTarget),
+    })
+
+    const onboarding = await this.startProviderFlow(providerId)
+    const providerLabel = onboarding ? findOnboardingProviderLabel(onboarding, providerId) : providerId
+
+    if (!onboarding) {
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "start_provider_flow",
+          success: false,
+          message: this.state.lastClientError ?? `${providerLabel} sign-in failed to start`,
+          selectedTarget,
+        }),
+      })
+      return null
+    }
+
+    this.patchState({
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "start_provider_flow",
+        success: true,
+        message: `${providerLabel} sign-in started. Continue in the auth section.`,
+        selectedTarget,
+      }),
+    })
+
+    return onboarding
+  }
+
+  submitProviderFlowInputFromSurface = async (flowId: string, input: string): Promise<WorkspaceOnboardingState | null> => {
+    const providerId = this.state.boot?.onboarding.activeFlow?.providerId ?? undefined
+    const selectedTarget: CommandSurfaceTarget = { kind: "auth", providerId, intent: "login" }
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "submit_provider_flow_input", selectedTarget),
+    })
+
+    const onboarding = await this.submitProviderFlowInput(flowId, input)
+    const providerLabel =
+      onboarding?.activeFlow?.providerLabel ??
+      (providerId && onboarding ? findOnboardingProviderLabel(onboarding, providerId) : providerId) ??
+      "Provider"
+
+    if (!onboarding) {
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "submit_provider_flow_input",
+          success: false,
+          message: this.state.lastClientError ?? `${providerLabel} sign-in failed`,
+          selectedTarget,
+        }),
+      })
+      return null
+    }
+
+    if (onboarding.activeFlow?.status === "failed") {
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "submit_provider_flow_input",
+          success: false,
+          message: onboarding.activeFlow.error ?? `${providerLabel} sign-in failed`,
+          selectedTarget,
+        }),
+      })
+      return onboarding
+    }
+
+    if (onboarding.bridgeAuthRefresh.phase === "failed") {
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "submit_provider_flow_input",
+          success: false,
+          message: onboarding.bridgeAuthRefresh.error ?? `${providerLabel} sign-in completed but bridge auth refresh failed`,
+          selectedTarget,
+        }),
+      })
+      return onboarding
+    }
+
+    const successMessage =
+      onboarding.activeFlow && ["running", "awaiting_browser_auth", "awaiting_input"].includes(onboarding.activeFlow.status)
+        ? `${providerLabel} sign-in advanced. Complete the remaining step in this panel.`
+        : `${providerLabel} sign-in complete.`
+
+    this.patchState({
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "submit_provider_flow_input",
+        success: true,
+        message: successMessage,
+        selectedTarget,
+      }),
+    })
+
+    return onboarding
+  }
+
+  cancelProviderFlowFromSurface = async (flowId: string): Promise<WorkspaceOnboardingState | null> => {
+    const providerId = this.state.boot?.onboarding.activeFlow?.providerId ?? undefined
+    const selectedTarget: CommandSurfaceTarget = { kind: "auth", providerId, intent: "login" }
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "cancel_provider_flow", selectedTarget),
+    })
+
+    const onboarding = await this.cancelProviderFlow(flowId)
+    const providerLabel =
+      onboarding?.activeFlow?.providerLabel ??
+      (providerId && onboarding ? findOnboardingProviderLabel(onboarding, providerId) : providerId) ??
+      "Provider"
+
+    if (!onboarding) {
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "cancel_provider_flow",
+          success: false,
+          message: this.state.lastClientError ?? `${providerLabel} sign-in cancellation failed`,
+          selectedTarget,
+        }),
+      })
+      return null
+    }
+
+    this.patchState({
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "cancel_provider_flow",
+        success: true,
+        message: `${providerLabel} sign-in cancelled.`,
+        selectedTarget,
+      }),
+    })
+
+    return onboarding
+  }
+
+  logoutProviderFromSurface = async (providerId: string): Promise<WorkspaceOnboardingState | null> => {
+    const selectedTarget: CommandSurfaceTarget = { kind: "auth", providerId, intent: "logout" }
+    this.patchState({
+      commandSurface: setCommandSurfacePending(this.state.commandSurface, "logout_provider", selectedTarget),
+    })
+
+    const onboarding = await this.logoutProvider(providerId)
+    const providerLabel = onboarding ? findOnboardingProviderLabel(onboarding, providerId) : providerId
+
+    if (!onboarding) {
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "logout_provider",
+          success: false,
+          message: this.state.lastClientError ?? `${providerLabel} logout failed`,
+          selectedTarget,
+        }),
+      })
+      return null
+    }
+
+    if (onboarding.bridgeAuthRefresh.phase === "failed") {
+      this.patchState({
+        commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+          action: "logout_provider",
+          success: false,
+          message: onboarding.bridgeAuthRefresh.error ?? `${providerLabel} logout completed but bridge auth refresh failed`,
+          selectedTarget,
+        }),
+      })
+      return onboarding
+    }
+
+    const providerState = onboarding.required.providers.find((provider) => provider.id === providerId)
+    const resultMessage = providerState?.configured
+      ? `${providerLabel} saved credentials were removed, but ${providerState.configuredVia} auth still keeps the provider available.`
+      : onboarding.locked
+        ? `${providerLabel} logged out — required setup is needed again.`
+        : `${providerLabel} logged out.`
+
+    this.patchState({
+      commandSurface: applyCommandSurfaceActionResult(this.state.commandSurface, {
+        action: "logout_provider",
+        success: true,
+        message: resultMessage,
+        selectedTarget,
+      }),
+    })
+
+    return onboarding
+  }
+
+  respondToUiRequest = async (id: string, response: Record<string, unknown>): Promise<void> => {
+    this.patchState({ commandInFlight: "extension_ui_response" })
+    try {
+      const result = await authFetch(this.buildUrl("/api/session/command"), {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({ type: "extension_ui_response", id, ...response }),
+      })
+      if (!result.ok) {
+        const body = await result.json().catch(() => ({ error: `HTTP ${result.status}` })) as { error?: string }
+        throw new Error(body.error ?? `extension_ui_response failed with ${result.status}`)
+      }
+      this.patchState({
+        pendingUiRequests: this.state.pendingUiRequests.filter((r) => r.id !== id),
+      })
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchState({
+        lastClientError: message,
+        terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine("error", `UI response failed — ${message}`)),
+      })
+    } finally {
+      this.patchState({ commandInFlight: null })
+    }
+  }
+
+  dismissUiRequest = async (id: string): Promise<void> => {
+    this.patchState({ commandInFlight: "extension_ui_response" })
+    try {
+      const result = await authFetch(this.buildUrl("/api/session/command"), {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({ type: "extension_ui_response", id, cancelled: true }),
+      })
+      if (!result.ok) {
+        const body = await result.json().catch(() => ({ error: `HTTP ${result.status}` })) as { error?: string }
+        throw new Error(body.error ?? `extension_ui_response cancel failed with ${result.status}`)
+      }
+      this.patchState({
+        pendingUiRequests: this.state.pendingUiRequests.filter((r) => r.id !== id),
+      })
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchState({
+        lastClientError: message,
+        terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine("error", `UI dismiss failed — ${message}`)),
+      })
+    } finally {
+      this.patchState({ commandInFlight: null })
+    }
+  }
+
+  sendSteer = async (message: string): Promise<void> => {
+    await this.sendCommand({ type: "steer", message })
+  }
+
+  sendAbort = async (): Promise<void> => {
+    await this.sendCommand({ type: "abort" })
+  }
+
+  pushChatUserMessage = (msg: ChatMessage) => {
+    this.patchState({ chatUserMessages: [...this.state.chatUserMessages, msg] })
+  }
+
+  submitInput = async (input: string, images?: PendingImage[]): Promise<BrowserSlashCommandDispatchResult | null> => {
+    const trimmed = input.trim()
+    if (!trimmed) return null
+
+    const outcome = dispatchBrowserSlashCommand(trimmed, {
+      isStreaming: this.state.boot?.bridge.sessionState?.isStreaming,
+    })
+
+    this.patchState({
+      lastSlashCommandOutcome: trimmed.startsWith("/") ? outcome : null,
+    })
+
+    // Evaluate contextual tips before sending to agent
+    if (outcome.kind === "prompt") {
+      const sessionState = this.state.boot?.bridge.sessionState
+      const tip = this.contextualTips.evaluate({
+        input: trimmed,
+        isStreaming: Boolean(sessionState?.isStreaming),
+        thinkingLevel: sessionState?.thinkingLevel,
+        // contextPercent not available in web — compaction nudge won't fire here
+        contextPercent: undefined,
+      })
+      if (tip) {
+        this.patchState({
+          terminalLines: withTerminalLine(
+            this.state.terminalLines,
+            createTerminalLine("system", `💡 ${tip}`),
+          ),
+        })
+      }
+    }
+
+    switch (outcome.kind) {
+      case "prompt":
+      case "rpc": {
+        const imagePayload = images?.map((i) => ({ type: "image" as const, data: i.data, mimeType: i.mimeType }))
+        const command = imagePayload && imagePayload.length > 0
+          ? { ...outcome.command, images: imagePayload }
+          : outcome.command
+        await this.sendCommand(command, { displayInput: trimmed })
+        return outcome
+      }
+      case "local":
+        if (outcome.action === "clear_terminal") {
+          this.clearTerminalLines()
+          return outcome
+        }
+        if (outcome.action === "refresh_workspace") {
+          await this.refreshBoot()
+          return outcome
+        }
+        if (outcome.action === "gsd_help") {
+          this.patchState({
+            terminalLines: withTerminalLine(
+              withTerminalLine(this.state.terminalLines, createTerminalLine("input", trimmed)),
+              createTerminalLine("system", GSD_HELP_TEXT),
+            ),
+          })
+          return outcome
+        }
+        return outcome
+      case "surface": {
+        if (IMPLEMENTED_BROWSER_COMMAND_SURFACES.has(outcome.surface)) {
+          this.patchState({
+            terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine("input", trimmed)),
+          })
+          this.openCommandSurface(outcome.surface, { source: "slash", args: outcome.args })
+          return outcome
+        }
+
+        const notice = getBrowserSlashCommandTerminalNotice(outcome)
+        let nextLines = withTerminalLine(this.state.terminalLines, createTerminalLine("input", trimmed))
+        if (notice) {
+          nextLines = withTerminalLine(nextLines, createTerminalLine(notice.type, notice.message))
+        }
+        this.patchState({ terminalLines: nextLines })
+        return outcome
+      }
+      case "reject": {
+        const notice = getBrowserSlashCommandTerminalNotice(outcome)
+        let nextLines = withTerminalLine(this.state.terminalLines, createTerminalLine("input", trimmed))
+        if (notice) {
+          nextLines = withTerminalLine(nextLines, createTerminalLine(notice.type, notice.message))
+        }
+        this.patchState({ terminalLines: nextLines })
+        return outcome
+      }
+      case "view-navigate": {
+        this.patchState({
+          terminalLines: withTerminalLine(
+            this.state.terminalLines,
+            createTerminalLine("system", `Navigating to ${outcome.view} view`),
+          ),
+        })
+        window.dispatchEvent(
+          new CustomEvent("gsd:navigate-view", { detail: { view: outcome.view } }),
+        )
+        return outcome
+      }
+    }
+  }
+
+  refreshBoot = async (options: { soft?: boolean } = {}): Promise<void> => {
+    if (this.bootPromise) return await this.bootPromise
+
+    this.lastBootRefreshAt = Date.now()
+    const softRefresh = Boolean(options.soft && this.state.boot)
+
+    this.bootPromise = (async () => {
+      if (!softRefresh) {
+        this.patchState({
+          bootStatus: "loading",
+          connectionState: this.state.connectionState === "connected" ? "connected" : "connecting",
+          lastClientError: null,
+        })
+      } else {
+        this.patchState({
+          lastClientError: null,
+        })
+      }
+
+      try {
+        const response = await authFetch(this.buildUrl("/api/boot"), {
+          method: "GET",
+          cache: "no-store",
+          headers: {
+            Accept: "application/json",
+          },
+        })
+
+        if (!response.ok) {
+          if (response.status === 401) {
+            this.patchState({
+              bootStatus: "unauthenticated",
+              connectionState: "error",
+            })
+            return
+          }
+          throw new Error(`Boot request failed with ${response.status}`)
+        }
+
+        const bootPayload = (await response.json()) as WorkspaceBootPayload
+        const boot = cloneBootWithBridge(bootPayload, bootPayload.bridge) ?? bootPayload
+        const live = applyBootToLiveState(this.state.live, boot, { soft: softRefresh })
+        this.lastBridgeDigest = null
+        this.lastBridgeDigest = [boot.bridge.phase, boot.bridge.activeSessionId, boot.bridge.lastError?.at, boot.bridge.lastError?.message].join("::")
+        this.patchState({
+          bootStatus: "ready",
+          boot,
+          live,
+          connectionState: boot.onboarding.locked
+            ? "idle"
+            : this.eventSource
+              ? this.state.connectionState
+              : "connecting",
+          lastBridgeError: boot.bridge.lastError,
+          sessionAttached: hasAttachedSession(boot.bridge),
+          lastClientError: null,
+          ...(softRefresh ? {} : { terminalLines: bootSeedLines(boot) }),
+        })
+        if (boot.onboarding.locked) {
+          this.closeEventStream()
+        } else {
+          this.ensureEventStream()
+        }
+      } catch (error) {
+        const message = normalizeClientError(error)
+        if (softRefresh) {
+          this.patchState({
+            lastClientError: message,
+            terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine("error", `Workspace refresh failed — ${message}`)),
+          })
+          return
+        }
+
+        this.patchState({
+          bootStatus: "error",
+          connectionState: "error",
+          lastClientError: message,
+          terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine("error", `Boot failed — ${message}`)),
+        })
+      }
+    })().finally(() => {
+      this.bootPromise = null
+    })
+
+    await this.bootPromise
+  }
+
+  private async refreshBootAfterCurrentSettles(options: { soft?: boolean } = {}): Promise<void> {
+    if (this.bootPromise) {
+      try {
+        await this.bootPromise
+      } catch {
+        // Preserve the original boot failure surface, then issue a fresh refresh.
+      }
+    }
+
+    await this.refreshBoot(options)
+  }
+
+  private invalidateLiveFreshness(
+    domains: LiveStateInvalidationDomain[],
+    reason: LiveStateInvalidationReason,
+    source: LiveStateInvalidationSource,
+  ): WorkspaceLiveState {
+    const nextFreshness = { ...this.state.live.freshness }
+
+    if (domains.includes("auto")) {
+      nextFreshness.auto = withFreshnessInvalidated(nextFreshness.auto, reason, source)
+    }
+    if (domains.includes("workspace")) {
+      nextFreshness.workspace = withFreshnessInvalidated(nextFreshness.workspace, reason, source)
+      nextFreshness.gitSummary = withFreshnessInvalidated(nextFreshness.gitSummary, reason, source)
+    }
+    if (domains.includes("recovery")) {
+      nextFreshness.recovery = withFreshnessInvalidated(nextFreshness.recovery, reason, source)
+      nextFreshness.sessionStats = withFreshnessInvalidated(nextFreshness.sessionStats, reason, source)
+    }
+    if (domains.includes("resumable_sessions")) {
+      nextFreshness.resumableSessions = withFreshnessInvalidated(nextFreshness.resumableSessions, reason, source)
+      nextFreshness.sessionBrowser = withFreshnessInvalidated(nextFreshness.sessionBrowser, reason, source)
+      nextFreshness.sessionStats = withFreshnessInvalidated(nextFreshness.sessionStats, reason, source)
+    }
+
+    const nextLive = {
+      ...this.state.live,
+      freshness: nextFreshness,
+    }
+    return {
+      ...nextLive,
+      recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: nextLive }),
+    }
+  }
+
+  private refreshOpenCommandSurfacesForInvalidation(event: LiveStateInvalidationEvent): void {
+    if (event.domains.includes("workspace") && this.state.commandSurface.open && this.state.commandSurface.section === "git") {
+      if (this.state.commandSurface.pendingAction !== "load_git_summary") {
+        void this.loadGitSummary()
+      }
+    }
+
+    if (event.domains.includes("recovery") && this.state.commandSurface.open && this.state.commandSurface.section === "recovery") {
+      if (this.state.commandSurface.pendingAction !== "load_recovery_diagnostics") {
+        void this.loadRecoveryDiagnostics()
+      }
+    }
+
+    if (event.domains.includes("resumable_sessions")) {
+      if (
+        this.state.commandSurface.open &&
+        (this.state.commandSurface.section === "resume" || this.state.commandSurface.section === "name") &&
+        this.state.commandSurface.pendingAction !== "load_session_browser"
+      ) {
+        void this.loadSessionBrowser()
+      }
+
+      if (this.state.commandSurface.open && this.state.commandSurface.section === "session") {
+        const activeSessionPath = this.state.boot?.bridge.activeSessionFile ?? this.state.boot?.bridge.sessionState?.sessionFile ?? null
+        this.patchState({
+          commandSurface: {
+            ...this.state.commandSurface,
+            sessionStats:
+              this.state.commandSurface.sessionStats && this.state.commandSurface.sessionStats.sessionFile === activeSessionPath
+                ? this.state.commandSurface.sessionStats
+                : null,
+          },
+        })
+        if (this.state.commandSurface.pendingAction !== "load_session_stats") {
+          void this.loadSessionStats()
+        }
+      }
+    }
+  }
+
+  private async reloadLiveState(
+    domains: LiveStateInvalidationDomain[],
+    reason: LiveStateInvalidationReason,
+  ): Promise<void> {
+    const requestedDomains = domains.filter((domain) => domain === "auto" || domain === "workspace" || domain === "resumable_sessions")
+
+    if (requestedDomains.length === 0) {
+      const nextLive = {
+        ...this.state.live,
+        freshness: {
+          ...this.state.live.freshness,
+          recovery: withFreshnessSucceeded(this.state.live.freshness.recovery),
+        },
+      }
+      this.patchState({
+        live: {
+          ...nextLive,
+          recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: nextLive }),
+        },
+      })
+      return
+    }
+
+    const nextFreshness = { ...this.state.live.freshness }
+    if (requestedDomains.includes("auto")) {
+      nextFreshness.auto = withFreshnessRequested(nextFreshness.auto)
+    }
+    if (requestedDomains.includes("workspace")) {
+      nextFreshness.workspace = withFreshnessRequested(nextFreshness.workspace)
+    }
+    if (requestedDomains.includes("resumable_sessions")) {
+      nextFreshness.resumableSessions = withFreshnessRequested(nextFreshness.resumableSessions)
+    }
+    nextFreshness.recovery = withFreshnessRequested(nextFreshness.recovery)
+
+    const requestedLive = {
+      ...this.state.live,
+      freshness: nextFreshness,
+      targetedRefreshCount: this.state.live.targetedRefreshCount + 1,
+    }
+    this.patchState({
+      live: {
+        ...requestedLive,
+        recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: requestedLive }),
+      },
+    })
+
+    const params = new URLSearchParams()
+    for (const domain of requestedDomains) {
+      params.append("domain", domain)
+    }
+
+    try {
+      const response = await authFetch(this.buildUrl(`/api/live-state?${params.toString()}`), {
+        method: "GET",
+        cache: "no-store",
+        headers: {
+          Accept: "application/json",
+        },
+      })
+      const payload = await response.json().catch(() => null) as {
+        auto?: AutoDashboardData
+        workspace?: WorkspaceIndex
+        resumableSessions?: BootResumableSession[]
+        error?: string
+      } | null
+
+      if (!response.ok || !payload) {
+        throw new Error(payload?.error ?? `Live state request failed with ${response.status}`)
+      }
+
+      let nextBoot = this.state.boot
+      const nextLive: WorkspaceLiveState = {
+        ...this.state.live,
+        freshness: { ...this.state.live.freshness },
+      }
+
+      if (requestedDomains.includes("auto") && payload.auto) {
+        nextLive.auto = payload.auto
+        nextLive.freshness.auto = withFreshnessSucceeded(nextLive.freshness.auto)
+        nextBoot = nextBoot
+          ? {
+              ...nextBoot,
+              auto: payload.auto,
+            }
+          : nextBoot
+      }
+
+      if (requestedDomains.includes("workspace") && payload.workspace) {
+        nextLive.workspace = payload.workspace
+        nextLive.freshness.workspace = withFreshnessSucceeded(nextLive.freshness.workspace)
+        nextBoot = nextBoot
+          ? {
+              ...nextBoot,
+              workspace: payload.workspace,
+            }
+          : nextBoot
+      }
+
+      if (requestedDomains.includes("resumable_sessions") && payload.resumableSessions) {
+        const nextSessions = overlayLiveBridgeSessionState(payload.resumableSessions, nextBoot)
+        nextLive.resumableSessions = nextSessions
+        nextLive.freshness.resumableSessions = withFreshnessSucceeded(nextLive.freshness.resumableSessions)
+        nextBoot = nextBoot
+          ? {
+              ...nextBoot,
+              resumableSessions: nextSessions,
+            }
+          : nextBoot
+      }
+
+      nextLive.freshness.recovery = withFreshnessSucceeded(nextLive.freshness.recovery)
+      nextLive.recoverySummary = createWorkspaceRecoverySummary({ boot: nextBoot, live: nextLive })
+      this.patchState({
+        ...(nextBoot ? { boot: nextBoot } : {}),
+        live: nextLive,
+      })
+    } catch (error) {
+      const message = normalizeClientError(error)
+      const failedLive: WorkspaceLiveState = {
+        ...this.state.live,
+        freshness: {
+          ...this.state.live.freshness,
+          auto:
+            requestedDomains.includes("auto")
+              ? withFreshnessFailed(this.state.live.freshness.auto, message)
+              : this.state.live.freshness.auto,
+          workspace:
+            requestedDomains.includes("workspace")
+              ? withFreshnessFailed(this.state.live.freshness.workspace, message)
+              : this.state.live.freshness.workspace,
+          resumableSessions:
+            requestedDomains.includes("resumable_sessions")
+              ? withFreshnessFailed(this.state.live.freshness.resumableSessions, message)
+              : this.state.live.freshness.resumableSessions,
+          recovery: withFreshnessFailed(this.state.live.freshness.recovery, message),
+        },
+      }
+
+      this.patchState({
+        lastClientError: message,
+        live: {
+          ...failedLive,
+          recoverySummary: createWorkspaceRecoverySummary({ boot: this.state.boot, live: failedLive }),
+        },
+        terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine("error", `Live refresh failed (${reason}) — ${message}`)),
+      })
+    }
+  }
+
+  private handleLiveStateInvalidation(event: LiveStateInvalidationEvent): void {
+    this.patchState({
+      live: this.invalidateLiveFreshness(event.domains, event.reason, event.source),
+      commandSurface: event.domains.includes("recovery")
+        ? {
+            ...this.state.commandSurface,
+            recovery: markRecoveryStateInvalidated(this.state.commandSurface.recovery),
+          }
+        : this.state.commandSurface,
+    })
+    this.refreshOpenCommandSurfacesForInvalidation(event)
+    void this.reloadLiveState(event.domains, event.reason)
+  }
+
+  refreshOnboarding = async (): Promise<WorkspaceOnboardingState | null> => {
+    this.patchState({
+      onboardingRequestState: "refreshing",
+      onboardingRequestProviderId: null,
+      lastClientError: null,
+    })
+
+    try {
+      return await this.fetchOnboardingState()
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchState({
+        lastClientError: message,
+        terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine("error", `Onboarding refresh failed — ${message}`)),
+      })
+      return null
+    } finally {
+      this.patchState({
+        onboardingRequestState: "idle",
+        onboardingRequestProviderId: null,
+      })
+    }
+  }
+
+  saveApiKey = async (providerId: string, apiKey: string): Promise<WorkspaceOnboardingState | null> => {
+    this.patchState({
+      onboardingRequestState: "saving_api_key",
+      onboardingRequestProviderId: providerId,
+      lastClientError: null,
+    })
+
+    try {
+      const onboarding = await this.postOnboardingAction({
+        action: "save_api_key",
+        providerId,
+        apiKey,
+      })
+      await this.syncAfterOnboardingMutation(onboarding)
+      return onboarding
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchState({
+        lastClientError: message,
+        terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine("error", `Credential setup failed — ${message}`)),
+      })
+      return null
+    } finally {
+      this.patchState({
+        onboardingRequestState: "idle",
+        onboardingRequestProviderId: null,
+      })
+    }
+  }
+
+  startProviderFlow = async (providerId: string): Promise<WorkspaceOnboardingState | null> => {
+    this.patchState({
+      onboardingRequestState: "starting_provider_flow",
+      onboardingRequestProviderId: providerId,
+      lastClientError: null,
+    })
+
+    try {
+      const onboarding = await this.postOnboardingAction({
+        action: "start_provider_flow",
+        providerId,
+      })
+      await this.syncAfterOnboardingMutation(onboarding)
+      return onboarding
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchState({
+        lastClientError: message,
+        terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine("error", `Provider sign-in failed to start — ${message}`)),
+      })
+      return null
+    } finally {
+      this.patchState({
+        onboardingRequestState: "idle",
+        onboardingRequestProviderId: null,
+      })
+    }
+  }
+
+  submitProviderFlowInput = async (flowId: string, input: string): Promise<WorkspaceOnboardingState | null> => {
+    this.patchState({
+      onboardingRequestState: "submitting_provider_flow_input",
+      onboardingRequestProviderId: this.state.boot?.onboarding.activeFlow?.providerId ?? null,
+      lastClientError: null,
+    })
+
+    try {
+      const onboarding = await this.postOnboardingAction({
+        action: "continue_provider_flow",
+        flowId,
+        input,
+      })
+      await this.syncAfterOnboardingMutation(onboarding)
+      return onboarding
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchState({
+        lastClientError: message,
+        terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine("error", `Provider sign-in input failed — ${message}`)),
+      })
+      return null
+    } finally {
+      this.patchState({
+        onboardingRequestState: "idle",
+        onboardingRequestProviderId: null,
+      })
+    }
+  }
+
+  cancelProviderFlow = async (flowId: string): Promise<WorkspaceOnboardingState | null> => {
+    this.patchState({
+      onboardingRequestState: "cancelling_provider_flow",
+      onboardingRequestProviderId: this.state.boot?.onboarding.activeFlow?.providerId ?? null,
+      lastClientError: null,
+    })
+
+    try {
+      const onboarding = await this.postOnboardingAction({
+        action: "cancel_provider_flow",
+        flowId,
+      })
+      await this.syncAfterOnboardingMutation(onboarding)
+      return onboarding
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchState({
+        lastClientError: message,
+        terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine("error", `Provider sign-in cancellation failed — ${message}`)),
+      })
+      return null
+    } finally {
+      this.patchState({
+        onboardingRequestState: "idle",
+        onboardingRequestProviderId: null,
+      })
+    }
+  }
+
+  logoutProvider = async (providerId: string): Promise<WorkspaceOnboardingState | null> => {
+    this.patchState({
+      onboardingRequestState: "logging_out_provider",
+      onboardingRequestProviderId: providerId,
+      lastClientError: null,
+    })
+
+    try {
+      const onboarding = await this.postOnboardingAction({
+        action: "logout_provider",
+        providerId,
+      })
+      await this.syncAfterOnboardingMutation(onboarding)
+      return onboarding
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchState({
+        lastClientError: message,
+        terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine("error", `Provider logout failed — ${message}`)),
+      })
+      return null
+    } finally {
+      this.patchState({
+        onboardingRequestState: "idle",
+        onboardingRequestProviderId: null,
+      })
+    }
+  }
+
+  sendCommand = async (
+    command: WorkspaceBridgeCommand,
+    options: { displayInput?: string; appendInputLine?: boolean; appendResponseLine?: boolean } = {},
+  ): Promise<WorkspaceCommandResponse | null> => {
+    this.clearCommandTimeout()
+
+    const nextPatch: Partial<WorkspaceStoreState> = {
+      commandInFlight: command.type,
+    }
+
+    if (options.appendInputLine !== false) {
+      nextPatch.terminalLines = withTerminalLine(
+        this.state.terminalLines,
+        createTerminalLine("input", options.displayInput ?? getCommandInputLabel(command)),
+      )
+    }
+
+    this.patchState(nextPatch)
+
+    this.commandTimeoutTimer = setTimeout(() => {
+      if (this.state.commandInFlight) {
+        this.patchState({
+          commandInFlight: null,
+          lastClientError: "Command timed out — controls re-enabled",
+          terminalLines: withTerminalLine(
+            this.state.terminalLines,
+            createTerminalLine("error", "Command timed out — controls re-enabled"),
+          ),
+        })
+      }
+    }, COMMAND_TIMEOUT_MS)
+
+    try {
+      const response = await authFetch(this.buildUrl("/api/session/command"), {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+        },
+        body: JSON.stringify(command),
+      })
+
+      const payload = (await response.json()) as WorkspaceCommandResponse | { ok: true }
+      if ("ok" in payload) {
+        return null
+      }
+
+      if (payload.command === "get_state" && payload.success && this.state.boot) {
+        const nextBridge = {
+          ...this.state.boot.bridge,
+          sessionState: payload.data as WorkspaceSessionState,
+          activeSessionId: (payload.data as WorkspaceSessionState).sessionId,
+          activeSessionFile: (payload.data as WorkspaceSessionState).sessionFile ?? this.state.boot.bridge.activeSessionFile,
+          lastCommandType: "get_state",
+          updatedAt: new Date().toISOString(),
+        }
+
+        this.patchState({
+          boot: cloneBootWithBridge(this.state.boot, nextBridge),
+          lastBridgeError: nextBridge.lastError,
+          sessionAttached: hasAttachedSession(nextBridge),
+        })
+      }
+
+      // Reset contextual tips on new session
+      if (payload.command === "new_session" && payload.success) {
+        this.contextualTips.reset()
+      }
+
+      if (payload.code === "onboarding_locked" && payload.details?.onboarding && this.state.boot) {
+        this.patchState({
+          boot: cloneBootWithPartialOnboarding(this.state.boot, payload.details.onboarding),
+        })
+      }
+
+      this.patchState({
+        ...(options.appendResponseLine === false
+          ? {}
+          : { terminalLines: withTerminalLine(this.state.terminalLines, responseToLine(payload)) }),
+        lastBridgeError: payload.success ? this.state.lastBridgeError : this.state.boot?.bridge.lastError ?? this.state.lastBridgeError,
+      })
+      return payload
+    } catch (error) {
+      const message = normalizeClientError(error)
+      this.patchState({
+        lastClientError: message,
+        terminalLines: withTerminalLine(
+          this.state.terminalLines,
+          createTerminalLine("error", `Command failed (${command.type}) — ${message}`),
+        ),
+      })
+      return {
+        type: "response",
+        command: command.type,
+        success: false,
+        error: message,
+      }
+    } finally {
+      this.clearCommandTimeout()
+      this.patchState({ commandInFlight: null })
+    }
+  }
+
+  private clearCommandTimeout(): void {
+    if (this.commandTimeoutTimer) {
+      clearTimeout(this.commandTimeoutTimer)
+      this.commandTimeoutTimer = null
+    }
+  }
+
+  private async fetchOnboardingState(silent = false): Promise<WorkspaceOnboardingState> {
+    const previousFlowStatus = this.state.boot?.onboarding.activeFlow?.status ?? null
+    const response = await authFetch(this.buildUrl("/api/onboarding"), {
+      method: "GET",
+      cache: "no-store",
+      headers: {
+        Accept: "application/json",
+      },
+    })
+    const payload = (await response.json()) as OnboardingApiPayload
+    if (!response.ok || !payload.onboarding) {
+      throw new Error(payload.error ?? `Onboarding request failed with ${response.status}`)
+    }
+
+    this.applyOnboardingState(payload.onboarding)
+
+    if (
+      previousFlowStatus &&
+      ACTIVE_ONBOARDING_FLOW_STATUSES.has(previousFlowStatus) &&
+      payload.onboarding.activeFlow &&
+      TERMINAL_ONBOARDING_FLOW_STATUSES.has(payload.onboarding.activeFlow.status)
+    ) {
+      await this.syncAfterOnboardingMutation(payload.onboarding)
+    } else if (!silent) {
+      this.appendOnboardingSummaryLine(payload.onboarding)
+    }
+
+    return payload.onboarding
+  }
+
+  private async postOnboardingAction(body: Record<string, unknown>): Promise<WorkspaceOnboardingState> {
+    const response = await authFetch(this.buildUrl("/api/onboarding"), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(body),
+    })
+
+    const payload = (await response.json()) as OnboardingApiPayload
+    if (!payload.onboarding) {
+      throw new Error(payload.error ?? `Onboarding action failed with ${response.status}`)
+    }
+
+    this.applyOnboardingState(payload.onboarding)
+    return payload.onboarding
+  }
+
+  private applyOnboardingState(onboarding: WorkspaceOnboardingState): void {
+    if (!this.state.boot) return
+    this.patchState({
+      boot: cloneBootWithOnboarding(this.state.boot, onboarding),
+    })
+  }
+
+  private async syncAfterOnboardingMutation(onboarding: WorkspaceOnboardingState): Promise<void> {
+    this.applyOnboardingState(onboarding)
+    this.appendOnboardingSummaryLine(onboarding)
+
+    if (onboarding.lastValidation?.status === "succeeded" || onboarding.bridgeAuthRefresh.phase !== "idle") {
+      void this.refreshBootAfterCurrentSettles({ soft: true })
+    }
+  }
+
+  private appendOnboardingSummaryLine(onboarding: WorkspaceOnboardingState): void {
+    const summary = summarizeOnboardingState(onboarding)
+    if (!summary) return
+
+    const lastLine = this.state.terminalLines.at(-1)
+    if (lastLine?.type === summary.type && lastLine.content === summary.message) {
+      return
+    }
+
+    this.patchState({
+      terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine(summary.type, summary.message)),
+    })
+  }
+
+  private emit(): void {
+    for (const listener of this.listeners) {
+      listener()
+    }
+  }
+
+  private patchState(patch: Partial<WorkspaceStoreState>): void {
+    this.state = { ...this.state, ...patch }
+    this.syncOnboardingPoller()
+    this.emit()
+  }
+
+  private syncOnboardingPoller(): void {
+    if (this.disposed) {
+      this.stopOnboardingPoller()
+      return
+    }
+
+    const flowStatus = this.state.boot?.onboarding.activeFlow?.status
+    const shouldPoll = Boolean(flowStatus && ACTIVE_ONBOARDING_FLOW_STATUSES.has(flowStatus))
+    if (shouldPoll && !this.onboardingPollTimer) {
+      this.onboardingPollTimer = setInterval(() => {
+        if (this.state.onboardingRequestState !== "idle") return
+        void this.fetchOnboardingState(true).catch((error) => {
+          const message = normalizeClientError(error)
+          this.patchState({
+            lastClientError: message,
+          })
+        })
+      }, 1500)
+      return
+    }
+
+    if (!shouldPoll) {
+      this.stopOnboardingPoller()
+    }
+  }
+
+  private stopOnboardingPoller(): void {
+    if (!this.onboardingPollTimer) return
+    clearInterval(this.onboardingPollTimer)
+    this.onboardingPollTimer = null
+  }
+
+  private ensureEventStream(): void {
+    if (this.eventSource || this.disposed || this.state.boot?.onboarding.locked) return
+
+    const stream = new EventSource(appendAuthParam(this.buildUrl("/api/session/events")))
+    this.eventSource = stream
+
+    stream.onopen = () => {
+      const previousState = this.lastStreamState
+      const wasDisconnected = previousState === "reconnecting" || previousState === "disconnected" || previousState === "error"
+      if (wasDisconnected) {
+        this.patchState({
+          terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine("success", "Live event stream reconnected")),
+        })
+      }
+      this.lastStreamState = "connected"
+      this.patchState({ connectionState: "connected", lastClientError: null })
+      if (wasDisconnected) {
+        void this.refreshBoot({ soft: true })
+      }
+    }
+
+    stream.onmessage = (message) => {
+      try {
+        const parsed: unknown = JSON.parse(message.data)
+        if (!isWorkspaceEvent(parsed)) {
+          this.patchState({
+            lastClientError: "Malformed event received from stream",
+            terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine("error", "Malformed event received from stream")),
+          })
+          return
+        }
+        this.handleEvent(parsed)
+      } catch (error) {
+        const text = normalizeClientError(error)
+        this.patchState({
+          lastClientError: text,
+          terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine("error", `Failed to parse stream event — ${text}`)),
+        })
+      }
+    }
+
+    stream.onerror = () => {
+      const nextConnectionState = this.lastStreamState === "connected" ? "reconnecting" : "error"
+      if (nextConnectionState !== this.lastStreamState) {
+        this.patchState({
+          connectionState: nextConnectionState,
+          terminalLines: withTerminalLine(
+            this.state.terminalLines,
+            createTerminalLine(
+              nextConnectionState === "reconnecting" ? "system" : "error",
+              nextConnectionState === "reconnecting"
+                ? "Live event stream disconnected — retrying…"
+                : "Live event stream failed before connection was established",
+            ),
+          ),
+        })
+      } else {
+        this.patchState({ connectionState: nextConnectionState })
+      }
+      this.lastStreamState = nextConnectionState
+    }
+  }
+
+  private closeEventStream(): void {
+    this.eventSource?.close()
+    this.eventSource = null
+  }
+
+  private handleEvent(event: WorkspaceEvent): void {
+    this.patchState({ lastEventType: event.type })
+
+    if (event.type === "bridge_status") {
+      this.recordBridgeStatus((event as BridgeStatusEvent).bridge)
+      return
+    }
+
+    if (event.type === "live_state_invalidation") {
+      this.handleLiveStateInvalidation(event as LiveStateInvalidationEvent)
+    }
+
+    // Route into structured live-interaction state (additive — summary lines still produced below)
+    this.routeLiveInteractionEvent(event)
+
+    const summary = summarizeEvent(event)
+    if (!summary) return
+
+    this.patchState({
+      terminalLines: withTerminalLine(this.state.terminalLines, createTerminalLine(summary.type, summary.message)),
+    })
+  }
+
+  private routeLiveInteractionEvent(event: WorkspaceEvent): void {
+    switch (event.type) {
+      case "extension_ui_request":
+        this.handleExtensionUiRequest(event as ExtensionUiRequestEvent)
+        break
+      case "message_update":
+        this.handleMessageUpdate(event as MessageUpdateEvent)
+        break
+      case "agent_end":
+      case "turn_end":
+        this.handleTurnBoundary()
+        break
+      case "tool_execution_start":
+        this.handleToolExecutionStart(event as ToolExecutionStartEvent)
+        break
+      case "tool_execution_update":
+        this.handleToolExecutionUpdate(event as ToolExecutionUpdateEvent)
+        break
+      case "tool_execution_end":
+        this.handleToolExecutionEnd(event as ToolExecutionEndEvent)
+        break
+      case "bridge_status":
+        // Handled upstream in handleEvent with early return — never reaches here
+        break
+      case "live_state_invalidation":
+        // Handled upstream in handleEvent via handleLiveStateInvalidation — no live interaction state update needed
+        break
+      case "extension_error":
+        // Terminal line produced by summarizeEvent — no live interaction state update needed
+        break
+    }
+  }
+
+  private handleExtensionUiRequest(event: ExtensionUiRequestEvent): void {
+    const method = event.method
+    switch (method) {
+      // Blocking methods → queue in pendingUiRequests
+      case "select":
+      case "confirm":
+      case "input":
+      case "editor":
+        this.patchState({
+          pendingUiRequests: [...this.state.pendingUiRequests, event as PendingUiRequest],
+        })
+        break
+      // Fire-and-forget methods → update state maps
+      case "notify":
+        // notify still produces a terminal line (via summarizeEvent), but we don't store it in pendingUiRequests
+        break
+      case "setStatus":
+        if (event.method === "setStatus") {
+          const next = { ...this.state.statusTexts }
+          if (event.statusText === undefined) {
+            delete next[event.statusKey]
+          } else {
+            next[event.statusKey] = event.statusText
+          }
+          this.patchState({ statusTexts: next })
+        }
+        break
+      case "setWidget":
+        if (event.method === "setWidget") {
+          const next = { ...this.state.widgetContents }
+          if (event.widgetLines === undefined) {
+            delete next[event.widgetKey]
+          } else {
+            next[event.widgetKey] = { lines: event.widgetLines, placement: event.widgetPlacement }
+          }
+          this.patchState({ widgetContents: next })
+        }
+        break
+      case "setTitle":
+        if (event.method === "setTitle") {
+          const nextTitle = event.title.trim()
+          this.patchState({ titleOverride: nextTitle ? nextTitle : null })
+        }
+        break
+      case "set_editor_text":
+        if (event.method === "set_editor_text") {
+          this.patchState({ editorTextBuffer: event.text })
+        }
+        break
+    }
+  }
+
+  private handleMessageUpdate(event: MessageUpdateEvent): void {
+    const assistantEvent = event.assistantMessageEvent
+    if (!assistantEvent) return
+    if (assistantEvent.type === "text_delta" && typeof assistantEvent.delta === "string") {
+      // If we were accumulating thinking and now text arrives, finalize the thinking segment
+      if (this.state.streamingThinkingText.length > 0) {
+        this.patchState({
+          currentTurnSegments: [...this.state.currentTurnSegments, { kind: "thinking", content: this.state.streamingThinkingText }],
+          streamingThinkingText: "",
+        })
+      }
+      this.patchState({
+        streamingAssistantText: this.state.streamingAssistantText + assistantEvent.delta,
+      })
+    } else if (assistantEvent.type === "thinking_delta" && typeof assistantEvent.delta === "string") {
+      // If we were accumulating text and now thinking arrives, finalize the text segment
+      if (this.state.streamingAssistantText.length > 0) {
+        this.patchState({
+          currentTurnSegments: [...this.state.currentTurnSegments, { kind: "text", content: this.state.streamingAssistantText }],
+          streamingAssistantText: "",
+        })
+      }
+      this.patchState({
+        streamingThinkingText: this.state.streamingThinkingText + assistantEvent.delta,
+      })
+    } else if (assistantEvent.type === "thinking_end") {
+      // Finalize thinking segment
+      if (this.state.streamingThinkingText.length > 0) {
+        this.patchState({
+          currentTurnSegments: [...this.state.currentTurnSegments, { kind: "thinking", content: this.state.streamingThinkingText }],
+          streamingThinkingText: "",
+        })
+      }
+    }
+  }
+
+  private handleTurnBoundary(): void {
+    // Finalize any remaining streaming content into segments
+    const pendingSegments: TurnSegment[] = []
+    if (this.state.streamingThinkingText.length > 0) {
+      pendingSegments.push({ kind: "thinking", content: this.state.streamingThinkingText })
+    }
+    if (this.state.streamingAssistantText.length > 0) {
+      pendingSegments.push({ kind: "text", content: this.state.streamingAssistantText })
+    }
+
+    const finalSegments = pendingSegments.length > 0
+      ? [...this.state.currentTurnSegments, ...pendingSegments]
+      : this.state.currentTurnSegments
+
+    // Build the flat transcript text (backward-compat for terminal.tsx / files-view.tsx)
+    const fullText = finalSegments
+      .filter((s): s is TurnSegment & { kind: "text" } => s.kind === "text")
+      .map((s) => s.content)
+      .join("")
+
+    if (fullText.length > 0 || finalSegments.length > 0) {
+      const nextTranscript = [...this.state.liveTranscript, fullText]
+      const nextThinking = [...this.state.liveThinkingTranscript, ""]
+      const nextSegments = [...this.state.completedTurnSegments, finalSegments]
+      const overflow = nextTranscript.length > MAX_TRANSCRIPT_BLOCKS ? nextTranscript.length - MAX_TRANSCRIPT_BLOCKS : 0
+      // When overflow trims the front of parallel arrays, also trim
+      // chatUserMessages to keep index-based interleaving aligned (#2707).
+      const trimmedUserMsgs = overflow > 0
+        ? this.state.chatUserMessages.slice(overflow)
+        : undefined
+      this.patchState({
+        liveTranscript: overflow > 0 ? nextTranscript.slice(overflow) : nextTranscript,
+        liveThinkingTranscript: overflow > 0 ? nextThinking.slice(overflow) : nextThinking,
+        completedTurnSegments: overflow > 0 ? nextSegments.slice(overflow) : nextSegments,
+        ...(trimmedUserMsgs !== undefined ? { chatUserMessages: trimmedUserMsgs } : {}),
+        streamingAssistantText: "",
+        streamingThinkingText: "",
+        currentTurnSegments: [],
+        completedToolExecutions: [],
+      })
+    } else if (this.state.streamingThinkingText.length > 0) {
+      // Turn ended with only thinking, no visible text — clear
+      this.patchState({
+        streamingThinkingText: "",
+        currentTurnSegments: [],
+        completedToolExecutions: [],
+      })
+    } else {
+      // Empty turn — just reset
+      this.patchState({
+        currentTurnSegments: [],
+        completedToolExecutions: [],
+      })
+    }
+  }
+
+  private handleToolExecutionStart(event: ToolExecutionStartEvent): void {
+    this.patchState({
+      activeToolExecution: {
+        id: event.toolCallId,
+        name: event.toolName,
+        args: (event as Record<string, unknown>).args as Record<string, unknown> | undefined,
+      },
+      // Treat pre-tool streaming text as ephemeral. Claude Code can emit
+      // provisional assistant text before a tool call, then replace it with
+      // the real final text after the tool completes. If we finalize that
+      // interim text here, the chat timeline shows stale text above the tool.
+      streamingAssistantText: "",
+      streamingThinkingText: "",
+    })
+  }
+
+  private handleToolExecutionUpdate(event: ToolExecutionUpdateEvent): void {
+    const active = this.state.activeToolExecution
+    if (!active || active.id !== event.toolCallId) return
+    this.patchState({
+      activeToolExecution: {
+        ...active,
+        result: event.partialResult
+          ? {
+              content: event.partialResult.content,
+              details: event.partialResult.details,
+              isError: Boolean(event.partialResult.isError),
+            }
+          : active.result,
+      },
+    })
+  }
+
+  private handleToolExecutionEnd(event: ToolExecutionEndEvent): void {
+    const active = this.state.activeToolExecution
+    if (active) {
+      const completed: CompletedToolExecution = {
+        id: active.id,
+        name: active.name,
+        args: active.args ?? {},
+        result: {
+          content: ((event as Record<string, unknown>).result as NonNullable<CompletedToolExecution["result"]> | undefined)?.content,
+          details: ((event as Record<string, unknown>).result as NonNullable<CompletedToolExecution["result"]> | undefined)?.details,
+          isError: event.isError,
+        },
+      }
+      const next = [...this.state.completedToolExecutions, completed]
+      this.patchState({
+        activeToolExecution: null,
+        completedToolExecutions: next.length > 50 ? next.slice(next.length - 50) : next,
+        // Also push tool segment into chronological order
+        currentTurnSegments: [...this.state.currentTurnSegments, { kind: "tool", tool: completed }],
+      })
+    } else {
+      this.patchState({ activeToolExecution: null })
+    }
+  }
+
+  private recordBridgeStatus(bridge: BridgeRuntimeSnapshot): void {
+    const digest = [bridge.phase, bridge.activeSessionId, bridge.lastError?.at, bridge.lastError?.message].join("::")
+    const shouldEmitLine = digest !== this.lastBridgeDigest
+    this.lastBridgeDigest = digest
+
+    const nextBoot = cloneBootWithBridge(this.state.boot, bridge)
+    const nextLiveBase: WorkspaceLiveState = {
+      ...this.state.live,
+      resumableSessions: overlayLiveBridgeSessionState(this.state.live.resumableSessions, nextBoot),
+    }
+    const nextLive = {
+      ...nextLiveBase,
+      recoverySummary: createWorkspaceRecoverySummary({ boot: nextBoot, live: nextLiveBase }),
+    }
+
+    const nextPatch: Partial<WorkspaceStoreState> = {
+      boot: nextBoot,
+      live: nextLive,
+      lastBridgeError: bridge.lastError,
+      sessionAttached: hasAttachedSession(bridge),
+      commandSurface: {
+        ...this.state.commandSurface,
+        sessionBrowser: syncSessionBrowserStateWithBridge(this.state.commandSurface.sessionBrowser, nextBoot),
+      },
+    }
+
+    if (shouldEmitLine) {
+      const summary = summarizeBridgeStatus(bridge)
+      nextPatch.terminalLines = withTerminalLine(this.state.terminalLines, createTerminalLine(summary.type, summary.message))
+    }
+
+    this.patchState(nextPatch)
+  }
+}
+
+const WorkspaceStoreContext = createContext<GSDWorkspaceStore | null>(null)
+
+export function GSDWorkspaceProvider({ children, store: externalStore }: { children: ReactNode; store?: GSDWorkspaceStore }) {
+  const [internalStore] = useState(() => new GSDWorkspaceStore())
+  const store = externalStore ?? internalStore
+
+  useEffect(() => {
+    // Only start/dispose if using internal store (not externally managed)
+    if (!externalStore) {
+      store.start()
+      return () => store.dispose()
+    }
+  }, [store, externalStore])
+
+  return <WorkspaceStoreContext.Provider value={store}>{children}</WorkspaceStoreContext.Provider>
+}
+
+function useWorkspaceStore(): GSDWorkspaceStore {
+  const store = useContext(WorkspaceStoreContext)
+  if (!store) {
+    throw new Error("useWorkspaceStore must be used within GSDWorkspaceProvider")
+  }
+  return store
+}
+
+export function useGSDWorkspaceState(): WorkspaceStoreState {
+  const store = useWorkspaceStore()
+  return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot)
+}
+
+export function useGSDWorkspaceActions(): Pick<
+  GSDWorkspaceStore,
+  | "sendCommand"
+  | "submitInput"
+  | "clearTerminalLines"
+  | "consumeEditorTextBuffer"
+  | "refreshBoot"
+  | "refreshOnboarding"
+  | "openCommandSurface"
+  | "closeCommandSurface"
+  | "setCommandSurfaceSection"
+  | "selectCommandSurfaceTarget"
+  | "loadGitSummary"
+  | "loadRecoveryDiagnostics"
+  | "loadForensicsDiagnostics"
+  | "loadDoctorDiagnostics"
+  | "applyDoctorFixes"
+  | "loadSkillHealthDiagnostics"
+  | "loadKnowledgeData"
+  | "loadCapturesData"
+  | "loadSettingsData"
+  | "loadHistoryData"
+  | "loadInspectData"
+  | "loadHooksData"
+  | "loadExportData"
+  | "loadUndoInfo"
+  | "loadCleanupData"
+  | "loadSteerData"
+  | "executeUndoAction"
+  | "executeCleanupAction"
+  | "resolveCaptureAction"
+  | "updateSessionBrowserState"
+  | "loadSessionBrowser"
+  | "renameSessionFromSurface"
+  | "loadAvailableModels"
+  | "applyModelSelection"
+  | "applyThinkingLevel"
+  | "setSteeringModeFromSurface"
+  | "setFollowUpModeFromSurface"
+  | "setAutoCompactionFromSurface"
+  | "setAutoRetryFromSurface"
+  | "abortRetryFromSurface"
+  | "switchSessionFromSurface"
+  | "loadSessionStats"
+  | "exportSessionFromSurface"
+  | "loadForkMessages"
+  | "forkSessionFromSurface"
+  | "compactSessionFromSurface"
+  | "saveApiKey"
+  | "saveApiKeyFromSurface"
+  | "startProviderFlow"
+  | "startProviderFlowFromSurface"
+  | "submitProviderFlowInput"
+  | "submitProviderFlowInputFromSurface"
+  | "cancelProviderFlow"
+  | "cancelProviderFlowFromSurface"
+  | "logoutProvider"
+  | "logoutProviderFromSurface"
+  | "respondToUiRequest"
+  | "dismissUiRequest"
+  | "sendSteer"
+  | "sendAbort"
+  | "pushChatUserMessage"
+> {
+  const store = useWorkspaceStore()
+  return {
+    sendCommand: store.sendCommand,
+    submitInput: store.submitInput,
+    clearTerminalLines: store.clearTerminalLines,
+    consumeEditorTextBuffer: store.consumeEditorTextBuffer,
+    refreshBoot: store.refreshBoot,
+    refreshOnboarding: store.refreshOnboarding,
+    openCommandSurface: store.openCommandSurface,
+    closeCommandSurface: store.closeCommandSurface,
+    setCommandSurfaceSection: store.setCommandSurfaceSection,
+    selectCommandSurfaceTarget: store.selectCommandSurfaceTarget,
+    loadGitSummary: store.loadGitSummary,
+    loadRecoveryDiagnostics: store.loadRecoveryDiagnostics,
+    loadForensicsDiagnostics: store.loadForensicsDiagnostics,
+    loadDoctorDiagnostics: store.loadDoctorDiagnostics,
+    applyDoctorFixes: store.applyDoctorFixes,
+    loadSkillHealthDiagnostics: store.loadSkillHealthDiagnostics,
+    loadKnowledgeData: store.loadKnowledgeData,
+    loadCapturesData: store.loadCapturesData,
+    loadSettingsData: store.loadSettingsData,
+    loadHistoryData: store.loadHistoryData,
+    loadInspectData: store.loadInspectData,
+    loadHooksData: store.loadHooksData,
+    loadExportData: store.loadExportData,
+    loadUndoInfo: store.loadUndoInfo,
+    loadCleanupData: store.loadCleanupData,
+    loadSteerData: store.loadSteerData,
+    executeUndoAction: store.executeUndoAction,
+    executeCleanupAction: store.executeCleanupAction,
+    resolveCaptureAction: store.resolveCaptureAction,
+    updateSessionBrowserState: store.updateSessionBrowserState,
+    loadSessionBrowser: store.loadSessionBrowser,
+    renameSessionFromSurface: store.renameSessionFromSurface,
+    loadAvailableModels: store.loadAvailableModels,
+    applyModelSelection: store.applyModelSelection,
+    applyThinkingLevel: store.applyThinkingLevel,
+    setSteeringModeFromSurface: store.setSteeringModeFromSurface,
+    setFollowUpModeFromSurface: store.setFollowUpModeFromSurface,
+    setAutoCompactionFromSurface: store.setAutoCompactionFromSurface,
+    setAutoRetryFromSurface: store.setAutoRetryFromSurface,
+    abortRetryFromSurface: store.abortRetryFromSurface,
+    switchSessionFromSurface: store.switchSessionFromSurface,
+    loadSessionStats: store.loadSessionStats,
+    exportSessionFromSurface: store.exportSessionFromSurface,
+    loadForkMessages: store.loadForkMessages,
+    forkSessionFromSurface: store.forkSessionFromSurface,
+    compactSessionFromSurface: store.compactSessionFromSurface,
+    saveApiKey: store.saveApiKey,
+    saveApiKeyFromSurface: store.saveApiKeyFromSurface,
+    startProviderFlow: store.startProviderFlow,
+    startProviderFlowFromSurface: store.startProviderFlowFromSurface,
+    submitProviderFlowInput: store.submitProviderFlowInput,
+    submitProviderFlowInputFromSurface: store.submitProviderFlowInputFromSurface,
+    cancelProviderFlow: store.cancelProviderFlow,
+    cancelProviderFlowFromSurface: store.cancelProviderFlowFromSurface,
+    logoutProvider: store.logoutProvider,
+    logoutProviderFromSurface: store.logoutProviderFromSurface,
+    respondToUiRequest: store.respondToUiRequest,
+    dismissUiRequest: store.dismissUiRequest,
+    sendSteer: store.sendSteer,
+    sendAbort: store.sendAbort,
+    pushChatUserMessage: store.pushChatUserMessage,
+  }
+}
+
+export function buildPromptCommand(
+  input: string,
+  bridge: BridgeRuntimeSnapshot | null | undefined,
+): WorkspaceBridgeCommand {
+  const outcome = dispatchBrowserSlashCommand(input, {
+    isStreaming: bridge?.sessionState?.isStreaming,
+  })
+
+  if (outcome.kind === "prompt" || outcome.kind === "rpc") {
+    return outcome.command
+  }
+
+  throw new Error(
+    `buildPromptCommand cannot serialize ${outcome.input || input} because browser dispatch resolved it to ${outcome.kind}; use submitInput() instead.`,
+  )
+}
+