stagent 0.1.0 → 0.1.2

package/README.md

@@ -2,6 +2,8 @@
 
 > A governed AI agent operations workspace for running, supervising, and reusing AI work through projects, workflows, documents, profiles, schedules, inbox approvals, and live monitoring.
 
+[![Download macOS Desktop](https://img.shields.io/badge/Download-macOS_Desktop-0a7cff?style=for-the-badge&logo=apple)](https://github.com/navam-io/stagent/releases/latest/download/Stagent.dmg) [![GitHub Releases](https://img.shields.io/github/v/release/navam-io/stagent?display_name=release&style=for-the-badge)](https://github.com/navam-io/stagent/releases/latest)
+
 [![Next.js 16](https://img.shields.io/badge/Next.js-16-black)](https://nextjs.org/) [![React 19](https://img.shields.io/badge/React-19-61DAFB)](https://react.dev/) [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6)](https://www.typescriptlang.org/) [![Claude Agent SDK](https://img.shields.io/badge/Claude-Agent_SDK-D97706)](https://docs.anthropic.com/) [![OpenAI Codex App Server](https://img.shields.io/badge/OpenAI-Codex_App_Server-10A37F)](https://developers.openai.com/codex/app-server) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 
 ## Why Stagent
@@ -10,34 +12,21 @@ AI agents are powerful, but production deployment breaks down when teams cannot
 
 Stagent is a local-first AI operations workspace built around governed execution and reusable automation primitives. Instead of treating every agent run as a one-off prompt, it gives teams a structured system of home workspace signals, execution dashboards, project context, workflow blueprints, reusable profiles, schedules, documents, inbox approvals, and live monitoring.
 
-## Quick Start
+## Get Started
 
-### NPX install
+### Download Desktop for macOS
 
-Requires Node.js 20 or newer.
+**Primary install path:** [Download the latest macOS desktop release](https://github.com/navam-io/stagent/releases/latest/download/Stagent.dmg)
 
-```bash
-export ANTHROPIC_API_KEY=your-anthropic-key
-export OPENAI_API_KEY=your-openai-key
+Grab the latest `Stagent.dmg` or `Stagent.app.zip` asset from GitHub Releases, then move `Stagent.app` into `/Applications`.
 
-npx stagent
-```
+Current desktop release notes:
 
-Useful variants:
+- macOS-only for now
+- GitHub desktop releases are intended to be Developer ID signed and notarized; local smoke builds created with `npm run desktop:release -- --skip-upload` will still warn if Apple credentials are not configured
+- the current desktop wrapper expects `node` to be available on the machine
 
-```bash
-npx stagent --port 3210
-npx stagent --no-open
-npm install -g stagent && stagent
-```
-
-Stagent stores local state in `~/.stagent/` by default. To isolate a run or smoke-test the packaged app, override the data directory:
-
-```bash
-STAGENT_DATA_DIR=/tmp/stagent-smoke npx stagent --reset --no-open
-```
-
-<img src="https://unpkg.com/stagent@latest/public/readme/home-workspace.png" alt="Stagent home workspace" width="1200" />
+<img src="./output/playwright/home-playwright-after.png" alt="Stagent home workspace" width="1200" />
 
 ### Repository development
 
@@ -228,7 +217,10 @@ File upload with drag-and-drop in task creation. Type-aware content preview for
 Configuration hub with provider-aware sections: Claude authentication (API key or OAuth), OpenAI Codex runtime API-key management, tool permissions (saved "Always Allow" patterns with revoke), and data management.
 
 #### CLI
-`npx stagent` launches the dev server and opens the dashboard. Built with Commander, compiled via tsup to `dist/cli.js`. The CLI supports `--port`, `--reset`, `--no-open`, and `STAGENT_DATA_DIR` for isolated packaged runs.
+Stagent still uses a small Node sidecar under the hood. It is built from `bin/cli.ts` into `dist/cli.js`, but it is now an internal desktop bootstrap rather than a user-facing distribution channel.
+
+#### Tauri Desktop
+The repo produces macOS desktop artifacts via Tauri. Local development uses `npm run desktop:dev`, local packaging uses `npm run desktop:build`, and release publishing now runs locally via `npm run desktop:release` so the uploaded GitHub assets stay on stable names: `Stagent.dmg` and `Stagent.app.zip`. Published releases must be built with `APPLE_SIGNING_IDENTITY` plus notarization credentials so the downloaded app clears Gatekeeper without the "Apple could not verify" malware warning. Keep `public/desktop-icon-512.png` as the dedicated rounded desktop source icon with transparent corners; `public/icon-512.png` remains the square web/PWA icon. The local release script also stamps the same branded icon onto the mounted DMG volume so Finder shows the corrected Stagent icon during install.
 
 #### Database
 SQLite with WAL mode via better-sqlite3 + Drizzle ORM. Eight tables: `projects`, `tasks`, `workflows`, `agent_logs`, `notifications`, `documents`, `schedules`, `settings`. Self-healing bootstrap — tables are created on startup if missing.
@@ -261,21 +253,32 @@ Responsive sidebar with collapsible icon-only mode, custom Stagent logo, tooltip
 ```bash
 npm run dev            # Next.js dev server (Turbopack)
 npm run build:cli      # Build CLI → dist/cli.js
-npm run smoke:npm      # Pack tarball and launch the packaged CLI from a temp install
 npm test               # Run Vitest
 npm run test:coverage  # Coverage report
 ```
 
-## NPM Release Checklist
+## Desktop Release Checklist
+
+```bash
+npm run desktop:release
+```
+
+For a build-only smoke check, run `npm run desktop:release -- --skip-upload`.
+
+Before publishing a real desktop release, configure Apple signing once on the release machine:
 
 ```bash
-npm version <patch|minor|major>
-npm run build:cli
-npm run smoke:npm
-npm publish
+export APPLE_SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)"
+xcrun notarytool store-credentials stagent-notary \
+  --apple-id "you@example.com" \
+  --team-id "TEAMID" \
+  --password "app-specific-password"
+export APPLE_NOTARY_PROFILE="stagent-notary"
 ```
 
-`npm run smoke:npm` builds the CLI, creates a real npm tarball with `npm pack`, extracts it into a temporary hoisted-layout install, launches the packaged app with `--no-open`, verifies data-directory bootstrap plus server startup, and then cleans up.
+You can use direct credentials instead of a keychain profile by exporting `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, and `APPLE_TEAM_ID`.
+
+The release script builds locally on macOS, signs the app, notarizes and staples the app bundle and DMG when Apple credentials are configured, verifies the DMG, creates or updates the `desktop-v<package.json version>` GitHub release, uploads `Stagent.dmg` and `Stagent.app.zip`, and refreshes the stable download URL at `https://github.com/navam-io/stagent/releases/latest/download/Stagent.dmg`. Uploads now fail fast unless Developer ID signing and notarization are configured so unsigned artifacts are not published by accident.
 
 ### Project Structure
 

package/dist/cli.js

@@ -2,11 +2,11 @@
 
 // bin/cli.ts
 import { program } from "commander";
-import { dirname, join as join2 } from "path";
+import { dirname as dirname2, join as join3 } from "path";
 import { fileURLToPath } from "url";
 import {
   mkdirSync,
-  existsSync,
+  existsSync as existsSync2,
   readFileSync,
   writeFileSync,
   cpSync,
@@ -18,54 +18,372 @@ import Database from "better-sqlite3";
 import { drizzle } from "drizzle-orm/better-sqlite3";
 import { migrate } from "drizzle-orm/better-sqlite3/migrator";
 
+// src/lib/desktop/sidecar-launch.ts
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+var SIDECAR_LOOPBACK_HOST = "127.0.0.1";
+function wasPortExplicitlyRequested(argv) {
+  return argv.some(
+    (argument) => argument === "-p" || argument === "--port" || argument.startsWith("--port=")
+  );
+}
+async function resolveSidecarPort({
+  argv,
+  requestedPort: requestedPort2,
+  findAvailablePort: findAvailablePort2
+}) {
+  if (wasPortExplicitlyRequested(argv)) {
+    return requestedPort2;
+  }
+  return findAvailablePort2(requestedPort2);
+}
+function findClosestPath(cwd, segments, exists = existsSync) {
+  let dir = cwd;
+  while (true) {
+    const candidate = join(dir, ...segments);
+    if (exists(candidate)) {
+      return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+}
+function resolveNextEntrypoint(cwd, exists = existsSync) {
+  const nextEntrypoint = findClosestPath(cwd, ["node_modules", "next", "dist", "bin", "next"], exists);
+  if (nextEntrypoint) {
+    return nextEntrypoint;
+  }
+  throw new Error(
+    `Could not resolve Next.js CLI entrypoint from ${cwd}. Expected node_modules/next/dist/bin/next.`
+  );
+}
+function buildNextLaunchArgs({
+  isPrebuilt,
+  port,
+  host = SIDECAR_LOOPBACK_HOST
+}) {
+  if (isPrebuilt) {
+    return ["start", "--hostname", host, "--port", String(port)];
+  }
+  return ["dev", "--turbopack", "--hostname", host, "--port", String(port)];
+}
+function buildSidecarUrl(port, host = SIDECAR_LOOPBACK_HOST) {
+  return `http://${host}:${port}`;
+}
+
 // src/lib/utils/stagent-paths.ts
 import { homedir } from "os";
-import { join } from "path";
+import { join as join2 } from "path";
 function getStagentDataDir() {
-  return process.env.STAGENT_DATA_DIR || join(homedir(), ".stagent");
+  return process.env.STAGENT_DATA_DIR || join2(homedir(), ".stagent");
 }
 function getStagentDbPath() {
-  return join(getStagentDataDir(), "stagent.db");
+  return join2(getStagentDataDir(), "stagent.db");
+}
+
+// src/lib/db/bootstrap.ts
+import { readMigrationFiles } from "drizzle-orm/migrator";
+var STAGENT_TABLES = [
+  "projects",
+  "tasks",
+  "workflows",
+  "agent_logs",
+  "notifications",
+  "settings",
+  "documents",
+  "schedules",
+  "usage_ledger",
+  "learned_context"
+];
+function bootstrapStagentDatabase(sqlite2) {
+  sqlite2.exec(`
+    CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY NOT NULL,
+      name TEXT NOT NULL,
+      description TEXT,
+      status TEXT DEFAULT 'active' NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS tasks (
+      id TEXT PRIMARY KEY NOT NULL,
+      project_id TEXT,
+      workflow_id TEXT,
+      schedule_id TEXT,
+      title TEXT NOT NULL,
+      description TEXT,
+      status TEXT DEFAULT 'planned' NOT NULL,
+      assigned_agent TEXT,
+      agent_profile TEXT,
+      priority INTEGER DEFAULT 2 NOT NULL,
+      result TEXT,
+      session_id TEXT,
+      resume_count INTEGER DEFAULT 0 NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      FOREIGN KEY (project_id) REFERENCES projects(id) ON UPDATE NO ACTION ON DELETE NO ACTION,
+      FOREIGN KEY (workflow_id) REFERENCES workflows(id) ON UPDATE NO ACTION ON DELETE NO ACTION,
+      FOREIGN KEY (schedule_id) REFERENCES schedules(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+    );
+
+    CREATE TABLE IF NOT EXISTS workflows (
+      id TEXT PRIMARY KEY NOT NULL,
+      project_id TEXT,
+      name TEXT NOT NULL,
+      definition TEXT NOT NULL,
+      status TEXT DEFAULT 'draft' NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      FOREIGN KEY (project_id) REFERENCES projects(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+    );
+
+    CREATE TABLE IF NOT EXISTS agent_logs (
+      id TEXT PRIMARY KEY NOT NULL,
+      task_id TEXT,
+      agent_type TEXT NOT NULL,
+      event TEXT NOT NULL,
+      payload TEXT,
+      timestamp INTEGER NOT NULL,
+      FOREIGN KEY (task_id) REFERENCES tasks(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+    );
+
+    CREATE TABLE IF NOT EXISTS notifications (
+      id TEXT PRIMARY KEY NOT NULL,
+      task_id TEXT,
+      type TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT,
+      read INTEGER DEFAULT 0 NOT NULL,
+      tool_name TEXT,
+      tool_input TEXT,
+      response TEXT,
+      responded_at INTEGER,
+      created_at INTEGER NOT NULL,
+      FOREIGN KEY (task_id) REFERENCES tasks(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+    );
+
+    CREATE TABLE IF NOT EXISTS settings (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
+    CREATE INDEX IF NOT EXISTS idx_tasks_project_id ON tasks(project_id);
+    CREATE INDEX IF NOT EXISTS idx_agent_logs_task_id ON agent_logs(task_id);
+    CREATE INDEX IF NOT EXISTS idx_agent_logs_timestamp ON agent_logs(timestamp);
+
+    CREATE TABLE IF NOT EXISTS documents (
+      id TEXT PRIMARY KEY NOT NULL,
+      task_id TEXT,
+      project_id TEXT,
+      filename TEXT NOT NULL,
+      original_name TEXT NOT NULL,
+      mime_type TEXT NOT NULL,
+      size INTEGER NOT NULL,
+      storage_path TEXT NOT NULL,
+      version INTEGER DEFAULT 1 NOT NULL,
+      direction TEXT DEFAULT 'input' NOT NULL,
+      category TEXT,
+      status TEXT DEFAULT 'uploaded' NOT NULL,
+      extracted_text TEXT,
+      processed_path TEXT,
+      processing_error TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      FOREIGN KEY (task_id) REFERENCES tasks(id) ON UPDATE NO ACTION ON DELETE NO ACTION,
+      FOREIGN KEY (project_id) REFERENCES projects(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+    );
+
+    CREATE TABLE IF NOT EXISTS schedules (
+      id TEXT PRIMARY KEY NOT NULL,
+      project_id TEXT,
+      name TEXT NOT NULL,
+      prompt TEXT NOT NULL,
+      cron_expression TEXT NOT NULL,
+      assigned_agent TEXT,
+      agent_profile TEXT,
+      recurs INTEGER DEFAULT 1 NOT NULL,
+      status TEXT DEFAULT 'active' NOT NULL,
+      max_firings INTEGER,
+      firing_count INTEGER DEFAULT 0 NOT NULL,
+      expires_at INTEGER,
+      last_fired_at INTEGER,
+      next_fire_at INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      FOREIGN KEY (project_id) REFERENCES projects(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_schedules_status ON schedules(status);
+    CREATE INDEX IF NOT EXISTS idx_schedules_next_fire_at ON schedules(next_fire_at);
+    CREATE INDEX IF NOT EXISTS idx_schedules_project_id ON schedules(project_id);
+
+    CREATE INDEX IF NOT EXISTS idx_notifications_task_id ON notifications(task_id);
+    CREATE INDEX IF NOT EXISTS idx_notifications_read ON notifications(read);
+    CREATE INDEX IF NOT EXISTS idx_documents_task_id ON documents(task_id);
+    CREATE INDEX IF NOT EXISTS idx_documents_project_id ON documents(project_id);
+
+    CREATE TABLE IF NOT EXISTS usage_ledger (
+      id TEXT PRIMARY KEY NOT NULL,
+      task_id TEXT,
+      workflow_id TEXT,
+      schedule_id TEXT,
+      project_id TEXT,
+      activity_type TEXT NOT NULL,
+      runtime_id TEXT NOT NULL,
+      provider_id TEXT NOT NULL,
+      model_id TEXT,
+      status TEXT NOT NULL,
+      input_tokens INTEGER,
+      output_tokens INTEGER,
+      total_tokens INTEGER,
+      cost_micros INTEGER,
+      pricing_version TEXT,
+      started_at INTEGER NOT NULL,
+      finished_at INTEGER NOT NULL,
+      FOREIGN KEY (task_id) REFERENCES tasks(id) ON UPDATE NO ACTION ON DELETE NO ACTION,
+      FOREIGN KEY (workflow_id) REFERENCES workflows(id) ON UPDATE NO ACTION ON DELETE NO ACTION,
+      FOREIGN KEY (schedule_id) REFERENCES schedules(id) ON UPDATE NO ACTION ON DELETE NO ACTION,
+      FOREIGN KEY (project_id) REFERENCES projects(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_usage_ledger_task_id ON usage_ledger(task_id);
+    CREATE INDEX IF NOT EXISTS idx_usage_ledger_activity_type ON usage_ledger(activity_type);
+    CREATE INDEX IF NOT EXISTS idx_usage_ledger_runtime_id ON usage_ledger(runtime_id);
+    CREATE INDEX IF NOT EXISTS idx_usage_ledger_provider_model ON usage_ledger(provider_id, model_id);
+    CREATE INDEX IF NOT EXISTS idx_usage_ledger_finished_at ON usage_ledger(finished_at);
+
+    CREATE TABLE IF NOT EXISTS learned_context (
+      id TEXT PRIMARY KEY NOT NULL,
+      profile_id TEXT NOT NULL,
+      version INTEGER NOT NULL,
+      content TEXT,
+      diff TEXT,
+      change_type TEXT NOT NULL,
+      source_task_id TEXT,
+      proposal_notification_id TEXT,
+      proposed_additions TEXT,
+      approved_by TEXT,
+      created_at INTEGER NOT NULL,
+      FOREIGN KEY (source_task_id) REFERENCES tasks(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_learned_context_profile_version ON learned_context(profile_id, version);
+    CREATE INDEX IF NOT EXISTS idx_learned_context_change_type ON learned_context(change_type);
+  `);
+  try {
+    sqlite2.exec(`ALTER TABLE tasks ADD COLUMN agent_profile TEXT;`);
+  } catch {
+  }
+  sqlite2.exec(`CREATE INDEX IF NOT EXISTS idx_tasks_agent_profile ON tasks(agent_profile);`);
+  try {
+    sqlite2.exec(`ALTER TABLE tasks ADD COLUMN workflow_id TEXT REFERENCES workflows(id);`);
+  } catch {
+  }
+  sqlite2.exec(`CREATE INDEX IF NOT EXISTS idx_tasks_workflow_id ON tasks(workflow_id);`);
+  try {
+    sqlite2.exec(`ALTER TABLE tasks ADD COLUMN schedule_id TEXT REFERENCES schedules(id);`);
+  } catch {
+  }
+  sqlite2.exec(`CREATE INDEX IF NOT EXISTS idx_tasks_schedule_id ON tasks(schedule_id);`);
+  try {
+    sqlite2.exec(`ALTER TABLE projects ADD COLUMN working_directory TEXT;`);
+  } catch {
+  }
+  try {
+    sqlite2.exec(`ALTER TABLE schedules ADD COLUMN assigned_agent TEXT;`);
+  } catch {
+  }
+  try {
+    sqlite2.exec(`ALTER TABLE documents ADD COLUMN version INTEGER NOT NULL DEFAULT 1;`);
+  } catch {
+  }
+}
+function hasLegacyStagentTables(sqlite2) {
+  const placeholders = STAGENT_TABLES.map(() => "?").join(", ");
+  const row = sqlite2.prepare(
+    `SELECT COUNT(*) AS count
+       FROM sqlite_master
+       WHERE type = 'table' AND name IN (${placeholders})`
+  ).get(...STAGENT_TABLES);
+  return row.count > 0;
+}
+function hasMigrationHistory(sqlite2, migrationsTable = "__drizzle_migrations") {
+  const tableRow = sqlite2.prepare(
+    `SELECT COUNT(*) AS count
+       FROM sqlite_master
+       WHERE type = 'table' AND name = ?`
+  ).get(migrationsTable);
+  if (tableRow.count === 0) {
+    return false;
+  }
+  const row = sqlite2.prepare(`SELECT COUNT(*) AS count FROM ${migrationsTable}`).get();
+  return row.count > 0;
+}
+function markAllMigrationsApplied(sqlite2, migrationsFolder, migrationsTable = "__drizzle_migrations") {
+  const migrations = readMigrationFiles({ migrationsFolder, migrationsTable });
+  sqlite2.exec(`
+    CREATE TABLE IF NOT EXISTS ${migrationsTable} (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      hash TEXT NOT NULL,
+      created_at NUMERIC
+    )
+  `);
+  const existing = sqlite2.prepare(`SELECT hash, created_at FROM ${migrationsTable}`).all();
+  const seen = new Set(existing.map((row) => `${row.hash}:${row.created_at}`));
+  const insert = sqlite2.prepare(
+    `INSERT INTO ${migrationsTable} (hash, created_at) VALUES (?, ?)`
+  );
+  for (const migration of migrations) {
+    const key = `${migration.hash}:${migration.folderMillis}`;
+    if (!seen.has(key)) {
+      insert.run(migration.hash, migration.folderMillis);
+    }
+  }
 }
 
 // bin/cli.ts
-var __dirname = dirname(fileURLToPath(import.meta.url));
-var appDir = join2(__dirname, "..");
+var __dirname = dirname2(fileURLToPath(import.meta.url));
+var appDir = join3(__dirname, "..");
 var DATA_DIR = getStagentDataDir();
 var dbPath = getStagentDbPath();
-var pkg = JSON.parse(readFileSync(join2(appDir, "package.json"), "utf-8"));
+var pkg = JSON.parse(readFileSync(join3(appDir, "package.json"), "utf-8"));
 var HELP_TEXT = `
 Data:
   Directory        ${DATA_DIR}
   Database         ${dbPath}
-  Sessions         ${join2(DATA_DIR, "sessions")}
-  Logs             ${join2(DATA_DIR, "logs")}
+  Sessions         ${join3(DATA_DIR, "sessions")}
+  Logs             ${join3(DATA_DIR, "logs")}
 
 Environment variables:
-  STAGENT_DATA_DIR Custom data directory for the CLI and web app
+  STAGENT_DATA_DIR Custom data directory for the desktop sidecar and web app
   ANTHROPIC_API_KEY Claude runtime access
   OPENAI_API_KEY   OpenAI Codex runtime access
 
 Examples:
-  npx stagent
-  npx stagent --port 3210 --no-open
-  STAGENT_DATA_DIR=/tmp/stagent-smoke npx stagent --reset
+  node dist/cli.js --port 3210 --no-open
+  STAGENT_DATA_DIR=/tmp/stagent-desktop node dist/cli.js --reset
 `;
-program.name("stagent").description("Governed AI agent workspace \u2014 local-first").version(pkg.version).addHelpText("after", HELP_TEXT).option("-p, --port <number>", "port to start on", "3000").option("--reset", "delete the local database before starting").option("--no-open", "don't auto-open browser").parse();
+program.name("stagent").description("Governed desktop AI agent workspace").version(pkg.version).addHelpText("after", HELP_TEXT).option("-p, --port <number>", "port to start on", "3000").option("--reset", "delete the local database before starting").option("--no-open", "don't auto-open browser").parse();
 var opts = program.opts();
 var requestedPort = Number.parseInt(opts.port, 10);
 if (Number.isNaN(requestedPort) || requestedPort <= 0) {
   program.error(`Invalid port: ${opts.port}`);
 }
-for (const dir of [DATA_DIR, join2(DATA_DIR, "logs"), join2(DATA_DIR, "sessions")]) {
+for (const dir of [DATA_DIR, join3(DATA_DIR, "logs"), join3(DATA_DIR, "sessions")]) {
   mkdirSync(dir, { recursive: true });
 }
 if (opts.reset) {
-  if (existsSync(dbPath)) {
+  if (existsSync2(dbPath)) {
     unlinkSync(dbPath);
     for (const suffix of ["-wal", "-shm"]) {
       const filePath = dbPath + suffix;
-      if (existsSync(filePath)) unlinkSync(filePath);
+      if (existsSync2(filePath)) unlinkSync(filePath);
     }
     console.log("Database reset.");
   } else {
@@ -75,9 +393,17 @@ if (opts.reset) {
 var sqlite = new Database(dbPath);
 sqlite.pragma("journal_mode = WAL");
 sqlite.pragma("foreign_keys = ON");
+var migrationsDir = join3(appDir, "src", "lib", "db", "migrations");
 var db = drizzle(sqlite);
-var migrationsDir = join2(appDir, "src", "lib", "db", "migrations");
-migrate(db, { migrationsFolder: migrationsDir });
+var needsLegacyRecovery = hasLegacyStagentTables(sqlite) && !hasMigrationHistory(sqlite);
+if (needsLegacyRecovery) {
+  bootstrapStagentDatabase(sqlite);
+  markAllMigrationsApplied(sqlite, migrationsDir);
+  console.log("Recovered legacy database schema.");
+} else {
+  migrate(db, { migrationsFolder: migrationsDir });
+  bootstrapStagentDatabase(sqlite);
+}
 sqlite.close();
 console.log("Database ready.");
 function findAvailablePort(preferred) {
@@ -91,31 +417,24 @@ function findAvailablePort(preferred) {
     });
   });
 }
-function findLocalBin(name, cwd) {
-  const local = join2(cwd, "node_modules", ".bin", name);
-  if (existsSync(local)) return local;
-  let dir = dirname(cwd);
-  while (dir !== dirname(dir)) {
-    const candidate = join2(dir, "node_modules", ".bin", name);
-    if (existsSync(candidate)) return candidate;
-    dir = dirname(dir);
-  }
-  return name;
-}
 async function main() {
-  const actualPort = await findAvailablePort(requestedPort);
+  const actualPort = await resolveSidecarPort({
+    argv: process.argv.slice(2),
+    requestedPort,
+    findAvailablePort
+  });
   let effectiveCwd = appDir;
-  const localNm = join2(appDir, "node_modules");
-  if (!existsSync(join2(localNm, "next", "package.json"))) {
-    let searchDir = dirname(appDir);
-    while (searchDir !== dirname(searchDir)) {
-      const candidate = join2(searchDir, "node_modules", "next", "package.json");
-      if (existsSync(candidate)) {
+  const localNm = join3(appDir, "node_modules");
+  if (!existsSync2(join3(localNm, "next", "package.json"))) {
+    let searchDir = dirname2(appDir);
+    while (searchDir !== dirname2(searchDir)) {
+      const candidate = join3(searchDir, "node_modules", "next", "package.json");
+      if (existsSync2(candidate)) {
         const hoistedRoot = searchDir;
         for (const name of ["src", "public"]) {
-          const dest = join2(hoistedRoot, name);
-          const src = join2(appDir, name);
-          if (!existsSync(dest) && existsSync(src)) {
+          const dest = join3(hoistedRoot, name);
+          const src = join3(appDir, name);
+          if (!existsSync2(dest) && existsSync2(src)) {
             cpSync(src, dest, { recursive: true });
           }
         }
@@ -127,23 +446,31 @@ async function main() {
           "components.json",
           "drizzle.config.ts"
         ]) {
-          const dest = join2(hoistedRoot, name);
-          const src = join2(appDir, name);
-          if (!existsSync(dest) && existsSync(src)) {
+          const dest = join3(hoistedRoot, name);
+          const src = join3(appDir, name);
+          if (!existsSync2(dest) && existsSync2(src)) {
             writeFileSync(dest, readFileSync(src));
           }
         }
         effectiveCwd = hoistedRoot;
         break;
       }
-      searchDir = dirname(searchDir);
+      searchDir = dirname2(searchDir);
     }
   }
-  const nextBin = findLocalBin("next", effectiveCwd);
+  const nextEntrypoint = resolveNextEntrypoint(effectiveCwd);
+  const isPrebuilt = existsSync2(join3(effectiveCwd, ".next", "BUILD_ID"));
+  const nextArgs = buildNextLaunchArgs({
+    isPrebuilt,
+    port: actualPort
+  });
+  const sidecarUrl = buildSidecarUrl(actualPort);
   console.log(`Stagent ${pkg.version}`);
   console.log(`Data dir: ${DATA_DIR}`);
-  console.log(`Starting Stagent on http://localhost:${actualPort}`);
-  const child = spawn(nextBin, ["dev", "--turbopack", "--port", String(actualPort)], {
+  console.log(`Mode: ${isPrebuilt ? "production" : "development"}`);
+  console.log(`Next entry: ${nextEntrypoint}`);
+  console.log(`Starting Stagent on ${sidecarUrl}`);
+  const child = spawn(process.execPath, [nextEntrypoint, ...nextArgs], {
     cwd: effectiveCwd,
     stdio: "inherit",
     env: {
@@ -156,7 +483,7 @@ async function main() {
     setTimeout(async () => {
       try {
         const open = (await import("open")).default;
-        await open(`http://localhost:${actualPort}`);
+        await open(sidecarUrl);
       } catch {
       }
     }, 3e3);