remcodex 0.1.0-beta.10 → 0.1.0-beta.11

package/README.md

@@ -1,104 +1,45 @@
-# 🚀 RemCodex
+# RemCodex
 
-> Remote control for Codex.  
-> From your browser and phone.
+> Control Codex from anywhere. Even on your phone.
 
-Run Codex on one machine.  
-Monitor, approve, and control the same session from another.
+RemCodex is a local-first web UI for running, reviewing, approving, and resuming Codex sessions from your browser.
 
-🌐 https://remcodex.com
+It is built for the real workflow: long-running sessions, mobile check-ins, approval prompts, imported rollout history, and timeline-style execution flow.
 
-> Not a remote desktop. Not a proxy.  
-> A local-first way to control Codex away from the terminal.
+- Watch live Codex runs without staying in the terminal
+- Approve sensitive actions from a cleaner UI
+- Pick up the same session again after refresh, sleep, or reconnect
 
-![RemCodex hero cover](docs/assets/hero-cover.png)
+## Status
 
----
+This project is currently a **beta / developer preview**.
 
-## ✨ What is RemCodex?
+It is already usable for local and internal workflows, but it is not yet packaged as a one-click desktop app.
 
-RemCodex is **remote control for Codex**.
+## Why People Use It
 
-It lets you start Codex on one machine, then keep the same session visible,
-interruptible, and controllable from another.
+Codex is powerful in the terminal, but many real workflows need a better control surface:
 
-- 👀 See what the AI is doing — in real time
-- ✅ Approve or reject actions before execution
-- ⏹ Interrupt or stop at any moment
-- 📱 Access your session from any device
-- 🔄 Sessions don’t break — they resume
+- checking progress from your phone
+- watching a long run without babysitting a terminal window
+- approving writes from a cleaner interface
+- reopening a session after refresh, sleep, or reconnect
+- reviewing imported rollout history next to native sessions
 
-> One session. Any device.
+RemCodex turns Codex's event stream into a browser-based workspace that is easier to follow, easier to resume, and easier to operate.
 
----
+## What It Does
 
-## 🎬 A real workflow
+- Run Codex sessions from a browser
+- View sessions in a single-page workspace with a sidebar and execution timeline
+- Follow streaming assistant output, commands, patches, and approvals
+- Approve or reject file-system actions from the UI
+- Import existing Codex rollout sessions from `~/.codex/sessions/...`
+- Keep imported sessions in sync while they are still active
+- Resume stale sessions after the page comes back from background
+- Work well on desktop and on mobile
 
-You start a long Codex session on your machine.
-
-Then you leave your desk.
-
-On your phone:
-
-- you see progress in real time
-- you receive an approval request
-- you approve it
-
-The session continues instantly.
-
-> Everything else can disconnect — your session won’t.
-
----
-
-## 🔥 Why RemCodex exists
-
-AI coding agents are powerful.  
-But today, they run like a black box.
-
-You either:
-
-- trust everything blindly
-- or sit in front of your terminal watching it
-
-RemCodex fixes that.
-
-> AI is no longer a black box.
-
----
-
-## ⚡ What it does
-
-- Real-time execution timeline (messages, commands, approvals)
-- Human-in-the-loop command approval
-- Multi-device access to the same live session
-- Resume after refresh, sleep, or reconnect
-- Browser-based UI — **no extra client required**
-- Works with Codex CLI
-
-> No extra client install. Just open a browser.  
-> Your code never leaves your machine.
-
----
-
-## 🚀 Quick start
-
-```bash
-npx remcodex
-```
-
-Then open:
-
-http://127.0.0.1:18840
-
-Access from another device:
-
-http://<your-ip>:18840
-
-> Runs entirely on your local machine. No cloud, no data upload.
-
----
-
-## 🖥 Screenshots
+## Screenshots
 
 ![RemCodex desktop workspace](docs/assets/hero-desktop.png)
 
@@ -114,203 +55,268 @@ http://<your-ip>:18840
 
 ![RemCodex imported Codex session](docs/assets/imported-session.png)
 
-> Bring imported Codex rollouts into the same workspace.
+> Bring imported Codex rollouts into the same workspace and keep them easy to review.
 
----
+## Who It Is For
 
-## 🧠 What it actually is
+- developers who already use Codex locally
+- people who want a browser-based control surface instead of raw terminal watching
+- teams who want to review or monitor runs from another device on the same network
+- anyone who wants approvals, timeline view, and imported rollout history in one place
 
-RemCodex is a **browser-based workspace for Codex sessions**.
+## Screens It Aims To Replace
 
-It is built for real workflows:
+- terminal-only session watching
+- ad-hoc mobile remote desktop checks
+- raw log scrolling for approvals and command progress
+- fragmented session history between local and imported rollouts
 
-- long-running sessions
-- mobile check-ins
-- approval prompts
-- imported rollout history
-- timeline-style execution flow
-
-Instead of raw terminal logs, you get a structured, visual timeline you can follow and control.
-
----
-
-## 🧩 Current product shape
+## Current Product Shape
 
 - Single-page workspace UI
 - Left sidebar for session navigation
-- Right-side execution timeline
-- Fixed input composer
+- Right-side timeline / execution flow for the active session
+- Fixed composer at the bottom
 - Semantic timeline rendering for:
-    - user messages
-    - assistant output
-    - thinking
-    - commands
-    - patches
-    - approvals
-    - system events
-
----
+  - user messages
+  - assistant commentary / final messages
+  - thinking
+  - commands
+  - patches
+  - approvals
+  - system events
 
-## ⚙️ Key behaviors
+## Tech Stack
 
-### Approvals
+- Backend: Node.js + TypeScript + Express + WebSocket
+- Database: SQLite via `better-sqlite3`
+- Terminal/runtime integration: `node-pty` + Codex app-server
+- Frontend: zero-build static web app (`web/`)
+- Markdown rendering: `markdown-it`
 
-- Writes inside working area → auto allowed
-- Writes outside → require approval
-- `Allow once` / `Allow for this turn` supported
-- Approval history stays visible in timeline
+## Requirements
 
----
+Before running this project, you should have:
 
-### Timeline
+- Node.js 20.x installed
+- Codex CLI installed and already working locally
+- A machine where this app can access your local Codex data and working directories
 
-- Semantic rendering (not raw logs)
-- Commands grouped into readable activity blocks
-- Running / failed states clearly visible
-- Smooth streaming + recovery after refresh
+This project is currently developed primarily around a local macOS workflow.
 
----
+## Quick Start
 
-### Imported sessions
+For the current developer preview, the recommended local install path is:
 
-- Import from `~/.codex/sessions/...`
-- Keep syncing if still active
-- Unified view with native sessions
+```bash
+npm install
+npm run build
+npm link
+remcodex start
+```
 
----
+If you switch Node.js versions later, reinstall dependencies and relink or reinstall `remcodex`.
 
-## 🧠 Architecture
+Then open:
 
-```
-Codex CLI → Event stream → Semantic layer → Timeline → Web UI
+```text
+http://127.0.0.1:3000
 ```
 
----
+If you want to make it reachable from your phone, expose the local machine on your LAN and open the same URL with your host IP.
 
-## ⚙️ Requirements
+## Local CLI
 
-- Node.js
-- Codex CLI (already working locally)
+RemCodex already ships with a local CLI entrypoint, even though the npm package is not published yet.
 
----
+If you do not want to run `npm link`, you can call the built CLI directly:
 
-## ⚙️ Configuration
+```bash
+node dist/server/src/cli.js start --no-open
+```
 
-Default port: **18840**
+Useful commands:
 
 ```bash
-PORT=18841 npx remcodex
+node dist/server/src/cli.js doctor
+node dist/server/src/cli.js start --no-open
+node dist/server/src/cli.js version
 ```
 
----
+Published package note:
 
-## 📦 Install FAQ
+- the npm package currently expects Node.js 20.x
+- if `better-sqlite3` or `node-pty` reports a native module / `NODE_MODULE_VERSION` error, reinstall `remcodex` under the same Node.js version you will use to run it
 
-### Why does `npx remcodex` hang on Linux?
+Use a specific database:
 
-First install may compile native deps:
+```bash
+node dist/server/src/cli.js start --db ~/.remcodex/remcodex-demo.db --no-open
+node dist/server/src/cli.js doctor --db ~/.remcodex/remcodex-demo.db
+```
 
-- `better-sqlite3`
-- `node-pty`
+Planned install target after the npm package is published:
 
-Make sure you have:
+```bash
+npx remcodex
+```
 
-- `python3`
-- `make`
-- `g++`
+## Development
 
----
+```bash
+npm install
+npm run dev
+```
 
-### Debug install issues
+Smoke-test the published-package shape locally:
 
 ```bash
-npm install -g remcodex
-remcodex doctor
-remcodex start
+npm run smoke:tarball
 ```
 
----
-
-### Headless mode
+Smoke-test a real isolated startup and `/health` check:
 
 ```bash
-npx remcodex --no-open
+npm run smoke:start
 ```
 
----
+## How It Works
+
+The app uses `codex app-server` as the primary runtime path.
 
-## 🔧 How it works
+At a high level:
 
-1. Codex emits events
-2. Backend stores them (SQLite)
-3. Frontend loads timeline snapshot
-4. Live updates stream via WebSocket
+1. Codex emits semantic events
+2. The backend stores them in SQLite
+3. The frontend reads an aggregated timeline view for initial load
+4. Live updates continue over WebSocket with catch-up after refresh
 
-Result:
+This gives the UI:
 
+- smooth streaming
 - recoverable sessions
-- real-time UI
-- consistent execution flow
+- imported rollout support
+- a consistent execution timeline instead of raw terminal logs
 
----
+## Key Behaviors
 
-## 📊 Status
+### Approvals
 
-- Beta / developer preview
-- Local-first architecture
-- No cloud dependency
+- Writes inside the working area usually pass directly
+- Writes outside the working area trigger approval
+- `Allow once` approves only the current request
+- `Allow for this turn` expands writable roots for the active turn
+- Historical approval records stay visible in the timeline
+- Only live approvals stay actionable in the bottom approval bar
 
----
+### Imported Codex Sessions
 
-## 🗺 Roadmap
+- Existing Codex rollouts can be imported from local session history
+- Imported sessions keep their own source metadata
+- Imported sessions can continue syncing after you open them
+- Native sessions are excluded from the import picker
 
-**Visibility**
+### Timeline and Execution Flow
 
-- fully observable execution
-- clear action timeline
+- The UI renders semantic timeline items, not raw logs
+- Commands and patches can be grouped into lighter activity summaries
+- Running and failed commands remain visually important
+- The final thinking placeholder appears only at the end of the active flow
 
-**Control**
+## Configuration
 
-- fine-grained approvals
-- safer execution
+Supported environment variables:
 
-**Continuity**
+- `PORT`
+- `DATABASE_PATH`
+- `PROJECT_ROOTS`
+- `CODEX_COMMAND`
+- `CODEX_MODE`
 
-- survive refresh / sleep
-- stable long runs
+For launch screenshots or demo data, you can rebuild a clean demo database with:
 
-**Access**
+```bash
+DATABASE_PATH="$HOME/.remcodex/remcodex-demo.db" ~/.nvm/versions/node/v20.19.5/bin/node scripts/seed-launch-demo-data.js --clean
+```
+- `REMOTE_HOSTS`
+- `ACTIVE_REMOTE_HOST`
+
+Notes:
+
+- The default runtime mode is `app-server`
+- `exec-json` is kept only as a fallback compatibility path
+- If `PROJECT_ROOTS` is not set, the app falls back to a broad local browsing root
+
+## Project Structure
+
+```text
+server/
+  src/
+    app.ts
+    controllers/
+    db/
+    gateways/
+    services/
+    types/
+    utils/
+web/
+  index.html
+  styles.css
+  api.js
+  session-ws.js
+  app.js
+scripts/
+  fix-node-pty-helper.js
+  import-codex-rollout.js
+  reset-semantic-demo-data.js
+```
 
-- control from any device
+## Main Endpoints
 
-**Integration**
+- `GET /health`
+- `GET /api/codex/mode`
+- `GET /api/codex/status`
+- `GET /api/codex/quota`
+- `GET /api/sessions`
+- `GET /api/sessions/:sessionId`
+- `GET /api/sessions/:sessionId/timeline`
+- `GET /api/sessions/:sessionId/events`
+- `POST /api/sessions`
+- `POST /api/sessions/:sessionId/messages`
+- `POST /api/sessions/:sessionId/stop`
+- `POST /api/sessions/:sessionId/approvals/:requestId`
+- `WS /ws/sessions/:sessionId`
 
-- IDE integrations
-- optional sharing
+## What Is Not Finished Yet
 
----
+This is the honest list:
 
-## 👥 Who it’s for
+- no polished installer yet
+- no desktop packaging yet
+- no full automated test suite yet
+- no production-grade auth / multi-user hardening yet
+- no release pipeline yet
 
-- developers already using Codex
-- people tired of terminal-only workflows
-- anyone who wants **control, not just output**
-- multi-device workflows
+If you are comfortable cloning a repo and running a local Node app, you can use it today.
 
----
+## Roadmap
 
-## ⚠️ What’s not finished yet
+Near-term:
 
-- no polished installer yet
-- no desktop packaging
-- no production-grade auth
-- no release pipeline
+- improve onboarding and installation
+- ship a cleaner public README and screenshots
+- add stronger regression coverage
+- harden long-running session recovery
+- continue refining the execution timeline UI
+
+Later:
 
-If you're comfortable running a local Node app —  
-you can use it today.
+- package for easier local install
+- optional sync / multi-device helpers
+- stronger sharing, auditing, and team workflows
 
----
+## License
 
-## 📄 License
+No license has been added yet.
 
-MIT License
+Until a license is added, assume this repository is **source-available for review only**, not open source for reuse.

package/dist/server/src/app.js

@@ -3,13 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_PORT = void 0;
-exports.resolvePackageRoot = resolvePackageRoot;
-exports.resolveDefaultDatabasePath = resolveDefaultDatabasePath;
 exports.startRemCodexServer = startRemCodexServer;
 const node_fs_1 = require("node:fs");
 const node_http_1 = __importDefault(require("node:http"));
-const node_os_1 = require("node:os");
 const node_path_1 = __importDefault(require("node:path"));
 const express_1 = __importDefault(require("express"));
 const codex_options_controller_1 = require("./controllers/codex-options.controller");
@@ -24,36 +20,15 @@ const codex_rollout_sync_1 = require("./services/codex-rollout-sync");
 const project_manager_1 = require("./services/project-manager");
 const session_manager_1 = require("./services/session-manager");
 const session_timeline_service_1 = require("./services/session-timeline-service");
+const runtime_paths_1 = require("./utils/runtime-paths");
 const command_1 = require("./utils/command");
 const errors_1 = require("./utils/errors");
-function isPackageRoot(root) {
-    return ((0, node_fs_1.existsSync)(node_path_1.default.join(root, "package.json")) &&
-        (0, node_fs_1.existsSync)(node_path_1.default.join(root, "web", "index.html")));
-}
-function resolvePackageRoot(startDir = __dirname) {
-    let current = node_path_1.default.resolve(startDir);
-    while (true) {
-        if (isPackageRoot(current)) {
-            return current;
-        }
-        const parent = node_path_1.default.dirname(current);
-        if (parent === current) {
-            break;
-        }
-        current = parent;
-    }
-    return process.cwd();
-}
-function resolveDefaultDatabasePath() {
-    return node_path_1.default.join((0, node_os_1.homedir)(), ".remcodex", "remcodex.db");
-}
-exports.DEFAULT_PORT = 18840;
 function buildRemCodexServer(options = {}) {
-    const repoRoot = options.repoRoot ? node_path_1.default.resolve(options.repoRoot) : resolvePackageRoot();
-    const port = options.port ?? Number.parseInt(process.env.PORT ?? String(exports.DEFAULT_PORT), 10);
+    const repoRoot = options.repoRoot ? node_path_1.default.resolve(options.repoRoot) : (0, runtime_paths_1.resolvePackageRoot)();
+    const port = options.port ?? Number.parseInt(process.env.PORT ?? "3000", 10);
     const databasePath = options.databasePath ??
         process.env.DATABASE_PATH ??
-        resolveDefaultDatabasePath();
+        (0, runtime_paths_1.resolveDefaultDatabasePath)();
     const codexCommand = (0, command_1.resolveExecutable)(options.codexCommand ?? process.env.CODEX_COMMAND ?? "codex");
     const codexMode = options.codexMode ?? (process.env.CODEX_MODE === "exec-json" ? "exec-json" : "app-server");
     const projectRootsEnv = options.projectRootsEnv ?? process.env.PROJECT_ROOTS;

package/dist/server/src/cli.js

@@ -1,5 +1,38 @@
 #!/usr/bin/env node
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -8,7 +41,7 @@ const node_fs_1 = require("node:fs");
 const node_child_process_1 = require("node:child_process");
 const node_os_1 = require("node:os");
 const node_path_1 = __importDefault(require("node:path"));
-const app_1 = require("./app");
+const runtime_paths_1 = require("./utils/runtime-paths");
 const command_1 = require("./utils/command");
 function print(message = "") {
     process.stdout.write(`${message}\n`);
@@ -18,7 +51,7 @@ function printError(message = "") {
 }
 function readPackageVersion() {
     try {
-        const packageRoot = (0, app_1.resolvePackageRoot)();
+        const packageRoot = (0, runtime_paths_1.resolvePackageRoot)();
         const packageJson = JSON.parse((0, node_fs_1.readFileSync)(node_path_1.default.join(packageRoot, "package.json"), "utf8"));
         return typeof packageJson.version === "string" ? packageJson.version : "0.0.0";
     }
@@ -123,12 +156,24 @@ function usage() {
     print("  --db <path>             Use a specific SQLite database path");
     print("  --no-open               Do not open a browser automatically");
 }
+function formatNativeModuleError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.includes("NODE_MODULE_VERSION")) {
+        return null;
+    }
+    return [
+        "Native module failed to load. This usually means RemCodex was installed with a different Node.js version.",
+        `Current Node: ${process.version}`,
+        "Reinstall remcodex with the same Node.js version you will use to run it.",
+        "If you use nvm/fnm/asdf, switch to the target Node version first, then reinstall.",
+    ].join("\n");
+}
 async function runDoctor(flags) {
     const version = readPackageVersion();
     const rawCodexCommand = process.env.CODEX_COMMAND ?? "codex";
     const codex = commandExists(rawCodexCommand);
-    const packageRoot = (0, app_1.resolvePackageRoot)();
-    const databasePath = flags.databasePath ?? process.env.DATABASE_PATH ?? (0, app_1.resolveDefaultDatabasePath)();
+    const packageRoot = (0, runtime_paths_1.resolvePackageRoot)();
+    const databasePath = flags.databasePath ?? process.env.DATABASE_PATH ?? (0, runtime_paths_1.resolveDefaultDatabasePath)();
     const databaseDir = node_path_1.default.dirname(databasePath);
     const databaseDirExists = (0, node_fs_1.existsSync)(databaseDir);
     const databaseDirWritable = databaseDirExists && (() => {
@@ -161,6 +206,18 @@ async function runDoctor(flags) {
     return 0;
 }
 async function runStart(flags) {
+    let startRemCodexServer;
+    try {
+        ({ startRemCodexServer } = await Promise.resolve().then(() => __importStar(require("./app"))));
+    }
+    catch (error) {
+        const nativeModuleMessage = formatNativeModuleError(error);
+        if (nativeModuleMessage) {
+            printError(nativeModuleMessage);
+            return 1;
+        }
+        throw error;
+    }
     const version = readPackageVersion();
     const rawCodexCommand = process.env.CODEX_COMMAND ?? "codex";
     const codex = commandExists(rawCodexCommand);
@@ -169,14 +226,14 @@ async function runStart(flags) {
         printError("Install Codex first, or set CODEX_COMMAND to the correct executable.");
         return 1;
     }
-    const preferredPort = flags.port ?? Number.parseInt(process.env.PORT ?? String(app_1.DEFAULT_PORT), 10);
+    const preferredPort = flags.port ?? Number.parseInt(process.env.PORT ?? "3000", 10);
     const codexMode = process.env.CODEX_MODE === "exec-json" ? "exec-json" : "app-server";
     let started = null;
     let activePort = preferredPort;
     for (let offset = 0; offset < 20; offset += 1) {
         const candidate = preferredPort + offset;
         try {
-            started = await (0, app_1.startRemCodexServer)({
+            started = await startRemCodexServer({
                 port: candidate,
                 databasePath: flags.databasePath,
                 codexCommand: rawCodexCommand,

package/dist/server/src/db/migrations.js

@@ -6,6 +6,35 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runMigrations = runMigrations;
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
+function isPackageRoot(root) {
+    return (0, node_fs_1.existsSync)(node_path_1.default.join(root, "package.json")) && (0, node_fs_1.existsSync)(node_path_1.default.join(root, "web", "index.html"));
+}
+function resolvePackageRoot(startDir = __dirname) {
+    let current = node_path_1.default.resolve(startDir);
+    while (true) {
+        if (isPackageRoot(current)) {
+            return current;
+        }
+        const parent = node_path_1.default.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return process.cwd();
+}
+function resolveSchemaFile() {
+    const packageRoot = resolvePackageRoot();
+    const candidates = [
+        node_path_1.default.join(packageRoot, "server", "src", "db", "schema.sql"),
+        node_path_1.default.join(packageRoot, "dist", "server", "src", "db", "schema.sql"),
+    ];
+    const resolved = candidates.find((candidate) => (0, node_fs_1.existsSync)(candidate));
+    if (!resolved) {
+        throw new Error(`Database schema file not found. Tried: ${candidates.join(", ")}`);
+    }
+    return resolved;
+}
 function ensureColumn(db, table, column, definition) {
     const rows = db.prepare(`PRAGMA table_info(${table})`).all();
     if (rows.some((row) => row.name === column)) {
@@ -14,7 +43,7 @@ function ensureColumn(db, table, column, definition) {
     db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
 }
 function runMigrations(db) {
-    const schemaFile = node_path_1.default.join(process.cwd(), "server", "src", "db", "schema.sql");
+    const schemaFile = resolveSchemaFile();
     const schema = (0, node_fs_1.readFileSync)(schemaFile, "utf8");
     db.exec(schema);
     ensureColumn(db, "sessions", "source_kind", "TEXT NOT NULL DEFAULT 'native'");

package/dist/server/src/db/schema.sql

@@ -0,0 +1,48 @@
+CREATE TABLE IF NOT EXISTS projects (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  path TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,
+  title TEXT,
+  project_id TEXT NOT NULL,
+  status TEXT NOT NULL,
+  pid INTEGER,
+  codex_thread_id TEXT,
+  source_kind TEXT NOT NULL DEFAULT 'native',
+  source_rollout_path TEXT,
+  source_thread_id TEXT,
+  source_sync_cursor INTEGER,
+  source_last_synced_at TEXT,
+  source_rollout_has_open_turn INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  FOREIGN KEY (project_id) REFERENCES projects(id)
+);
+
+CREATE TABLE IF NOT EXISTS session_events (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  turn_id TEXT,
+  seq INTEGER NOT NULL,
+  event_type TEXT NOT NULL,
+  message_id TEXT,
+  call_id TEXT,
+  request_id TEXT,
+  phase TEXT,
+  stream TEXT,
+  payload_json TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  FOREIGN KEY (session_id) REFERENCES sessions(id),
+  UNIQUE (session_id, seq)
+);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_project_id ON sessions(project_id);
+CREATE INDEX IF NOT EXISTS idx_session_events_session_seq ON session_events(session_id, seq);
+CREATE INDEX IF NOT EXISTS idx_session_events_type_seq ON session_events(session_id, event_type, seq);
+CREATE INDEX IF NOT EXISTS idx_session_events_message_id ON session_events(session_id, message_id, seq);
+CREATE INDEX IF NOT EXISTS idx_session_events_call_id ON session_events(session_id, call_id, seq);
+CREATE INDEX IF NOT EXISTS idx_session_events_request_id ON session_events(session_id, request_id, seq);

package/dist/server/src/services/session-manager.js

@@ -279,17 +279,6 @@ class SessionManager {
             seq: event.seq,
         };
     }
-    stopSession(sessionId) {
-        const runtime = this.runners.get(sessionId);
-        if (!runtime || !runtime.runner.isAlive()) {
-            this.setStatus(sessionId, "idle");
-            return { accepted: true };
-        }
-        runtime.stopRequested = true;
-        this.setStatus(sessionId, "stopping");
-        runtime.runner.stop();
-        return { accepted: true };
-    }
     retryApprovalRequest(sessionId, requestId, codexLaunch) {
         const session = this.getSessionOrThrow(sessionId);
         const project = this.options.projectManager.getProject(session.project_id);
@@ -314,6 +303,17 @@ class SessionManager {
             turnId,
         };
     }
+    stopSession(sessionId) {
+        const runtime = this.runners.get(sessionId);
+        if (!runtime || !runtime.runner.isAlive()) {
+            this.setStatus(sessionId, "idle");
+            return { accepted: true };
+        }
+        runtime.stopRequested = true;
+        this.setStatus(sessionId, "stopping");
+        runtime.runner.stop();
+        return { accepted: true };
+    }
     resolveApproval(sessionId, requestId, decision) {
         const runtime = this.runners.get(sessionId);
         if (!runtime?.runner.isAlive()) {

package/dist/server/src/utils/runtime-paths.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePackageRoot = resolvePackageRoot;
+exports.resolveDefaultDatabasePath = resolveDefaultDatabasePath;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+function isPackageRoot(root) {
+    return ((0, node_fs_1.existsSync)(node_path_1.default.join(root, "package.json")) &&
+        (0, node_fs_1.existsSync)(node_path_1.default.join(root, "web", "index.html")));
+}
+function resolvePackageRoot(startDir = __dirname) {
+    let current = node_path_1.default.resolve(startDir);
+    while (true) {
+        if (isPackageRoot(current)) {
+            return current;
+        }
+        const parent = node_path_1.default.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return process.cwd();
+}
+function resolveDefaultDatabasePath() {
+    return node_path_1.default.join((0, node_os_1.homedir)(), ".remcodex", "remcodex.db");
+}

package/package.json

@@ -1,23 +1,31 @@
 {
   "name": "remcodex",
-  "version": "0.1.0-beta.10",
+  "version": "0.1.0-beta.11",
   "description": "Control Codex from anywhere. Even on your phone.",
-  "license": "MIT",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": "20.x"
+  },
   "bin": {
     "remcodex": "dist/server/src/cli.js"
   },
   "files": [
     "dist",
     "web",
+    "scripts/check-node-version.js",
     "scripts/fix-node-pty-helper.js",
-    "README.md"
+    "README.md",
+    "docs/assets"
   ],
   "scripts": {
+    "preinstall": "node scripts/check-node-version.js",
     "postinstall": "node scripts/fix-node-pty-helper.js",
     "dev": "tsx watch server/src/app.ts",
     "start": "tsx server/src/cli.ts --no-open",
-    "build": "tsc -p tsconfig.json",
-    "cli": "tsx server/src/cli.ts --no-open"
+    "build": "tsc -p tsconfig.json && node scripts/copy-db-assets.js",
+    "cli": "tsx server/src/cli.ts --no-open",
+    "smoke:tarball": "node scripts/smoke-test-tarball.js",
+    "smoke:start": "node scripts/smoke-start-tarball.js"
   },
   "dependencies": {
     "better-sqlite3": "^11.8.1",

package/scripts/check-node-version.js

@@ -0,0 +1,14 @@
+const supportedMajor = 20;
+const currentVersion = process.versions.node;
+const currentMajor = Number.parseInt(currentVersion.split(".")[0] || "", 10);
+
+if (currentMajor !== supportedMajor) {
+  console.error(
+    [
+      `remcodex requires Node.js ${supportedMajor}.x for the published package.`,
+      `Current Node.js: ${currentVersion}`,
+      "Switch Node versions first, then reinstall remcodex so native modules are built against the same runtime.",
+    ].join("\n"),
+  );
+  process.exit(1);
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 RemCodex contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.