State Management and Runtime Architecture

​

Overview

​

Frontend State Management

​

Architecture

• An internal data structure (Map, object, or class)
• Direct read/write functions (get*, set*)
• React hooks (use*) that subscribe to changes via useSyncExternalStore
• Optional localStorage fallback for persistence

​

Runtime State (Central Persistence)

export interface RuntimeState {
  version: number;                          // Schema version for migrations
  sessions: Record<string, WorktreeSession>;   // All open worktree/root sessions
  openProjects: StoredProject[];            // Open projects in sidebar
  recents: RecentWorkspace[];               // Recently opened projects
  settings: Partial<AppSettings>;           // Terminal and app settings
  keybindings: Partial<Record<ActionId, Shortcut | null>>;  // Custom key bindings
  attribution: boolean;                     // Co-author hook enabled flag
  migrations: Record<string, boolean>;      // Migration tracking
  tabs: PersistedTab[];                     // Non-terminal tabs (diff, preview, editor)
  sessionOrder: string[];                   // instanceIds in tab-bar order
  activeInstanceId: string | null;          // Last focused session's instanceId
  prompts: Array<...>;                      // Custom and builtin prompts
  atlasProjects: Record<string, boolean>;   // Project codebase indexing decisions
}

​

Store Modules

​

1. Work State (src/store/workState.ts)

• Map of sessionId -> "idle" | "working" | "done"
• Separate listener sets per session (prevents O(N²) re-renders)

​

2. Worktree Sessions (src/store/sessions.ts)

export interface WorktreeSession {
  name: string;                 // User-facing session name
  agent?: string;               // CLI command hint ("claude", "gemini", etc)
  conversationId?: string;      // Claude API conversation UUID for --resume
  instanceId?: string;          // Permanent PTY session ID (minted once)
  projectId: string;            // Project this session belongs to
  closed?: boolean;             // Soft-closed (tab closed but can re-open)
  isRootSession?: boolean;      // true = opened in project root (no worktree)
  noGit?: boolean;              // true = user chose to proceed without git
}

• Worktree sessions: keyed by worktree path (e.g., /path/to/project/.tempest/my-workspace)
• Root sessions: keyed by <projectPath>::root::<sessionId> (ROOT_SESSION_PREFIX) to avoid collisions
• Multiple root sessions can coexist in the same project

​

3. App Settings (src/store/appSettings.ts)

export interface AppSettings {
  terminalFontSize: number;            // Default: 13
  terminalFontFamily: string;          // Default: "Geist Mono"
  terminalCursorStyle: "block" | "bar" | "underline";  // Default: "block"
  terminalCursorBlink: boolean;        // Default: true
  terminalScrollback: number;          // Default: 1000
  sidebarFontSize: number;             // Default: 14
  branchPrefix: string;                // Auto-prefix for new branches
  commitMessageTemplate: string;       // Default: "Agent work"
  atlasEnabled: boolean;               // Enable codebase indexing
  atlasAutoIndex: boolean;             // Auto-index new projects
}

​

4. Keybindings (src/store/keybindings.ts)

export type ActionId =
  | "toggleTheme" | "openSettings" | "toggleLeftSidebar"
  | "toggleRightSidebar" | "openProject" | "newWorkspace"
  | "closeTab" | "nextTab" | "prevTab" | "broadcast"
  | "splitPaneV" | "splitPaneH" | "openQueue";

export interface Shortcut {
  key: string;      // e.g., "T", "\\", "ArrowUp"
  ctrl: boolean;
  shift: boolean;
  alt: boolean;
}

​

5. Attribution (src/store/attribution.ts)

Co-authored-by: Tempest <tempestai.dev@gmail.com>

​

6. Open Projects (src/store/openProjects.ts)

export interface StoredProject {
  id: string;         // UUID
  name: string;       // Display name
  path: string;       // File system path
  expanded: boolean;  // Sidebar tree expansion state
}

​

7. Recent Workspaces (src/store/recents.ts)

export interface RecentWorkspace {
  id: string;
  name: string;
  path: string;
  lastOpened: string;  // ISO 8601 timestamp
}

​

8. Message Queue (src/store/messageQueue.ts)

export interface QueueItem {
  id: string;
  text: string;
}

​

9. Prompts (src/store/prompts.ts)

export interface PromptEntry {
  id: string;
  title: string;
  body: string;
  enabled: boolean;
  isBuiltin: boolean;
}

​

10. Session Manager (src/store/sessionManager.ts)

• QUIET_MS (5000ms): If no output received for 5s, mark done (unless title says busy or insufficient bytes received)
• TURN_STARTED_BYTES (200): Minimum bytes required before heuristic timers fire (gates false positives during thinking window)
• DEAD_ZONE_MS (300ms): After user presses Enter, suppress done signals to avoid echo false-positives
• CEIL_MS (12000ms): Hard ceiling; if still working after 12s, force done (safety net for keepalive loops)

class SessionManager {
  register(sessionId, channel, isAgent, onDone?, onChunk?, agentHint?)
  unregister(sessionId)
  attach(sessionId, onData)        // Called by TerminalPane on mount
  detach(sessionId, onData)        // Called by TerminalPane on unmount
  markUserInput(sessionId)         // Called when user presses Enter
  updateTitle(sessionId, title)    // Called by term.onTitleChange()
  setOnChunk(sessionId, onChunk)   // Update per-chunk callback
}

export const sessionManager = new SessionManager();

​

11. Runtime State (Lib) (src/lib/runtimeState.ts)

export async function loadRuntimeState(): Promise<void>

1. Merges patch into in-memory _state
2. Calls persist() which invokes write_runtime_state over Tauri IPC
3. Waits for Rust to write atomically (temp file, then rename)

​

Backend State (Rust)

​

Architecture

​

PtyState (Concurrent PTY Registry)

pub struct PtyState(pub(crate) Arc<DashMap<String, Arc<PtySession>>>);

struct PtySession {
  writer: Mutex<Box<dyn Write + Send>>,           // stdin to PTY
  master: Mutex<Box<dyn portable_pty::MasterPty + Send>>,  // master side of PTY
  _slave: Mutex<Box<dyn portable_pty::SlavePty + Send>>,   // slave side (slave end of PTY)
  child:  Mutex<Box<dyn portable_pty::Child + Send + Sync>>, // shell process
  cwd: String,                                    // working directory
}

1. Frontend calls create_pty_session(...) with a unique session_id
2. Rust spawns PTY, starts background reader thread
3. PTY is inserted into DashMap under session_id
4. Frontend can then call write_to_pty(session_id, data) or resize_pty(session_id, ...)
5. When tab closes, frontend calls close_pty_session(session_id) or close_and_remove_worktree(session_id, ...)
6. Rust removes entry from DashMap, kills child process, waits for exit, cleans up

​

ZenState (Secondary Windows)

pub struct ZenState(pub Mutex<std::collections::HashMap<String, (String, String)>>);

​

State Synchronization

​

Frontend to Backend

​

Backend to Frontend

const branch = await invoke<string>("get_git_branch", { path });

const channel = new Channel<{ session_id: string; data: string }>();
channel.onmessage = (event) => {
  const { session_id, data } = event.payload;
  // Update terminal state
};
await invoke("create_pty_session", {
  session_id,
  cwd,
  rows, cols,
  command, args,
  on_event: channel,
});

​

Storage Layer

• All frontend state lives in RuntimeState (typed, centralized)
• Persisted to <app-data-dir>/runtime-state.json atomically via write_runtime_state
• Loaded on app startup via loadRuntimeState
• Falls back to localStorage for migration from older app versions

• No persistent backend state (stateless design)
• Git state is stored in .git/ directories (managed by git CLI)
• PTY session state exists only while the process runs
• Process IDs persisted to .tempest-pid sidecar files inside worktrees for crash recovery

​

localStorage Keys (Deprecated)

​

Session State Deep Dive

​

Complete Session Lifecycle

1. Creation: User clicks “New Workspace” or opens a project, frontend calls createWorktree(projectPath, name)
   • Rust creates .tempest/<name> git worktree
   • Returns worktree path
2. Storage: Frontend saves session to RuntimeState:
   const session: WorktreeSession = {
     name: "feature-x",
     projectId: project.id,
     isRootSession: false,
     // No conversationId or agent yet
   };
   saveWorktreeSession(worktreePath, session);
   
3. PTY Spawn: Frontend calls createPtySession(sessionId, cwd, ...)
   • Rust opens PTY, saves PID to .tempest-pid
   • Starts background reader thread streaming output
4. Agent Launch: If user runs claude in shell, sessionManager detects OSC title changes
   • Sets workState to “working”
   • Stores conversationId (extracted from agent output)
5. Completion: Agent finishes, signals OSC/DEC sequence
   • sessionManager detects signal or timeout
   • Sets workState to “done”
   • Optional: frontend auto-saves session with timestamp
6. Closure: User closes tab
   • Frontend calls closeWorktreeSession(worktreePath)
   • Sets closed: true in RuntimeState (soft close)
   • PTY is still alive (can re-open)
7. Deletion: User clicks “Delete” in sidebar
   • Frontend calls closeAndRemoveWorktree(sessionId, repoPath, worktreePath)
   • Rust kills PTY, waits for process exit, removes worktree dir
   • Frontend removes session from RuntimeState

​

Restore on App Restart

1. loadRuntimeState() reads disk, populating sessions
2. For each open (non-closed) worktree session:
   • Check if .tempest-pid exists
   • If yes, process was orphaned; kill it via taskkill /F /T (Windows) or kill -9 (Unix)
3. For each root session:
   • Call dedupeRootSessions(projectPath) to merge duplicates from old restore bug
   • Restore ghost tabs for root sessions that were closed but are being restored

​

Project State Tracking

• activeInstanceId in RuntimeState (which session tab is focused)
• That session’s WorktreeSession.projectId
• That project’s StoredProject.path

• Sidebar lists all StoredProject entries
• Frontend tracks open projects via getOpenProjects() / saveOpenProjects(...)
• Projects are added via folder picker in welcome screen, persisted to RuntimeState

• On app startup, pruneOrphanedSessions(validPaths) removes sessions for deleted projects
• Prevents stale entries accumulating

​

Key Design Decisions

1. No Redux/Zustand: Custom stores are simpler, smaller, and need no external dependencies for this use case.
2. useSyncExternalStore: Ensures React re-renders only when subscribed state changes, avoiding O(N²) updates across hundreds of sessions.
3. RuntimeState centralization: Single source of truth makes state debugging and persistence easy.
4. Atomic disk writes: Every state change persists atomically (temp file + rename), preventing corruption on crash.
5. Stateless Rust backend: No memory-resident app state reduces crashes and restart costs.
6. DashMap for PTY sessions: Lock-free concurrent HashMap allows many PTY read/write operations to proceed in parallel without global locks.
7. Lazy initialization of merged defaults: Keybindings and settings merge defaults on access, so app updates can add new defaults without migration code.
8. Ephemeral vs persistent: Work state, queue, WebGL pool are ephemeral (lost on restart). Everything else lives in RuntimeState and survives.