@cryptiklemur/lattice 1.17.1 → 1.18.0

package/.serena/memories/code_style_and_conventions.md

@@ -0,0 +1,35 @@
+# Code Style and Conventions
+
+## JavaScript/TypeScript
+- Use `const`/`let` (NOT `var`)
+- Use named function declarations, not arrow functions — except for anonymous callbacks where arrows are fine
+- ESM throughout (server + client)
+- Follow .editorconfig: 2-space indent, LF line endings, UTF-8
+
+## Icons
+- Use `lucide-react` for ALL icons
+- Import individually: `import { Settings, Moon } from "lucide-react"`
+- No emojis for icons or in UI
+
+## Comments
+- No section separator comments (// ========)
+- No organizational header comments
+- Keep code clean without visual separators
+
+## Design System
+- See `.impeccable.md` for comprehensive design guidelines
+- Dark-first with 23 base16 themes via OKLCH CSS variables
+- Tailwind + daisyUI component framework
+- Typography: JetBrains Mono (headings/code), IBM Plex Sans (body)
+- Three surface tiers: Chrome (base-200), Stage (base-100 + dot-grid), Elevated (base-300 + shadow)
+- Never hardcode colors — always use CSS variables/theme tokens
+- WCAG AA contrast, prefers-reduced-motion, keyboard-first
+
+## Types
+- `HistoryMessage` uses a discriminated union type (`HistoryMessageType`)
+- Shared types in `shared/src/models.ts`
+- Message protocol in `shared/src/messages.ts`
+- All `var` in existing code is legacy — new code should use `const`/`let`
+
+## Pre-existing Errors
+- DO NOT EVER LEAVE PRE-EXISTING ERRORS. FIX THEM.

package/.serena/memories/project_overview.md

@@ -0,0 +1,51 @@
+# Lattice — Project Overview
+
+**Purpose**: Multi-machine agentic dashboard for Claude Code. Web UI for monitoring sessions, managing projects, tracking costs, and orchestrating across mesh-networked nodes.
+
+**Status**: Alpha (pre-1.0), work directly on main branch.
+
+## Tech Stack
+
+- **Runtime**: Bun (server), Node (CI), Vite (client bundler)
+- **Server**: Bun WebSocket server with typed message protocol
+- **Client**: React 19 + Vite 8 + Tailwind CSS + daisyUI
+- **Shared**: TypeScript types and constants (no build step, imported directly)
+- **State**: Tanstack Store (client), Tanstack Router (routing)
+- **Sessions**: Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`)
+- **Charts**: Recharts
+- **Testing**: Playwright (chromium only)
+- **CI**: GitHub Actions (typecheck + build + Playwright)
+- **Release**: semantic-release on push to main
+
+## Monorepo Structure
+
+```
+lattice/
+├── shared/     — TypeScript types, message definitions, constants
+├── server/     — Bun WebSocket server, handlers, analytics, mesh networking
+├── client/     — React + Vite dashboard, UI components, 23 themes
+├── themes/     — Base16 theme JSON files (dark + light)
+├── tests/      — Playwright test files
+└── docs/       — Screenshots, audit docs
+```
+
+## Architecture
+
+- Server communicates with clients via WebSocket using typed messages defined in `shared/`
+- Sessions managed through Claude Agent SDK
+- 23 base16 themes with OKLCH color space
+- PWA with service worker caching (Workbox)
+- Mesh networking for multi-machine orchestration
+- Structured logging with `debug` package (lattice:* namespaces)
+
+## Key Features
+
+- Real-time chat with tool approval, context tracking, cost per message
+- Session tabs with split-pane support
+- Message bookmarks (per-session + global)
+- Analytics dashboard (15+ chart types)
+- Daily cost budget with configurable enforcement
+- Keyboard shortcuts overlay (press ?)
+- Session hover previews, auto-titling, date range search
+- MCP server management, skill marketplace
+- Memory management UI

package/.serena/memories/suggested_commands.md

@@ -0,0 +1,32 @@
+# Suggested Commands
+
+## Development
+- `bun run dev` — Start server (--watch) + Vite dev server, hot reloads both
+- `bun run build` — Build all workspaces (only client produces output)
+- `bun run typecheck` — Run tsc across all workspaces
+
+## Testing
+- `bunx playwright test` — Run all Playwright tests (server must be running on :7654)
+- `bunx playwright test tests/session-flow.spec.ts` — Run single test file
+
+## Type Checking (per-workspace, as CI does it)
+- `bunx tsc -p shared/tsconfig.json` — Build shared types (must run first)
+- `bunx tsc --noEmit -p server/tsconfig.json` — Typecheck server
+- `bunx tsc --noEmit -p client/tsconfig.json` — Typecheck client
+
+## Client Build
+- `cd client && npx vite build` — Build client for production
+
+## Server
+- `bun run server/src/index.ts daemon` — Run server daemon directly
+- `bun run server/src/index.ts daemon --port 8080` — Custom port
+- Default port: 7654, binds to 0.0.0.0
+
+## Environment
+- `ANTHROPIC_API_KEY` — Optional, uses `claude setup-token` if not set
+- `DEBUG=lattice:*` — Enable structured debug logging
+
+## Git
+- Commit messages: Angular Commit Convention (feat/fix/refactor/etc)
+- Releases: automated via semantic-release on push to main
+- Never add AI attribution to commits

package/.serena/memories/task_completion_checklist.md

@@ -0,0 +1,15 @@
+# Task Completion Checklist
+
+When a coding task is completed, verify the following:
+
+1. **Type check** — Run `bunx tsc --noEmit -p client/tsconfig.json` and `bunx tsc --noEmit -p server/tsconfig.json` (build shared first with `bunx tsc -p shared/tsconfig.json`)
+2. **Build** — Run `cd client && npx vite build` to verify client builds
+3. **Server build** — Run `bun build server/src/index.ts --target=bun --outdir=/tmp/check` to verify server bundles
+4. **No pre-existing errors** — Fix any errors you encounter, don't leave them
+5. **Code style** — const/let (not var), named functions (not arrows except callbacks), lucide-react icons only
+6. **Git** — Only commit when explicitly asked. Angular Commit Convention. No AI attribution.
+
+## Important Notes
+- The PWA service worker caches old bundles. After rebuilding client, users need to clear SW cache in browser to see changes.
+- Server serves from `client/dist/` (built output), NOT from Vite dev server. Client changes require `npx vite build` to appear on port 7654.
+- Vite dev server runs on :5173 separately but can't connect WebSocket without the Bun server on :7654.

package/.serena/project.yml

@@ -136,3 +136,17 @@ symbol_info_budget:
 # list of regex patterns which, when matched, mark a memory entry as read‑only.
 # Extends the list from the global configuration, merging the two lists.
 read_only_memory_patterns: []
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
+# No documentation on options means no options are available.
+ls_specific_settings: {}

package/client/src/components/dashboard/DashboardView.tsx

@@ -12,6 +12,7 @@ import {
 } from "lucide-react";
 import type { ServerMessage, SessionSummary, LatticeConfig } from "@lattice/shared";
 import { formatSessionTitle } from "../../utils/formatSessionTitle";
+import { openSessionTab } from "../../stores/workspace";
 
 function relativeTime(ts: number): string {
   var diff = Date.now() - ts;
@@ -157,7 +158,7 @@ export function DashboardView() {
                 return (
                   <button
                     key={s.id}
-                    onClick={function () { sidebar.navigateToSession(s.projectSlug, s.id); }}
+                    onClick={function () { openSessionTab(s.id, s.projectSlug, s.title); sidebar.navigateToSession(s.projectSlug, s.id); }}
                     className="flex items-center gap-3 px-3 py-2 rounded-xl border border-base-content/15 bg-base-200 hover:border-base-content/30 transition-colors duration-[120ms] cursor-pointer text-left focus-visible:ring-2 focus-visible:ring-primary"
                   >
                     <MessageSquare size={12} className="text-base-content/30 flex-shrink-0" />

package/client/src/components/dashboard/ProjectDashboardView.tsx

@@ -9,6 +9,7 @@ import {
 } from "lucide-react";
 import type { ProjectSettingsSection } from "../../stores/sidebar";
 import type { SessionSummary, ServerMessage } from "@lattice/shared";
+import { openSessionTab } from "../../stores/workspace";
 
 function StatCard({ label, value, icon }: { label: string; value: string | number; icon: React.ReactNode }) {
   return (
@@ -74,9 +75,10 @@ export function ProjectDashboardView() {
     sidebar.openProjectSettings(section);
   }
 
-  function goToSession(sessionId: string) {
+  function goToSession(s: SessionSummary) {
     if (activeProject) {
-      sidebar.setActiveSessionId(sessionId);
+      openSessionTab(s.id, activeProject.slug, s.title);
+      sidebar.setActiveSessionId(s.id);
     }
   }
 
@@ -130,7 +132,7 @@ export function ProjectDashboardView() {
                   return (
                     <button
                       key={s.id}
-                      onClick={function () { goToSession(s.id); }}
+                      onClick={function () { goToSession(s); }}
                       className="flex items-center gap-3 px-3 py-2 rounded-xl border border-base-content/15 bg-base-300 hover:border-base-content/30 transition-colors duration-[120ms] cursor-pointer text-left focus-visible:ring-2 focus-visible:ring-primary"
                     >
                       <MessageSquare size={12} className="text-base-content/30 flex-shrink-0" />

package/client/src/components/sidebar/Sidebar.tsx

@@ -10,7 +10,7 @@ import { useSidebar } from "../../hooks/useSidebar";
 import { useSession } from "../../hooks/useSession";
 import { clearSession } from "../../stores/session";
 import { useOnline } from "../../hooks/useOnline";
-import { openTab, openSessionTab } from "../../stores/workspace";
+import { openTab, openSessionTab, getWorkspaceStore } from "../../stores/workspace";
 import { getSidebarStore, goToAnalytics } from "../../stores/sidebar";
 import { ProjectRail } from "./ProjectRail";
 import { SessionList } from "./SessionList";
@@ -214,7 +214,13 @@ export function Sidebar({ onSessionSelect }: { onSessionSelect?: () => void }) {
     if (!sidebar.activeProjectSlug || !sidebar.activeSessionId) return;
     if (!activeProject) return;
     initialActivatedRef.current = true;
-    openSessionTab(sidebar.activeSessionId, sidebar.activeProjectSlug, "Session");
+    const wsState = getWorkspaceStore().state;
+    const alreadyHasTab = wsState.tabs.some(function (t) {
+      return t.type === "chat" && t.sessionId === sidebar.activeSessionId;
+    });
+    if (!alreadyHasTab) {
+      openSessionTab(sidebar.activeSessionId, sidebar.activeProjectSlug, "Session");
+    }
     session.activateSession(sidebar.activeProjectSlug, sidebar.activeSessionId);
   }, [sidebar.activeProjectSlug, sidebar.activeSessionId, activeProject]);
 

package/client/src/lib/workspace-url.ts

@@ -0,0 +1,217 @@
+import type { Tab, Pane, TabType, WorkspaceState } from "../stores/workspace";
+
+const TAB_TYPES: Set<string> = new Set(["chat", "files", "terminal", "notes", "tasks", "bookmarks", "analytics"]);
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function shortSessionId(uuid: string): string {
+  return uuid.slice(0, 8);
+}
+
+export function encodeWorkspaceUrl(
+  state: WorkspaceState,
+  tabs: Tab[],
+  primaryProjectSlug: string | null,
+): string {
+  if (tabs.length === 0) return "";
+  if (tabs.length === 1 && tabs[0].id === "chat" && !tabs[0].sessionId) return "";
+
+  const panes = state.panes;
+  const activePaneId = state.activePaneId;
+
+  function encodeTab(tab: Tab, isActive: boolean): string {
+    let token = tab.type;
+    if (tab.type === "chat" && tab.sessionId) {
+      const shortId = shortSessionId(tab.sessionId);
+      if (tab.projectSlug && tab.projectSlug !== primaryProjectSlug) {
+        token += ":" + shortId + "." + tab.projectSlug;
+      } else {
+        token += ":" + shortId;
+      }
+    }
+    if (isActive) {
+      token += "*";
+    }
+    return token;
+  }
+
+  const paneTokens: string[] = [];
+  for (let pi = 0; pi < panes.length; pi++) {
+    const pane = panes[pi];
+    const tabTokens: string[] = [];
+    for (let ti = 0; ti < pane.tabIds.length; ti++) {
+      const tabId = pane.tabIds[ti];
+      const tab = tabs.find(function (t) { return t.id === tabId; });
+      if (!tab) continue;
+      const isActive = tabId === pane.activeTabId;
+      tabTokens.push(encodeTab(tab, isActive));
+    }
+    paneTokens.push(tabTokens.join(","));
+  }
+
+  let result = paneTokens.join("|");
+
+  if (panes.length > 1 && state.splitDirection) {
+    const dirChar = state.splitDirection === "horizontal" ? "h" : "v";
+    let activePaneIndex = 0;
+    for (let i = 0; i < panes.length; i++) {
+      if (panes[i].id === activePaneId) {
+        activePaneIndex = i;
+        break;
+      }
+    }
+    result += "|" + dirChar + activePaneIndex;
+  }
+
+  return result;
+}
+
+export interface DecodedWorkspace {
+  tabs: Tab[];
+  panes: Pane[];
+  activePaneId: string;
+  splitDirection: "horizontal" | "vertical" | null;
+}
+
+export function decodeWorkspaceUrl(
+  tParam: string,
+  primaryProjectSlug: string | null,
+  resolveFullId: (shortId: string, projectSlug: string) => string | null,
+): DecodedWorkspace {
+  const segments = tParam.split("|");
+  const tabs: Tab[] = [];
+  const panes: Pane[] = [];
+  let splitDirection: "horizontal" | "vertical" | null = null;
+  let activePaneIndex = 0;
+
+  const labels: Record<TabType, string> = {
+    chat: "Chat",
+    files: "Files",
+    terminal: "Terminal",
+    notes: "Notes",
+    tasks: "Tasks",
+    bookmarks: "Bookmarks",
+    analytics: "Analytics",
+  };
+
+  let splitMeta: string | null = null;
+  const paneSegments: string[] = [];
+
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    if (seg.length <= 3 && /^[hv]\d$/.test(seg)) {
+      splitMeta = seg;
+    } else {
+      paneSegments.push(seg);
+    }
+  }
+
+  if (splitMeta) {
+    splitDirection = splitMeta[0] === "h" ? "horizontal" : "vertical";
+    activePaneIndex = parseInt(splitMeta[1], 10);
+  }
+
+  for (let pi = 0; pi < paneSegments.length; pi++) {
+    const paneId = "pane-" + (pi + 1);
+    const tabTokens = paneSegments[pi].split(",").filter(function (s) { return s.length > 0; });
+    const paneTabIds: string[] = [];
+    let paneActiveTabId = "";
+
+    for (let ti = 0; ti < tabTokens.length; ti++) {
+      let token = tabTokens[ti];
+      const isActive = token.endsWith("*");
+      if (isActive) {
+        token = token.slice(0, -1);
+      }
+
+      const colonIdx = token.indexOf(":");
+      let tabType: TabType;
+      let sessionShortId: string | null = null;
+      let projectSlug: string | null = null;
+
+      if (colonIdx !== -1) {
+        tabType = token.slice(0, colonIdx) as TabType;
+        const rest = token.slice(colonIdx + 1);
+        const dotIdx = rest.indexOf(".");
+        if (dotIdx !== -1) {
+          sessionShortId = rest.slice(0, dotIdx);
+          projectSlug = rest.slice(dotIdx + 1);
+        } else {
+          sessionShortId = rest;
+          projectSlug = primaryProjectSlug;
+        }
+      } else {
+        tabType = token as TabType;
+      }
+
+      if (!TAB_TYPES.has(tabType)) continue;
+
+      let tab: Tab;
+      if (tabType === "chat" && sessionShortId && projectSlug) {
+        const fullId = resolveFullId(sessionShortId, projectSlug);
+        const resolvedId = fullId || sessionShortId;
+        const tabId = "chat-" + resolvedId;
+        tab = {
+          id: tabId,
+          type: "chat",
+          label: "Session",
+          closeable: true,
+          sessionId: resolvedId,
+          projectSlug: projectSlug,
+        };
+      } else if (tabType === "chat") {
+        tab = { id: "chat", type: "chat", label: "Chat", closeable: false };
+      } else {
+        tab = {
+          id: tabType,
+          type: tabType,
+          label: labels[tabType],
+          closeable: true,
+        };
+      }
+
+      const existingIdx = tabs.findIndex(function (t) { return t.id === tab.id; });
+      if (existingIdx === -1) {
+        tabs.push(tab);
+      }
+      paneTabIds.push(tab.id);
+
+      if (isActive) {
+        paneActiveTabId = tab.id;
+      }
+    }
+
+    if (paneTabIds.length > 0) {
+      if (!paneActiveTabId) {
+        paneActiveTabId = paneTabIds[0];
+      }
+      panes.push({ id: paneId, tabIds: paneTabIds, activeTabId: paneActiveTabId });
+    }
+  }
+
+  if (panes.length === 0) {
+    const defaultTab: Tab = { id: "chat", type: "chat", label: "Chat", closeable: false };
+    tabs.push(defaultTab);
+    panes.push({ id: "pane-1", tabIds: ["chat"], activeTabId: "chat" });
+  }
+
+  const resolvedActivePaneIndex = Math.min(activePaneIndex, panes.length - 1);
+  const activePaneId = panes[resolvedActivePaneIndex].id;
+
+  if (panes.length < 2) {
+    splitDirection = null;
+  }
+
+  return { tabs, panes, activePaneId, splitDirection };
+}
+
+export function isLegacySessionUrl(pathname: string): { projectSlug: string; sessionId: string } | null {
+  const parts = pathname.split("/").filter(function (p) { return p.length > 0; });
+  if (parts.length < 2) return null;
+  if (parts[0] === "settings") return null;
+  if (parts[1] === "settings") return null;
+  if (UUID_PATTERN.test(parts[1])) {
+    return { projectSlug: parts[0], sessionId: parts[1] };
+  }
+  return null;
+}

package/client/src/router.tsx

@@ -532,12 +532,6 @@ var projectRoute = createRoute({
   component: IndexPage,
 });
 
-var sessionRoute = createRoute({
-  getParentRoute: function () { return rootRoute; },
-  path: "/$projectSlug/$sessionId",
-  component: IndexPage,
-});
-
 var settingsRoute = createRoute({
   getParentRoute: function () { return rootRoute; },
   path: "/settings/$section",
@@ -562,7 +556,7 @@ var projectSettingsIndexRoute = createRoute({
   component: IndexPage,
 });
 
-var routeTree = rootRoute.addChildren([indexRoute, settingsIndexRoute, settingsRoute, projectSettingsIndexRoute, projectSettingsRoute, projectRoute, sessionRoute]);
+var routeTree = rootRoute.addChildren([indexRoute, settingsIndexRoute, settingsRoute, projectSettingsIndexRoute, projectSettingsRoute, projectRoute]);
 
 export var router = createRouter({ routeTree });
 

package/client/src/stores/sidebar.ts

@@ -1,5 +1,8 @@
 import { Store } from "@tanstack/react-store";
 import type { ProjectSettingsSection } from "@lattice/shared";
+import { encodeWorkspaceUrl, decodeWorkspaceUrl, isLegacySessionUrl, shortSessionId } from "../lib/workspace-url";
+import type { DecodedWorkspace } from "../lib/workspace-url";
+import { getWorkspaceStore, restoreWorkspace, setUrlSyncCallback } from "./workspace";
 
 export type { ProjectSettingsSection };
 
@@ -32,33 +35,82 @@ export interface SidebarState {
   confirmRemoveSlug: string | null;
 }
 
-var SETTINGS_SECTIONS: SettingsSection[] = ["appearance", "claude", "environment", "mcp", "skills", "nodes", "editor", "rules", "memory", "notifications", "budget"];
+const SETTINGS_SECTIONS: SettingsSection[] = ["appearance", "claude", "environment", "mcp", "skills", "nodes", "editor", "rules", "memory", "notifications", "budget"];
+
+interface ParsedUrl {
+  projectSlug: string | null;
+  sessionId: string | null;
+  settingsSection: SettingsSection | null;
+  projectSettingsSection: ProjectSettingsSection | null;
+  tParam: string | null;
+  decodedWorkspace: DecodedWorkspace | null;
+}
+
+function resolveFullIdFromNothing(_shortId: string, _projectSlug: string): string | null {
+  return null;
+}
+
+function parseInitialUrl(): ParsedUrl {
+  const path = window.location.pathname;
+  const parts = path.split("/").filter(function (p) { return p.length > 0; });
+  const searchParams = new URLSearchParams(window.location.search);
+  const tParam = searchParams.get("t");
 
-function parseInitialUrl(): { projectSlug: string | null; sessionId: string | null; settingsSection: SettingsSection | null; projectSettingsSection: ProjectSettingsSection | null } {
-  var path = window.location.pathname;
-  var parts = path.split("/").filter(function (p) { return p.length > 0; });
   if (parts[0] === "settings") {
-    var section = parts[1] as SettingsSection;
+    const section = parts[1] as SettingsSection;
     if (section && SETTINGS_SECTIONS.indexOf(section) !== -1) {
-      return { projectSlug: null, sessionId: null, settingsSection: section, projectSettingsSection: null };
+      return { projectSlug: null, sessionId: null, settingsSection: section, projectSettingsSection: null, tParam: null, decodedWorkspace: null };
     }
-    return { projectSlug: null, sessionId: null, settingsSection: "appearance", projectSettingsSection: null };
+    return { projectSlug: null, sessionId: null, settingsSection: "appearance", projectSettingsSection: null, tParam: null, decodedWorkspace: null };
   }
+
   if (parts.length >= 2 && parts[1] === "settings") {
-    return { projectSlug: parts[0], sessionId: null, settingsSection: null, projectSettingsSection: (parts[2] || "general") as ProjectSettingsSection };
+    return { projectSlug: parts[0], sessionId: null, settingsSection: null, projectSettingsSection: (parts[2] || "general") as ProjectSettingsSection, tParam: null, decodedWorkspace: null };
   }
-  if (parts.length >= 2) {
-    return { projectSlug: parts[0], sessionId: parts[1], settingsSection: null, projectSettingsSection: null };
+
+  const legacy = isLegacySessionUrl(path);
+  if (legacy && !tParam) {
+    const shortId = shortSessionId(legacy.sessionId);
+    const newUrl = "/" + legacy.projectSlug + "?t=chat:" + shortId + "*";
+    window.history.replaceState(null, "", newUrl);
+    const decoded = decodeWorkspaceUrl("chat:" + shortId + "*", legacy.projectSlug, resolveFullIdFromNothing);
+    return {
+      projectSlug: legacy.projectSlug,
+      sessionId: legacy.sessionId,
+      settingsSection: null,
+      projectSettingsSection: null,
+      tParam: "chat:" + shortId + "*",
+      decodedWorkspace: decoded,
+    };
   }
-  if (parts.length === 1) {
-    return { projectSlug: parts[0], sessionId: null, settingsSection: null, projectSettingsSection: null };
+
+  if (parts.length >= 1 && parts[0] !== "settings") {
+    const projectSlug = parts[0];
+    if (tParam) {
+      const decoded = decodeWorkspaceUrl(tParam, projectSlug, resolveFullIdFromNothing);
+      let sessionId: string | null = null;
+      const activePane = decoded.panes.find(function (p) { return p.id === decoded.activePaneId; });
+      if (activePane) {
+        const activeTab = decoded.tabs.find(function (t) { return t.id === activePane.activeTabId; });
+        if (activeTab && activeTab.type === "chat" && activeTab.sessionId) {
+          sessionId = activeTab.sessionId;
+        }
+      }
+      return { projectSlug, sessionId, settingsSection: null, projectSettingsSection: null, tParam, decodedWorkspace: decoded };
+    }
+    return { projectSlug, sessionId: null, settingsSection: null, projectSettingsSection: null, tParam: null, decodedWorkspace: null };
   }
-  return { projectSlug: null, sessionId: null, settingsSection: null, projectSettingsSection: null };
+
+  return { projectSlug: null, sessionId: null, settingsSection: null, projectSettingsSection: null, tParam: null, decodedWorkspace: null };
 }
 
-var initialUrl = parseInitialUrl();
+const initialUrl = parseInitialUrl();
 
-var sidebarStore = new Store<SidebarState>({
+if (initialUrl.decodedWorkspace) {
+  restoreWorkspace(initialUrl.decodedWorkspace);
+}
+
+const sidebarStore = new Store<SidebarState>({
   activeProjectSlug: initialUrl.settingsSection ? null : initialUrl.projectSlug,
   activeSessionId: initialUrl.settingsSection ? null : initialUrl.sessionId,
   sidebarMode: (initialUrl.settingsSection || initialUrl.projectSettingsSection) ? "settings" : "project",
@@ -67,7 +119,7 @@ var sidebarStore = new Store<SidebarState>({
     : initialUrl.projectSettingsSection
     ? { type: "project-settings", section: initialUrl.projectSettingsSection }
     : initialUrl.projectSlug
-    ? (initialUrl.sessionId ? { type: "chat" } : { type: "project-dashboard" })
+    ? (initialUrl.sessionId || initialUrl.tParam ? { type: "chat" } : { type: "project-dashboard" })
     : { type: "dashboard" },
   previousView: null,
   userMenuOpen: false,
@@ -78,19 +130,67 @@ var sidebarStore = new Store<SidebarState>({
   confirmRemoveSlug: null,
 });
 
-function pushUrl(projectSlug: string | null, sessionId: string | null): void {
-  var path = "/";
+let lastEncodedUrl = "";
+
+function pushUrl(projectSlug: string | null, replace: boolean = false): void {
+  const wsState = getWorkspaceStore().state;
+  const encoded = encodeWorkspaceUrl(wsState, wsState.tabs, projectSlug);
+  let path = "/";
   if (projectSlug) {
     path = "/" + projectSlug;
-    if (sessionId) {
-      path = path + "/" + sessionId;
+    if (encoded) {
+      path += "?t=" + encoded;
     }
   }
-  if (window.location.pathname !== path) {
-    window.history.pushState(null, "", path);
+  const hash = window.location.hash;
+  const fullUrl = path + hash;
+  if (window.location.pathname + window.location.search !== path) {
+    if (replace) {
+      window.history.replaceState(null, "", fullUrl);
+    } else {
+      window.history.pushState(null, "", fullUrl);
+    }
   }
+  lastEncodedUrl = encoded;
 }
 
+export function syncUrlFromWorkspace(): void {
+  const state = sidebarStore.state;
+  if (state.sidebarMode === "settings") return;
+  if (!state.activeProjectSlug) return;
+
+  const wsState = getWorkspaceStore().state;
+  const encoded = encodeWorkspaceUrl(wsState, wsState.tabs, state.activeProjectSlug);
+
+  if (encoded === lastEncodedUrl) return;
+
+  const isActiveTabChangeOnly = detectActiveTabChangeOnly(lastEncodedUrl, encoded);
+  lastEncodedUrl = encoded;
+
+  let path = "/" + state.activeProjectSlug;
+  if (encoded) {
+    path += "?t=" + encoded;
+  }
+  const hash = window.location.hash;
+  const fullUrl = path + hash;
+
+  if (window.location.pathname + window.location.search !== path) {
+    if (isActiveTabChangeOnly) {
+      window.history.replaceState(null, "", fullUrl);
+    } else {
+      window.history.pushState(null, "", fullUrl);
+    }
+  }
+}
+
+function detectActiveTabChangeOnly(oldEncoded: string, newEncoded: string): boolean {
+  const oldStripped = oldEncoded.replace(/\*/g, "");
+  const newStripped = newEncoded.replace(/\*/g, "");
+  return oldStripped === newStripped;
+}
+
+setUrlSyncCallback(syncUrlFromWorkspace);
+
 export function getSidebarStore(): Store<SidebarState> {
   return sidebarStore;
 }
@@ -107,11 +207,17 @@ export function setActiveProjectSlug(slug: string | null): void {
       projectDropdownOpen: false,
     };
   });
-  pushUrl(slug, null);
+  let path = "/";
+  if (slug) {
+    path = "/" + slug;
+  }
+  if (window.location.pathname + window.location.search !== path) {
+    window.history.pushState(null, "", path);
+  }
+  lastEncodedUrl = "";
 }
 
 export function setActiveSessionId(sessionId: string | null): void {
-  var state = sidebarStore.state;
   sidebarStore.setState(function (s) {
     return {
       ...s,
@@ -119,7 +225,6 @@ export function setActiveSessionId(sessionId: string | null): void {
       activeView: sessionId ? { type: "chat" } : s.activeView,
     };
   });
-  pushUrl(state.activeProjectSlug, sessionId);
 }
 
 export function navigateToSession(projectSlug: string, sessionId: string): void {
@@ -134,7 +239,6 @@ export function navigateToSession(projectSlug: string, sessionId: string): void
       projectDropdownOpen: false,
     };
   });
-  pushUrl(projectSlug, sessionId);
 }
 
 export function openSettings(section: SettingsSection): void {
@@ -148,7 +252,7 @@ export function openSettings(section: SettingsSection): void {
       projectDropdownOpen: false,
     };
   });
-  var path = "/settings/" + section;
+  const path = "/settings/" + section;
   if (window.location.pathname !== path) {
     window.history.pushState(null, "", path);
   }
@@ -161,7 +265,7 @@ export function setSettingsSection(section: SettingsSection): void {
       activeView: { type: "settings", section: section },
     };
   });
-  var path = "/settings/" + section;
+  const path = "/settings/" + section;
   if (window.location.pathname !== path) {
     window.history.replaceState(null, "", path);
   }
@@ -178,8 +282,8 @@ export function openProjectSettings(section: ProjectSettingsSection): void {
       projectDropdownOpen: false,
     };
   });
-  var state = sidebarStore.state;
-  var path = "/" + state.activeProjectSlug + "/settings/" + section;
+  const state = sidebarStore.state;
+  const path = "/" + state.activeProjectSlug + "/settings/" + section;
   if (window.location.pathname !== path) {
     window.history.pushState(null, "", path);
   }
@@ -192,16 +296,16 @@ export function setProjectSettingsSection(section: ProjectSettingsSection): void
       activeView: { type: "project-settings", section: section },
     };
   });
-  var state = sidebarStore.state;
-  var path = "/" + state.activeProjectSlug + "/settings/" + section;
+  const state = sidebarStore.state;
+  const path = "/" + state.activeProjectSlug + "/settings/" + section;
   if (window.location.pathname !== path) {
     window.history.replaceState(null, "", path);
   }
 }
 
 export function exitSettings(): void {
-  var state = sidebarStore.state;
-  var restored = state.previousView ?? { type: "chat" } as ActiveView;
+  const state = sidebarStore.state;
+  const restored = state.previousView ?? { type: "chat" } as ActiveView;
   sidebarStore.setState(function (s) {
     return {
       ...s,
@@ -210,11 +314,7 @@ export function exitSettings(): void {
       previousView: null,
     };
   });
-  if (state.activeView.type === "project-settings") {
-    pushUrl(state.activeProjectSlug, null);
-  } else {
-    pushUrl(state.activeProjectSlug, state.activeSessionId);
-  }
+  pushUrl(state.activeProjectSlug);
 }
 
 export function goToProjectDashboard(): void {
@@ -228,8 +328,15 @@ export function goToProjectDashboard(): void {
       projectDropdownOpen: false,
     };
   });
-  var state = sidebarStore.state;
-  pushUrl(state.activeProjectSlug, null);
+  const state = sidebarStore.state;
+  let path = "/";
+  if (state.activeProjectSlug) {
+    path = "/" + state.activeProjectSlug;
+  }
+  if (window.location.pathname + window.location.search !== path) {
+    window.history.pushState(null, "", path);
+  }
+  lastEncodedUrl = "";
 }
 
 export function goToDashboard(): void {
@@ -244,54 +351,96 @@ export function goToDashboard(): void {
       projectDropdownOpen: false,
     };
   });
-  pushUrl(null, null);
+  if (window.location.pathname + window.location.search !== "/") {
+    window.history.pushState(null, "", "/");
+  }
+  lastEncodedUrl = "";
 }
 
 export function goToAnalytics(): void {
   sidebarStore.setState(function (state) {
     return { ...state, activeView: { type: "analytics" }, sidebarMode: "project" };
   });
-  pushUrl(sidebarStore.state.activeProjectSlug, null);
+  pushUrl(sidebarStore.state.activeProjectSlug);
 }
 
 export function handlePopState(): void {
-  var url = parseInitialUrl();
-  if (url.settingsSection) {
+  const path = window.location.pathname;
+  const parts = path.split("/").filter(function (p) { return p.length > 0; });
+  const searchParams = new URLSearchParams(window.location.search);
+  const tParam = searchParams.get("t");
+
+  if (parts[0] === "settings") {
+    const section = (parts[1] || "appearance") as SettingsSection;
     sidebarStore.setState(function (state) {
       return {
         ...state,
         sidebarMode: "settings",
-        activeView: { type: "settings", section: url.settingsSection! },
+        activeView: { type: "settings", section: section },
         userMenuOpen: false,
         projectDropdownOpen: false,
       };
     });
-  } else if (url.projectSettingsSection) {
+    return;
+  }
+
+  if (parts.length >= 2 && parts[1] === "settings") {
+    const projectSettingsSection = (parts[2] || "general") as ProjectSettingsSection;
     sidebarStore.setState(function (state) {
       return {
         ...state,
-        activeProjectSlug: url.projectSlug,
+        activeProjectSlug: parts[0],
         sidebarMode: "settings",
-        activeView: { type: "project-settings", section: url.projectSettingsSection! },
+        activeView: { type: "project-settings", section: projectSettingsSection },
         userMenuOpen: false,
         projectDropdownOpen: false,
       };
     });
-  } else {
+    return;
+  }
+
+  const projectSlug = parts.length > 0 ? parts[0] : null;
+
+  if (tParam && projectSlug) {
+    const decoded = decodeWorkspaceUrl(tParam, projectSlug, resolveFullIdFromNothing);
+    restoreWorkspace(decoded);
+    lastEncodedUrl = tParam;
+
+    let sessionId: string | null = null;
+    const activePane = decoded.panes.find(function (p) { return p.id === decoded.activePaneId; });
+    if (activePane) {
+      const activeTab = decoded.tabs.find(function (t) { return t.id === activePane.activeTabId; });
+      if (activeTab && activeTab.type === "chat" && activeTab.sessionId) {
+        sessionId = activeTab.sessionId;
+      }
+    }
+
     sidebarStore.setState(function (state) {
       return {
         ...state,
-        activeProjectSlug: url.projectSlug,
-        activeSessionId: url.sessionId,
+        activeProjectSlug: projectSlug,
+        activeSessionId: sessionId,
         sidebarMode: "project",
-        activeView: url.projectSlug
-          ? (url.sessionId ? { type: "chat" } : { type: "project-dashboard" })
-          : { type: "dashboard" },
+        activeView: sessionId || decoded.tabs.length > 0 ? { type: "chat" } : { type: "project-dashboard" },
         userMenuOpen: false,
         projectDropdownOpen: false,
       };
     });
+    return;
   }
+
+  sidebarStore.setState(function (state) {
+    return {
+      ...state,
+      activeProjectSlug: projectSlug,
+      activeSessionId: null,
+      sidebarMode: "project",
+      activeView: projectSlug ? { type: "project-dashboard" } : { type: "dashboard" },
+      userMenuOpen: false,
+      projectDropdownOpen: false,
+    };
+  });
+  lastEncodedUrl = "";
 }
 
 export function toggleUserMenu(): void {

package/client/src/stores/workspace.ts

@@ -1,4 +1,5 @@
 import { Store } from "@tanstack/react-store";
+import type { DecodedWorkspace } from "../lib/workspace-url";
 
 export type TabType = "chat" | "files" | "terminal" | "notes" | "tasks" | "bookmarks" | "analytics";
 
@@ -364,3 +365,34 @@ export function getActiveSessionTab(): Tab | null {
   if (!activeTab || activeTab.type !== "chat") return null;
   return activeTab;
 }
+
+let urlSyncCallback: (() => void) | null = null;
+let urlSyncSuppressed = false;
+
+export function setUrlSyncCallback(cb: () => void): void {
+  urlSyncCallback = cb;
+}
+
+function notifyUrlSync(): void {
+  if (!urlSyncSuppressed && urlSyncCallback) {
+    urlSyncCallback();
+  }
+}
+
+export function restoreWorkspace(data: DecodedWorkspace): void {
+  urlSyncSuppressed = true;
+  workspaceStore.setState(function (state) {
+    return {
+      ...state,
+      tabs: data.tabs,
+      panes: data.panes,
+      activePaneId: data.activePaneId,
+      splitDirection: data.splitDirection,
+    };
+  });
+  urlSyncSuppressed = false;
+}
+
+workspaceStore.subscribe(function () {
+  notifyUrlSync();
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cryptiklemur/lattice",
-  "version": "1.17.1",
+  "version": "1.18.0",
   "description": "Multi-machine agentic dashboard for Claude Code. Monitor sessions, manage MCP servers and skills, orchestrate across mesh-networked nodes.",
   "license": "MIT",
   "author": "Aaron Scherer <me@aaronscherer.me>",