synabun 1.3.0 → 2.0.0-beta

package/neural-interface/lib/memory-map-worker.js

@@ -0,0 +1,165 @@
+// ── Memory map worker ──
+//
+// Computes island layouts off the main thread. It opens its own read-only
+// connection (never lib/db.js — that one is read-write and runs migrations),
+// reads every live memory of the requested categories in one short read
+// transaction, closes the database, and then:
+//   1. posts `meta`: the change-feed watermarks and each island's members and
+//      centroid (the service packs the geography from these right away);
+//   2. lays out every island with ≥ MAP.MIN_FIT memories, smallest first,
+//      posting each one as it lands (with named regions for big islands);
+//   3. posts `done`.
+// The worker holds no state, so terminate() is always a safe cancel.
+
+import { isMainThread, parentPort, workerData } from 'node:worker_threads';
+import { DatabaseSync } from 'node:sqlite';
+import { realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, resolve, sep } from 'node:path';
+import { MAP, cleanTag, contentTerms, densityRegions, labelRegions, layoutIsland } from './memory-map-layout.js';
+
+export const MEMORY_MAP_WORKER_URL = new URL(import.meta.url);
+
+/** Under a test runner, refuse any database outside the temp directory. */
+function assertTestDb(dbPath) {
+  if (!process.env.NODE_TEST_CONTEXT && !process.env.VITEST) return;
+  const real = (p) => { try { return realpathSync(p); } catch { return p; } };
+  const roots = [tmpdir(), '/tmp'].flatMap((r) => [r, real(r)]);
+  const full = resolve(dbPath);
+  const fullReal = real(dirname(full)) + sep + basename(full);
+  const under = (p, root) => p === root || p.startsWith(root.endsWith(sep) ? root : root + sep);
+  if (roots.some((root) => under(full, root) || under(fullReal, root))) return;
+  throw new Error(`memory-map worker refuses ${dbPath} under a test runner`);
+}
+
+function readSnapshot({ dbPath, categories }) {
+  assertTestDb(dbPath);
+  const db = new DatabaseSync(dbPath, { readOnly: true });
+  try {
+    db.exec('PRAGMA busy_timeout = 5000');
+    db.exec('BEGIN');
+    try {
+      const maxSeq = (entity) => {
+        try {
+          return Number(db.prepare('SELECT COALESCE(MAX(seq), 0) AS s FROM memory_changes WHERE entity = ?').get(entity).s) || 0;
+        } catch { return 0; }
+      };
+      const watermark = { mem: maxSeq('memories'), filt: maxSeq('memory_filters') };
+      const filter = Array.isArray(categories) ? categories : null;
+      const where = filter
+        ? `trashed_at IS NULL AND (CASE WHEN category = '' THEN 'uncategorized' ELSE category END) IN (SELECT value FROM json_each(?))`
+        : 'trashed_at IS NULL';
+      const args = filter ? [JSON.stringify(filter)] : [];
+      const total = Number(db.prepare(`SELECT COUNT(*) AS n FROM memories WHERE ${where}`).get(...args).n) || 0;
+      const rows = db.prepare(
+        `SELECT id, category, created_at, importance, tags, substr(content, 1, 600) AS head, vector
+           FROM memories WHERE ${where}
+          ORDER BY (CASE WHEN category = '' THEN 'uncategorized' ELSE category END), created_at, id`,
+      ).iterate(...args);
+
+      let dim = 0;
+      let X = null;
+      const islands = [];
+      let cur = null;
+      let row = 0;
+      for (const r of rows) {
+        const blob = r.vector;
+        if (!blob || blob.byteLength < 4 || blob.byteLength % 4) continue;
+        if (!dim) {
+          dim = blob.byteLength / 4;
+          X = new Float32Array(Math.max(total, 1) * dim);
+        }
+        if (blob.byteLength / 4 !== dim) continue;
+        const name = r.category || 'uncategorized';
+        if (!cur || cur.name !== name) {
+          cur = { name, start: row, ids: [], created: [], imp: [], tags: [], heads: [] };
+          islands.push(cur);
+        }
+        const aligned = blob.byteOffset % 4 === 0
+          ? new Float32Array(blob.buffer, blob.byteOffset, dim)
+          : new Float32Array(Uint8Array.from(blob).buffer);
+        X.set(aligned, row * dim);
+        cur.ids.push(r.id);
+        const ms = Date.parse(r.created_at);
+        cur.created.push(Number.isFinite(ms) ? ms : 0);
+        cur.imp.push(Math.max(1, Math.min(10, Math.round(Number(r.importance) || 5))));
+        let tags = [];
+        try { const parsed = JSON.parse(r.tags || '[]'); if (Array.isArray(parsed)) tags = parsed; } catch {}
+        cur.tags.push(tags);
+        cur.heads.push(r.head || '');
+        row++;
+      }
+      return { watermark, dim, X: X || new Float32Array(0), islands };
+    } finally {
+      try { db.exec('COMMIT'); } catch {}
+    }
+  } finally {
+    db.close();
+  }
+}
+
+function centroidOf(X, start, n, dim) {
+  const c = new Float32Array(dim);
+  for (let i = 0; i < n; i++) {
+    const b = (start + i) * dim;
+    for (let d = 0; d < dim; d++) c[d] += X[b + d];
+  }
+  let norm = 0;
+  for (let d = 0; d < dim; d++) norm += c[d] * c[d];
+  norm = Math.sqrt(norm);
+  if (norm > 0) for (let d = 0; d < dim; d++) c[d] /= norm;
+  return c;
+}
+
+function regionsFor(island, uv, banned) {
+  const n = island.ids.length;
+  if (n < MAP.REGION_MIN) return [];
+  const regions = densityRegions(uv, n);
+  if (!regions.peaks.length) return [];
+  const bannedSet = new Set(banned || []);
+  const tagTerms = island.tags.map((tags) => [...new Set(tags.map((t) => cleanTag(t, bannedSet)).filter(Boolean))]);
+  const labels = labelRegions(
+    regions,
+    (i) => tagTerms[i],
+    (i) => contentTerms(island.heads[i], bannedSet),
+    n,
+  );
+  return regions.peaks.map((p, i) => ({ label: labels[i], u: p.u, v: p.v, count: p.count }));
+}
+
+export function runMemoryMapJob(job, post) {
+  const snap = readSnapshot(job);
+  const { dim, X, islands } = snap;
+  post({
+    type: 'meta',
+    jobId: job.jobId,
+    watermark: snap.watermark,
+    dim,
+    islands: islands.map((isl) => ({
+      name: isl.name,
+      ids: isl.ids,
+      created: isl.created,
+      imp: isl.imp,
+      centroid: dim ? centroidOf(X, isl.start, isl.ids.length, dim) : new Float32Array(0),
+    })),
+  });
+  const order = islands
+    .filter((isl) => isl.ids.length >= MAP.MIN_FIT)
+    .sort((a, b) => a.ids.length - b.ids.length || (a.name < b.name ? -1 : 1));
+  for (const isl of order) {
+    const n = isl.ids.length;
+    const uv = layoutIsland(X.subarray(isl.start * dim, (isl.start + n) * dim), n, dim, isl.name);
+    const regions = regionsFor(isl, uv, job.banned?.[isl.name]);
+    post({ type: 'island', jobId: job.jobId, name: isl.name, ids: isl.ids, uv, regions }, [uv.buffer]);
+  }
+  post({ type: 'done', jobId: job.jobId });
+}
+
+if (!isMainThread && workerData?.memoryMapJob) {
+  const job = workerData.memoryMapJob;
+  try {
+    runMemoryMapJob(job, (msg, transfer) => parentPort.postMessage(msg, transfer || []));
+  } catch (error) {
+    parentPort.postMessage({ type: 'error', jobId: job.jobId, message: error?.message || String(error), stack: error?.stack || '' });
+  }
+}

package/neural-interface/lib/memory-session-capture.js

@@ -0,0 +1,81 @@
+import { open } from 'node:fs/promises';
+import { getDb } from '../../mcp-server/dist/services/sqlite.js';
+import { detectProject } from '../../mcp-server/dist/config.js';
+import { normalizeMemoryEvents, ingestMemoryEvents } from '../../mcp-server/dist/services/memory-sessions.js';
+import { maintenancePaused } from './memory-timers.js';
+
+export function queueMemoryCapture({host,sessionId,filePath,project,cwd}) {
+  if(!filePath || !sessionId || !['claude-code','codex'].includes(host))return;
+  getDb().prepare(`INSERT INTO memory_capture_files(host,session_id,file_path,project,cwd) VALUES(?,?,?,?,?)
+    ON CONFLICT(host,session_id) DO UPDATE SET file_path=excluded.file_path,project=excluded.project,cwd=excluded.cwd,status='pending',error=NULL`)
+    .run(host,sessionId,filePath,cwd ? detectProject(cwd) : project || 'global',cwd || null);
+}
+
+let running=false;
+let timer=null;
+export async function captureMemoryFileBatch(target) {
+  if(running)return {busy:true};
+  if(maintenancePaused())return {paused:true};
+  running=true;
+  const d=getDb();
+  const job=target ? d.prepare("SELECT * FROM memory_capture_files WHERE host=? AND session_id=? AND status='pending'").get(target.host,target.sessionId)
+    : d.prepare("SELECT * FROM memory_capture_files WHERE status='pending' ORDER BY byte_offset LIMIT 1").get();
+  let file;
+  try {
+    if(!job)return;
+    file=await open(job.file_path,'r');
+    const stat=await file.stat();
+    const offset=stat.size<job.byte_offset ? 0 : job.byte_offset;
+    // Bounded file reads keep large transcripts off the UI request path.
+    let buffer=Buffer.alloc(256*1024);
+    let {bytesRead}=await file.read(buffer,0,buffer.length,offset);
+    if(!bytesRead){d.prepare("UPDATE memory_capture_files SET status='complete' WHERE host=? AND session_id=?").run(job.host,job.session_id);return;}
+    while(buffer.subarray(0,bytesRead).lastIndexOf(10)<0 && bytesRead===buffer.length && buffer.length<8*1024*1024) {
+      buffer=Buffer.alloc(buffer.length*2);
+      ({bytesRead}=await file.read(buffer,0,buffer.length,offset));
+    }
+    const bytes=buffer.subarray(0,bytesRead);
+    const newline=bytes.lastIndexOf(10);
+    let consumed=newline+1;
+    if(newline<0) {
+      if(bytesRead===buffer.length)throw new Error('Transcript record exceeds 8 MiB; original source retained.');
+      // A valid final JSON record need not end in a newline. Incomplete tails
+      // remain pending until the writer finishes them.
+      try{JSON.parse(bytes.toString('utf8'));consumed=bytesRead;}catch{return;}
+    }
+    const records=[];
+    let position=offset;
+    for(const line of bytes.subarray(0,consumed).toString('utf8').split('\n')) {
+      if(line.trim()) {try {const record=JSON.parse(line);records.push({...record,id:record.id || record.uuid || `byte:${position}`});}catch{}}
+      position+=Buffer.byteLength(line)+1;
+    }
+    const sourceCwd=job.cwd || records.find(r=>r.cwd)?.cwd || records.find(r=>r.type==='session_meta')?.payload?.cwd;
+    const project=sourceCwd ? detectProject(sourceCwd) : job.project;
+    const events=normalizeMemoryEvents(job.host,records,{session_id:job.session_id,project,cwd:sourceCwd});
+    if(maintenancePaused())return;
+    ingestMemoryEvents(events);
+    // Replaying after a crash between intake and checkpoint is idempotent.
+    d.prepare("UPDATE memory_capture_files SET byte_offset=?,status=?,error=NULL WHERE host=? AND session_id=?")
+      .run(offset+consumed,offset+consumed>=stat.size ? 'complete':'pending',job.host,job.session_id);
+  }catch(error){if(job)d.prepare("UPDATE memory_capture_files SET status='failed',error=? WHERE host=? AND session_id=?").run(error.message,job.host,job.session_id);}
+  finally{await file?.close();running=false;}
+}
+let startTimer=null;
+// offsetMs keeps this tick out of phase with the 2 s maintenance timer so the
+// two never stack on the same event-loop turn.
+export function startMemoryCapture({offsetMs=1000,intervalMs=2000}={}) {
+  if(timer||startTimer)return;
+  const tick=()=>captureMemoryFileBatch().catch(error=>console.error('[memory capture]',error.message));
+  startTimer=setTimeout(()=>{
+    startTimer=null;
+    timer=setInterval(tick,intervalMs);
+    timer.unref();
+  },offsetMs);
+  startTimer.unref();
+}
+export function stopMemoryCapture(){
+  if(startTimer)clearTimeout(startTimer);
+  if(timer)clearInterval(timer);
+  startTimer=null;
+  timer=null;
+}

package/neural-interface/lib/memory-timers.js

@@ -0,0 +1,62 @@
+// Cheap gates for the background memory timers that share the Neural
+// Interface event loop with terminal I/O.
+//
+// maintenanceStatus() (mcp-server) runs ~9 queries — GROUP BYs over every
+// memory_jobs row, relation lists, retrieval and TypeSafe stats — and the 2 s
+// maintenance and capture timers each called it just to read the paused flag,
+// stalling the loop ~30-40 ms twice every 2 s. runMaintenanceBatch() also
+// opened a BEGIN IMMEDIATE transaction on every tick, which waits synchronously
+// (busy_timeout) whenever another process holds the write lock.
+//
+// These gates read one kv row and probe idx_memory_jobs_status_kind, so an idle
+// tick costs microseconds and never takes the write lock. The probes mirror
+// runMaintenanceBatch's own claim query: pending non-judge jobs under the retry
+// limit, or a `running` claim older than 5 minutes (which the batch resets).
+
+import { getDb } from '../../mcp-server/dist/services/sqlite.js';
+import { runMaintenanceBatch } from '../../mcp-server/dist/services/memory-maintenance.js';
+
+const STALE_RUNNING_MS = 300_000;
+
+export function maintenancePaused(d = getDb()) {
+  const row = d.prepare("SELECT value FROM kv_config WHERE key='memory_maintenance_paused'").get();
+  return row?.value === 'true';
+}
+
+export function maintenanceHasWork(d = getDb(), now = Date.now()) {
+  if (d.prepare("SELECT 1 FROM memory_jobs WHERE status='pending' AND kind!='judge' AND attempts<3 LIMIT 1").get()) return true;
+  const staleBefore = new Date(now - STALE_RUNNING_MS).toISOString();
+  return !!d.prepare("SELECT 1 FROM memory_jobs WHERE status='running' AND updated_at<? LIMIT 1").get(staleBefore);
+}
+
+let maintenanceTimer = null;
+let batchInFlight = false;
+
+/**
+ * Drop-in replacement for mcp-server's startMemoryMaintenance(): same batch,
+ * same cadence, but a tick with nothing to do returns before touching the
+ * expensive status queries or the write lock.
+ */
+export function startGatedMemoryMaintenance({ intervalMs = 2000, runBatch = runMaintenanceBatch } = {}) {
+  if (maintenanceTimer) return;
+  maintenanceTimer = setInterval(() => {
+    if (batchInFlight) return;
+    try {
+      const d = getDb();
+      if (maintenancePaused(d) || !maintenanceHasWork(d)) return;
+    } catch {
+      return;
+    }
+    batchInFlight = true;
+    Promise.resolve()
+      .then(() => runBatch())
+      .catch((error) => console.error('[memory maintenance]', error?.message || error))
+      .finally(() => { batchInFlight = false; });
+  }, intervalMs);
+  maintenanceTimer.unref?.();
+}
+
+export function stopGatedMemoryMaintenance() {
+  if (maintenanceTimer) clearInterval(maintenanceTimer);
+  maintenanceTimer = null;
+}

package/neural-interface/lib/morelogin.js

@@ -0,0 +1,301 @@
+/**
+ * MoreLogin local-API client + detection.
+ *
+ * MoreLogin (https://www.morelogin.com) is an anti-detect / multi-account
+ * browser. Its desktop client exposes a local HTTP API (default
+ * http://127.0.0.1:40000) that can list / create / start / stop browser
+ * "environments" (profiles). Starting a profile returns a Chrome DevTools
+ * `debugPort`, which we connect to with Playwright's `connectOverCDP()` — the
+ * exact same mechanism SynaBun already uses for its CDP "attach" mode.
+ *
+ * Auth: on localhost most builds accept UNSIGNED requests. The documented
+ * signed scheme (MD5 of apiId+nonce+secret) is applied only when an API id +
+ * secret are configured (MoreLogin → Settings → API & MCP → API), as optional
+ * hardening for setups that enforce it.
+ *
+ * Verified live (v2.58.0): POST /api/env/page {pageNo,pageSize} →
+ *   { code:0, data:{ total, current, pages, dataList:[{ id, envName, groupId, proxyId, proxy }] } }
+ *
+ * Built-ins only — no new dependency. ESM, Node >= 22 (global fetch + node:crypto).
+ */
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+
+export const DEFAULT_MORELOGIN_PORT = 40000;
+
+/** Resolve the MoreLogin local-API port: env → saved config → default. */
+export function getMoreLoginPort(savedCfg) {
+  const fromEnv = parseInt(process.env.MORELOGIN_API_PORT || '', 10);
+  if (Number.isFinite(fromEnv) && fromEnv > 0) return fromEnv;
+  const ml = savedCfg && (savedCfg.morelogin || savedCfg);
+  const fromCfg = parseInt((ml && (ml.port ?? ml.moreloginPort)) ?? '', 10);
+  if (Number.isFinite(fromCfg) && fromCfg > 0) return fromCfg;
+  return DEFAULT_MORELOGIN_PORT;
+}
+
+/** Detect a MoreLogin desktop install per-OS. Returns { installed, path }. */
+export function isMoreLoginInstalled() {
+  const candidates = [];
+  if (process.platform === 'darwin') {
+    candidates.push('/Applications/MoreLogin.app');
+  } else if (process.platform === 'win32') {
+    const { LOCALAPPDATA, ProgramFiles } = process.env;
+    const PF86 = process.env['ProgramFiles(x86)'];
+    if (LOCALAPPDATA) candidates.push(`${LOCALAPPDATA}\\Programs\\MoreLogin\\MoreLogin.exe`, `${LOCALAPPDATA}\\MoreLogin\\MoreLogin.exe`);
+    if (ProgramFiles) candidates.push(`${ProgramFiles}\\MoreLogin\\MoreLogin.exe`);
+    if (PF86) candidates.push(`${PF86}\\MoreLogin\\MoreLogin.exe`);
+  } else {
+    candidates.push('/opt/MoreLogin/morelogin', '/opt/morelogin/morelogin', '/usr/share/morelogin');
+    if (process.env.HOME) candidates.push(`${process.env.HOME}/.local/share/MoreLogin`);
+  }
+  for (const p of candidates) {
+    try { if (existsSync(p)) return { installed: true, path: p }; } catch { /* ignore */ }
+  }
+  return { installed: false, path: null };
+}
+
+/**
+ * Launch the installed MoreLogin desktop app. Best-effort, never throws —
+ * the app is long-running so this is fire-and-forget (detached + unref'd).
+ * Returns { launched, path, error }.
+ */
+export function launchMoreLoginApp() {
+  const { installed, path } = isMoreLoginInstalled();
+  if (!installed) return { launched: false, path: null, error: 'MoreLogin is not installed' };
+  try {
+    const child = process.platform === 'darwin'
+      ? spawn('open', [path], { detached: true, stdio: 'ignore' })
+      : spawn(path, [], { detached: true, stdio: 'ignore', windowsHide: false });
+    child.unref();
+    return { launched: true, path, error: null };
+  } catch (err) {
+    return { launched: false, path, error: err?.message || String(err) };
+  }
+}
+
+function md5(value) {
+  return createHash('md5').update(value).digest('hex');
+}
+
+/** Build request headers, signing only when credentials are present. */
+function buildHeaders(opts = {}) {
+  const headers = { 'Content-Type': 'application/json' };
+  const appId = opts.appId || process.env.MORELOGIN_API_ID || '';
+  const secretKey = opts.secretKey || process.env.MORELOGIN_SECRET || '';
+  if (appId && secretKey) {
+    // X-Nonce-Id = "<timestamp>:<random>"; Authorization = md5(apiId + nonce + secret)
+    const nonceId = `${Date.now()}:${Math.random().toString(36).slice(2, 14)}`;
+    headers['X-Api-Id'] = String(appId);
+    headers['X-Nonce-Id'] = nonceId;
+    headers['Authorization'] = md5(String(appId) + nonceId + String(secretKey));
+  }
+  return headers;
+}
+
+/**
+ * Low-level POST to the MoreLogin local API. Returns the `data` payload.
+ * Throws with a `.code` of MORELOGIN_UNREACHABLE | MORELOGIN_HTTP | MORELOGIN_API.
+ */
+async function request(path, body, opts = {}) {
+  const port = opts.port || getMoreLoginPort(opts.savedCfg);
+  const url = `http://127.0.0.1:${port}${path}`;
+  let res;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: buildHeaders(opts),
+      body: JSON.stringify(body || {}),
+      signal: AbortSignal.timeout(opts.timeout || 15000),
+    });
+  } catch (err) {
+    const e = new Error(`MoreLogin API unreachable on :${port} (${err?.message || err})`);
+    e.code = 'MORELOGIN_UNREACHABLE';
+    throw e;
+  }
+  let json = null;
+  try { json = await res.json(); }
+  catch { try { await res.body?.cancel(); } catch { /* ignore */ } }
+  if (!res.ok) {
+    const e = new Error(`MoreLogin API ${path} → HTTP ${res.status}`);
+    e.code = 'MORELOGIN_HTTP';
+    e.status = res.status;
+    throw e;
+  }
+  if (json && json.code !== undefined && json.code !== 0) {
+    const e = new Error(`MoreLogin API ${path}: ${json.msg || `code ${json.code}`}`);
+    e.code = 'MORELOGIN_API';
+    e.apiCode = json.code;
+    throw e;
+  }
+  return json ? json.data : null;
+}
+
+/**
+ * Normalize the `proxy` blob MoreLogin attaches to an env row. Kept (rather than
+ * dropped) because a profile's proxy is invisible from SynaBun otherwise — when a
+ * page fails to load there is no way to tell whether traffic left the machine.
+ * Shape varies by version; every field is best-effort.
+ */
+function normalizeProxy(p) {
+  if (!p || typeof p !== 'object') return null;
+  const host = p.proxyIp || p.host || p.ip || p.server || null;
+  const port = p.proxyPort ?? p.port ?? null;
+  const type = p.proxyType || p.type || p.protocol || null;
+  const country = p.country || p.countryCode || p.ipCountry || null;
+  if (!host && !type && !country) return null;
+  return {
+    type: type != null ? String(type) : null,
+    host: host != null ? String(host) : null,
+    port: port != null ? String(port) : null,
+    country: country != null ? String(country) : null,
+  };
+}
+
+function normalizeProfile(e = {}) {
+  return {
+    id: e.id != null ? String(e.id) : null,
+    name: e.envName || e.name || (e.id != null ? `env-${e.id}` : 'env'),
+    status: e.localStatus || e.status || null,
+    groupId: e.groupId != null ? String(e.groupId) : null,
+    proxyId: e.proxyId != null ? String(e.proxyId) : null,
+    proxy: normalizeProxy(e.proxy),
+  };
+}
+
+/** List browser profiles (environments). Returns normalized rows. */
+export async function listProfiles(opts = {}) {
+  const data = await request('/api/env/page', { pageNo: opts.pageNo || 1, pageSize: opts.pageSize || 100 }, opts);
+  const list = (data && (data.dataList || data.list)) || [];
+  return list.map(normalizeProfile).filter(p => p.id);
+}
+
+/** Lightweight reachability probe. Never throws — returns {running, count}. */
+export async function probeMoreLoginApi(opts = {}) {
+  try {
+    const data = await request('/api/env/page', { pageNo: 1, pageSize: 1 }, { ...opts, timeout: opts.timeout || 4000 });
+    const total = data && data.total != null ? Number(data.total)
+      : (data && (data.dataList || data.list) ? (data.dataList || data.list).length : 0);
+    return { running: true, count: Number.isFinite(total) ? total : 0 };
+  } catch (err) {
+    return { running: false, count: 0, error: err?.message || String(err), errCode: err?.code || null };
+  }
+}
+
+/**
+ * Ensure MoreLogin's local API is reachable, auto-launching the desktop app
+ * and waiting for it to come up if it isn't already running. Bounded by
+ * timeoutMs (default 25s — MoreLogin is a heavier multi-process Electron app
+ * than a plain browser relaunch). Never throws — mirrors probeMoreLoginApi's
+ * always-resolve contract. While MoreLogin is the default browser, a
+ * `running: false` result FAILS the session in createBrowserSession(); nothing
+ * falls back to Chrome.
+ */
+export async function ensureMoreLoginRunning(opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 25000;
+  const intervalMs = opts.intervalMs ?? 1000;
+
+  let probe = await probeMoreLoginApi(opts);
+  if (probe.running) return { ...probe, launched: false };
+
+  const launch = launchMoreLoginApp();
+  if (!launch.launched) return { ...probe, launched: false, launchError: launch.error };
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await new Promise(r => setTimeout(r, intervalMs));
+    probe = await probeMoreLoginApi(opts);
+    if (probe.running) return { ...probe, launched: true };
+  }
+  return { ...probe, launched: true, timedOut: true };
+}
+
+/** Combined install + running status, used by the UI/status endpoints. */
+export async function getMoreLoginStatus(opts = {}) {
+  const inst = isMoreLoginInstalled();
+  const port = getMoreLoginPort(opts.savedCfg);
+  const probe = await probeMoreLoginApi({ ...opts, port });
+  return {
+    installed: inst.installed,
+    appPath: inst.path,
+    port,
+    running: probe.running,
+    profileCount: probe.count || 0,
+    signed: !!((opts.appId || process.env.MORELOGIN_API_ID) && (opts.secretKey || process.env.MORELOGIN_SECRET)),
+    error: probe.error || null,
+  };
+}
+
+function extractDebugPort(data) {
+  if (!data || typeof data !== 'object') return null;
+  const raw = data.debugPort ?? data.debug_port ?? data.port;
+  const port = parseInt(raw, 10);
+  return Number.isFinite(port) && port > 0 ? port : null;
+}
+
+/** Query a single profile's status (best-effort across body shapes). */
+export async function profileStatus(envId, opts = {}) {
+  try {
+    return await request('/api/env/status', { envId: String(envId) }, opts);
+  } catch (err) {
+    if (err?.code === 'MORELOGIN_UNREACHABLE') throw err;
+    // Some builds expect an array — retry once with envIds.
+    try { return await request('/api/env/status', { envIds: [String(envId)] }, opts); }
+    catch { return null; }
+  }
+}
+
+/**
+ * Start (launch) a profile and return { debugPort, webdriver, raw }.
+ * Recovers the debugPort via status when the env is already running.
+ */
+export async function startProfile(envId, opts = {}) {
+  let data = null;
+  try {
+    data = await request('/api/env/start', { envId: String(envId), ...(opts.startArgs || {}) }, opts);
+  } catch (err) {
+    if (err?.code === 'MORELOGIN_UNREACHABLE' || err?.code === 'MORELOGIN_HTTP') throw err;
+    // MORELOGIN_API (e.g. "already running") → fall through to status recovery.
+  }
+  let port = extractDebugPort(data);
+  let webdriver = data && data.webdriver;
+  if (!port) {
+    // Already-running or no port echoed — recover from status. A `status` object
+    // may be keyed directly or under a list.
+    const st = await profileStatus(envId, opts);
+    const stData = Array.isArray(st?.dataList) ? st.dataList[0] : (Array.isArray(st) ? st[0] : st);
+    port = extractDebugPort(stData);
+    webdriver = webdriver || (stData && stData.webdriver);
+  }
+  if (!port) throw new Error(`MoreLogin started env ${envId} but returned no debugPort`);
+  return { debugPort: port, webdriver: webdriver || null, raw: data };
+}
+
+/** Stop (close) a profile. */
+export async function stopProfile(envId, opts = {}) {
+  return request('/api/env/close', { envId: String(envId) }, opts);
+}
+
+/** Create a quick profile. Shape varies by version; pass `opts.body` to override. */
+export async function createProfile(opts = {}) {
+  const body = {
+    quantity: 1,
+    browserTypeId: opts.browserTypeId || 1,
+    ...(opts.name ? { name: opts.name } : {}),
+    ...(opts.body || {}),
+  };
+  const data = await request('/api/env/create/quick', body, opts);
+  // Returns { envIds:[...] } or { id } depending on version.
+  const ids = data && (data.envIds || (data.id != null ? [data.id] : []));
+  return { ids: (ids || []).map(String), raw: data };
+}
+
+/** Return the first profile, creating a default "SynaBun" profile if none exist. */
+export async function ensureDefaultProfile(opts = {}) {
+  const list = await listProfiles(opts);
+  if (list.length) return list[0];
+  await createProfile({ ...opts, name: opts.defaultName || 'SynaBun' });
+  const after = await listProfiles(opts);
+  if (!after.length) throw new Error('MoreLogin: no profiles available and auto-create failed');
+  return after[0];
+}