@myagentroam/node 0.1.0 → 0.1.2

package/dist/database.js

@@ -1,8 +1,11 @@
 import { randomUUID } from 'node:crypto';
-import { mkdirSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, rmSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { runnerDefaultConfigurationSchema } from '@myagentroam/protocol';
+import { assertNodeSchema, NODE_SCHEMA_V1 } from './migrations/v001.js';
+import { assertNodeSchemaV2, migrateNodeSchemaV2, NODE_SCHEMA_VERSION_V2 } from './migrations/v002.js';
+const NODE_SCHEMA_VERSION = NODE_SCHEMA_VERSION_V2;
 export class NodeDatabase {
     now;
     activeWorkspaceLeaseCount() {
@@ -17,13 +20,20 @@ export class NodeDatabase {
         this.nodeIdProvider = typeof nodeId === 'string' ? () => nodeId : nodeId;
         if (path !== ':memory:')
             mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-        this.raw = new DatabaseSync(path, {
-            enableForeignKeyConstraints: true,
-            timeout: 5_000,
-            defensive: true
-        });
-        this.raw.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;');
-        migrate(this.raw);
+        const releaseMigrationLock = acquireNodeMigrationLock(path);
+        try {
+            this.raw = new DatabaseSync(path, {
+                enableForeignKeyConstraints: true,
+                timeout: 5_000,
+                defensive: true
+            });
+            this.raw.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;');
+            migrate(this.raw);
+            initializeEphemeralRuntimeTables(this.raw);
+        }
+        finally {
+            releaseMigrationLock();
+        }
     }
     close() {
         this.raw.close();
@@ -126,6 +136,7 @@ export class NodeDatabase {
             // Session deletion cascades their runs, conversation and attachments. The workspace
             // record itself never represents a filesystem deletion.
             this.raw.prepare('DELETE FROM agent_sessions WHERE workspace_id = ?').run(id);
+            this.raw.prepare('DELETE FROM legacy_agent_sessions WHERE workspace_id = ?').run(id);
             this.raw.prepare('DELETE FROM workspaces WHERE id = ?').run(id);
             this.raw.exec('COMMIT');
             return current;
@@ -158,7 +169,7 @@ export class NodeDatabase {
             createdAt: this.now()
         };
         this.raw
-            .prepare(`INSERT INTO agent_sessions
+            .prepare(`INSERT INTO legacy_agent_sessions
           (id, workspace_id, runner, external_session_id, native_control, channel_token, cwd, model, effort, access, custom_title, runner_title, pinned_at, title_source, last_activity_at, created_at, updated_at)
          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
             .run(session.id, session.workspaceId, session.runner, session.externalSessionId, session.nativeControl, session.channelToken, session.cwd, session.model, session.effort, session.access, session.customTitle, session.runnerTitle, session.pinnedAt, session.titleSource, session.lastActivityAt, session.createdAt, session.createdAt);
@@ -166,13 +177,13 @@ export class NodeDatabase {
     }
     getAgentSession(id) {
         const row = this.raw
-            .prepare('SELECT id, workspace_id, runner, external_session_id, native_control, channel_token, cwd, model, effort, access, custom_title, runner_title, pinned_at, title_source, last_activity_at, created_at FROM agent_sessions WHERE id = ?')
+            .prepare('SELECT id, workspace_id, runner, external_session_id, native_control, channel_token, cwd, model, effort, access, custom_title, runner_title, pinned_at, title_source, last_activity_at, created_at FROM legacy_agent_sessions WHERE id = ?')
             .get(id);
         return row === undefined ? undefined : session(row, this.nodeIdProvider());
     }
     updateAgentSessionConfiguration(input) {
         const result = this.raw
-            .prepare(`UPDATE agent_sessions
+            .prepare(`UPDATE legacy_agent_sessions
          SET model = ?, effort = ?, access = ?, updated_at = ?
          WHERE id = ?`)
             .run(input.model, input.effort, input.access, this.now(), input.sessionId);
@@ -182,20 +193,20 @@ export class NodeDatabase {
     }
     listAgentSessions() {
         return this.raw
-            .prepare('SELECT id, workspace_id, runner, external_session_id, native_control, channel_token, cwd, model, effort, access, custom_title, runner_title, pinned_at, title_source, last_activity_at, created_at FROM agent_sessions ORDER BY pinned_at IS NULL, pinned_at DESC, last_activity_at DESC, id DESC')
+            .prepare('SELECT id, workspace_id, runner, external_session_id, native_control, channel_token, cwd, model, effort, access, custom_title, runner_title, pinned_at, title_source, last_activity_at, created_at FROM legacy_agent_sessions ORDER BY pinned_at IS NULL, pinned_at DESC, last_activity_at DESC, id DESC')
             .all()
             .map((row) => session(row, this.nodeIdProvider()));
     }
     findAgentSessionByExternalSession(runner, externalSessionId) {
         const row = this.raw
             .prepare(`SELECT id, workspace_id, runner, external_session_id, native_control, channel_token, cwd, model, effort, access, custom_title, runner_title, pinned_at, title_source, last_activity_at, created_at
-         FROM agent_sessions WHERE runner = ? AND external_session_id = ?`)
+         FROM legacy_agent_sessions WHERE runner = ? AND external_session_id = ?`)
             .get(runner, externalSessionId);
         return row === undefined ? undefined : session(row, this.nodeIdProvider());
     }
     setNativeControl(sessionId, nativeControl) {
         const result = this.raw
-            .prepare('UPDATE agent_sessions SET native_control = ?, updated_at = ? WHERE id = ?')
+            .prepare('UPDATE legacy_agent_sessions SET native_control = ?, updated_at = ? WHERE id = ?')
             .run(nativeControl, this.now(), sessionId);
         if (Number(result.changes) === 0)
             throw new Error('SESSION_NOT_FOUND');
@@ -204,7 +215,7 @@ export class NodeDatabase {
         if (externalSessionId.length === 0)
             throw new Error('SESSION_EXTERNAL_ID_INVALID');
         const result = this.raw
-            .prepare("UPDATE agent_sessions SET external_session_id = ?, native_control = 'MAR_MANAGED', updated_at = ? WHERE id = ?")
+            .prepare("UPDATE legacy_agent_sessions SET external_session_id = ?, native_control = 'MAR_MANAGED', updated_at = ? WHERE id = ?")
             .run(externalSessionId, this.now(), sessionId);
         if (Number(result.changes) === 0)
             throw new Error('SESSION_NOT_FOUND');
@@ -213,7 +224,7 @@ export class NodeDatabase {
         if (token.length < 16)
             throw new Error('SESSION_CHANNEL_TOKEN_INVALID');
         const result = this.raw
-            .prepare('UPDATE agent_sessions SET channel_token = ?, updated_at = ? WHERE id = ?')
+            .prepare('UPDATE legacy_agent_sessions SET channel_token = ?, updated_at = ? WHERE id = ?')
             .run(token, this.now(), sessionId);
         if (Number(result.changes) === 0)
             throw new Error('SESSION_NOT_FOUND');
@@ -228,26 +239,21 @@ export class NodeDatabase {
         const pinnedAt = input.pinned === undefined ? current.pinnedAt : input.pinned ? this.now() : null;
         const titleSource = title === null ? 'AUTO' : 'CUSTOM';
         this.raw
-            .prepare('UPDATE agent_sessions SET custom_title = ?, pinned_at = ?, title_source = ?, updated_at = ? WHERE id = ?')
+            .prepare('UPDATE legacy_agent_sessions SET custom_title = ?, pinned_at = ?, title_source = ?, updated_at = ? WHERE id = ?')
             .run(title, pinnedAt, titleSource, this.now(), input.sessionId);
         return this.getAgentSession(input.sessionId);
     }
     getNativeSessionMetadata(runner, externalSessionId, workspaceId) {
         const row = this.raw
-            .prepare(`SELECT custom_title, runner_title, runner_title_pending, pinned_at, model, effort, access FROM native_session_metadata
-         WHERE runner = ? AND external_session_id = ? AND workspace_id = ?`)
-            .get(runner, externalSessionId, workspaceId);
-        return row === undefined
-            ? undefined
-            : {
-                customTitle: nullableString(row, 'custom_title'),
-                runnerTitle: nullableString(row, 'runner_title'),
-                runnerTitlePending: row['runner_title_pending'] === 1,
-                pinnedAt: nullableNumber(row, 'pinned_at'),
-                model: nullableString(row, 'model'),
-                effort: nullableString(row, 'effort'),
-                access: nullableString(row, 'access')
-            };
+            .prepare('SELECT pin_order, metadata FROM agent_sessions WHERE id = ? AND runner = ? AND workspace_id = ?')
+            .get(externalSessionId, runner, workspaceId);
+        if (row === undefined)
+            return undefined;
+        return {
+            ...sessionMetadata(row),
+            pinnedAt: row['pin_order'] === null ? null : 1,
+            pinOrder: nullableNumber(row, 'pin_order')
+        };
     }
     saveNativeSessionMetadata(input) {
         const current = this.getNativeSessionMetadata(input.runner, input.externalSessionId, input.workspaceId);
@@ -264,21 +270,99 @@ export class NodeDatabase {
             throw new Error('SESSION_TITLE_INVALID');
         if (runnerTitle !== null && runnerTitle.length > 160)
             throw new Error('SESSION_TITLE_INVALID');
-        const pinnedAt = input.pinned === undefined ? (current?.pinnedAt ?? null) : input.pinned ? this.now() : null;
+        let pinOrder = current?.pinOrder ?? null;
+        const pinAtTop = input.pinned === true && pinOrder === null;
+        if (pinAtTop)
+            pinOrder = 0;
+        else if (input.pinned === false)
+            pinOrder = null;
         const model = input.model === undefined ? (current?.model ?? null) : input.model;
         const effort = input.effort === undefined ? (current?.effort ?? null) : input.effort;
         const access = input.access === undefined ? (current?.access ?? null) : input.access;
-        this.raw
-            .prepare(`INSERT INTO native_session_metadata
-          (runner, external_session_id, workspace_id, custom_title, runner_title, runner_title_pending, pinned_at, model, effort, access, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-         ON CONFLICT(runner, external_session_id, workspace_id) DO UPDATE SET
-           custom_title = excluded.custom_title, runner_title = excluded.runner_title,
-           runner_title_pending = excluded.runner_title_pending, pinned_at = excluded.pinned_at,
-           model = excluded.model, effort = excluded.effort, access = excluded.access,
-           updated_at = excluded.updated_at`)
-            .run(input.runner, input.externalSessionId, input.workspaceId, customTitle, runnerTitle, runnerTitlePending ? 1 : 0, pinnedAt, model, effort, access, this.now());
-        return { customTitle, runnerTitle, runnerTitlePending, pinnedAt, model, effort, access };
+        const metadata = JSON.stringify({
+            version: 1,
+            customTitle,
+            runnerTitle,
+            runnerTitlePending,
+            model,
+            effort,
+            access
+        });
+        this.raw.exec('BEGIN IMMEDIATE');
+        try {
+            if (pinAtTop)
+                this.raw
+                    .prepare('UPDATE agent_sessions SET pin_order = pin_order + 1 WHERE workspace_id = ? AND pin_order IS NOT NULL')
+                    .run(input.workspaceId);
+            this.raw
+                .prepare(`INSERT INTO agent_sessions (id, workspace_id, runner, pin_order, metadata)
+           VALUES (?, ?, ?, ?, ?)
+           ON CONFLICT(id) DO UPDATE SET workspace_id = excluded.workspace_id,
+             runner = excluded.runner, pin_order = excluded.pin_order, metadata = excluded.metadata`)
+                .run(input.externalSessionId, input.workspaceId, input.runner, pinOrder, metadata);
+            this.raw.exec('COMMIT');
+        }
+        catch (error) {
+            this.raw.exec('ROLLBACK');
+            throw error;
+        }
+        return {
+            customTitle,
+            runnerTitle,
+            runnerTitlePending,
+            pinnedAt: pinOrder === null ? null : 1,
+            pinOrder,
+            model,
+            effort,
+            access
+        };
+    }
+    listSessionRecords(workspaceId) {
+        return this.raw
+            .prepare('SELECT id, workspace_id, runner, pin_order, metadata FROM agent_sessions WHERE workspace_id = ? ORDER BY pin_order IS NULL, pin_order, id')
+            .all(workspaceId).map((row) => ({
+            id: stringValue(row, 'id'),
+            workspaceId: stringValue(row, 'workspace_id'),
+            runner: stringValue(row, 'runner'),
+            pinOrder: nullableNumber(row, 'pin_order'),
+            metadata: {
+                ...sessionMetadata(row),
+                pinnedAt: row['pin_order'] === null ? null : 1,
+                pinOrder: nullableNumber(row, 'pin_order')
+            }
+        }));
+    }
+    movePinnedSession(sessionId, direction) {
+        const current = this.raw
+            .prepare('SELECT workspace_id, pin_order FROM agent_sessions WHERE id = ?')
+            .get(sessionId);
+        if (current === undefined || current['pin_order'] === null)
+            throw new Error('SESSION_NOT_PINNED');
+        const order = numberValue(current, 'pin_order');
+        const adjacent = this.raw
+            .prepare(direction === 'up'
+            ? 'SELECT id, pin_order FROM agent_sessions WHERE workspace_id = ? AND pin_order < ? ORDER BY pin_order DESC LIMIT 1'
+            : 'SELECT id, pin_order FROM agent_sessions WHERE workspace_id = ? AND pin_order > ? ORDER BY pin_order ASC LIMIT 1')
+            .get(stringValue(current, 'workspace_id'), order);
+        if (adjacent === undefined)
+            return;
+        this.raw.exec('BEGIN IMMEDIATE');
+        try {
+            this.raw
+                .prepare('UPDATE agent_sessions SET pin_order = ? WHERE id = ?')
+                .run(order, stringValue(adjacent, 'id'));
+            this.raw
+                .prepare('UPDATE agent_sessions SET pin_order = ? WHERE id = ?')
+                .run(numberValue(adjacent, 'pin_order'), sessionId);
+            this.raw.exec('COMMIT');
+        }
+        catch (error) {
+            this.raw.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    deleteSessionRecord(sessionId) {
+        return (Number(this.raw.prepare('DELETE FROM agent_sessions WHERE id = ?').run(sessionId).changes) > 0);
     }
     /**
      * Replaces only transcript-derived, run-less history. Managed Run turns are
@@ -319,7 +403,7 @@ export class NodeDatabase {
             }
             const runnerTitle = history.title?.trim().slice(0, 160) || current.runnerTitle;
             this.raw
-                .prepare(`UPDATE agent_sessions
+                .prepare(`UPDATE legacy_agent_sessions
            SET runner_title = ?, title_source = CASE WHEN custom_title IS NULL THEN 'RUNNER' ELSE title_source END,
                last_activity_at = CASE WHEN ? > last_activity_at THEN ? ELSE last_activity_at END, updated_at = ?
            WHERE id = ?`)
@@ -409,7 +493,7 @@ export class NodeDatabase {
             }), value.createdAt, value.createdAt, value.createdAt, value.createdAt);
             this.recordConversationItemChange(value.sessionId, userItemId, 0);
             this.raw
-                .prepare('UPDATE agent_sessions SET last_activity_at = ?, updated_at = ? WHERE id = ?')
+                .prepare('UPDATE legacy_agent_sessions SET last_activity_at = ?, updated_at = ? WHERE id = ?')
                 .run(value.createdAt, value.createdAt, value.sessionId);
             this.recordWorkspaceActivity(value.workspaceId, 'run.created', {
                 runId: value.id,
@@ -909,210 +993,171 @@ export class NodeDatabase {
             }
         }
         this.raw
-            .prepare('UPDATE agent_sessions SET last_activity_at = ?, updated_at = ? WHERE id = ?')
+            .prepare('UPDATE legacy_agent_sessions SET last_activity_at = ?, updated_at = ? WHERE id = ?')
             .run(timestamp, timestamp, sessionId);
     }
     nodeIdProvider;
 }
 function migrate(database) {
-    database.exec(`CREATE TABLE IF NOT EXISTS node_schema_migrations (version INTEGER PRIMARY KEY, applied_at INTEGER NOT NULL) STRICT;
-     CREATE TABLE IF NOT EXISTS workspaces (
-       id TEXT PRIMARY KEY, path TEXT NOT NULL UNIQUE, kind TEXT NOT NULL CHECK (kind IN ('DIRECTORY', 'GIT_WORKSPACE')),
-       git_summary TEXT,
-       created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
-     ) STRICT;
-     CREATE TABLE IF NOT EXISTS agent_sessions (
-       id TEXT PRIMARY KEY, workspace_id TEXT NOT NULL REFERENCES workspaces(id),
-       runner TEXT NOT NULL CHECK (runner IN ('codex', 'claude-code')), external_session_id TEXT,
-       native_control TEXT NOT NULL DEFAULT 'EXTERNAL' CHECK (native_control IN ('MAR_MANAGED', 'EXTERNAL')), channel_token TEXT,
-       cwd TEXT NOT NULL, model TEXT, effort TEXT, access TEXT, custom_title TEXT, runner_title TEXT, pinned_at INTEGER,
-       title_source TEXT NOT NULL DEFAULT 'AUTO' CHECK (title_source IN ('AUTO', 'RUNNER', 'CUSTOM')),
-       last_activity_at INTEGER NOT NULL DEFAULT 0, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
-     ) STRICT;
-     CREATE TABLE IF NOT EXISTS native_session_checkpoints (
-       session_id TEXT PRIMARY KEY REFERENCES agent_sessions(id) ON DELETE CASCADE,
-       digest TEXT NOT NULL, updated_at INTEGER NOT NULL
-     ) STRICT;
-     CREATE TABLE IF NOT EXISTS native_session_metadata (
-       runner TEXT NOT NULL CHECK (runner IN ('codex', 'claude-code')),
-       external_session_id TEXT NOT NULL, workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
-       custom_title TEXT, runner_title TEXT, runner_title_pending INTEGER NOT NULL DEFAULT 0 CHECK (runner_title_pending IN (0, 1)), pinned_at INTEGER,
-       model TEXT, effort TEXT, access TEXT, updated_at INTEGER NOT NULL,
-       PRIMARY KEY (runner, external_session_id, workspace_id)
-     ) STRICT;
-     CREATE TABLE IF NOT EXISTS session_messages (
-       id TEXT PRIMARY KEY, session_id TEXT NOT NULL REFERENCES agent_sessions(id) ON DELETE CASCADE,
-       client_message_id TEXT NOT NULL, role TEXT NOT NULL CHECK (role IN ('USER', 'ASSISTANT', 'SYSTEM')),
-       content TEXT NOT NULL, created_at INTEGER NOT NULL, UNIQUE(session_id, client_message_id)
-     ) STRICT;
-     CREATE TABLE IF NOT EXISTS message_attachments (
-       id TEXT PRIMARY KEY, message_id TEXT NOT NULL REFERENCES session_messages(id) ON DELETE CASCADE,
-       name TEXT NOT NULL, mime TEXT NOT NULL, byte_size INTEGER NOT NULL CHECK (byte_size >= 0),
-       data BLOB NOT NULL, created_at INTEGER NOT NULL
-     ) STRICT;
-     CREATE TABLE IF NOT EXISTS agent_runs (
-       id TEXT PRIMARY KEY, session_id TEXT NOT NULL REFERENCES agent_sessions(id) ON DELETE CASCADE,
-       message_id TEXT NOT NULL UNIQUE REFERENCES session_messages(id) ON DELETE CASCADE,
-       workspace_id TEXT NOT NULL REFERENCES workspaces(id), runner TEXT NOT NULL CHECK (runner IN ('codex', 'claude-code')),
-       status TEXT NOT NULL CHECK (status IN ('QUEUED', 'STARTING', 'RUNNING', 'CANCELLING', 'SUCCEEDED', 'FAILED', 'CANCELLED', 'INTERRUPTED')),
-       recovery_state TEXT NOT NULL CHECK (recovery_state IN ('ACTIVE', 'SUSPECT', 'LOST')),
-       recovery_updated_at INTEGER NOT NULL DEFAULT 0, version INTEGER NOT NULL CHECK (version >= 0),
-       created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
-     ) STRICT;
-     CREATE TABLE IF NOT EXISTS run_events (
-       id INTEGER PRIMARY KEY, run_id TEXT NOT NULL REFERENCES agent_runs(id) ON DELETE CASCADE,
-       sequence INTEGER NOT NULL CHECK (sequence > 0), event_type TEXT NOT NULL, payload TEXT NOT NULL,
-       created_at INTEGER NOT NULL, UNIQUE(run_id, sequence)
-     ) STRICT;
-     CREATE TABLE IF NOT EXISTS conversation_turns (
-       id TEXT PRIMARY KEY, session_id TEXT NOT NULL REFERENCES agent_sessions(id) ON DELETE CASCADE,
-       run_id TEXT UNIQUE REFERENCES agent_runs(id) ON DELETE SET NULL, user_item_id TEXT,
-       status TEXT NOT NULL, model TEXT, effort TEXT, access TEXT,
-       started_at INTEGER, completed_at INTEGER, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
-     ) STRICT;
-     CREATE TABLE IF NOT EXISTS conversation_items (
-       id TEXT PRIMARY KEY, session_id TEXT NOT NULL REFERENCES agent_sessions(id) ON DELETE CASCADE,
-       turn_id TEXT NOT NULL REFERENCES conversation_turns(id) ON DELETE CASCADE,
-       run_id TEXT REFERENCES agent_runs(id) ON DELETE SET NULL, parent_item_id TEXT,
-       source_sequence INTEGER, revision INTEGER NOT NULL CHECK (revision >= 0), kind TEXT NOT NULL,
-       status TEXT NOT NULL, payload TEXT NOT NULL, started_at INTEGER, completed_at INTEGER,
-       created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, UNIQUE(turn_id, id)
-     ) STRICT;
-     CREATE TABLE IF NOT EXISTS conversation_item_events (
-       id INTEGER PRIMARY KEY, session_id TEXT NOT NULL REFERENCES agent_sessions(id) ON DELETE CASCADE,
-       item_id TEXT NOT NULL REFERENCES conversation_items(id) ON DELETE CASCADE,
-       revision INTEGER NOT NULL CHECK (revision >= 0), created_at INTEGER NOT NULL
-     ) STRICT;
-     CREATE TABLE IF NOT EXISTS workspace_activity_events (
-       id INTEGER PRIMARY KEY, workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
-       event_type TEXT NOT NULL, payload TEXT NOT NULL, created_at INTEGER NOT NULL
-     ) STRICT;
-     CREATE TABLE IF NOT EXISTS approvals (
-       id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES agent_runs(id) ON DELETE CASCADE,
-       status TEXT NOT NULL CHECK (status IN ('PENDING', 'APPROVED', 'REJECTED', 'EXPIRED')), payload TEXT NOT NULL,
-       expires_at INTEGER NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, decided_at INTEGER
-     ) STRICT;
-     CREATE TABLE IF NOT EXISTS workspace_leases (
-       id TEXT PRIMARY KEY, workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
-       run_id TEXT NOT NULL UNIQUE REFERENCES agent_runs(id) ON DELETE CASCADE,
-       state TEXT NOT NULL CHECK (state IN ('ACTIVE', 'SUSPECT', 'RELEASED')), created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
-     ) STRICT;
-     CREATE UNIQUE INDEX IF NOT EXISTS workspace_leases_active_workspace_idx
-       ON workspace_leases(workspace_id) WHERE state IN ('ACTIVE', 'SUSPECT');
-     CREATE TABLE IF NOT EXISTS run_snapshots (
-       run_id TEXT PRIMARY KEY REFERENCES agent_runs(id) ON DELETE CASCADE, snapshot TEXT NOT NULL, created_at INTEGER NOT NULL
-     ) STRICT;
-     CREATE TABLE IF NOT EXISTS terminal_sessions (
-       id TEXT PRIMARY KEY, workspace_id TEXT REFERENCES workspaces(id) ON DELETE SET NULL, profile_id TEXT NOT NULL,
-       state TEXT NOT NULL CHECK (state IN ('RUNNING', 'EXITED', 'CLOSED')),
-       exit_code INTEGER, rows INTEGER NOT NULL CHECK (rows > 0 AND rows <= 1000),
-       cols INTEGER NOT NULL CHECK (cols > 0 AND cols <= 1000),
-       latest_sequence INTEGER NOT NULL CHECK (latest_sequence >= 0),
-       created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
-     ) STRICT;
-     CREATE TABLE IF NOT EXISTS runner_defaults (
-       runner TEXT PRIMARY KEY CHECK (runner IN ('codex', 'claude-code')),
-       model TEXT NOT NULL, effort TEXT NOT NULL, access TEXT NOT NULL
-     ) STRICT;
-     CREATE INDEX IF NOT EXISTS agent_runs_session_idx ON agent_runs(session_id, created_at);
-     CREATE INDEX IF NOT EXISTS run_events_cursor_idx ON run_events(run_id, sequence);
-     CREATE INDEX IF NOT EXISTS conversation_turns_session_idx ON conversation_turns(session_id, created_at, id);
-     CREATE INDEX IF NOT EXISTS conversation_items_turn_idx ON conversation_items(turn_id, source_sequence);
-     CREATE INDEX IF NOT EXISTS conversation_items_session_cursor_idx ON conversation_items(session_id, updated_at, id);
-     CREATE INDEX IF NOT EXISTS conversation_item_events_session_cursor_idx ON conversation_item_events(session_id, id);
-     CREATE INDEX IF NOT EXISTS workspace_activity_cursor_idx ON workspace_activity_events(workspace_id, id);`);
-    database.exec('DROP TABLE IF EXISTS run_change_snapshots');
-    const workspaceColumns = database
-        .prepare('PRAGMA table_info(workspaces)')
-        .all();
-    // A short-lived legacy schema required this field without a default. The
-    // current Workspace model has no sharing flag, so retaining it would reject
-    // every subsequent registration performed by the current INSERT statement.
-    if (workspaceColumns.some((column) => column['name'] === 'share_allowed'))
-        database.exec('ALTER TABLE workspaces DROP COLUMN share_allowed');
-    const nativeMetadataColumns = database
-        .prepare('PRAGMA table_info(native_session_metadata)')
-        .all();
-    if (!nativeMetadataColumns.some((column) => column['name'] === 'runner_title'))
-        database.exec('ALTER TABLE native_session_metadata ADD COLUMN runner_title TEXT');
-    if (!nativeMetadataColumns.some((column) => column['name'] === 'runner_title_pending'))
-        database.exec('ALTER TABLE native_session_metadata ADD COLUMN runner_title_pending INTEGER NOT NULL DEFAULT 0 CHECK (runner_title_pending IN (0, 1))');
-    for (const column of ['model', 'effort', 'access']) {
-        if (!nativeMetadataColumns.some((value) => value['name'] === column))
-            database.exec(`ALTER TABLE native_session_metadata ADD COLUMN ${column} TEXT`);
-    }
-    const runnerDefaultColumns = database
-        .prepare('PRAGMA table_info(runner_defaults)')
-        .all();
-    if (runnerDefaultColumns.some((column) => column['name'] === 'singleton')) {
-        database.exec(`BEGIN IMMEDIATE;
-       CREATE TABLE runner_defaults_next (
-         runner TEXT PRIMARY KEY CHECK (runner IN ('codex', 'claude-code')),
-         model TEXT NOT NULL, effort TEXT NOT NULL, access TEXT NOT NULL
-       ) STRICT;
-       INSERT INTO runner_defaults_next (runner, model, effort, access)
-         SELECT runner, model, effort, access FROM runner_defaults;
-       DROP TABLE runner_defaults;
-       ALTER TABLE runner_defaults_next RENAME TO runner_defaults;
-       COMMIT;`);
-    }
-    const columns = database.prepare('PRAGMA table_info(agent_sessions)').all();
-    if (!columns.some((column) => column['name'] === 'native_control')) {
-        // Existing databases cannot prove how an old native ID was obtained.  The
-        // safe migration is therefore OBSERVE_ONLY until the user creates or
-        // resumes it through this Node again.
-        database.exec("ALTER TABLE agent_sessions ADD COLUMN native_control TEXT NOT NULL DEFAULT 'EXTERNAL' CHECK (native_control IN ('MAR_MANAGED', 'EXTERNAL'))");
-    }
-    if (!columns.some((column) => column['name'] === 'custom_title')) {
-        database.exec('ALTER TABLE agent_sessions ADD COLUMN custom_title TEXT');
-    }
-    if (!columns.some((column) => column['name'] === 'runner_title')) {
-        database.exec('ALTER TABLE agent_sessions ADD COLUMN runner_title TEXT');
-    }
-    if (!columns.some((column) => column['name'] === 'pinned_at')) {
-        database.exec('ALTER TABLE agent_sessions ADD COLUMN pinned_at INTEGER');
-    }
-    if (!columns.some((column) => column['name'] === 'title_source')) {
-        database.exec("ALTER TABLE agent_sessions ADD COLUMN title_source TEXT NOT NULL DEFAULT 'AUTO'");
-    }
-    if (!columns.some((column) => column['name'] === 'last_activity_at')) {
-        database.exec('ALTER TABLE agent_sessions ADD COLUMN last_activity_at INTEGER NOT NULL DEFAULT 0');
-    }
-    for (const column of ['model', 'effort', 'access']) {
-        if (!columns.some((value) => value['name'] === column)) {
-            database.exec(`ALTER TABLE agent_sessions ADD COLUMN ${column} TEXT`);
+    const existingApplicationTables = database
+        .prepare("SELECT COUNT(*) AS count FROM sqlite_master WHERE type = 'table' AND name IN ('workspaces', 'agent_sessions', 'runner_defaults')")
+        .get();
+    const existingMigrationTable = database
+        .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'node_schema_migrations'")
+        .get();
+    const existingMigrationRows = existingMigrationTable === undefined
+        ? 0
+        : numberValue(database.prepare('SELECT COUNT(*) AS count FROM node_schema_migrations').get(), 'count');
+    let currentUnversionedSchema = false;
+    if (numberValue(existingApplicationTables, 'count') > 0 && existingMigrationRows === 0) {
+        try {
+            assertNodeSchemaV2(database);
+            currentUnversionedSchema = true;
+        }
+        catch {
+            assertNodeSchema(database);
+        }
+    }
+    if (currentUnversionedSchema) {
+        database.exec('BEGIN IMMEDIATE');
+        try {
+            database
+                .prepare('INSERT INTO node_schema_migrations (version, applied_at) VALUES (?, ?), (?, ?)')
+                .run(1, Date.now(), 2, Date.now());
+            database.exec('COMMIT');
+            return;
+        }
+        catch (error) {
+            database.exec('ROLLBACK');
+            throw error;
         }
     }
-    // Pre-existing projections did not retain a detail cursor stream. Seed one
-    // final snapshot event per item; native runner payload is never reconstructed.
-    database.exec(`INSERT INTO conversation_item_events (session_id, item_id, revision, created_at)
-     SELECT ci.session_id, ci.id, ci.revision, ci.updated_at
-     FROM conversation_items ci
-     WHERE NOT EXISTS (
-       SELECT 1 FROM conversation_item_events cie WHERE cie.item_id = ci.id
-     )`);
-    const terminalColumns = database
-        .prepare('PRAGMA table_info(terminal_sessions)')
+    if (numberValue(existingApplicationTables, 'count') === 0)
+        database.exec(NODE_SCHEMA_V1);
+    const migrations = database
+        .prepare('SELECT version FROM node_schema_migrations ORDER BY version')
         .all();
-    if (!terminalColumns.some((column) => column['name'] === 'workspace_id')) {
-        database.exec('ALTER TABLE terminal_sessions ADD COLUMN workspace_id TEXT REFERENCES workspaces(id) ON DELETE SET NULL');
+    const versions = migrations.map((row) => numberValue(row, 'version'));
+    const current = versions.at(-1) ?? 0;
+    if (versions.some((version) => version > NODE_SCHEMA_VERSION))
+        throw new Error('NODE_DATABASE_VERSION_UNSUPPORTED');
+    if (versions.some((version, index) => version !== index + 1))
+        throw new Error('NODE_DATABASE_MIGRATION_HISTORY_INVALID');
+    const hasApplicationTables = database
+        .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name IN ('workspaces', 'agent_sessions', 'runner_defaults') LIMIT 1")
+        .get();
+    if (current === 0 && hasApplicationTables !== undefined) {
+        assertNodeSchema(database);
+        database.exec('BEGIN IMMEDIATE');
+        try {
+            database
+                .prepare('INSERT INTO node_schema_migrations (version, applied_at) VALUES (?, ?)')
+                .run(1, Date.now());
+            database.exec('COMMIT');
+        }
+        catch (error) {
+            database.exec('ROLLBACK');
+            throw error;
+        }
+        migrateNodeSchemaV2(database);
+        assertNodeSchemaV2(database);
+        return;
+    }
+    if (current === 0) {
+        database.exec('BEGIN IMMEDIATE');
+        try {
+            database.exec('CREATE TABLE IF NOT EXISTS node_schema_migrations (version INTEGER PRIMARY KEY, applied_at INTEGER NOT NULL) STRICT');
+            database
+                .prepare('INSERT INTO node_schema_migrations (version, applied_at) VALUES (?, ?)')
+                .run(1, Date.now());
+            database.exec('COMMIT');
+        }
+        catch (error) {
+            database.exec('ROLLBACK');
+            throw error;
+        }
     }
-    const approvalDefinition = database
-        .prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'approvals'")
+    const afterBaseline = database
+        .prepare('SELECT MAX(version) AS version FROM node_schema_migrations')
         .get();
-    if (approvalDefinition !== undefined &&
-        !stringValue(approvalDefinition, 'sql').includes("'EXPIRED'")) {
-        database.exec(`BEGIN IMMEDIATE;
-       CREATE TABLE approvals_next (
-         id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES agent_runs(id) ON DELETE CASCADE,
-         status TEXT NOT NULL CHECK (status IN ('PENDING', 'APPROVED', 'REJECTED', 'EXPIRED')), payload TEXT NOT NULL,
-         expires_at INTEGER NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, decided_at INTEGER
-       ) STRICT;
-       INSERT INTO approvals_next (id, run_id, status, payload, expires_at, created_at, updated_at, decided_at)
-         SELECT id, run_id, status, payload, expires_at, created_at, updated_at, decided_at FROM approvals;
-       DROP TABLE approvals;
-       ALTER TABLE approvals_next RENAME TO approvals;
-       COMMIT;`);
+    if (numberValue(afterBaseline, 'version') === 1)
+        migrateNodeSchemaV2(database);
+    if (NODE_SCHEMA_VERSION === 2) {
+        assertNodeSchemaV2(database);
+    }
+    else {
+        assertNodeSchema(database);
+    }
+}
+function sessionMetadata(row) {
+    const raw = JSON.parse(stringValue(row, 'metadata'));
+    if (raw['version'] !== 1)
+        throw new Error('SESSION_METADATA_VERSION_UNSUPPORTED');
+    const value = (key) => typeof raw[key] === 'string' ? raw[key] : null;
+    return {
+        customTitle: value('customTitle'),
+        runnerTitle: value('runnerTitle'),
+        runnerTitlePending: raw['runnerTitlePending'] === true,
+        model: value('model'),
+        effort: value('effort'),
+        access: value('access')
+    };
+}
+/**
+ * Legacy database helpers are still used by focused lifecycle tests, but the
+ * product runtime lives in NodeRuntimeState. Keep those helpers explicitly
+ * process-local so no Session/Run/Conversation state reaches the Node file.
+ */
+function initializeEphemeralRuntimeTables(database) {
+    const runtimeTables = new Set([
+        'agent_sessions',
+        'native_session_checkpoints',
+        'session_messages',
+        'message_attachments',
+        'agent_runs',
+        'run_events',
+        'conversation_turns',
+        'conversation_items',
+        'conversation_item_events',
+        'workspace_activity_events',
+        'approvals',
+        'workspace_leases',
+        'run_snapshots'
+    ]);
+    for (const raw of NODE_SCHEMA_V1.split(';')) {
+        const statement = raw.trim();
+        const match = statement.match(/^CREATE TABLE IF NOT EXISTS ([a-z_]+)/);
+        if (match === null || !runtimeTables.has(match[1] ?? ''))
+            continue;
+        database.exec(statement
+            .replace(/^CREATE TABLE IF NOT EXISTS/, 'CREATE TEMP TABLE IF NOT EXISTS')
+            .replace('CREATE TEMP TABLE IF NOT EXISTS agent_sessions', 'CREATE TEMP TABLE IF NOT EXISTS legacy_agent_sessions')
+            .replaceAll('REFERENCES agent_sessions', 'REFERENCES legacy_agent_sessions')
+            .replaceAll(/ REFERENCES workspaces\(id\)(?: ON DELETE (?:CASCADE|SET NULL))?/g, '') + ';');
+    }
+    database.exec(`CREATE UNIQUE INDEX IF NOT EXISTS temp.workspace_leases_active_workspace_idx
+       ON workspace_leases(workspace_id) WHERE state IN ('ACTIVE', 'SUSPECT')`);
+}
+function acquireNodeMigrationLock(databasePath) {
+    if (databasePath === ':memory:')
+        return () => undefined;
+    const lockPath = `${databasePath}.migration.lock`;
+    const deadline = Date.now() + 5_000;
+    while (true) {
+        try {
+            const descriptor = openSync(lockPath, 'wx', 0o600);
+            return () => {
+                closeSync(descriptor);
+                if (existsSync(lockPath))
+                    rmSync(lockPath);
+            };
+        }
+        catch (error) {
+            const code = error instanceof Error && 'code' in error ? error.code : undefined;
+            if (code !== 'EEXIST' || Date.now() >= deadline)
+                throw new Error('NODE_DATABASE_MIGRATION_LOCK_UNAVAILABLE');
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+        }
     }
 }
 function workspace(row) {