@lazyingart/agintiflow 0.20.131 → 0.20.133

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.131",
+  "version": "0.20.133",
   "type": "module",
   "description": "AgInTiFlow is a project-aware agent workspace for hybrid wet-dry R&D, hardware-aware intelligence, software automation, and industrial workflows.",
   "license": "Apache-2.0",
@@ -66,6 +66,7 @@
     "scripts/smoke-platform.js",
     "scripts/smoke-perception-research.js",
     "scripts/smoke-permission-modes.js",
+    "scripts/smoke-runtime-compat.js",
     "scripts/smoke-skills.js",
     "scripts/smoke-skillmesh.js",
     "scripts/smoke-tmux-tools.js",
@@ -104,6 +105,7 @@
     "smoke:platform": "node scripts/smoke-platform.js",
     "smoke:perception-research": "node scripts/smoke-perception-research.js",
     "smoke:permission-modes": "node scripts/smoke-permission-modes.js",
+    "smoke:runtime-compat": "node scripts/smoke-runtime-compat.js",
     "smoke:tmux-tools": "node scripts/smoke-tmux-tools.js",
     "smoke:web-api": "node scripts/smoke-web-api.js",
     "smoke:web-autostart": "node scripts/smoke-web-autostart.js",
@@ -114,7 +116,7 @@
     "postinstall": "node scripts/postinstall-webapp.js",
     "supervision:seed": "node scripts/seed-supervised-homework.js",
     "storage:migrate": "node bin/aginti-cli.js storage migrate",
-    "test": "npm run check && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:docker-command && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:auth && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:tmux-tools && npm run smoke:cli-chat && npm run smoke:inbox",
+    "test": "npm run check && npm run smoke:runtime-compat && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:docker-command && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:auth && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:tmux-tools && npm run smoke:cli-chat && npm run smoke:inbox",
     "pack:dry-run": "npm pack --dry-run",
     "smoke:capabilities": "node scripts/smoke-capabilities.js"
   },

package/scripts/smoke-runtime-compat.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "agintiflow-runtime-compat-"));
+const agintiflowHome = path.join(tempRoot, ".agintiflow-home");
+process.env.AGINTIFLOW_HOME = agintiflowHome;
+process.env.AGINTIFLOW_FORCE_JSON_DB = "1";
+
+const { formatNodeSqliteRecovery, nodeSqliteStatus } = await import("../src/sqlite.js");
+const { WebDatabase } = await import("../src/web-db.js");
+const { deleteSessionIndex, listSessionIndex, renameSessionIndex, upsertSessionIndex } = await import("../src/session-index.js");
+
+const sqliteStatus = nodeSqliteStatus();
+assert.equal(sqliteStatus.ok, false, "forced sqlite fallback should report unavailable node:sqlite");
+assert.equal(sqliteStatus.forcedJson, true, "forced sqlite fallback should be marked as forced");
+const recovery = formatNodeSqliteRecovery(sqliteStatus);
+assert.match(recovery, /Node\.js 22\+/);
+assert.match(recovery, /npm install -g @lazyingart\/agintiflow@latest/);
+
+const db = new WebDatabase(tempRoot);
+assert.equal(db.driver, "json", "WebDatabase should use JSON fallback when node:sqlite is unavailable");
+
+const preferences = db.getPreferences();
+db.savePreferences({ ...preferences, model: "runtime-compat-model" });
+assert.equal(db.getPreferences().model, "runtime-compat-model", "JSON fallback preferences should persist");
+
+const session = {
+  sessionId: "runtime-compat-session",
+  projectRoot: tempRoot,
+  commandCwd: tempRoot,
+  provider: "mock",
+  model: "mock-model",
+  goal: "runtime compatibility",
+  title: "Runtime Compatibility",
+  status: "finished",
+  startedAt: "2026-05-14T00:00:00.000Z",
+  updatedAt: "2026-05-14T00:01:00.000Z",
+  result: "ok",
+};
+db.upsertSession(session);
+assert.equal(db.getSession(session.sessionId)?.title, "Runtime Compatibility", "JSON fallback session should persist");
+assert.equal(db.listSessions(5).length, 1, "JSON fallback session listing should work");
+assert.equal(db.renameSession(session.sessionId, "Renamed Runtime Compatibility"), true, "JSON fallback rename should work");
+assert.equal(db.getSession(session.sessionId)?.title, "Renamed Runtime Compatibility", "JSON fallback rename should persist");
+assert.equal(db.deleteSession(session.sessionId), true, "JSON fallback delete should work");
+assert.equal(db.getSession(session.sessionId), null, "JSON fallback delete should remove the session");
+
+assert.equal(upsertSessionIndex(session), true, "JSON fallback global index upsert should work");
+assert.equal(listSessionIndex({ projectRoot: tempRoot }).length, 1, "JSON fallback global index listing should work");
+assert.equal(renameSessionIndex(session.sessionId, "Indexed Runtime Compatibility"), true, "JSON fallback global index rename should work");
+assert.equal(deleteSessionIndex(session.sessionId), true, "JSON fallback global index delete should work");
+
+const port = 45200 + Math.floor(Math.random() * 500);
+const server = spawn(process.execPath, [path.join(repoRoot, "bin/aginti-cli.js"), "web", "--port", String(port), "--host", "127.0.0.1"], {
+  cwd: tempRoot,
+  env: {
+    ...process.env,
+    AGINTIFLOW_HOME: agintiflowHome,
+    AGINTIFLOW_RUNTIME_DIR: tempRoot,
+    AGINTIFLOW_FORCE_JSON_DB: "1",
+  },
+  stdio: ["ignore", "pipe", "pipe"],
+});
+
+let stdout = "";
+let stderr = "";
+server.stdout.on("data", (chunk) => {
+  stdout += chunk.toString();
+});
+server.stderr.on("data", (chunk) => {
+  stderr += chunk.toString();
+});
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForHealth() {
+  const deadline = Date.now() + 15000;
+  while (Date.now() < deadline) {
+    if (server.exitCode !== null) break;
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/health`);
+      const health = await response.json();
+      if (health.ok) return health;
+    } catch {
+      await delay(250);
+    }
+  }
+  throw new Error(`forced JSON web health failed. stdout=${stdout.slice(-500)} stderr=${stderr.slice(-500)}`);
+}
+
+try {
+  const health = await waitForHealth();
+  assert.equal(health.storageDriver, "json", "web health should advertise JSON fallback storage");
+  assert.equal(health.runtimeDir, tempRoot, "web runtime should use the requested project root");
+} finally {
+  if (server.exitCode === null && !server.killed) {
+    server.kill("SIGTERM");
+    await new Promise((resolve) => server.once("exit", resolve));
+  }
+}
+
+console.log("runtime compatibility smoke ok");

package/src/cli.js

@@ -1098,6 +1098,7 @@ function parseInitOptions(argv = []) {
 function printDoctorReport(report) {
   console.log(`AgInTiFlow ${report.package.version} (npm latest: ${report.package.npmLatest})`);
   console.log(`node=${report.node.version} ok=${report.node.ok}`);
+  console.log(`nodeSqlite=${report.node.sqlite?.ok ? "available" : "fallback-json"} storage=${report.node.sqlite?.ok ? "sqlite" : "json"}`);
   console.log(`platform=${report.platform.label} family=${report.platform.linuxFamily || report.platform.platform}`);
   console.log(`project=${report.project.root}`);
   console.log(`instructions=${report.project.instructionsPath} present=${report.project.instructionsPresent}`);
@@ -1126,6 +1127,10 @@ function printDoctorReport(report) {
     console.log("platform setup hints:");
     for (const hint of report.platform.setupHints) console.log(`- ${hint}`);
   }
+  if (report.node.recovery?.length) {
+    console.log("node runtime recovery:");
+    for (const line of report.node.recovery) console.log(`- ${line}`);
+  }
 }
 
 async function readStdin() {

package/src/docker-setup.js

@@ -91,6 +91,12 @@ export function formatDockerSetupText(summary = {}) {
   if (!summary.dockerAvailable) {
     lines.push("Docker is not available.");
     lines.push(`Install path: ${summary.install?.command || "Install Docker, then run: aginti docker setup"}`);
+    if (summary.install?.supported) {
+      lines.push("Install command: aginti docker install-host --yes");
+      lines.push("After install, open a fresh shell or run newgrp docker, then run: aginti docker setup");
+    } else {
+      lines.push("After installing Docker for this platform, run: aginti docker setup");
+    }
   } else if (!summary.imageReady || summary.preflightOk === false) {
     lines.push("Next: aginti docker setup");
   } else {

package/src/platform.js

@@ -58,6 +58,7 @@ export function platformSetupHints(info = platformInfo()) {
   if (info.isWsl) {
     return [
       "Use the Linux/WSL shell as the primary AgInTiFlow environment; keep projects under the WSL filesystem for best file and Docker performance.",
+      "Use Node.js 22+ from nvm/fnm/NodeSource; if an old ~/.npm-global/bin/aginti is earlier on PATH, reinstall AgInTiFlow after switching Node.",
       "Use Docker Desktop with WSL integration or Docker Engine inside WSL for docker-workspace mode.",
       "For LaTeX, reuse WSL latexmk/pdflatex when installed, or use the companion Docker sandbox image.",
     ];
@@ -65,6 +66,7 @@ export function platformSetupHints(info = platformInfo()) {
   if (info.isMac) {
     return [
       "Use Node.js 22+ from Homebrew, nvm, fnm, or the official installer.",
+      "After changing Node versions, verify `node -v`, `which aginti`, and reinstall with `npm install -g @lazyingart/agintiflow@latest` so the CLI uses the same Node that installed it.",
       "Use Docker Desktop or Colima for docker-workspace mode; the Ubuntu Docker installer is intentionally not used on macOS.",
       "For LaTeX, reuse MacTeX/BasicTeX when latexmk and pdflatex are on PATH; otherwise use the companion Docker sandbox image.",
       "Use Homebrew for optional host tools such as ripgrep, git, python, and latexmk when you choose host mode.",
@@ -80,6 +82,7 @@ export function platformSetupHints(info = platformInfo()) {
   if (info.linuxFamily === "debian") {
     return [
       "Use Node.js 22+ from nvm/fnm, NodeSource, or distro packages.",
+      "After changing Node versions, verify `node -v`, `which aginti`, and reinstall with `npm install -g @lazyingart/agintiflow@latest` to avoid stale npm-global shims.",
       "Docker can be installed with scripts/install-docker-ubuntu.sh on Ubuntu/Debian-like hosts.",
       "For LaTeX, reuse host latexmk/pdflatex when available; otherwise use the companion Docker sandbox image.",
     ];

package/src/project.js

@@ -6,6 +6,7 @@ import { promisify } from "node:util";
 import { listAgentWrappers } from "./tool-wrappers.js";
 import { getDockerSandboxStatus } from "./docker-sandbox.js";
 import { platformInfo, platformLabel, platformSetupHints } from "./platform.js";
+import { nodeSqliteRecoveryLines, nodeSqliteStatus } from "./sqlite.js";
 import { buildAgintiInstructions, normalizeInstructionTemplate } from "./behavior-contract.js";
 import {
   LEGACY_PROJECT_SESSIONS_DIR_NAME,
@@ -758,6 +759,7 @@ export async function doctorReport(projectRoot, packageVersion, config) {
   const paths = projectPaths(projectRoot);
   const keyStatus = providerKeyStatus(projectRoot);
   const platform = platformInfo();
+  const sqliteStatus = nodeSqliteStatus();
   const [sessions, dockerStatus, latestVersion, instructions] = await Promise.all([
     listProjectSessions(projectRoot, 8),
     getDockerSandboxStatus(config).catch((error) => ({ ok: false, error: error.message })),
@@ -775,6 +777,8 @@ export async function doctorReport(projectRoot, packageVersion, config) {
     node: {
       version: process.version,
       ok: Number(process.versions.node.split(".")[0]) >= 22,
+      sqlite: sqliteStatus,
+      recovery: sqliteStatus.ok ? [] : nodeSqliteRecoveryLines(sqliteStatus),
     },
     platform: {
       ...platform,

package/src/session-index.js

@@ -17,6 +17,7 @@ export function globalSessionPaths(sessionId = "") {
     home,
     sessionsDir,
     indexDbPath: path.join(sessionsDir, "index.sqlite"),
+    indexJsonPath: path.join(sessionsDir, "index.json"),
     sessionDir: sessionId ? path.join(sessionsDir, sessionId) : "",
   };
 }
@@ -29,7 +30,8 @@ export function isSafeSessionId(sessionId) {
 function ensureIndexDb() {
   const paths = globalSessionPaths();
   fs.mkdirSync(paths.sessionsDir, { recursive: true });
-  const DatabaseSync = loadDatabaseSync();
+  const DatabaseSync = loadDatabaseSync({ optional: true });
+  if (!DatabaseSync) return null;
   const db = new DatabaseSync(paths.indexDbPath);
   db.exec(`
     CREATE TABLE IF NOT EXISTS sessions (
@@ -57,14 +59,86 @@ function ensureIndexDb() {
   return db;
 }
 
+function emptyIndexState() {
+  return {
+    sessions: {},
+  };
+}
+
+function readIndexJson() {
+  const paths = globalSessionPaths();
+  fs.mkdirSync(paths.sessionsDir, { recursive: true });
+  try {
+    const parsed = JSON.parse(fs.readFileSync(paths.indexJsonPath, "utf8"));
+    return {
+      ...emptyIndexState(),
+      ...parsed,
+      sessions: parsed && typeof parsed.sessions === "object" && parsed.sessions ? parsed.sessions : {},
+    };
+  } catch {
+    return emptyIndexState();
+  }
+}
+
+function writeIndexJson(state) {
+  const paths = globalSessionPaths();
+  fs.mkdirSync(paths.sessionsDir, { recursive: true });
+  const tmpPath = `${paths.indexJsonPath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmpPath, `${JSON.stringify(state, null, 2)}\n`);
+  fs.renameSync(tmpPath, paths.indexJsonPath);
+}
+
+function normalizeIndexRecord(record = {}, sessionId = "") {
+  const now = new Date().toISOString();
+  const paths = globalSessionPaths(sessionId);
+  const createdAt = record.createdAt || record.startedAt || record.created_at || now;
+  const updatedAt = record.updatedAt || record.updated_at || createdAt || now;
+  return {
+    sessionId,
+    projectRoot: String(record.projectRoot || record.project_root || ""),
+    commandCwd: String(record.commandCwd || record.command_cwd || record.projectRoot || record.project_root || ""),
+    projectSessionsDir: String(record.projectSessionsDir || record.project_sessions_dir || ""),
+    sessionDir: String(record.sessionDir || record.session_dir || paths.sessionDir),
+    provider: String(record.provider || ""),
+    model: String(record.model || ""),
+    goal: String(record.goal || ""),
+    title: String(record.title || ""),
+    status: String(record.status || ""),
+    createdAt,
+    updatedAt,
+    endedAt: record.endedAt || record.ended_at || null,
+    result: String(record.result || ""),
+    error: String(record.error || ""),
+  };
+}
+
 export function upsertSessionIndex(record = {}) {
   const sessionId = String(record.sessionId || record.session_id || "").trim();
   if (!isSafeSessionId(sessionId)) return false;
-  const now = new Date().toISOString();
   const db = ensureIndexDb();
+  const normalized = normalizeIndexRecord(record, sessionId);
+  if (!db) {
+    const state = readIndexJson();
+    const previous = state.sessions[sessionId] || {};
+    state.sessions[sessionId] = {
+      ...previous,
+      ...normalized,
+      projectRoot: normalized.projectRoot || previous.projectRoot || "",
+      commandCwd: normalized.commandCwd || previous.commandCwd || "",
+      projectSessionsDir: normalized.projectSessionsDir || previous.projectSessionsDir || "",
+      sessionDir: normalized.sessionDir || previous.sessionDir || globalSessionPaths(sessionId).sessionDir,
+      provider: normalized.provider || previous.provider || "",
+      model: normalized.model || previous.model || "",
+      goal: normalized.goal || previous.goal || "",
+      title: normalized.title || previous.title || "",
+      status: normalized.status || previous.status || "",
+      result: normalized.result || previous.result || "",
+      error: normalized.error || previous.error || "",
+    };
+    writeIndexJson(state);
+    return true;
+  }
   const paths = globalSessionPaths(sessionId);
-  const createdAt = record.createdAt || record.startedAt || record.created_at || now;
-  const updatedAt = record.updatedAt || record.updated_at || createdAt || now;
   db.prepare(
     `INSERT INTO sessions (
        session_id, project_root, command_cwd, project_sessions_dir, session_dir,
@@ -86,20 +160,20 @@ export function upsertSessionIndex(record = {}) {
        error = CASE WHEN excluded.error != '' THEN excluded.error ELSE sessions.error END`
   ).run(
     sessionId,
-    String(record.projectRoot || record.project_root || ""),
-    String(record.commandCwd || record.command_cwd || record.projectRoot || record.project_root || ""),
-    String(record.projectSessionsDir || record.project_sessions_dir || ""),
-    String(record.sessionDir || record.session_dir || paths.sessionDir),
-    String(record.provider || ""),
-    String(record.model || ""),
-    String(record.goal || ""),
-    String(record.title || ""),
-    String(record.status || ""),
-    createdAt,
-    updatedAt,
-    record.endedAt || record.ended_at || null,
-    String(record.result || ""),
-    String(record.error || "")
+    normalized.projectRoot,
+    normalized.commandCwd,
+    normalized.projectSessionsDir,
+    normalized.sessionDir || paths.sessionDir,
+    normalized.provider,
+    normalized.model,
+    normalized.goal,
+    normalized.title,
+    normalized.status,
+    normalized.createdAt,
+    normalized.updatedAt,
+    normalized.endedAt,
+    normalized.result,
+    normalized.error
   );
   return true;
 }
@@ -107,6 +181,14 @@ export function upsertSessionIndex(record = {}) {
 export function renameSessionIndex(sessionId, title) {
   if (!isSafeSessionId(sessionId)) return false;
   const db = ensureIndexDb();
+  if (!db) {
+    const state = readIndexJson();
+    if (!state.sessions[sessionId]) return false;
+    state.sessions[sessionId].title = String(title || "").trim();
+    state.sessions[sessionId].updatedAt = new Date().toISOString();
+    writeIndexJson(state);
+    return true;
+  }
   const result = db
     .prepare("UPDATE sessions SET title = ?, updated_at = ? WHERE session_id = ?")
     .run(String(title || "").trim(), new Date().toISOString(), sessionId);
@@ -116,6 +198,13 @@ export function renameSessionIndex(sessionId, title) {
 export function deleteSessionIndex(sessionId) {
   if (!isSafeSessionId(sessionId)) return false;
   const db = ensureIndexDb();
+  if (!db) {
+    const state = readIndexJson();
+    if (!state.sessions[sessionId]) return false;
+    delete state.sessions[sessionId];
+    writeIndexJson(state);
+    return true;
+  }
   const result = db.prepare("DELETE FROM sessions WHERE session_id = ?").run(sessionId);
   return result.changes > 0;
 }
@@ -123,6 +212,18 @@ export function deleteSessionIndex(sessionId) {
 export function listSessionIndex({ projectRoot = "", commandCwd = "", limit = 100 } = {}) {
   const db = ensureIndexDb();
   const maxRows = Math.min(Math.max(Number(limit) || 100, 1), 1000);
+  if (!db) {
+    const resolvedProjectRoot = projectRoot ? path.resolve(projectRoot) : "";
+    const resolvedCommandCwd = commandCwd ? path.resolve(commandCwd) : "";
+    return Object.values(readIndexJson().sessions)
+      .filter((session) => {
+        if (resolvedProjectRoot && session.projectRoot !== resolvedProjectRoot) return false;
+        if (resolvedCommandCwd && session.commandCwd !== resolvedCommandCwd) return false;
+        return true;
+      })
+      .sort((left, right) => String(right.updatedAt || "").localeCompare(String(left.updatedAt || "")))
+      .slice(0, maxRows);
+  }
   const columns = `session_id AS sessionId, project_root AS projectRoot, command_cwd AS commandCwd, project_sessions_dir AS projectSessionsDir,
     session_dir AS sessionDir, provider, model, goal, title, status,
     created_at AS createdAt, updated_at AS updatedAt, ended_at AS endedAt, result, error`;

package/src/sqlite.js

@@ -2,18 +2,126 @@ import { createRequire } from "node:module";
 
 const require = createRequire(import.meta.url);
 let cachedDatabaseSync = null;
+let cachedUnavailableError = null;
 
-export function loadDatabaseSync() {
-  if (cachedDatabaseSync) return cachedDatabaseSync;
+export const NODE_SQLITE_UNAVAILABLE_CODE = "AGINTIFLOW_NODE_SQLITE_UNAVAILABLE";
+
+function nodeMajorVersion(version = process.versions.node) {
+  return Number(String(version || "").split(".")[0]) || 0;
+}
+
+function requireNodeSqliteSilently() {
   const originalEmitWarning = process.emitWarning;
   process.emitWarning = function filteredSqliteWarning(warning, ...args) {
     if (String(warning || "").includes("SQLite is an experimental feature")) return;
     return originalEmitWarning.call(process, warning, ...args);
   };
   try {
-    cachedDatabaseSync = require("node:sqlite").DatabaseSync;
-    return cachedDatabaseSync;
+    return require("node:sqlite");
   } finally {
     process.emitWarning = originalEmitWarning;
   }
 }
+
+export function nodeSqliteStatus() {
+  const nodeVersion = process.version;
+  const nodeMajor = nodeMajorVersion();
+  const forcedJson = process.env.AGINTIFLOW_FORCE_JSON_DB === "1" || process.env.AGINTIFLOW_FORCE_SQLITE_UNAVAILABLE === "1";
+  if (forcedJson) {
+    return {
+      ok: false,
+      forcedJson: true,
+      nodeVersion,
+      nodeMajor,
+      requiredNodeMajor: 22,
+      code: NODE_SQLITE_UNAVAILABLE_CODE,
+      message: "AGINTIFLOW_FORCE_JSON_DB is enabled; using JSON fallback storage.",
+    };
+  }
+  try {
+    requireNodeSqliteSilently();
+    return {
+      ok: true,
+      forcedJson: false,
+      nodeVersion,
+      nodeMajor,
+      requiredNodeMajor: 22,
+      code: "",
+      message: "node:sqlite is available.",
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      forcedJson: false,
+      nodeVersion,
+      nodeMajor,
+      requiredNodeMajor: 22,
+      code: NODE_SQLITE_UNAVAILABLE_CODE,
+      errorCode: error?.code || "",
+      message: error?.message || String(error),
+    };
+  }
+}
+
+export function nodeSqliteRecoveryLines(status = nodeSqliteStatus()) {
+  const lines = [
+    `AgInTiFlow web/session SQLite storage needs Node.js 22+ with node:sqlite; current node is ${status.nodeVersion || process.version}.`,
+    "AgInTiFlow will use a project-local JSON fallback when possible, but Node 22+ is still recommended for the full durable session index.",
+    "Recommended fix after installing Node 22+: npm install -g @lazyingart/agintiflow@latest",
+  ];
+
+  if (process.platform === "win32") {
+    lines.push("Windows: prefer WSL2 with Node 22+ and Docker Desktop WSL integration, or install Node 22+ with the official installer/nvm-windows.");
+  } else {
+    lines.push('nvm quick fix: export NVM_DIR="$HOME/.nvm"; . "$NVM_DIR/nvm.sh"; nvm install 22; nvm alias default 22; nvm use 22');
+    lines.push("If `which aginti` points to ~/.npm-global/bin/aginti after switching Node, remove the stale install or put the nvm bin directory before ~/.npm-global/bin in PATH.");
+  }
+
+  if (process.platform === "darwin") {
+    lines.push("macOS alternative: brew install node@22, then reinstall AgInTiFlow globally with that node on PATH.");
+  } else if (process.platform === "linux") {
+    lines.push("Linux alternative: install Node 22+ from NodeSource/fnm/nvm/distro packages, then open a new shell and verify `node -v` and `which aginti`.");
+  }
+
+  return lines;
+}
+
+export function formatNodeSqliteRecovery(status = nodeSqliteStatus()) {
+  return nodeSqliteRecoveryLines(status).join("\n");
+}
+
+export class AgintiSqliteUnavailableError extends Error {
+  constructor(cause, status = nodeSqliteStatus()) {
+    super(formatNodeSqliteRecovery(status));
+    this.name = "AgintiSqliteUnavailableError";
+    this.code = NODE_SQLITE_UNAVAILABLE_CODE;
+    this.status = status;
+    if (cause) this.cause = cause;
+  }
+}
+
+function unavailableError(cause = null) {
+  cachedUnavailableError = new AgintiSqliteUnavailableError(cause);
+  return cachedUnavailableError;
+}
+
+export function loadDatabaseSync(options = {}) {
+  if (cachedUnavailableError) {
+    if (options.optional) return null;
+    throw cachedUnavailableError;
+  }
+  if (cachedDatabaseSync) return cachedDatabaseSync;
+  if (process.env.AGINTIFLOW_FORCE_JSON_DB === "1" || process.env.AGINTIFLOW_FORCE_SQLITE_UNAVAILABLE === "1") {
+    const error = unavailableError(new Error("Forced JSON database fallback."));
+    if (options.optional) return null;
+    throw error;
+  }
+  try {
+    cachedDatabaseSync = requireNodeSqliteSilently().DatabaseSync;
+    return cachedDatabaseSync;
+  } catch (error) {
+    const wrapped = unavailableError(error);
+    if (options.optional) return null;
+    throw wrapped;
+  }
+}

package/src/web-db.js

@@ -9,6 +9,38 @@ import { permissionModeDefaults } from "./permission-modes.js";
 
 const PREFERENCES_SCHEMA_VERSION = 8;
 
+function jsonStatePath(dbPath) {
+  return dbPath.replace(/\.sqlite$/i, ".json");
+}
+
+function emptyJsonState() {
+  return {
+    preferences: {},
+    sessions: {},
+  };
+}
+
+function readJsonFile(filePath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    return {
+      ...emptyJsonState(),
+      ...parsed,
+      preferences: parsed && typeof parsed.preferences === "object" && parsed.preferences ? parsed.preferences : {},
+      sessions: parsed && typeof parsed.sessions === "object" && parsed.sessions ? parsed.sessions : {},
+    };
+  } catch {
+    return emptyJsonState();
+  }
+}
+
+function writeJsonFile(filePath, state) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmpPath, `${JSON.stringify(state, null, 2)}\n`);
+  fs.renameSync(tmpPath, filePath);
+}
+
 function defaultPreferences(baseDir) {
   const presets = getModelPresets();
   const roles = getModelRoleDefaults();
@@ -63,33 +95,40 @@ export class WebDatabase {
     this.paths = projectPaths(this.baseDir);
     this.dbDir = this.paths.sessionsDir;
     this.dbPath = this.paths.sessionDbPath;
+    this.jsonPath = jsonStatePath(this.dbPath);
     fs.mkdirSync(this.dbDir, { recursive: true });
-    const DatabaseSync = loadDatabaseSync();
-    this.db = new DatabaseSync(this.dbPath);
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS preferences (
-        key TEXT PRIMARY KEY,
-        value TEXT NOT NULL,
-        updated_at TEXT NOT NULL
-      );
+    const DatabaseSync = loadDatabaseSync({ optional: true });
+    this.driver = DatabaseSync ? "sqlite" : "json";
+    this.db = DatabaseSync ? new DatabaseSync(this.dbPath) : null;
+    if (this.db) {
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS preferences (
+          key TEXT PRIMARY KEY,
+          value TEXT NOT NULL,
+          updated_at TEXT NOT NULL
+        );
 
-      CREATE TABLE IF NOT EXISTS sessions (
-        session_id TEXT PRIMARY KEY,
-        provider TEXT NOT NULL,
-        model TEXT NOT NULL,
-        goal TEXT NOT NULL,
-        status TEXT NOT NULL,
-        started_at TEXT NOT NULL,
-        updated_at TEXT NOT NULL,
-        ended_at TEXT,
-        result TEXT,
-        error TEXT
-      );
-    `);
+        CREATE TABLE IF NOT EXISTS sessions (
+          session_id TEXT PRIMARY KEY,
+          provider TEXT NOT NULL,
+          model TEXT NOT NULL,
+          goal TEXT NOT NULL,
+          status TEXT NOT NULL,
+          started_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL,
+          ended_at TEXT,
+          result TEXT,
+          error TEXT
+        );
+      `);
+    } else if (!fs.existsSync(this.jsonPath)) {
+      writeJsonFile(this.jsonPath, emptyJsonState());
+    }
     this.migrate();
   }
 
   migrate() {
+    if (!this.db) return;
     const sessionColumns = this.db.prepare("PRAGMA table_info(sessions)").all();
     if (!sessionColumns.some((column) => column.name === "title")) {
       this.db.exec("ALTER TABLE sessions ADD COLUMN title TEXT NOT NULL DEFAULT ''");
@@ -108,12 +147,29 @@ export class WebDatabase {
     }
   }
 
+  readJsonState() {
+    return readJsonFile(this.jsonPath);
+  }
+
+  writeJsonState(state) {
+    writeJsonFile(this.jsonPath, state);
+  }
+
   getPreferences() {
+    if (!this.db) {
+      const raw = this.readJsonState().preferences.ui;
+      if (!raw) return defaultPreferences(this.baseDir);
+      return this.normalizePreferences(raw);
+    }
     const row = this.db.prepare("SELECT value FROM preferences WHERE key = ?").get("ui");
     if (!row) return defaultPreferences(this.baseDir);
 
+    return this.normalizePreferences(row.value);
+  }
+
+  normalizePreferences(value) {
     try {
-      const parsed = JSON.parse(row.value);
+      const parsed = typeof value === "string" ? JSON.parse(value) : value;
       const preferences = {
         ...defaultPreferences(this.baseDir),
         ...parsed,
@@ -177,6 +233,13 @@ export class WebDatabase {
   savePreferences(preferences) {
     const value = JSON.stringify(preferences);
     const updatedAt = new Date().toISOString();
+    if (!this.db) {
+      const state = this.readJsonState();
+      state.preferences.ui = value;
+      state.preferences.uiUpdatedAt = updatedAt;
+      this.writeJsonState(state);
+      return;
+    }
     this.db
       .prepare(
         `INSERT INTO preferences (key, value, updated_at)
@@ -192,6 +255,35 @@ export class WebDatabase {
     const commandCwd = session.commandCwd || projectRoot;
     const projectSessionsDir = session.projectSessionsDir || this.paths.sessionsDir;
     const sessionDir = session.sessionDir || path.join(this.paths.globalSessionsDir, session.sessionId);
+    const record = {
+      sessionId: session.sessionId,
+      projectRoot,
+      commandCwd,
+      projectSessionsDir,
+      sessionDir,
+      provider: session.provider,
+      model: session.model,
+      goal: session.goal,
+      title: session.title || "",
+      status: session.status,
+      startedAt: session.startedAt,
+      updatedAt,
+      endedAt: session.endedAt || null,
+      result: session.result || "",
+      error: session.error || "",
+    };
+    if (!this.db) {
+      const state = this.readJsonState();
+      const previous = state.sessions[session.sessionId] || {};
+      state.sessions[session.sessionId] = {
+        ...previous,
+        ...record,
+        title: record.title || previous.title || "",
+      };
+      this.writeJsonState(state);
+      this.syncSessionIndex(record);
+      return;
+    }
     this.db
       .prepare(
         `INSERT INTO sessions (
@@ -230,15 +322,14 @@ export class WebDatabase {
         session.result || "",
         session.error || ""
       );
+    this.syncSessionIndex(record);
+  }
+
+  syncSessionIndex(record) {
     try {
       upsertSessionIndex({
-        ...session,
-        projectRoot,
-        commandCwd,
-        projectSessionsDir,
-        sessionDir,
-        createdAt: session.startedAt,
-        updatedAt,
+        ...record,
+        createdAt: record.startedAt,
       });
     } catch {
       // The project-local database remains the fallback if the global index cannot be updated.
@@ -246,6 +337,9 @@ export class WebDatabase {
   }
 
   getSession(sessionId) {
+    if (!this.db) {
+      return this.readJsonState().sessions[sessionId] || null;
+    }
     return (
       this.db
         .prepare(
@@ -273,6 +367,12 @@ export class WebDatabase {
   }
 
   listSessions(limit = 20) {
+    if (!this.db) {
+      const maxRows = Math.min(Math.max(Number(limit) || 20, 1), 1000);
+      return Object.values(this.readJsonState().sessions)
+        .sort((left, right) => String(right.updatedAt || "").localeCompare(String(left.updatedAt || "")))
+        .slice(0, maxRows);
+    }
     return this.db
       .prepare(
         `SELECT
@@ -300,6 +400,19 @@ export class WebDatabase {
 
   renameSession(sessionId, title) {
     const updatedAt = new Date().toISOString();
+    if (!this.db) {
+      const state = this.readJsonState();
+      if (!state.sessions[sessionId]) return false;
+      state.sessions[sessionId].title = title;
+      state.sessions[sessionId].updatedAt = updatedAt;
+      this.writeJsonState(state);
+      try {
+        renameSessionIndex(sessionId, title);
+      } catch {
+        // Keep the project-local JSON store as the source of truth.
+      }
+      return true;
+    }
     const result = this.db
       .prepare("UPDATE sessions SET title = ?, updated_at = ? WHERE session_id = ?")
       .run(title, updatedAt, sessionId);
@@ -308,6 +421,18 @@ export class WebDatabase {
   }
 
   deleteSession(sessionId) {
+    if (!this.db) {
+      const state = this.readJsonState();
+      if (!state.sessions[sessionId]) return false;
+      delete state.sessions[sessionId];
+      this.writeJsonState(state);
+      try {
+        deleteSessionIndex(sessionId);
+      } catch {
+        // Keep the project-local JSON store as the source of truth.
+      }
+      return true;
+    }
     const result = this.db.prepare("DELETE FROM sessions WHERE session_id = ?").run(sessionId);
     if (result.changes > 0) deleteSessionIndex(sessionId);
     return result.changes > 0;

package/web.js

@@ -1397,6 +1397,7 @@ app.get("/health", (_req, res) => {
     sessionsDir,
     projectSessionsDir,
     packageDir,
+    storageDriver: db.driver || "sqlite",
   });
 });