@hienlh/ppm 0.9.85 → 0.9.87

package/docs/codebase-summary.md

@@ -1,13 +1,13 @@
 # PPM Codebase Summary
 
-**Last Updated:** 2026-04-06
-**Version:** 0.9.10
+**Last Updated:** 2026-04-15
+**Version:** 0.9.86
 **Repository:** PPM (Project & Process Manager) — Multi-provider web IDE/project manager with Claude Agent SDK
 
 **Core Statistics:**
-- **303 files** across CLI, server, web, and test layers
-- **490,667 tokens** total codebase size
-- **492 passing tests** (13 new tests for provider models API)
+- **366 files** across CLI, server, web, packages, and test layers
+- **885,308 tokens** total codebase size (repomix)
+- **500+ passing tests**
 - **Tech Stack:** Bun (runtime), Hono (HTTP), React (UI), Claude Agent SDK (AI)
 
 ---
@@ -60,9 +60,9 @@ src/
 │   ├── account.service.ts       # Account CRUD & encryption
 │   ├── upgrade.service.ts       # Version checking, installation
 │   ├── mcp-config.service.ts    # MCP server CRUD (list, get, set, remove, import)
-│   ├── extension.service.ts     # Extension lifecycle, activation, state management
+│   ├── extension.service.ts     # Extension lifecycle, activation, state management (bundled + user discovery)
 │   ├── extension-installer.ts   # npm install, symlink, removal
-│   ├── extension-manifest.ts    # Parse + discover manifests
+│   ├── extension-manifest.ts    # Parse manifests + bundled discovery from packages/ext-*
 │   ├── extension-rpc.ts         # RPC channel (request/response/events)
 │   ├── extension-host-worker.ts # Worker-side extension loading
 │   ├── contribution-registry.ts # Central registry for commands, views, config
@@ -166,9 +166,10 @@ src/
 │           │   ├── usage-badge.tsx  # Token usage display
 │           │   ├── attachment-chips.tsx # Display attached files
 │           │   └── chat-placeholder.tsx # Empty state
-│           ├── editor/              # Code editor (800+ LOC, 6 files)
+│           ├── editor/              # Code editor (900+ LOC, 7 files)
 │           │   ├── code-editor.tsx  # Monaco Editor integration (@monaco-editor/react, v2.0+)
 │           │   ├── diff-viewer.tsx  # Monaco diff viewer for git diffs (v2.0+)
+│           │   ├── conflict-editor.tsx # Inline conflict resolution (3-way markers, visual highlighting, v0.9.86+)
 │           │   ├── editor-breadcrumb.tsx # VSCode-style breadcrumb with nested dropdown
 │           │   ├── editor-toolbar.tsx # File-type contextual toolbar
 │           │   ├── csv-preview.tsx  # CSV table viewer with @tanstack/react-table
@@ -182,17 +183,17 @@ src/
 │           │   └── git-placeholder.tsx
 │           ├── layout/              # Layout components (13 files)
 │           │   ├── panel-layout.tsx  # Main grid layout (react-resizable-panels)
-│           │   ├── editor-panel.tsx  # Wrapper for tab content within a panel
+│           │   ├── editor-panel.tsx  # Wrapper for tab content within a panel (v0.9.85+: fallback guards)
 │           │   ├── project-bar.tsx   # 52px sidebar with project avatars, share popover
 │           │   ├── project-bottom-sheet.tsx # Mobile project switcher
 │           │   ├── sidebar.tsx       # Left sidebar (Explorer/Git/Database/Settings tabs)
-│           │   ├── tab-bar.tsx       # Tab bar with icons, connection color display
+│           │   ├── tab-bar.tsx       # Tab bar with icons, connection color display (v0.9.85+: fallback guards)
 │           │   ├── draggable-tab.tsx  # Draggable tab with context menu, rename, connection color
-│           │   ├── tab-content.tsx    # Router for tab content
+│           │   ├── tab-content.tsx    # Router for tab content (v0.9.85+: fallback guards)
 │           │   ├── split-drop-overlay.tsx # Drop zone for tab splitting
 │           │   ├── command-palette.tsx # Global command palette (Shift+Shift, DB table search)
 │           │   ├── add-project-form.tsx # Modal form to add projects
-│           │   ├── mobile-nav.tsx    # Bottom navigation for mobile
+│           │   ├── mobile-nav.tsx    # Bottom navigation for mobile (v0.9.85+: fallback guards)
 │           │   └── mobile-drawer.tsx # Mobile overlay drawer
 │           ├── database/            # Database management (5 files, 300+ LOC)
 │           │   ├── database-sidebar.tsx # Sidebar tab container (connection list, form)
@@ -377,6 +378,56 @@ GitStatusPanel refreshes: GET /api/project/:name/git/status
 UI updates staged/unstaged lists
 ```
 
+### Git Workflow Enhancements (v0.9.86+)
+
+**Stash Management:**
+- Toolbar popover lists all stashes (index, abbreviated hash, message)
+- Apply/Pop/Drop actions per stash with visual feedback
+- "Stash Changes" button saves uncommitted work to stash list
+- Stash state integrated into RepoInfo and refreshed on status changes
+
+**Conflict Detection & Resolution:**
+- Detects merge/rebase/cherry-pick state from .git sentinel files (MERGE_HEAD, rebase-merge/, CHERRY_PICK_HEAD)
+- Parses git status UU/AA/DD/AU/UA/DU/UD codes for unmerged entries
+- Conflict state banner shows state type, progress (e.g., "3/5" for rebase), and Continue/Skip/Abort actions
+- New `conflict-editor` tab type with Monaco-based visual conflict resolution
+  - Parses 3-way conflict markers (<<<<<<, =======, >>>>>>>)
+  - Highlights current (green), incoming (blue), and marker lines (gray)
+  - Accept buttons for Current / Incoming / Both with automatic save
+  - Real-time conflict counter: "N conflicts remaining" → "All resolved"
+
+**Rebase from Context Menu:**
+- Right-click commits to open rebase menu
+- Confirmation dialog with branch/target selection
+- Rebase state tracking and progress display during operation
+
+**Worktree Management:**
+- Popover UI for listing, creating, removing, pruning worktrees
+- Current worktree highlighted with active badge
+- "Create Worktree Here..." option in commit context menu
+- Auto-add unregistered worktrees as projects with confirmation
+- Branch-already-exists handling with force-replace option
+
+### Tab System Safety (v0.9.85+)
+
+All tab routing and rendering components now include fallback guards for unknown tab types:
+
+**Components Updated:**
+- `tab-bar.tsx` — Tab item rendering with fallback icon/label
+- `mobile-nav.tsx` — Mobile tab selection with fallback handling
+- `tab-content.tsx` — Content router with "Unknown tab type" fallback
+- `editor-panel.tsx` — Panel wrapper with graceful unknown type handling
+
+**Behavior:**
+- Unknown tab types no longer crash the UI
+- Fallback displays icon + tab identifier
+- Users can still close/manage unknown tabs
+- Enables safe extension tab additions without core UI changes
+
+**Motivation:** Support future extension-contributed tab types without requiring core UI updates.
+
+---
+
 ## Critical Types
 
 | Type | Location | Purpose |
@@ -384,9 +435,11 @@ UI updates staged/unstaged lists
 | `ApiResponse<T>` | types/api.ts | Standard envelope for all REST responses |
 | `AIProvider` | providers/provider.interface.ts | Interface for AI model adapters |
 | `ChatEvent` | types/chat.ts | Union of streaming message types |
-| `GitStatus` | types/git.ts | Current branch, staged, unstaged, untracked files |
+| `GitStatus` | types/git.ts | Current branch, staged, unstaged, untracked files (includes conflicted field v0.9.86+) |
 | `Session` | types/chat.ts | Chat session with ID, projectName, title, createdAt |
 | `Project` | types/project.ts | Project config (name, path) |
+| `MergeState` | ext-git-graph/src/types.ts | Merge/rebase/cherry-pick state with progress tracking (v0.9.86+) |
+| `TabType` | web/stores/tab-store.ts | "editor" \| "chat" \| "terminal" \| "database" \| "git-graph" \| "conflict-editor" \| "settings" (v0.9.86+) |
 
 ## External Dependencies
 
@@ -624,6 +677,109 @@ ppm ext disable @ppm/ext-db       # Disable
 ppm ext dev /path/to/src          # Dev symlink
 ```
 
+### Bundled Extensions (v0.9.85+)
+
+PPM ships with pre-built extensions in `packages/ext-*` that are auto-discovered and available out-of-the-box:
+
+**Discovery:**
+- `discoverBundledManifests()` scans `packages/` for directories matching `ext-*`
+- Bundled extensions loaded during `discover()` before user-installed extensions
+- User-installed extensions override bundled if same ID (user takes precedence)
+
+**Behavior:**
+- `ppm ext list` shows "Source" column: `bundled` (cyan) vs `user`
+- Bundled extensions cannot be removed (`ppm ext remove` rejected with helpful message)
+- Use `ppm ext disable` to turn off bundled extensions
+- Removal protection prevents accidental deletion of core extensions
+
+**Current Bundled Extensions:**
+- `@ppm/ext-git-graph` — Interactive git history visualization with workflow actions
+
+**Architecture:**
+- Extension paths tracked in `extensionService.extensionPaths` (ID → directory)
+- Bundled IDs tracked in `extensionService.bundledIds` Set
+- `isBundled(id)` public method for checking extension source
+
+---
+
+## ext-git-graph Extension (Git History Visualization)
+
+### Overview
+The git-graph extension provides an interactive SVG visualization of repository commit history with comprehensive git workflow support. Implements the vscode-git-graph deterministic layout algorithm with faithful branch path rendering.
+
+### Key Features
+
+**Graph Visualization:**
+- Single SVG model with continuous Bézier branch paths for smooth merge visualization
+- Deterministic lane assignment algorithm with greedy color reuse for branch lanes
+- Shadow lines for visual depth and branch continuity
+- Proper HEAD/stash node rendering (hollow circle for HEAD, nested circles for stash)
+- Mobile SVG alignment: gridY matches 44px CSS row height for responsive layouts
+
+**Git Workflow Actions:**
+- **File Operations:** Stage/unstage files, open in editor, discard changes
+- **Commits:** Create commits directly from webview with message and file selection
+- **Branch Operations:** Stash/reset/clean with context menu and safety warnings
+- **Repository:** Auto-fetch with configurable interval, manual fetch button
+- **Filters:** Branch/tag/remote filters, tree/list view toggle
+
+**UI Components:**
+- Resizable graph column for flexible workspace adjustment
+- Branch filter dropdown for quick navigation
+- Tree/list view toggle for different visualization modes
+- Commit detail panel with file diffs and action buttons
+- Context menus with destructive operation warnings
+
+### Architecture
+
+**Location:** `packages/ext-git-graph/`
+
+**Files:**
+- `extension.ts` (370 LOC) — RPC handlers, git operations, settings management
+- `webview-html.ts` (443 additions) — Faithful SVG graph rendering with deterministic layout
+- `types.ts` — Extension settings, message types, git operation definitions
+- `git-log-parser.ts` — Parse git log with branches, tags, remotes, stashes
+- `extension.test.ts` (230+ lines) — Integration tests for RPC handlers
+- `webview-html.test.ts` — Graph rendering and layout tests
+
+**RPC Protocol:**
+- `gitStatus()` — Get current repo state
+- `gitLog()` — Fetch commit history
+- `stage(path)` / `unstage(path)` — File staging
+- `commit(message, files)` — Create commit
+- `stash()` / `reset(ref)` / `clean()` — Branch operations
+- `openFile(path)` — Open in editor (IPC to main window)
+
+**Settings:**
+- `autoFetchInterval: number` — Seconds between auto-fetches (0 = disabled)
+
+### Security
+
+**Path Validation:**
+- `assertSafePath()` in extension-rpc-handlers ensures git operations only on registered project paths
+- Prevents directory traversal attacks
+- Cross-project workspace safety via RPC sandboxing
+
+**XSS Prevention:**
+- `escHtml()` applied to parent hashes and file status in detail panel
+- Sanitized commit messages and metadata display
+
+### Mobile & Responsive
+
+- Long-press support for context menus on touch devices
+- Responsive CSS with flexible column sizing
+- Dark/light theme support via CSS variables
+- Touch-friendly button sizing (44px minimum)
+
+### Testing
+
+**62 unit tests** covering:
+- Git log parsing (commits, branches, tags, stashes)
+- Parser edge cases (merge commits, rebases, detached HEAD)
+- RPC handler validation and error cases
+- Webview HTML rendering and layout algorithms
+- Integration with main extension lifecycle
+
 ---
 
 ## Slash-Discovery Module (Modular Command Engine)

package/docs/extension-development-guide.md

@@ -279,6 +279,78 @@ const value = context.globalState.get("key");
 await context.workspaceState.update("project", "data");
 ```
 
+### Process Spawning (Subprocess Execution)
+
+Extensions needing to run external commands use the RPC `process:spawn` handler. This is essential for extensions that interact with CLIs (git, docker, node, etc.).
+
+```typescript
+// Inside your extension (via RPC)
+const rpc = (context as any).rpc;
+
+const result = await rpc.request("process:spawn", [
+  "git",                    // command (must be in allowlist)
+  ["log", "--oneline", "-n", "10"],  // args array
+  { cwd: process.cwd() }    // options: { cwd?: string, timeout?: number }
+]);
+
+// Result structure
+if (!result.error) {
+  const { code, stdout, stderr } = result;
+  console.log("Exit code:", code);
+  console.log("Output:", stdout);
+} else {
+  console.error("Command failed:", result.error);
+}
+```
+
+**Allowed Commands** (security allowlist):
+- `git` — Version control operations
+- `node`, `bun` — JavaScript runtimes
+- `npm`, `yarn`, `pnpm` — Package managers
+- `docker` — Container operations
+- `psql` — PostgreSQL CLI
+- `sqlite3` — SQLite CLI
+- `python3`, `python` — Python runtime
+
+**Restrictions:**
+- CWD limited to current project root (no path escaping)
+- 30-second timeout by default
+- Stdout/stderr captured as strings
+- Non-zero exit codes returned as error
+
+**Example: Git Graph Extension**
+
+```typescript
+// In ext-git-graph, spawn git to fetch log
+export async function activate(context: ExtensionContext, vscode: any) {
+  const rpc = (context as any).rpc;
+  
+  context.subscriptions.push(
+    vscode.commands.registerCommand("git-graph.view", async () => {
+      try {
+        const result = await rpc.request("process:spawn", [
+          "git",
+          ["log", "--all", "--oneline", "--graph"],
+          { cwd: process.cwd() }
+        ]);
+        
+        if (result.error) {
+          await vscode.window.showErrorMessage(`Git error: ${result.error}`);
+          return;
+        }
+        
+        // Parse result.stdout and render graph in webview
+        const commits = parseGitLog(result.stdout);
+        const panel = vscode.window.createWebviewPanel("git-graph", "Git Graph", vscode.ViewColumn.Active);
+        panel.webview.html = renderSvgGraph(commits);
+      } catch (e) {
+        await vscode.window.showErrorMessage(`Failed to load git graph: ${e}`);
+      }
+    })
+  );
+}
+```
+
 ### Utilities
 
 ```typescript
@@ -313,6 +385,7 @@ emitter.fire("event data");  // Notify listeners
 | **Webview Panel** | ✅ Supported | Sandboxed iframe, 2-way messaging |
 | **Workspace Config** | ✅ Supported | Read/write user & workspace settings |
 | **Workspace FS** | ⚠️ Partial | Read, write, stat, readDirectory (no watch) |
+| **Process Spawn** | ✅ Supported | Run external commands (git, npm, etc.) |
 | **Storage (Memento)** | ✅ Supported | Global & workspace state, auto-persisted |
 | **Uri** | ✅ Supported | File/webview URI utilities |
 | **EventEmitter** | ✅ Supported | Custom event streams |
@@ -439,7 +512,9 @@ ppm ext dev ./path/to/extension
 
 ---
 
-## Example: Database Viewer
+## Examples
+
+### Database Viewer
 
 See `packages/ext-database/` in the PPM repo for a complete reference extension:
 
@@ -490,6 +565,28 @@ export function activate(context: ExtensionContext, vscode: any) {
 }
 ```
 
+### Git Graph
+
+See `packages/ext-git-graph/` for an extension using **process:spawn** to run git commands:
+
+- **Process spawning** via RPC to execute `git log` across any registered project
+- **SVG graph rendering** faithful port of vscode-git-graph algorithm:
+  - Single SVG overlay with continuous branch paths (Bézier curves)
+  - Shadow lines for visual depth
+  - HEAD and stash node indicators
+  - Color-coded column tracking for branch visualization
+- **Webview panel** for interactive visualization with scrolling commit list
+- **Commit details** panel with author, date, message, and file changes
+- **Context menu** for actions (checkout, cherry-pick, etc.)
+- **Search/find** widget with navigation within the graph
+
+Key patterns:
+- Use `process:spawn` RPC to safely run git commands from any registered project root
+- Parse git log output and compute graph coordinates (row, column, edge routing)
+- Render single SVG overlay synchronized with commit list rows
+- Implement custom graph rendering algorithm (path computation, Bézier curves, node placement)
+- Two-way messaging between extension and webview for interactions and detail panel updates
+
 ---
 
 ## Best Practices

package/docs/journals/260414-1400-ext-git-graph-port-complete.md

@@ -0,0 +1,147 @@
+# Git-Graph Extension Port — Phase 1-4 Complete
+
+**Date**: 2026-04-14 14:00
+**Severity**: Medium (architectural pattern addition)
+**Component**: @ppm/ext-git-graph (new extension), process:spawn RPC handler, extension RPC security
+**Status**: Resolved (phases 1-4), Phase 5 deferred to v0.2
+
+## What Happened
+
+Completed port of vscode-git-graph concepts to PPM as a self-contained extension. Full implementation of phases 1-4 per plan at `plans/260414-1132-ext-git-graph-port/plan.md`:
+
+1. **Extension scaffold** — Created `packages/ext-git-graph/` with clean-room rewrite (not copy-paste from vscode-git-graph)
+2. **Git log parsing** — Implemented `GitLogParser` to parse `git log --pretty=fuller --numstat` into SVG-compatible commit graph (7 source files)
+3. **RPC infrastructure** — Added `process:spawn` handler to PPM core enabling extensions to execute subprocesses from Worker threads
+4. **Security hardening** — Fixed critical vulnerability in process:spawn with command allowlist + CWD sandboxing + env var filtering
+5. **Tests** — 62 new tests, all 1269 suite passing, zero TypeScript regressions
+
+Committed as `451811c` with 2304 lines across 14 files.
+
+## The Brutal Truth
+
+This was **exciting but risky**. We shipped a brand-new capability (process spawning from extensions) and initially did it with zero security guardrails. The security review caught it immediately, but that's a pattern we need to kill: **never add execution capabilities without threat modeling first.**
+
+The temptation to just make git work from the webview was strong enough that we cut corners on the design phase. We got lucky the code reviewer was paranoid. Next time it won't be.
+
+## Technical Details
+
+### Process Spawn Handler (src/services/extension-rpc-handlers.ts)
+
+Added `process:spawn` RPC handler enabling extensions to execute commands. Initial implementation had **no restrictions** — any command, any args, any env.
+
+```typescript
+// BEFORE: Wide open execution
+const { command, args, options } = message.payload;
+const process = spawn(command, args, options);
+
+// AFTER: Allowlist + constraints
+const ALLOWED_COMMANDS = new Set(['git', 'node', 'bun', 'npx', 'sqlite3']);
+if (!ALLOWED_COMMANDS.has(command)) {
+  throw new Error(`Command not allowed: ${command}`);
+}
+// CWD sandboxed to project directory
+// ANTHROPIC_API_KEY and auth env vars filtered
+```
+
+### Git Log Parsing (packages/ext-git-graph/src/git-log-parser.ts)
+
+Switched from `--stat` to `--numstat` for reliable file change counts. `--stat` produces human-readable output that varies by terminal width; `--numstat` is machine-parseable and deterministic.
+
+```bash
+# Used:
+git log --pretty=fuller --numstat --graph
+
+# Output: additions<tab>deletions<tab>filename
+1    0    src/app.ts
+14   2    package.json
+```
+
+### Security Fixes
+
+**Root cause**: Added new capability without threat model. Extensions running in Worker threads got full subprocess execution permission.
+
+**Fix**:
+- Command allowlist (git, node, bun, npx, sqlite3 only)
+- CWD constrained to project directory (no filesystem escape)
+- Env var blocklist (ANTHROPIC_API_KEY, OPENAI_API_KEY, GITHUB_TOKEN, etc.)
+- No shell interpolation (`{ shell: false }`)
+- Timeout enforced (30s default)
+
+## What We Tried
+
+1. **Direct webview subprocess execution** — Blocked by Bun WebSocket limitations, webviews can't spawn processes
+2. **Defer to v0.2** — Initial plan (phases 1-4 in one sprint was ambitious)
+3. **Generic "any command" RPC** — Code review rejected immediately, security concern
+4. **Allowlist approach** — Accepted, provides extension developers clear expectations
+
+## Root Cause Analysis
+
+**Why did we design process:spawn without security guardrails?**
+
+1. **Pressure to ship**: Phase 4 (webview integration) drove implementation speed over design
+2. **Assumption of trust**: Thought "extensions are trusted code," forgot that extensions can be community-written
+3. **No threat model**: Skipped asking "what can go wrong?" before coding
+4. **Copy-paste instinct**: Wanted to make it "work like vscode," forgot PPM runs user code differently (in Workers, not main thread)
+
+We got lucky. The code reviewer (rightfully paranoid) caught it. But this is a pattern we need to break: **new capabilities require threat modeling before implementation, not after.**
+
+## Lessons Learned
+
+1. **New execution paths need threat model before code**
+   - process:spawn is the second execution handler (after tool execution in SDK provider)
+   - Both need documented threat models and allowlist rationale
+   - Code review should include security architect, not just functionality check
+
+2. **Allowlist is better than blocklist for subprocess execution**
+   - `{ shell: false }` is good but not sufficient (can still exec arbitrary binaries)
+   - Command allowlist is explicit and auditable
+   - Future: move allowlist to config for self-hosted extensions
+
+3. **--numstat vs --stat for parsing**
+   - Machine-readable output first, always
+   - Human formatting should be applied on render, not parsing
+   - This decision unblocks future work (avatars, statistics)
+
+4. **Phases should be strict — defer aggressively**
+   - Phase 5 (avatars, auto-refresh, settings, GPG, multi-repo) deferred to v0.2
+   - Shipping 4 phases in one sprint was tight; no time for complexity
+   - v0.2 roadmap is now clear (these are committed features)
+
+## Next Steps
+
+1. **Document process:spawn threat model** — Add to `docs/system-architecture.md` (extension security section)
+   - Allowed commands and rationale
+   - Environment filtering rules
+   - Timeout behavior
+   - Future: community extension sandboxing
+
+2. **Phase 5 for v0.2** — Deferred features:
+   - Avatar rendering in commit nodes (requires image caching)
+   - Auto-refresh on file watch (requires debounced git log polling)
+   - User preferences (dark mode, node size, graph direction)
+   - GPG signature verification (requires gpg in allowlist)
+   - Multi-repository support (requires RPC batching)
+
+3. **Extension RPC security audit** — Review other RPC handlers for similar gaps
+   - `file:read`, `file:write`, `git:*` handlers
+   - Document allowlist for each
+   - Add to security review checklist
+
+4. **Extension marketplace trust model** — When we ship ext marketplace (v1.0), need:
+   - Permission declaration (like Android APKs)
+   - Audit log of extension subprocess calls
+   - User warning on suspicious commands
+
+## Files Changed
+
+- `packages/ext-git-graph/` — 7 source files (2047 lines)
+- `src/services/extension-rpc-handlers.ts` — Added process:spawn handler
+- `packages/vscode-compat/src/process.ts` — ProcessService API
+- 4 new test files, 62 new tests
+- `packages/ext-git-graph/tests/git-log-parser.test.ts` — 28 parsing tests
+
+**Commit**: `451811c` | **Lines**: +2304 / -12 | **Tests**: 1269 passing (62 new)
+
+---
+
+**Written by**: Engineering diarist | **Next review**: Before Phase 5 planning (v0.2 scope meeting)

package/docs/journals/260414-1452-git-graph-faithful-port.md

@@ -0,0 +1,144 @@
+# Git Graph Algorithm Port: SVG Rendering Faithful to vscode-git-graph
+
+**Date**: 2026-04-14 14:52
+**Severity**: High
+**Component**: ext-git-graph WebView
+**Status**: Resolved
+
+## What Happened
+
+Completed faithful port of vscode-git-graph `graph.ts` SVG rendering algorithm into PPM's ext-git-graph extension. Previous implementation was a from-scratch rewrite that stripped out critical features entirely: no continuous lines between commits, no merge routing logic, no HEAD/stash styling, no shadow lines for depth.
+
+The port restored full feature parity with the original while adapting for PPM's commit model and mobile layout requirements.
+
+## The Brutal Truth
+
+This was frustrating because the previous implementation _looked_ functional at first glance — it rendered some boxes and lines — but fundamentally misunderstood how git graph visualization works. When you have multiple branches interleaving, you can't just draw independent vertical lines per commit. You need intelligent path routing to:
+- Avoid visual collisions at merge points
+- Reuse column assignments across the graph
+- Transition smoothly between lane positions with curves
+- Visually distinguish shadow (background) vs active (foreground) paths
+
+Spending days on a rewrite that missed all this was inefficient. Should have deconstructed vscode-git-graph from day one instead of guessing.
+
+The real kick is that the algorithm's complexity made sense only after reading the original code. No amount of visual inspection of the original output would have revealed why it worked — the graph determinism is in the column allocation and path-finding, not just drawing code.
+
+## Technical Details
+
+### Porting Scope
+
+**Implemented faithfully:**
+- `GBranch`, `GVertex`, `GEdge` data structures
+- `determinePath(from, to, availableColours)` — core routing algorithm
+- `graphGetAvailableColour(graph, row, col)` — column reuse across rows
+- Bézier curve transitions with `d = 0.8 × gridY` control point offset
+- Shadow lines: thicker, semi-transparent paths behind colored paths
+- HEAD node: hollow circle with branch label
+- Stash node: nested circles (outer for stash, inner for commit)
+- Commit dot centering in column with optional border ring
+
+**Intentionally skipped (not needed for PPM):**
+- `onlyFollowFirstParent` filter mode
+- `UNCOMMITTED` virtual commit node
+- Circle-at-checkout indicator (PPM uses different HEAD semantics)
+- `--all` ref filtering (PPM loads fixed commit range)
+
+**Adapted for PPM:**
+- Stash detection: `state.stashes` Set instead of `commit.stash` boolean (PPM model)
+- Grid config: `{ x: 16, y: 28, gridX: 8, gridY: 14 }` — compact for table row height
+- Mobile SVG: viewport width detection, gridY 28→44px on mobile for touch targets
+
+### Bugs Fixed During Implementation
+
+**Critical: Dot Misalignment (1px per row cumulative)**
+
+`.col-graph` had explicit `height: 28px` styling. Parent had `box-sizing: border-box` with `1px border`. This created:
+```
+Parent min-height: 28px (includes border)
+  → Content box: 27px (28 - 1px border)
+Row parent expanded to 29px to fit
+SVG used 28px intervals
+Result: 1px drift cumulative, visible misalignment by row 10+
+```
+
+Fix: Removed explicit `height`, let flexbox handle alignment. SVG uses computed row height.
+
+**High: Path Scope Rejection**
+
+Extensions couldn't execute git in user project directories. `assertSafePath` in `extension-rpc-handlers.ts` only allowed CWD and `~/.ppm/extensions/`. User projects were rejected.
+
+```typescript
+// Before
+if (cwd !== CWD && !cwd.startsWith(PPM_EXTENSIONS_DIR)) {
+  throw new Error("Path not allowed");
+}
+
+// After
+if (!isAllowedPath(cwd, [CWD, PPM_EXTENSIONS_DIR, ...registeredProjectPaths])) {
+  throw new Error("Path not allowed");
+}
+```
+
+**Medium: XSS in Detail Panel**
+
+Parent hashes and file status inserted into innerHTML without escaping. User with special chars in file path (e.g., `test<img onerror="alert('xss')">`) would execute.
+
+Fix: Used `textContent` for data, `innerHTML` for formatted markup only.
+
+**Medium: Regex Ordering in formatCommitMessage**
+
+URL regex ran before hash regex. URLs like `https://github.com/user/repo/commit/abc123` would partially match hash pattern, creating nested HTML tags.
+
+```typescript
+// Before: [urlRegex, hashRegex]
+// "https://github.com/.../commit/abc123" → hash regex matched "abc123" inside URL match
+
+// After: [hashRegex, urlRegex]
+// Hash captured first, URL captures remaining text
+```
+
+## What We Tried
+
+1. **Incremental line-by-line port** — too manual, errors in transcription
+2. **Type-driven porting** — created interfaces matching vscode-git-graph `GVertex`, `GBranch` — this worked; types guided implementation
+3. **Test-driven validation** — wrote tests for `determinePath` against known graph structures from vscode-git-graph repo — caught routing bugs early
+4. **Visual diff** — side-by-side video of original vs PPM output, frame-by-frame comparison at merge points — identified misaligned dots
+
+## Root Cause Analysis
+
+The previous rewrite failed because:
+1. **Assumed simplicity** — git graph looked like "connect the dots" instead of a constrained layout problem
+2. **No algorithm study** — didn't read vscode-git-graph source before coding; reverse-engineered from output only
+3. **Incomplete feature list** — shadow lines, HEAD styling, merge routing logic were invisible until you needed them
+4. **No test fixtures** — built without reference commits to validate against
+
+The SVG dot misalignment was a cascade: explicit height forcing a mismatch between CSS row size and SVG coordinate system. `box-sizing: border-box` made the issue subtle — 28px height looked right until it didn't.
+
+Path scope was security-by-assumption — extending permissions to extensions should have been part of original design, not a bandage.
+
+## Lessons Learned
+
+1. **Port, don't rewrite** — When reimplementing an algorithm from proven code, read the original first. Guessing costs more than transcription.
+
+2. **Constrained layout problems need algorithm study** — Graph layout, routing, and column allocation aren't intuitive. Trace through examples before coding.
+
+3. **CSS height mismatches are invisible at first** — When CSS-defined height meets SVG coordinate system, they must align explicitly. Don't rely on browser rendering to fix 1px errors; they compound.
+
+4. **Security permissions evolve with features** — Extensions need project access; this wasn't a later concern, it was a design gap. Build permission model upfront.
+
+5. **Test against canonical output** — Generate test cases from the original algorithm, not from guessed behavior. Side-by-side comparison is necessary, not optional.
+
+## Next Steps
+
+1. **Monitor visual regression** — Run vscode-git-graph test repo against PPM output quarterly to catch algorithm drift
+2. **Document grid config** — Add comments explaining `gridY: 28` choice and mobile override, so future maintainers understand dependencies
+3. **Consider performance** — Profile SVG rendering with 500+ commits; may need canvas or virtualization for large repos
+4. **Security audit** — Review all extension RPC handlers for similar path scope issues
+
+---
+
+**Commit**: `24ad424` feat(ext-git-graph): port vscode-git-graph algorithm with faithful SVG rendering
+
+**Tests**: 62/62 passing (4 test files)
+
+**Review**: 3 critical, 2 high, 4 medium findings — all critical/high addressed before merge