prompt_objects 0.5.0 → 0.7.0

data/lib/prompt_objects/session/store.rb

@@ -3,13 +3,16 @@
 require "sqlite3"
 require "json"
 require "securerandom"
+require "monitor"
 
 module PromptObjects
   module Session
     # SQLite-based session storage for conversation history.
     # Each environment has its own sessions.db file (gitignored for privacy).
     class Store
-      SCHEMA_VERSION = 6
+      SCHEMA_VERSION = 11
+
+      attr_reader :migration_backup_path
 
       # Thread types for conversation branching
       THREAD_TYPES = %w[root continuation delegation fork].freeze
@@ -20,6 +23,7 @@ module PromptObjects
       # @param db_path [String] Path to the SQLite database file
       def initialize(db_path)
         @db_path = db_path
+        @db_monitor = Monitor.new
         @db = SQLite3::Database.new(db_path)
         @db.results_as_hash = true
 
@@ -29,12 +33,27 @@ module PromptObjects
         # Set busy timeout to 5 seconds - wait for locks instead of failing immediately
         @db.busy_timeout = 5000
 
+        backup_before_destructive_migration
         setup_schema
+        @db.execute("PRAGMA foreign_keys=ON")
       end
 
       # Close the database connection.
       def close
-        @db.close if @db
+        @db_monitor.synchronize { @db.close if @db }
+      end
+
+      # Repositories use this serialized connection boundary during the
+      # migration away from direct Store SQL. Monitor is reentrant so a
+      # repository transaction may safely call a repository read helper.
+      def with_connection
+        @db_monitor.synchronize { yield @db }
+      end
+
+      def transaction
+        @db_monitor.synchronize do
+          @db.transaction { yield @db }
+        end
       end
 
       # --- Session/Thread CRUD ---
@@ -51,13 +70,13 @@ module PromptObjects
       # @param thread_type [String] Type of thread: root, continuation, delegation, fork
       # @return [String] Session ID
       def create_session(po_name:, name: nil, source: "tui", source_client: nil, metadata: {},
-                         parent_session_id: nil, parent_message_id: nil, parent_po: nil, thread_type: "root")
-        id = SecureRandom.uuid
+                         parent_session_id: nil, parent_message_id: nil, parent_po: nil,
+                         thread_type: "root", workspace_session_id: nil, id: SecureRandom.uuid)
         now = Time.now.utc.iso8601
 
-        @db.execute(<<~SQL, [id, po_name, name, source, source_client, source, now, now, metadata.to_json, parent_session_id, parent_message_id, parent_po, thread_type])
-          INSERT INTO sessions (id, po_name, name, source, source_client, last_message_source, created_at, updated_at, metadata, parent_session_id, parent_message_id, parent_po, thread_type)
-          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        @db.execute(<<~SQL, [id, po_name, name, source, source_client, source, now, now, metadata.to_json, parent_session_id, parent_message_id, parent_po, thread_type, workspace_session_id])
+          INSERT INTO sessions (id, po_name, name, source, source_client, last_message_source, created_at, updated_at, metadata, parent_session_id, parent_message_id, parent_po, thread_type, workspace_session_id)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         SQL
 
         id
@@ -165,6 +184,29 @@ module PromptObjects
         rows.map { |row| parse_session_row(row, include_count: true) }
       end
 
+      # List environment-level sessions (po_name IS NULL) — the shared-context
+      # "jam" sessions managed from the UI, most recent first.
+      # @param limit [Integer, nil] Maximum number of sessions
+      # @return [Array<Hash>] Session data with message counts
+      def list_environment_sessions(limit: nil)
+        sql = <<~SQL
+          SELECT s.*, COUNT(m.id) as message_count
+          FROM sessions s
+          LEFT JOIN messages m ON m.session_id = s.id
+          WHERE s.po_name IS NULL
+          GROUP BY s.id
+          ORDER BY s.updated_at DESC
+        SQL
+
+        params = []
+        if limit
+          sql += " LIMIT ?"
+          params << limit
+        end
+
+        @db.execute(sql, params).map { |row| parse_session_row(row, include_count: true) }
+      end
+
       # --- Thread Navigation ---
 
       # Get all child threads of a session.
@@ -409,10 +451,13 @@ module PromptObjects
         @db.execute("UPDATE sessions SET #{updates.join(', ')} WHERE id = ?", params)
       end
 
-      # Delete a session and all its messages.
+      # Delete a session, its messages, and any env_data scoped to it.
+      # (env_data is keyed by root_thread_id; for a non-root sub-thread this
+      # DELETE is a harmless no-op since its data lives under the root.)
       # @param id [String] Session ID
       def delete_session(id)
         @db.execute("DELETE FROM messages WHERE session_id = ?", [id])
+        @db.execute("DELETE FROM env_data WHERE root_thread_id = ?", [id])
         @db.execute("DELETE FROM sessions WHERE id = ?", [id])
       end
 
@@ -595,6 +640,137 @@ module PromptObjects
         row["count"]
       end
 
+      # --- Environment Data (Shared Key-Value Store) ---
+
+      # Resolve the root thread ID for a session by walking up the delegation chain.
+      # @param session_id [String] Any session ID in a delegation chain
+      # @return [String] The root thread's session ID
+      def resolve_root_thread(session_id)
+        lineage = get_thread_lineage(session_id)
+        return session_id if lineage.empty?
+
+        lineage.first[:id]
+      end
+
+      # Store a key-value pair scoped to a root thread.
+      # Uses INSERT OR REPLACE to create or overwrite.
+      # @param root_thread_id [String] Root thread scope
+      # @param key [String] Data key
+      # @param short_description [String] Brief description for discoverability
+      # @param value [Object] Data value (will be JSON-serialized)
+      # @param stored_by [String] PO name that stored this
+      def store_env_data(root_thread_id:, key:, short_description:, value:, stored_by:)
+        now = Time.now.utc.iso8601
+        json_value = JSON.generate(value)
+
+        @db.execute(<<~SQL, [root_thread_id, key, short_description, json_value, stored_by, now, now])
+          INSERT INTO env_data (root_thread_id, key, short_description, value, stored_by, created_at, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?)
+          ON CONFLICT(root_thread_id, key) DO UPDATE SET
+            short_description = excluded.short_description,
+            value = excluded.value,
+            stored_by = excluded.stored_by,
+            updated_at = excluded.updated_at
+        SQL
+      end
+
+      # Get a single env data entry by key.
+      # @param root_thread_id [String] Root thread scope
+      # @param key [String] Data key
+      # @return [Hash, nil] Entry with parsed value, or nil if not found
+      def get_env_data(root_thread_id:, key:)
+        row = @db.get_first_row(<<~SQL, [root_thread_id, key])
+          SELECT key, short_description, value, stored_by, created_at, updated_at
+          FROM env_data
+          WHERE root_thread_id = ? AND key = ?
+        SQL
+
+        return nil unless row
+
+        {
+          key: row["key"],
+          short_description: row["short_description"],
+          value: JSON.parse(row["value"], symbolize_names: true),
+          stored_by: row["stored_by"],
+          created_at: row["created_at"],
+          updated_at: row["updated_at"]
+        }
+      end
+
+      # List all env data keys and descriptions for a root thread (no values).
+      # @param root_thread_id [String] Root thread scope
+      # @return [Array<Hash>] Entries with key and short_description only
+      def list_env_data(root_thread_id:)
+        rows = @db.execute(<<~SQL, [root_thread_id])
+          SELECT key, short_description FROM env_data
+          WHERE root_thread_id = ?
+          ORDER BY key ASC
+        SQL
+
+        rows.map { |row| { key: row["key"], short_description: row["short_description"] } }
+      end
+
+      # List all env data entries with full values for a root thread.
+      # @param root_thread_id [String] Root thread scope
+      # @return [Array<Hash>] Full entries with parsed values
+      def list_env_data_full(root_thread_id:)
+        rows = @db.execute(<<~SQL, [root_thread_id])
+          SELECT key, short_description, value, stored_by, created_at, updated_at
+          FROM env_data WHERE root_thread_id = ? ORDER BY key ASC
+        SQL
+
+        rows.map do |row|
+          {
+            key: row["key"],
+            short_description: row["short_description"],
+            value: JSON.parse(row["value"]),
+            stored_by: row["stored_by"],
+            created_at: row["created_at"],
+            updated_at: row["updated_at"]
+          }
+        end
+      end
+
+      # Update an existing env data entry.
+      # @param root_thread_id [String] Root thread scope
+      # @param key [String] Data key
+      # @param short_description [String, nil] New description (keeps existing if nil)
+      # @param value [Object, nil] New value (keeps existing if nil)
+      # @param stored_by [String] PO name performing the update
+      # @return [Boolean] True if updated, false if key not found
+      def update_env_data(root_thread_id:, key:, short_description: nil, value: nil, stored_by:)
+        existing = get_env_data(root_thread_id: root_thread_id, key: key)
+        return false unless existing
+
+        updates = ["updated_at = ?", "stored_by = ?"]
+        params = [Time.now.utc.iso8601, stored_by]
+
+        if short_description
+          updates << "short_description = ?"
+          params << short_description
+        end
+
+        if value
+          updates << "value = ?"
+          params << JSON.generate(value)
+        end
+
+        params << root_thread_id
+        params << key
+
+        @db.execute("UPDATE env_data SET #{updates.join(', ')} WHERE root_thread_id = ? AND key = ?", params)
+        true
+      end
+
+      # Delete an env data entry.
+      # @param root_thread_id [String] Root thread scope
+      # @param key [String] Data key
+      # @return [Boolean] True if deleted, false if key not found
+      def delete_env_data(root_thread_id:, key:)
+        @db.execute("DELETE FROM env_data WHERE root_thread_id = ? AND key = ?", [root_thread_id, key])
+        @db.changes > 0
+      end
+
       # --- Usage Aggregation ---
 
       # Get total token usage for a session.
@@ -763,7 +939,7 @@ module PromptObjects
         tree = get_thread_tree(session_id)
         return nil unless tree
 
-        serialize_tree_for_export(tree)
+        serialize_tree_for_export(tree, is_root: true)
       end
 
       # --- Import ---
@@ -908,11 +1084,11 @@ module PromptObjects
         end
       end
 
-      def serialize_tree_for_export(node)
+      def serialize_tree_for_export(node, is_root: false)
         session = node[:session]
         messages = get_messages(session[:id])
 
-        {
+        result = {
           session: {
             id: session[:id],
             po_name: session[:po_name],
@@ -934,6 +1110,13 @@ module PromptObjects
           },
           children: (node[:children] || []).map { |c| serialize_tree_for_export(c) }
         }
+
+        if is_root
+          env_data = list_env_data_full(root_thread_id: session[:id])
+          result[:env_data] = env_data unless env_data.empty?
+        end
+
+        result
       end
 
       def setup_schema
@@ -959,9 +1142,18 @@ module PromptObjects
 
       def create_schema
         @db.execute_batch(<<~SQL)
+          CREATE TABLE IF NOT EXISTS workspace_sessions (
+            id TEXT PRIMARY KEY,
+            name TEXT,
+            status TEXT NOT NULL DEFAULT 'active',
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            metadata TEXT NOT NULL DEFAULT '{}'
+          );
+
           CREATE TABLE IF NOT EXISTS sessions (
             id TEXT PRIMARY KEY,
-            po_name TEXT NOT NULL,
+            po_name TEXT,
             name TEXT,
             source TEXT DEFAULT 'tui',
             source_client TEXT,
@@ -973,13 +1165,24 @@ module PromptObjects
             parent_session_id TEXT,
             parent_message_id INTEGER,
             parent_po TEXT,
-            thread_type TEXT DEFAULT 'root'
+            thread_type TEXT DEFAULT 'root',
+            -- Environment-level sessions (v8)
+            session_type TEXT DEFAULT 'environment',
+            initiated_by TEXT,
+            -- Run-based runtime foundation (v10)
+            workspace_session_id TEXT REFERENCES workspace_sessions(id),
+            parent_run_id TEXT,
+            retention_policy TEXT,
+            archived INTEGER NOT NULL DEFAULT 0,
+            last_run_status TEXT,
+            last_activity_at TEXT
           );
 
           CREATE INDEX IF NOT EXISTS idx_sessions_po_name ON sessions(po_name);
           CREATE INDEX IF NOT EXISTS idx_sessions_updated_at ON sessions(updated_at);
           CREATE INDEX IF NOT EXISTS idx_sessions_source ON sessions(source);
           CREATE INDEX IF NOT EXISTS idx_sessions_parent ON sessions(parent_session_id);
+          CREATE INDEX IF NOT EXISTS idx_sessions_workspace ON sessions(workspace_session_id);
 
           CREATE TABLE IF NOT EXISTS messages (
             id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -990,10 +1193,21 @@ module PromptObjects
             tool_calls TEXT,
             tool_results TEXT,
             usage TEXT,
-            created_at TEXT NOT NULL
+            created_at TEXT NOT NULL,
+            -- Environment-level sessions (v8)
+            target_po TEXT,
+            from_source TEXT,
+            -- Run provenance and stable logical ordering (v10)
+            message_uid TEXT,
+            run_id TEXT,
+            turn_ordinal INTEGER,
+            position INTEGER
           );
 
           CREATE INDEX IF NOT EXISTS idx_messages_session_id ON messages(session_id);
+          CREATE UNIQUE INDEX IF NOT EXISTS idx_messages_uid ON messages(message_uid) WHERE message_uid IS NOT NULL;
+          CREATE INDEX IF NOT EXISTS idx_messages_run ON messages(run_id);
+          CREATE INDEX IF NOT EXISTS idx_messages_turn ON messages(session_id, turn_ordinal, position);
 
           -- Full-text search index for message content
           CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
@@ -1030,6 +1244,144 @@ module PromptObjects
 
           CREATE INDEX IF NOT EXISTS idx_events_session ON events(session_id);
           CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(timestamp);
+
+          -- Shared environment data, scoped to session (v7 original, v8 adds session_id alias)
+          CREATE TABLE IF NOT EXISTS env_data (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            root_thread_id TEXT NOT NULL,
+            session_id TEXT,
+            key TEXT NOT NULL,
+            short_description TEXT NOT NULL,
+            value TEXT NOT NULL,
+            stored_by TEXT NOT NULL,
+            created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+            updated_at TEXT DEFAULT CURRENT_TIMESTAMP,
+            workspace_session_id TEXT REFERENCES workspace_sessions(id),
+            UNIQUE(root_thread_id, key)
+          );
+
+          CREATE INDEX IF NOT EXISTS idx_env_data_root ON env_data(root_thread_id);
+          CREATE INDEX IF NOT EXISTS idx_env_data_session ON env_data(session_id);
+          CREATE INDEX IF NOT EXISTS idx_env_data_workspace ON env_data(workspace_session_id);
+
+          CREATE TABLE IF NOT EXISTS runs (
+            id TEXT PRIMARY KEY,
+            client_request_id TEXT,
+            workspace_session_id TEXT NOT NULL REFERENCES workspace_sessions(id),
+            thread_id TEXT NOT NULL REFERENCES sessions(id),
+            po_name TEXT NOT NULL,
+            turn_ordinal INTEGER NOT NULL,
+            input_content TEXT,
+            input_message_id INTEGER REFERENCES messages(id),
+            history_cutoff_message_id INTEGER REFERENCES messages(id),
+            definition_version TEXT NOT NULL,
+            provider TEXT,
+            model TEXT,
+            capability_policy_version TEXT,
+            source_type TEXT NOT NULL,
+            source_name TEXT,
+            parent_run_id TEXT REFERENCES runs(id),
+            root_run_id TEXT,
+            status TEXT NOT NULL,
+            priority INTEGER NOT NULL DEFAULT 0,
+            enqueued_at TEXT NOT NULL,
+            started_at TEXT,
+            finished_at TEXT,
+            cancellation_reason TEXT,
+            final_response TEXT,
+            usage TEXT,
+            error_class TEXT,
+            error_message TEXT,
+            metadata TEXT NOT NULL DEFAULT '{}',
+            UNIQUE(thread_id, turn_ordinal)
+          );
+
+          CREATE UNIQUE INDEX IF NOT EXISTS idx_runs_client_request
+            ON runs(workspace_session_id, source_type, client_request_id)
+            WHERE client_request_id IS NOT NULL;
+          CREATE INDEX IF NOT EXISTS idx_runs_workspace_status ON runs(workspace_session_id, status);
+          CREATE INDEX IF NOT EXISTS idx_runs_thread_status ON runs(thread_id, status);
+          CREATE INDEX IF NOT EXISTS idx_runs_parent ON runs(parent_run_id);
+
+          CREATE TABLE IF NOT EXISTS run_definitions (
+            run_id TEXT PRIMARY KEY REFERENCES runs(id),
+            po_name TEXT NOT NULL,
+            version TEXT NOT NULL,
+            prompt TEXT NOT NULL,
+            config TEXT NOT NULL,
+            provider TEXT,
+            model TEXT,
+            capability_policy_version TEXT NOT NULL,
+            created_at TEXT NOT NULL
+          );
+
+          CREATE TABLE IF NOT EXISTS workspace_events (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            workspace_session_id TEXT NOT NULL REFERENCES workspace_sessions(id),
+            event_type TEXT NOT NULL,
+            entity_type TEXT,
+            entity_id TEXT,
+            payload TEXT NOT NULL DEFAULT '{}',
+            created_at TEXT NOT NULL
+          );
+
+          CREATE INDEX IF NOT EXISTS idx_workspace_events_scope ON workspace_events(workspace_session_id, id);
+
+          CREATE TABLE IF NOT EXISTS run_events (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            run_id TEXT NOT NULL REFERENCES runs(id),
+            sequence INTEGER NOT NULL,
+            workspace_cursor INTEGER NOT NULL UNIQUE REFERENCES workspace_events(id),
+            workspace_session_id TEXT NOT NULL REFERENCES workspace_sessions(id),
+            thread_id TEXT NOT NULL REFERENCES sessions(id),
+            kind TEXT NOT NULL,
+            timestamp TEXT NOT NULL,
+            data TEXT NOT NULL DEFAULT '{}',
+            UNIQUE(run_id, sequence)
+          );
+
+          CREATE INDEX IF NOT EXISTS idx_run_events_run ON run_events(run_id, sequence);
+          CREATE INDEX IF NOT EXISTS idx_run_events_workspace ON run_events(workspace_session_id, workspace_cursor);
+
+          CREATE TABLE IF NOT EXISTS tool_executions (
+            id TEXT PRIMARY KEY,
+            provider_tool_call_id TEXT NOT NULL,
+            run_id TEXT NOT NULL REFERENCES runs(id),
+            batch_id TEXT NOT NULL,
+            batch_position INTEGER NOT NULL,
+            capability_name TEXT NOT NULL,
+            capability_policy_version TEXT,
+            status TEXT NOT NULL,
+            resource_keys TEXT NOT NULL DEFAULT '[]',
+            arguments TEXT NOT NULL DEFAULT '{}',
+            result TEXT,
+            error_class TEXT,
+            error_message TEXT,
+            cancellation_reason TEXT,
+            started_at TEXT,
+            finished_at TEXT,
+            UNIQUE(run_id, provider_tool_call_id)
+          );
+
+          CREATE INDEX IF NOT EXISTS idx_tool_executions_run ON tool_executions(run_id, batch_position);
+
+          CREATE TABLE IF NOT EXISTS artifacts (
+            id TEXT PRIMARY KEY,
+            workspace_session_id TEXT NOT NULL REFERENCES workspace_sessions(id),
+            owner_po TEXT NOT NULL,
+            owner_thread_id TEXT REFERENCES sessions(id),
+            producing_run_id TEXT REFERENCES runs(id),
+            title TEXT NOT NULL,
+            html TEXT NOT NULL,
+            revision INTEGER NOT NULL DEFAULT 1,
+            mode TEXT NOT NULL DEFAULT 'replace',
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            metadata TEXT NOT NULL DEFAULT '{}'
+          );
+
+          CREATE INDEX IF NOT EXISTS idx_artifacts_workspace ON artifacts(workspace_session_id, updated_at);
+          CREATE INDEX IF NOT EXISTS idx_artifacts_owner_thread ON artifacts(owner_thread_id);
         SQL
       end
 
@@ -1107,6 +1459,399 @@ module PromptObjects
           # Add usage column for token tracking
           @db.execute("ALTER TABLE messages ADD COLUMN usage TEXT")
         end
+
+        if from_version < 7
+          # Add shared environment data table for delegation chains
+          @db.execute_batch(<<~SQL)
+            CREATE TABLE IF NOT EXISTS env_data (
+              id INTEGER PRIMARY KEY AUTOINCREMENT,
+              root_thread_id TEXT NOT NULL,
+              key TEXT NOT NULL,
+              short_description TEXT NOT NULL,
+              value TEXT NOT NULL,
+              stored_by TEXT NOT NULL,
+              created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+              updated_at TEXT DEFAULT CURRENT_TIMESTAMP,
+              UNIQUE(root_thread_id, key)
+            );
+
+            CREATE INDEX IF NOT EXISTS idx_env_data_root ON env_data(root_thread_id);
+          SQL
+        end
+
+        if from_version < 8
+          # Environment-level sessions: add session_type, initiated_by to sessions;
+          # target_po, from_source to messages; session_id to env_data
+          @db.execute_batch(<<~SQL)
+            ALTER TABLE sessions ADD COLUMN session_type TEXT DEFAULT 'environment';
+            ALTER TABLE sessions ADD COLUMN initiated_by TEXT;
+
+            ALTER TABLE messages ADD COLUMN target_po TEXT;
+            ALTER TABLE messages ADD COLUMN from_source TEXT;
+
+            ALTER TABLE env_data ADD COLUMN session_id TEXT;
+            CREATE INDEX IF NOT EXISTS idx_env_data_session ON env_data(session_id);
+          SQL
+
+          # Migrate existing data: set session_type based on thread_type,
+          # populate target_po from session's po_name, copy root_thread_id to session_id
+          @db.execute("UPDATE sessions SET session_type = 'delegation' WHERE thread_type = 'delegation'")
+          @db.execute("UPDATE sessions SET initiated_by = 'human' WHERE session_type = 'environment'")
+          @db.execute("UPDATE messages SET target_po = (SELECT po_name FROM sessions WHERE sessions.id = messages.session_id) WHERE target_po IS NULL")
+          @db.execute("UPDATE messages SET from_source = 'human' WHERE role = 'user' AND from_source IS NULL")
+          @db.execute("UPDATE env_data SET session_id = root_thread_id WHERE session_id IS NULL")
+        end
+
+        if from_version < 9
+          # v8 introduced environment sessions (po_name IS NULL), but databases
+          # created before that have `po_name TEXT NOT NULL`, and ALTER TABLE
+          # can't drop a NOT NULL constraint. Rebuild the sessions table with a
+          # nullable po_name so create_environment_session works on upgrade.
+          # (Fresh DBs go through create_schema, which is already nullable.)
+          @db.execute_batch(<<~SQL)
+            CREATE TABLE sessions_new (
+              id TEXT PRIMARY KEY,
+              po_name TEXT,
+              name TEXT,
+              source TEXT DEFAULT 'tui',
+              source_client TEXT,
+              last_message_source TEXT,
+              created_at TEXT NOT NULL,
+              updated_at TEXT NOT NULL,
+              metadata TEXT DEFAULT '{}',
+              parent_session_id TEXT,
+              parent_message_id INTEGER,
+              parent_po TEXT,
+              thread_type TEXT DEFAULT 'root',
+              session_type TEXT DEFAULT 'environment',
+              initiated_by TEXT
+            );
+
+            INSERT INTO sessions_new (
+              id, po_name, name, source, source_client, last_message_source,
+              created_at, updated_at, metadata, parent_session_id,
+              parent_message_id, parent_po, thread_type, session_type, initiated_by
+            )
+            SELECT
+              id, po_name, name, source, source_client, last_message_source,
+              created_at, updated_at, metadata, parent_session_id,
+              parent_message_id, parent_po, thread_type, session_type, initiated_by
+            FROM sessions;
+
+            DROP TABLE sessions;
+            ALTER TABLE sessions_new RENAME TO sessions;
+
+            CREATE INDEX IF NOT EXISTS idx_sessions_po_name ON sessions(po_name);
+            CREATE INDEX IF NOT EXISTS idx_sessions_updated_at ON sessions(updated_at);
+            CREATE INDEX IF NOT EXISTS idx_sessions_source ON sessions(source);
+            CREATE INDEX IF NOT EXISTS idx_sessions_parent ON sessions(parent_session_id);
+          SQL
+        end
+
+        migrate_schema_v10 if from_version < 10
+        migrate_schema_v11 if from_version < 11
+      end
+
+      def migrate_schema_v11
+        @db.transaction do
+          @db.execute_batch(<<~SQL)
+            CREATE TABLE IF NOT EXISTS run_definitions (
+              run_id TEXT PRIMARY KEY REFERENCES runs(id),
+              po_name TEXT NOT NULL,
+              version TEXT NOT NULL,
+              prompt TEXT NOT NULL,
+              config TEXT NOT NULL,
+              provider TEXT,
+              model TEXT,
+              capability_policy_version TEXT NOT NULL,
+              created_at TEXT NOT NULL
+            );
+          SQL
+        end
+      end
+
+      def migrate_schema_v10
+        @db.transaction do
+          @db.execute_batch(<<~SQL)
+            CREATE TABLE IF NOT EXISTS workspace_sessions (
+              id TEXT PRIMARY KEY,
+              name TEXT,
+              status TEXT NOT NULL DEFAULT 'active',
+              created_at TEXT NOT NULL,
+              updated_at TEXT NOT NULL,
+              metadata TEXT NOT NULL DEFAULT '{}'
+            );
+          SQL
+
+          add_column_unless_exists("sessions", "workspace_session_id", "TEXT REFERENCES workspace_sessions(id)")
+          add_column_unless_exists("sessions", "parent_run_id", "TEXT")
+          add_column_unless_exists("sessions", "retention_policy", "TEXT")
+          add_column_unless_exists("sessions", "archived", "INTEGER NOT NULL DEFAULT 0")
+          add_column_unless_exists("sessions", "last_run_status", "TEXT")
+          add_column_unless_exists("sessions", "last_activity_at", "TEXT")
+
+          if table_exists?("messages")
+            add_column_unless_exists("messages", "message_uid", "TEXT")
+            add_column_unless_exists("messages", "run_id", "TEXT")
+            add_column_unless_exists("messages", "turn_ordinal", "INTEGER")
+            add_column_unless_exists("messages", "position", "INTEGER")
+          end
+
+          if table_exists?("env_data")
+            add_column_unless_exists("env_data", "workspace_session_id", "TEXT REFERENCES workspace_sessions(id)")
+          end
+
+          create_v10_runtime_tables
+          backfill_workspace_sessions
+          backfill_artifacts_from_env_data
+          create_v10_indexes
+        end
+      end
+
+      def create_v10_runtime_tables
+        @db.execute_batch(<<~SQL)
+          CREATE TABLE IF NOT EXISTS runs (
+            id TEXT PRIMARY KEY,
+            client_request_id TEXT,
+            workspace_session_id TEXT NOT NULL REFERENCES workspace_sessions(id),
+            thread_id TEXT NOT NULL REFERENCES sessions(id),
+            po_name TEXT NOT NULL,
+            turn_ordinal INTEGER NOT NULL,
+            input_content TEXT,
+            input_message_id INTEGER,
+            history_cutoff_message_id INTEGER,
+            definition_version TEXT NOT NULL,
+            provider TEXT,
+            model TEXT,
+            capability_policy_version TEXT,
+            source_type TEXT NOT NULL,
+            source_name TEXT,
+            parent_run_id TEXT REFERENCES runs(id),
+            root_run_id TEXT,
+            status TEXT NOT NULL,
+            priority INTEGER NOT NULL DEFAULT 0,
+            enqueued_at TEXT NOT NULL,
+            started_at TEXT,
+            finished_at TEXT,
+            cancellation_reason TEXT,
+            final_response TEXT,
+            usage TEXT,
+            error_class TEXT,
+            error_message TEXT,
+            metadata TEXT NOT NULL DEFAULT '{}',
+            UNIQUE(thread_id, turn_ordinal)
+          );
+
+          CREATE TABLE IF NOT EXISTS workspace_events (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            workspace_session_id TEXT NOT NULL REFERENCES workspace_sessions(id),
+            event_type TEXT NOT NULL,
+            entity_type TEXT,
+            entity_id TEXT,
+            payload TEXT NOT NULL DEFAULT '{}',
+            created_at TEXT NOT NULL
+          );
+
+          CREATE TABLE IF NOT EXISTS run_events (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            run_id TEXT NOT NULL REFERENCES runs(id),
+            sequence INTEGER NOT NULL,
+            workspace_cursor INTEGER NOT NULL UNIQUE REFERENCES workspace_events(id),
+            workspace_session_id TEXT NOT NULL REFERENCES workspace_sessions(id),
+            thread_id TEXT NOT NULL REFERENCES sessions(id),
+            kind TEXT NOT NULL,
+            timestamp TEXT NOT NULL,
+            data TEXT NOT NULL DEFAULT '{}',
+            UNIQUE(run_id, sequence)
+          );
+
+          CREATE TABLE IF NOT EXISTS tool_executions (
+            id TEXT PRIMARY KEY,
+            provider_tool_call_id TEXT NOT NULL,
+            run_id TEXT NOT NULL REFERENCES runs(id),
+            batch_id TEXT NOT NULL,
+            batch_position INTEGER NOT NULL,
+            capability_name TEXT NOT NULL,
+            capability_policy_version TEXT,
+            status TEXT NOT NULL,
+            resource_keys TEXT NOT NULL DEFAULT '[]',
+            arguments TEXT NOT NULL DEFAULT '{}',
+            result TEXT,
+            error_class TEXT,
+            error_message TEXT,
+            cancellation_reason TEXT,
+            started_at TEXT,
+            finished_at TEXT,
+            UNIQUE(run_id, provider_tool_call_id)
+          );
+
+          CREATE TABLE IF NOT EXISTS artifacts (
+            id TEXT PRIMARY KEY,
+            workspace_session_id TEXT NOT NULL REFERENCES workspace_sessions(id),
+            owner_po TEXT NOT NULL,
+            owner_thread_id TEXT REFERENCES sessions(id),
+            producing_run_id TEXT REFERENCES runs(id),
+            title TEXT NOT NULL,
+            html TEXT NOT NULL,
+            revision INTEGER NOT NULL DEFAULT 1,
+            mode TEXT NOT NULL DEFAULT 'replace',
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            metadata TEXT NOT NULL DEFAULT '{}'
+          );
+        SQL
+      end
+
+      def create_v10_indexes
+        @db.execute("CREATE INDEX IF NOT EXISTS idx_sessions_workspace ON sessions(workspace_session_id)")
+        if table_exists?("messages")
+          @db.execute("CREATE UNIQUE INDEX IF NOT EXISTS idx_messages_uid ON messages(message_uid) WHERE message_uid IS NOT NULL")
+          @db.execute("CREATE INDEX IF NOT EXISTS idx_messages_run ON messages(run_id)")
+          @db.execute("CREATE INDEX IF NOT EXISTS idx_messages_turn ON messages(session_id, turn_ordinal, position)")
+        end
+        @db.execute("CREATE INDEX IF NOT EXISTS idx_env_data_workspace ON env_data(workspace_session_id)") if table_exists?("env_data")
+        @db.execute(<<~SQL)
+          CREATE UNIQUE INDEX IF NOT EXISTS idx_runs_client_request
+          ON runs(workspace_session_id, source_type, client_request_id)
+          WHERE client_request_id IS NOT NULL
+        SQL
+        @db.execute("CREATE INDEX IF NOT EXISTS idx_runs_workspace_status ON runs(workspace_session_id, status)")
+        @db.execute("CREATE INDEX IF NOT EXISTS idx_runs_thread_status ON runs(thread_id, status)")
+        @db.execute("CREATE INDEX IF NOT EXISTS idx_runs_parent ON runs(parent_run_id)")
+        @db.execute("CREATE INDEX IF NOT EXISTS idx_workspace_events_scope ON workspace_events(workspace_session_id, id)")
+        @db.execute("CREATE INDEX IF NOT EXISTS idx_run_events_run ON run_events(run_id, sequence)")
+        @db.execute("CREATE INDEX IF NOT EXISTS idx_run_events_workspace ON run_events(workspace_session_id, workspace_cursor)")
+        @db.execute("CREATE INDEX IF NOT EXISTS idx_tool_executions_run ON tool_executions(run_id, batch_position)")
+        @db.execute("CREATE INDEX IF NOT EXISTS idx_artifacts_workspace ON artifacts(workspace_session_id, updated_at)")
+        @db.execute("CREATE INDEX IF NOT EXISTS idx_artifacts_owner_thread ON artifacts(owner_thread_id)")
+      end
+
+      def backup_before_destructive_migration
+        version = get_schema_version
+        return if @db_path == ":memory:" || version.zero? || version >= SCHEMA_VERSION
+        return unless File.file?(@db_path)
+
+        timestamp = Time.now.utc.strftime("%Y%m%dT%H%M%S%6NZ")
+        @migration_backup_path = "#{@db_path}.backup-v#{version}-#{timestamp}"
+        destination = SQLite3::Database.new(@migration_backup_path)
+        backup = SQLite3::Backup.new(destination, "main", @db, "main")
+        backup.step(-1)
+        backup.finish
+      ensure
+        destination&.close
+      end
+
+      def table_exists?(table)
+        !@db.get_first_value(
+          "SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?",
+          [table]
+        ).nil?
+      end
+
+      def column_exists?(table, column)
+        return false unless table_exists?(table)
+
+        @db.table_info(table).any? { |definition| definition["name"] == column }
+      end
+
+      def add_column_unless_exists(table, column, definition)
+        return if column_exists?(table, column)
+
+        @db.execute("ALTER TABLE #{table} ADD COLUMN #{column} #{definition}")
+      end
+
+      def backfill_workspace_sessions
+        environment_rows = @db.execute(<<~SQL)
+          SELECT id, name, created_at, updated_at, metadata
+          FROM sessions
+          WHERE po_name IS NULL
+          ORDER BY created_at ASC
+        SQL
+
+        environment_rows.each do |row|
+          @db.execute(<<~SQL, [row["id"], row["name"], row["created_at"], row["updated_at"], row["metadata"] || "{}"])
+            INSERT OR IGNORE INTO workspace_sessions (id, name, status, created_at, updated_at, metadata)
+            VALUES (?, ?, 'active', ?, ?, ?)
+          SQL
+          @db.execute("UPDATE sessions SET workspace_session_id = ? WHERE id = ?", [row["id"], row["id"]])
+        end
+
+        workspace_ids = @db.execute("SELECT id FROM workspace_sessions ORDER BY created_at ASC").map { |row| row["id"] }
+        fallback_id = if workspace_ids.one?
+                        workspace_ids.first
+                      else
+                        create_imported_workspace
+                      end
+
+        @db.execute(
+          "UPDATE sessions SET workspace_session_id = ? WHERE workspace_session_id IS NULL",
+          [fallback_id]
+        )
+
+        return unless table_exists?("env_data")
+
+        @db.execute(<<~SQL)
+          UPDATE env_data
+          SET workspace_session_id = session_id
+          WHERE workspace_session_id IS NULL
+            AND session_id IN (SELECT id FROM workspace_sessions)
+        SQL
+        @db.execute(<<~SQL)
+          UPDATE env_data
+          SET workspace_session_id = (
+            SELECT workspace_session_id FROM sessions WHERE sessions.id = env_data.root_thread_id
+          )
+          WHERE workspace_session_id IS NULL
+        SQL
+        @db.execute(
+          "UPDATE env_data SET workspace_session_id = ? WHERE workspace_session_id IS NULL",
+          [fallback_id]
+        )
+      end
+
+      def create_imported_workspace
+        existing = @db.get_first_value("SELECT id FROM workspace_sessions WHERE name = 'Imported legacy threads' LIMIT 1")
+        return existing if existing
+
+        id = SecureRandom.uuid
+        now = Time.now.utc.iso8601
+        @db.execute(<<~SQL, [id, now, now])
+          INSERT INTO workspace_sessions (id, name, status, created_at, updated_at, metadata)
+          VALUES (?, 'Imported legacy threads', 'active', ?, ?, '{}')
+        SQL
+        id
+      end
+
+      def backfill_artifacts_from_env_data
+        return unless table_exists?("env_data")
+
+        rows = @db.execute(<<~SQL)
+          SELECT key, workspace_session_id, value, stored_by, created_at, updated_at
+          FROM env_data
+          WHERE key LIKE 'artifact_%'
+        SQL
+        rows.each do |row|
+          value = JSON.parse(row["value"])
+          title = value["title"]
+          html = value["html"]
+          next unless row["workspace_session_id"] && title && html
+
+          owner_po = value["rendered_by"] || row["stored_by"] || "unknown"
+          owner_thread_id = @db.get_first_value(<<~SQL, [row["workspace_session_id"], owner_po])
+            SELECT id FROM sessions
+            WHERE workspace_session_id = ? AND po_name = ?
+            ORDER BY updated_at DESC
+            LIMIT 1
+          SQL
+          @db.execute(<<~SQL, [row["key"], row["workspace_session_id"], owner_po, owner_thread_id, title, html, row["created_at"], row["updated_at"]])
+            INSERT OR IGNORE INTO artifacts (
+              id, workspace_session_id, owner_po, owner_thread_id, producing_run_id,
+              title, html, revision, mode, created_at, updated_at, metadata
+            ) VALUES (?, ?, ?, ?, NULL, ?, ?, 1, 'replace', ?, ?, '{}')
+          SQL
+        rescue JSON::ParserError
+          next
+        end
       end
 
       def empty_usage
@@ -1184,7 +1929,17 @@ module PromptObjects
           parent_session_id: row["parent_session_id"],
           parent_message_id: row["parent_message_id"],
           parent_po: row["parent_po"],
-          thread_type: row["thread_type"] || "root"
+          thread_type: row["thread_type"] || "root",
+          # Environment session fields (v8)
+          session_type: row["session_type"] || "environment",
+          initiated_by: row["initiated_by"],
+          # Run-based runtime fields (v10)
+          workspace_session_id: row["workspace_session_id"],
+          parent_run_id: row["parent_run_id"],
+          retention_policy: row["retention_policy"],
+          archived: row["archived"].to_i == 1,
+          last_run_status: row["last_run_status"],
+          last_activity_at: row["last_activity_at"] ? Time.parse(row["last_activity_at"]) : nil
         }
         result[:message_count] = row["message_count"] if include_count && row["message_count"]
         result
@@ -1213,6 +1968,10 @@ module PromptObjects
           tool_calls: row["tool_calls"] ? JSON.parse(row["tool_calls"], symbolize_names: true) : nil,
           tool_results: row["tool_results"] ? JSON.parse(row["tool_results"], symbolize_names: true) : nil,
           usage: row["usage"] ? JSON.parse(row["usage"], symbolize_names: true) : nil,
+          message_uid: row["message_uid"],
+          run_id: row["run_id"],
+          turn_ordinal: row["turn_ordinal"],
+          position: row["position"],
           created_at: row["created_at"] ? Time.parse(row["created_at"]) : nil
         }
       end