@remits/remits-cli 0.1.69

package/index.js

@@ -0,0 +1,4379 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const http = require('http');
+const crypto = require('crypto');
+const { execFileSync, execSync, spawnSync } = require('child_process');
+const axios = require('axios');
+const openModule = require('open');
+const { Client } = require('@stomp/stompjs');
+const WebSocket = require('ws');
+const YAML = require('yaml');
+
+Object.assign(global, { WebSocket });
+const openBrowser = (openModule && typeof openModule === 'function')
+  ? openModule
+  : (openModule && typeof openModule.default === 'function' ? openModule.default : null);
+
+//const DEFAULT_BASE_URL = process.env.REMITS_BASE_URL || 'http://localhost:8080';
+const DEFAULT_BASE_URL = process.env.REMITS_BASE_URL || 'https://remits-529558023549.us-east5.run.app';
+const SESSION_DIR = path.join(os.homedir(), '.remits-cli');
+const SESSIONS_FILE = path.join(SESSION_DIR, 'sessions.json');
+const CONFIG_FILE = path.join(SESSION_DIR, 'config.json');
+const LISTENER_PID_FILE = path.join(SESSION_DIR, 'listener.pid');
+const TMUX_ACTIVITY_LOG_FILE = path.join(SESSION_DIR, 'tmux-activity.log');
+const SKILL_SOURCE_FILE = path.join(__dirname, 'skills', 'remits-cli', 'SKILL.md');
+const ACCOUNT_REPO_INDEX_FILE = path.join(SESSION_DIR, 'account-repos.json');
+const SERVICE_STATE_FILE = path.join(SESSION_DIR, 'service-state.json');
+const ISSUES_DIR = path.join(SESSION_DIR, 'issues');
+const WEBSOCKET_STATE_FILE = path.join(SESSION_DIR, 'websocket-state.json');
+const AUTO_UPDATE_LOCK_DIR = path.join(SESSION_DIR, 'auto-update.lock');
+const AUTO_UPDATE_DISABLED_VALUES = new Set(['0', 'false', 'no', 'off']);
+const REMITS_CLI_PACKAGE_NAME = '@remits/remits-cli';
+const DEFAULT_DATA_MODE = 'test';
+const DEFAULT_AGENT = 'claude';
+const SUPPORTED_AGENTS = ['claude', 'codex', 'gemini'];
+const MAX_TRACKED_MESSAGE_IDS = 1000;
+const MAX_RECENT_WEBSOCKET_MESSAGES = 40;
+const DASHBOARD_HOST = '127.0.0.1';
+const DEFAULT_DASHBOARD_PORT = Number(process.env.REMITS_CLI_DASHBOARD_PORT || 8787);
+const DEFAULT_SCAN_MAX_DEPTH = Number(process.env.REMITS_CLI_SCAN_MAX_DEPTH || 8);
+const SERVICE_MAINTENANCE_INTERVAL_MS = Number(process.env.REMITS_CLI_SERVICE_MAINTENANCE_INTERVAL_MS || 15000);
+const WEBSOCKET_RECONNECT_DELAY_MS = Number(process.env.REMITS_CLI_WEBSOCKET_RECONNECT_DELAY_MS || 5000);
+const WEBSOCKET_HEARTBEAT_MS = Number(process.env.REMITS_CLI_WEBSOCKET_HEARTBEAT_MS || 10000);
+const WEBSOCKET_CONNECTION_TIMEOUT_MS = Number(process.env.REMITS_CLI_WEBSOCKET_CONNECTION_TIMEOUT_MS || 15000);
+const WEBSOCKET_WATCHDOG_GRACE_MS = Number(process.env.REMITS_CLI_WEBSOCKET_WATCHDOG_GRACE_MS || 30000);
+const ACCOUNT_SCAN_EXCLUDE_DIRS = new Set([
+  '.git',
+  '.gradle',
+  '.idea',
+  '.next',
+  '.npm',
+  '.pnpm-store',
+  '.remits-cli',
+  '.terraform',
+  '.trash',
+  '.venv',
+  '.yarn',
+  'Applications',
+  'Library',
+  'Movies',
+  'Music',
+  'Pictures',
+  'System',
+  'Trash',
+  'Volumes',
+  'build',
+  'dist',
+  'node_modules',
+  'target',
+  'tmp'
+]);
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) {
+      out._.push(arg);
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith('--')) {
+      out[key] = true;
+    } else {
+      out[key] = next;
+      i += 1;
+    }
+  }
+  return out;
+}
+
+function ensureSessionDir() {
+  if (!fs.existsSync(SESSION_DIR)) {
+    fs.mkdirSync(SESSION_DIR, { recursive: true });
+  }
+}
+
+function atomicWriteFile(file, content) {
+  ensureDir(path.dirname(file));
+  const tempFile = path.join(
+    path.dirname(file),
+    '.' + path.basename(file) + '.tmp-' + process.pid + '-' + crypto.randomUUID().slice(0, 8)
+  );
+  fs.writeFileSync(tempFile, content);
+  fs.renameSync(tempFile, file);
+}
+
+function normalizeBaseUrl(value) {
+  return String(value || '').trim().replace(/\/+$/, '');
+}
+
+function hasExplicitDataModeFlag(flags) {
+  return Boolean(
+    flags &&
+    (
+      Object.prototype.hasOwnProperty.call(flags, 'data-mode') ||
+      Object.prototype.hasOwnProperty.call(flags, 'dataMode')
+    )
+  );
+}
+
+function canonicalSessionKey(accountId, baseUrl, dataMode) {
+  const normalizedAccountId = Number(accountId);
+  const normalizedBaseUrl = normalizeBaseUrl(baseUrl || DEFAULT_BASE_URL);
+  const normalizedDataMode = normalizeDataMode(dataMode);
+  return String(normalizedAccountId) + '::' + normalizedDataMode + '::' + normalizedBaseUrl;
+}
+
+function listSessionsFromStore(store) {
+  return Object.values(store || {})
+    .filter((session) => session && session.accountId && session.token)
+    .sort((a, b) => String(b.updatedAt || '').localeCompare(String(a.updatedAt || '')));
+}
+
+function normalizeSessionsStore(rawSessions) {
+  const normalized = {};
+  for (const [rawKey, rawValue] of Object.entries(rawSessions || {})) {
+    if (!rawValue || typeof rawValue !== 'object') {
+      continue;
+    }
+    const accountId = Number(rawValue.accountId || rawKey);
+    if (!Number.isFinite(accountId) || accountId <= 0) {
+      continue;
+    }
+    const session = {
+      ...rawValue,
+      accountId,
+      baseUrl: normalizeBaseUrl(rawValue.baseUrl || DEFAULT_BASE_URL),
+      dataMode: normalizeDataMode(rawValue.dataMode),
+      updatedAt: rawValue.updatedAt || new Date().toISOString()
+    };
+    normalized[canonicalSessionKey(accountId, session.baseUrl, session.dataMode)] = session;
+  }
+  return normalized;
+}
+
+function readAllSessions() {
+  if (!fs.existsSync(SESSIONS_FILE)) {
+    return {};
+  }
+  try {
+    return normalizeSessionsStore(JSON.parse(fs.readFileSync(SESSIONS_FILE, 'utf8')));
+  } catch (_) {
+    return {};
+  }
+}
+
+function writeAllSessions(sessions) {
+  ensureSessionDir();
+  atomicWriteFile(SESSIONS_FILE, JSON.stringify(normalizeSessionsStore(sessions), null, 2));
+}
+
+function readSession(match = {}, options = {}) {
+  const criteria = (typeof match === 'object' && match !== null) ? match : { accountId: match };
+  const normalizedAccountId = criteria.accountId != null ? Number(criteria.accountId) : null;
+  const normalizedBaseUrl = criteria.baseUrl ? normalizeBaseUrl(criteria.baseUrl) : null;
+  const normalizedDataMode = criteria.dataMode ? normalizeDataMode(criteria.dataMode) : null;
+  const strictBaseUrl = Boolean(options.strictBaseUrl && normalizedBaseUrl);
+  const strictDataMode = Boolean(options.strictDataMode && normalizedDataMode);
+  const entries = listSessionsFromStore(readAllSessions());
+
+  let candidates = entries.filter((session) => {
+    if (normalizedAccountId && Number(session.accountId) !== normalizedAccountId) {
+      return false;
+    }
+    if (strictBaseUrl && normalizeBaseUrl(session.baseUrl) !== normalizedBaseUrl) {
+      return false;
+    }
+    if (strictDataMode && normalizeDataMode(session.dataMode) !== normalizedDataMode) {
+      return false;
+    }
+    return true;
+  });
+
+  if (!candidates.length) {
+    return null;
+  }
+
+  candidates.sort((a, b) => {
+    const score = (session) => {
+      let value = 0;
+      if (normalizedAccountId && Number(session.accountId) === normalizedAccountId) value += 8;
+      if (normalizedBaseUrl && normalizeBaseUrl(session.baseUrl) === normalizedBaseUrl) value += 4;
+      if (normalizedDataMode && normalizeDataMode(session.dataMode) === normalizedDataMode) value += 2;
+      return value;
+    };
+    const scoreDiff = score(b) - score(a);
+    if (scoreDiff !== 0) {
+      return scoreDiff;
+    }
+    return String(b.updatedAt || '').localeCompare(String(a.updatedAt || ''));
+  });
+
+  return candidates[0] || null;
+}
+
+function writeSession(accountId, data, options = {}) {
+  const sessions = readAllSessions();
+  const session = {
+    ...data,
+    accountId: Number(accountId),
+    baseUrl: normalizeBaseUrl((options.baseUrl || data.baseUrl || DEFAULT_BASE_URL)),
+    dataMode: normalizeDataMode(options.dataMode || data.dataMode),
+    updatedAt: data.updatedAt || new Date().toISOString()
+  };
+  sessions[canonicalSessionKey(session.accountId, session.baseUrl, session.dataMode)] = session;
+  writeAllSessions(sessions);
+}
+
+function readConfig() {
+  if (!fs.existsSync(CONFIG_FILE)) {
+    return {};
+  }
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  } catch (_) {
+    return {};
+  }
+}
+
+function writeConfig(data) {
+  ensureSessionDir();
+  atomicWriteFile(CONFIG_FILE, JSON.stringify(data, null, 2));
+}
+
+function getPreferredAgent() {
+  const config = readConfig();
+  return config.agent || DEFAULT_AGENT;
+}
+
+function normalizeDataMode(value) {
+  const mode = String(value || DEFAULT_DATA_MODE).trim().toLowerCase();
+  return mode === 'prod' ? 'prod' : 'test';
+}
+
+function resolveDataMode(flags, session) {
+  if (flags && Object.prototype.hasOwnProperty.call(flags, 'data-mode')) {
+    return normalizeDataMode(flags['data-mode']);
+  }
+  if (flags && Object.prototype.hasOwnProperty.call(flags, 'dataMode')) {
+    return normalizeDataMode(flags.dataMode);
+  }
+  if (session && session.dataMode) {
+    return normalizeDataMode(session.dataMode);
+  }
+  return DEFAULT_DATA_MODE;
+}
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function localStatePaths(cwd) {
+  const base = path.join(cwd, '.remits-cli');
+  return {
+    base,
+    toolsDir: path.join(base, 'tools'),
+    sessionsDir: path.join(base, 'sessions'),
+    toolResponsesDir: path.join(base, 'tool-responses'),
+    currentSessionFile: path.join(base, 'current-session.txt')
+  };
+}
+
+function ensureLocalState(cwd) {
+  const paths = localStatePaths(cwd);
+  ensureDir(paths.base);
+  ensureDir(paths.toolsDir);
+  ensureDir(paths.sessionsDir);
+  ensureDir(paths.toolResponsesDir);
+  return paths;
+}
+
+function currentLocalSessionName(cwd) {
+  const paths = ensureLocalState(cwd);
+  if (fs.existsSync(paths.currentSessionFile)) {
+    const existing = fs.readFileSync(paths.currentSessionFile, 'utf8').trim();
+    if (existing) {
+      return existing;
+    }
+  }
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const sessionName = 'session-' + timestamp + '-' + crypto.randomUUID().slice(0, 8);
+  atomicWriteFile(paths.currentSessionFile, sessionName + '\n');
+  return sessionName;
+}
+
+function sessionJsonlFile(cwd) {
+  const paths = ensureLocalState(cwd);
+  return path.join(paths.sessionsDir, currentLocalSessionName(cwd) + '.jsonl');
+}
+
+const CONTENT_FIELDS = new Set(['source', 'html', 'javascript', 'css', 'schema', 'inputSchema', 'previewData']);
+
+function sanitizeForLog(value) {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(sanitizeForLog);
+  }
+  if (typeof value !== 'object') {
+    return value;
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (k.toLowerCase() === 'token') {
+      out[k] = '[redacted]';
+    } else if (CONTENT_FIELDS.has(k) && typeof v === 'string') {
+      out[k] = '[' + v.length + ' chars]';
+    } else {
+      out[k] = sanitizeForLog(v);
+    }
+  }
+  return out;
+}
+
+function appendSessionLog(cwd, entry) {
+  const file = sessionJsonlFile(cwd);
+  fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+  return file;
+}
+
+function summarizeDispatchMessage(message) {
+  const safeMessage = message && typeof message === 'object' ? message : {};
+  const promptText = safeMessage.prompt || safeMessage.message || '';
+  return sanitizeForLog({
+    accountId: safeMessage.accountId || null,
+    implementationAccountId: safeMessage.implementationAccountId || null,
+    ticketId: safeMessage.ticketId || null,
+    legacyTaskId: safeMessage.taskId || null,
+    type: safeMessage.type || null,
+    promptLength: typeof promptText === 'string' ? promptText.length : 0,
+    keys: Object.keys(safeMessage).sort()
+  });
+}
+
+function appendGlobalActivityLog(scope, event, meta = {}, level = 'info') {
+  ensureSessionDir();
+  const safeMeta = sanitizeForLog(meta);
+  const payload = Object.keys(safeMeta || {}).length ? ' ' + JSON.stringify(safeMeta) : '';
+  const line = new Date().toISOString() + ' [' + level + '] [' + scope + '] ' + event + payload + '\n';
+  fs.appendFileSync(TMUX_ACTIVITY_LOG_FILE, line);
+  return TMUX_ACTIVITY_LOG_FILE;
+}
+
+function writeToolResponseFile(cwd, callId, responsePayload) {
+  const paths = ensureLocalState(cwd);
+  const file = path.join(paths.toolResponsesDir, callId + '.json');
+  atomicWriteFile(file, JSON.stringify(responsePayload, null, 2));
+  return file;
+}
+
+function normalizeName(name) {
+  return name.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/\s+/g, ' ').trim();
+}
+
+function stableStringify(obj) {
+  if (obj === null || typeof obj !== 'object') {
+    return JSON.stringify(obj);
+  }
+  if (Array.isArray(obj)) {
+    return '[' + obj.map(stableStringify).join(',') + ']';
+  }
+  const keys = Object.keys(obj).sort();
+  return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k])).join(',') + '}';
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function currentBranch(cwd) {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+  } catch (err) {
+    return 'main';
+  }
+}
+
+function shellQuote(value) {
+  return '\'' + String(value).replace(/'/g, '\'\"\'\"\'' ) + '\'';
+}
+
+function runGit(cwd, command) {
+  try {
+    return execSync(command, { cwd, stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+  } catch (err) {
+    const stderr = err && err.stderr ? err.stderr.toString().trim() : '';
+    const stdout = err && err.stdout ? err.stdout.toString().trim() : '';
+    const details = stderr || stdout || err.message;
+    throw new Error('Git command failed: ' + command + (details ? ' :: ' + details : ''));
+  }
+}
+
+function currentHeadSha(cwd, ref = 'HEAD') {
+  return runGit(cwd, 'git rev-parse ' + shellQuote(ref));
+}
+
+function loadAccountId(cwd) {
+  const file = path.join(cwd, 'account-info.json');
+  if (!fs.existsSync(file)) {
+    throw new Error('account-info.json not found in current directory');
+  }
+  const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  return Number(data.id || data.accountId || (data.account && data.account.id));
+}
+
+function loadAccountInfo(cwd) {
+  const file = path.join(cwd, 'account-info.json');
+  if (!fs.existsSync(file)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+function readAccountRepoIndex() {
+  if (!fs.existsSync(ACCOUNT_REPO_INDEX_FILE)) {
+    return {};
+  }
+  try {
+    return JSON.parse(fs.readFileSync(ACCOUNT_REPO_INDEX_FILE, 'utf8'));
+  } catch (_) {
+    return {};
+  }
+}
+
+function writeAccountRepoIndex(index) {
+  ensureSessionDir();
+  atomicWriteFile(ACCOUNT_REPO_INDEX_FILE, JSON.stringify(index, null, 2));
+}
+
+function buildAccountRepoEntryFromInfo(info, directory, source = 'discovered') {
+  if (!info || typeof info !== 'object') {
+    return null;
+  }
+  const accountId = Number(info.id || info.accountId || (info.account && info.account.id));
+  if (!Number.isFinite(accountId) || accountId <= 0) {
+    return null;
+  }
+  return {
+    accountId,
+    name: info.name || info.accountName || (info.account && info.account.name) || '',
+    type: info.type || info.accountType || (info.account && info.account.type) || null,
+    platformAccountId: info.platformAccountId || (info.platform && info.platform.id) || null,
+    directory: path.resolve(directory),
+    accountInfoPath: path.join(path.resolve(directory), 'account-info.json'),
+    source,
+    updatedAt: new Date().toISOString()
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Guide distribution
+//
+// Front-stage guides are NOT bundled with the npm package. They are downloaded
+// from the platform's authenticated `/cli/guides` endpoint and written into the
+// local account repo, so only users who can authenticate to the Remits platform
+// ever receive them. See ensureGuidesSynced() / downloadAndSyncGuides().
+// ---------------------------------------------------------------------------
+
+function removeLegacyGuideCopies(repoGuidesDir, fileNames, summary, repoRoot) {
+  for (const fileName of fileNames) {
+    const legacyPath = path.join(repoGuidesDir, fileName);
+    if (!fs.existsSync(legacyPath)) {
+      continue;
+    }
+    try {
+      fs.unlinkSync(legacyPath);
+      if (summary && Array.isArray(summary.removed)) {
+        summary.removed.push(path.relative(repoRoot, legacyPath));
+      }
+    } catch (_) {
+      // Best-effort cleanup; a later sync still refreshes the root copy.
+    }
+  }
+}
+
+function writeFileIfChanged(filePath, content) {
+  if (fs.existsSync(filePath)) {
+    try {
+      if (fs.readFileSync(filePath, 'utf8') === content) {
+        return false;
+      }
+    } catch (_) {
+      // Fall through and rewrite unreadable files.
+    }
+  }
+  atomicWriteFile(filePath, content);
+  return true;
+}
+
+function writeGuideGroup(group, targetDir, repoRoot, summary) {
+  if (!group || typeof group !== 'object') {
+    return;
+  }
+  const names = Object.keys(group).filter((name) => typeof group[name] === 'string').sort();
+  if (!names.length) {
+    return;
+  }
+  ensureDir(targetDir);
+  for (const name of names) {
+    const targetPath = path.join(targetDir, name);
+    if (writeFileIfChanged(targetPath, group[name])) {
+      summary.updated.push(path.relative(repoRoot, targetPath));
+    }
+  }
+}
+
+// Write a guide payload downloaded from `/cli/guides` into an account repo.
+// Mirrors the layout the platform exports: the instruction template fans out to
+// the agent guidance files, root guides land at the repo root, and component /
+// feature guides land under guides/ and guides/features/.
+function writeGuidePayloadIntoRepo(repoDir, payload) {
+  const resolvedRepoDir = path.resolve(repoDir);
+  const repoGuidesDir = path.join(resolvedRepoDir, 'guides');
+  const summary = {
+    updated: [],
+    removed: [],
+    missingSources: []
+  };
+
+  const instruction = payload && payload.instruction;
+  if (typeof instruction === 'string' && instruction.length) {
+    for (const fileName of ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md']) {
+      const targetPath = path.join(resolvedRepoDir, fileName);
+      if (writeFileIfChanged(targetPath, instruction)) {
+        summary.updated.push(path.relative(resolvedRepoDir, targetPath));
+      }
+    }
+  }
+
+  ensureDir(repoGuidesDir);
+  // Older CLI versions copied these into guides/; they now live at the repo root.
+  removeLegacyGuideCopies(repoGuidesDir, [
+    'platform-overview.md',
+    'development-guide.md'
+  ], summary, resolvedRepoDir);
+
+  const rootFiles = (payload && payload.root) || {};
+  for (const name of Object.keys(rootFiles).sort()) {
+    if (typeof rootFiles[name] !== 'string') {
+      continue;
+    }
+    const targetPath = path.join(resolvedRepoDir, name);
+    if (writeFileIfChanged(targetPath, rootFiles[name])) {
+      summary.updated.push(path.relative(resolvedRepoDir, targetPath));
+    }
+  }
+
+  writeGuideGroup(payload && payload.components, repoGuidesDir, resolvedRepoDir, summary);
+  writeGuideGroup(payload && payload.features, path.join(repoGuidesDir, 'features'), resolvedRepoDir, summary);
+
+  return summary;
+}
+
+// Cache the downloaded payload for the lifetime of the process so a single
+// invocation that touches multiple repos only fetches guides once.
+let GUIDES_PAYLOAD_CACHE = null;
+
+async function fetchGuidesPayload(cwd, ctx) {
+  const baseUrl = normalizeBaseUrl((ctx && ctx.baseUrl) || DEFAULT_BASE_URL);
+  const token = ctx && ctx.session && ctx.session.token;
+  if (!token) {
+    return null;
+  }
+  const cacheKey = baseUrl + '|' + token;
+  if (GUIDES_PAYLOAD_CACHE && GUIDES_PAYLOAD_CACHE.key === cacheKey) {
+    return GUIDES_PAYLOAD_CACHE.payload;
+  }
+  const api = buildAxios(baseUrl, token);
+  let data = null;
+  try {
+    data = await loggedPost(api, cwd, '/cli/guides', {
+      token,
+      accountId: (ctx && ctx.accountId) || undefined
+    }).then((r) => r.data);
+  } catch (_) {
+    // Best-effort: never fail a command because guides could not be fetched.
+    return null;
+  }
+  if (!data || !data.success) {
+    return null;
+  }
+  GUIDES_PAYLOAD_CACHE = { key: cacheKey, payload: data };
+  return data;
+}
+
+async function downloadAndSyncGuides(cwd, ctx) {
+  const payload = await fetchGuidesPayload(cwd, ctx);
+  if (!payload) {
+    return null;
+  }
+  return writeGuidePayloadIntoRepo(cwd, payload);
+}
+
+// Ensure the current account repo has the latest guides. Authenticates first
+// (interactive terminals only) so guides are only ever delivered to users who
+// can authenticate to the platform.
+async function ensureGuidesSynced(cwd, flags) {
+  if (!loadAccountInfo(cwd)) {
+    return; // Guides are only written into account repos.
+  }
+
+  let accountId = null;
+  const fromFlag = Number(flags && flags['account-id']);
+  if (Number.isFinite(fromFlag) && fromFlag > 0) {
+    accountId = fromFlag;
+  }
+  if (!accountId) {
+    try { accountId = loadAccountId(cwd); } catch (_) { /* not in a repo */ }
+  }
+
+  const requestedBaseUrl = flags && flags['base-url'] ? normalizeBaseUrl(flags['base-url']) : null;
+  const sessionMatch = { accountId, baseUrl: requestedBaseUrl };
+  const sessionOptions = { strictBaseUrl: Boolean(requestedBaseUrl) };
+  let session = readSession(sessionMatch, sessionOptions);
+
+  if (!session || !session.token) {
+    // Auto-authenticate, but only when we can safely open a browser. In
+    // non-interactive contexts (CI, agent sandboxes) skip silently and let the
+    // invoked command surface its own auth guidance.
+    if (!process.stdout || !process.stdout.isTTY) {
+      return;
+    }
+    try {
+      await authCommand(flags); // authCommand syncs guides on success.
+    } catch (_) {
+      // Auth failed or was cancelled; leave guides untouched.
+    }
+    return;
+  }
+
+  const baseUrl = requestedBaseUrl || session.baseUrl || DEFAULT_BASE_URL;
+  await downloadAndSyncGuides(cwd, {
+    session,
+    baseUrl,
+    accountId: accountId || session.accountId
+  });
+
+  // Authenticated users also get the core Remits platform repo locally so they
+  // can analyze back-stage seams when diagnosing platform brittleness. Pull it
+  // up-to-date so analysis runs against current code.
+  try { ensurePlatformRepoLocal({ allowClone: true, pull: true }); } catch (_) { /* best-effort */ }
+}
+
+// ---------------------------------------------------------------------------
+// Remits platform repo (back stage)
+//
+// Anyone with a Remits auth account + remits-cli also gets the core platform
+// repo locally, so they can analyze back-stage seams (and open a fix PR) when a
+// front-stage failure turns out to be platform brittleness. The repo is tracked
+// in the account-repo inventory under the reserved `platform` key.
+// ---------------------------------------------------------------------------
+
+const PLATFORM_REPO_GIT_URL = process.env.REMITS_PLATFORM_GIT_URL || 'git@github.com:tmillhouse/remits.git';
+const PLATFORM_REPO_INVENTORY_KEY = 'platform';
+let PLATFORM_REPO_CLONE_ATTEMPTED = false;
+let PLATFORM_REPO_PULL_ATTEMPTED = false;
+
+function defaultPlatformRepoDir() {
+  const envDir = process.env.REMITS_PLATFORM_DIR;
+  if (envDir) {
+    return path.resolve(envDir);
+  }
+  return path.join(os.homedir(), 'remits');
+}
+
+function looksLikePlatformRepo(dir) {
+  if (!dir) {
+    return false;
+  }
+  try {
+    return fs.existsSync(path.join(dir, 'build.gradle'))
+      && fs.existsSync(path.join(dir, 'grails-app'))
+      && fs.existsSync(path.join(dir, 'cli', 'index.js'));
+  } catch (_) {
+    return false;
+  }
+}
+
+function getPlatformRepoEntry(index) {
+  const idx = index || readAccountRepoIndex();
+  const entry = idx[PLATFORM_REPO_INVENTORY_KEY];
+  return entry && entry.directory ? entry : null;
+}
+
+function setPlatformRepoEntry(directory, source) {
+  const index = readAccountRepoIndex();
+  index[PLATFORM_REPO_INVENTORY_KEY] = {
+    type: 'PLATFORM_REPO',
+    name: 'Remits Platform',
+    directory: path.resolve(directory),
+    gitUrl: PLATFORM_REPO_GIT_URL,
+    source: source || 'detected',
+    updatedAt: new Date().toISOString()
+  };
+  writeAccountRepoIndex(index);
+  return index[PLATFORM_REPO_INVENTORY_KEY];
+}
+
+// Fast-forward an existing platform repo so back-stage analysis runs against
+// up-to-date code. Best-effort and safe: skips a dirty tree (never clobbers
+// local work) and uses --ff-only so it no-ops rather than creating merge
+// commits when the branch has diverged. Runs at most once per process.
+function maybePullPlatformRepo(dir, options) {
+  if (!options || !options.pull || PLATFORM_REPO_PULL_ATTEMPTED) {
+    return;
+  }
+  PLATFORM_REPO_PULL_ATTEMPTED = true;
+  try {
+    const dirty = execSync('git -C ' + shellQuote(dir) + ' status --porcelain', { stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString().trim();
+    if (dirty) {
+      console.log('[platform] Skipping git pull: ' + dir + ' has uncommitted changes.');
+      return;
+    }
+    console.log('[platform] Updating Remits platform repo (git pull)...');
+    execSync('git -C ' + shellQuote(dir) + ' pull --ff-only', { stdio: 'inherit' });
+  } catch (err) {
+    console.log('[platform] git pull did not complete cleanly (leaving the repo as-is): ' + (err && err.message ? err.message : String(err)));
+  }
+}
+
+// Resolve the local platform repo, cloning it if necessary. Detection is cheap
+// and always runs; the (one-time, heavier) clone only runs when allowed and in
+// an interactive terminal so CI/agent sandboxes are never blocked on it. When
+// `options.pull` is set, an already-present repo is fast-forwarded so analysis
+// runs against current code.
+function ensurePlatformRepoLocal(options = {}) {
+  // 1. Already recorded and still present.
+  const recorded = getPlatformRepoEntry();
+  if (recorded && looksLikePlatformRepo(recorded.directory)) {
+    maybePullPlatformRepo(recorded.directory, options);
+    return recorded.directory;
+  }
+
+  // 2. Detect an existing local copy: env override, the running CLI source
+  //    (dev mode), or the default clone directory.
+  const candidates = [
+    process.env.REMITS_PLATFORM_DIR ? path.resolve(process.env.REMITS_PLATFORM_DIR) : null,
+    path.resolve(__dirname, '..'),
+    defaultPlatformRepoDir()
+  ].filter(Boolean);
+  for (const dir of candidates) {
+    if (looksLikePlatformRepo(dir)) {
+      setPlatformRepoEntry(dir, 'detected');
+      maybePullPlatformRepo(dir, options);
+      return dir;
+    }
+  }
+
+  // 3. Clone it (one-time, interactive only).
+  if (!options.allowClone || PLATFORM_REPO_CLONE_ATTEMPTED) {
+    return null;
+  }
+  if (!process.stdout || !process.stdout.isTTY) {
+    return null;
+  }
+  PLATFORM_REPO_CLONE_ATTEMPTED = true;
+
+  const target = defaultPlatformRepoDir();
+  if (fs.existsSync(target)) {
+    console.log('[platform] Skipping clone: ' + target + ' already exists but is not the Remits platform repo. Set REMITS_PLATFORM_DIR to its location.');
+    return null;
+  }
+  try {
+    console.log('[platform] Cloning Remits platform repo into ' + target + ' (one-time)...');
+    ensureDir(path.dirname(target));
+    execSync('git clone ' + shellQuote(PLATFORM_REPO_GIT_URL) + ' ' + shellQuote(target), { stdio: 'inherit' });
+  } catch (err) {
+    console.log('[platform] Could not clone the Remits platform repo automatically: ' + (err && err.message ? err.message : String(err)));
+    console.log('[platform] Clone it manually with: git clone ' + PLATFORM_REPO_GIT_URL + ' ' + target);
+    return null;
+  }
+  if (looksLikePlatformRepo(target)) {
+    setPlatformRepoEntry(target, 'cloned');
+    console.log('[platform] Remits platform repo available at ' + target);
+    return target;
+  }
+  return null;
+}
+
+// Account-repo inventory helpers that exclude the reserved platform entry, so
+// account-only consumers (dashboard, counts) never trip over it.
+function listAccountRepoEntries(index) {
+  const idx = index || readAccountRepoIndex();
+  return Object.values(idx).filter((entry) => entry && entry.directory && Number.isFinite(Number(entry.accountId)));
+}
+
+function countAccountRepos(index) {
+  return listAccountRepoEntries(index).length;
+}
+
+function mergeAccountRepoEntries(entries, options = {}) {
+  const nextIndex = options.existingIndex ? { ...options.existingIndex } : {};
+  for (const entry of entries) {
+    if (!entry || !entry.accountId || !entry.directory) {
+      continue;
+    }
+    nextIndex[String(entry.accountId)] = entry;
+  }
+  writeAccountRepoIndex(nextIndex);
+  return nextIndex;
+}
+
+function updateAccountRepoIndex(cwd) {
+  const info = loadAccountInfo(cwd);
+  if (!info) {
+    return;
+  }
+  try { syncInstalledSkills(); } catch (_) { /* best-effort */ }
+  const entry = buildAccountRepoEntryFromInfo(info, cwd, 'cwd');
+  if (!entry) {
+    return;
+  }
+  mergeAccountRepoEntries([entry], { existingIndex: readAccountRepoIndex() });
+}
+
+function defaultAccountScanRoots() {
+  const envRoots = String(process.env.REMITS_CLI_SCAN_ROOTS || '')
+    .split(path.delimiter)
+    .map((value) => value.trim())
+    .filter(Boolean);
+  if (envRoots.length) {
+    return envRoots.filter((dir) => fs.existsSync(dir));
+  }
+  const home = os.homedir();
+  return [home].filter((dir) => fs.existsSync(dir));
+}
+
+function walkForAccountInfo(dir, depth, matches, visited, platformMatches) {
+  const resolvedDir = path.resolve(dir);
+  if (visited.has(resolvedDir)) {
+    return;
+  }
+  visited.add(resolvedDir);
+
+  let entries;
+  try {
+    entries = fs.readdirSync(resolvedDir, { withFileTypes: true });
+  } catch (_) {
+    return;
+  }
+
+  const names = new Set(entries.map((entry) => entry.name));
+  for (const entry of entries) {
+    if (entry.isFile() && entry.name === 'account-info.json') {
+      matches.push(path.join(resolvedDir, entry.name));
+    }
+  }
+  // Cheap marker check from the directory listing we already read — detect the
+  // Remits platform repo so it lands in the inventory even though it has no
+  // account-info.json.
+  if (platformMatches && names.has('build.gradle') && names.has('grails-app')
+      && names.has('settings.gradle') && names.has('cli')) {
+    platformMatches.push(resolvedDir);
+  }
+
+  if (depth >= DEFAULT_SCAN_MAX_DEPTH) {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) {
+      continue;
+    }
+    if (ACCOUNT_SCAN_EXCLUDE_DIRS.has(entry.name)) {
+      continue;
+    }
+    if (entry.name.startsWith('.') && entry.name !== '.config') {
+      continue;
+    }
+    walkForAccountInfo(path.join(resolvedDir, entry.name), depth + 1, matches, visited, platformMatches);
+  }
+}
+
+function discoverAccountRepos() {
+  const matches = [];
+  const platformMatches = [];
+  const visited = new Set();
+  const roots = defaultAccountScanRoots();
+  for (const root of roots) {
+    walkForAccountInfo(root, 0, matches, visited, platformMatches);
+  }
+  try { syncInstalledSkills(); } catch (_) { /* best-effort */ }
+
+  const entries = [];
+  for (const file of matches) {
+    try {
+      const repoDir = path.dirname(file);
+      const info = JSON.parse(fs.readFileSync(file, 'utf8'));
+      const entry = buildAccountRepoEntryFromInfo(info, repoDir, 'scan');
+      if (entry) {
+        entries.push(entry);
+      }
+    } catch (_) {
+      // Skip invalid files during discovery.
+    }
+  }
+
+  // Record an already-present platform repo from the scan if one isn't tracked
+  // yet; otherwise fall back to detection/clone.
+  if (!getPlatformRepoEntry()) {
+    const found = platformMatches.find(looksLikePlatformRepo);
+    if (found) {
+      setPlatformRepoEntry(found, 'scan');
+    } else {
+      try { ensurePlatformRepoLocal({ allowClone: true }); } catch (_) { /* best-effort */ }
+    }
+  }
+
+  const index = mergeAccountRepoEntries(entries, { existingIndex: readAccountRepoIndex() });
+  return {
+    roots,
+    matches: matches.length,
+    repoCount: countAccountRepos(index),
+    entries: index,
+    scannedAt: new Date().toISOString()
+  };
+}
+
+function resolvePreferredAccountId(cwd, flags, session) {
+  // Explicit --account-id wins over the repo's account-info.json so users can
+  // target a child account (e.g. a customer) from a parent-account repo.
+  const fromFlag = Number(flags && flags['account-id']);
+  if (Number.isFinite(fromFlag) && fromFlag > 0) {
+    return fromFlag;
+  }
+
+  try {
+    const fromRepo = loadAccountId(cwd);
+    if (Number.isFinite(fromRepo) && fromRepo > 0) {
+      try { updateAccountRepoIndex(cwd); } catch (_) { /* best-effort */ }
+      return fromRepo;
+    }
+  } catch (_) {
+    // Fall back to session when not in an account repo.
+  }
+
+  if (session && session.accountId) {
+    const fromSession = Number(session.accountId);
+    if (Number.isFinite(fromSession) && fromSession > 0) {
+      return fromSession;
+    }
+  }
+
+  throw new Error('Unable to resolve account id. Use an account repo with account-info.json or pass --account-id.');
+}
+
+function resolveSessionContext(cwd, flags) {
+  // Explicit --account-id wins over the repo's account-info.json so users can
+  // target a child account (e.g. a customer) from a parent-account repo.
+  let accountId = null;
+  const fromFlag = Number(flags && flags['account-id']);
+  if (Number.isFinite(fromFlag) && fromFlag > 0) {
+    accountId = fromFlag;
+  }
+
+  if (!accountId) {
+    try {
+      accountId = loadAccountId(cwd);
+      try { updateAccountRepoIndex(cwd); } catch (_) { /* best-effort */ }
+    } catch (_) { /* not in an account repo */ }
+  }
+
+  const requestedBaseUrl = flags && flags['base-url'] ? normalizeBaseUrl(flags['base-url']) : null;
+  const session = readSession({
+    accountId,
+    baseUrl: requestedBaseUrl,
+    dataMode: hasExplicitDataModeFlag(flags) ? resolveDataMode(flags, null) : null
+  }, {
+    strictBaseUrl: Boolean(requestedBaseUrl)
+  });
+  if (!session || !session.token) {
+    if (accountId && requestedBaseUrl) {
+      throw new Error('Not authenticated for account ' + accountId + ' at ' + requestedBaseUrl + '. Run: remits-cli auth --base-url ' + requestedBaseUrl + ' --account-id ' + accountId);
+    }
+    throw new Error('Not authenticated. Run: remits-cli auth');
+  }
+
+  // Final accountId resolution: flag > repo > session
+  if (!accountId) {
+    accountId = session.accountId;
+  }
+
+  return { session, accountId };
+}
+
+function collectComponents(cwd) {
+  const mapping = {
+    schemas: 'schema',
+    readers: 'reader',
+    actions: 'action',
+    embeddables: 'embeddable',
+    rules: 'rule',
+    templates: 'htmltemplate',
+    agents: 'utility',
+    tools: 'tool',
+    prompts: 'prompt',
+    tests: 'test'
+  };
+
+  const byKey = new Map();
+  for (const dirName of Object.keys(mapping)) {
+    const type = mapping[dirName];
+    const dir = path.join(cwd, 'components', dirName);
+    if (!fs.existsSync(dir)) {
+      continue;
+    }
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile());
+    for (const entry of entries) {
+      const fileName = entry.name;
+      const metaMatch = fileName.match(/^(.+?)_(.+)\.meta\.ya?ml$/i);
+      const match = metaMatch || fileName.match(/^(.+?)_(.+)\.([^.]+)$/);
+      if (!match) {
+        continue;
+      }
+      const prefix = match[1];
+      const rawName = match[2];
+      const ext = metaMatch ? 'meta' : match[3].toLowerCase();
+      const id = /^\d+$/.test(prefix) ? Number(prefix) : null;
+      const name = prefix.startsWith('new') || !id ? normalizeName(rawName) : normalizeName(rawName);
+      const key = type + ':' + (id ? 'id:' + id : 'name:' + name.toLowerCase());
+
+      if (!byKey.has(key)) {
+        byKey.set(key, { type, id, name });
+      }
+      const component = byKey.get(key);
+      const filePath = path.join(dir, fileName);
+      const content = fs.readFileSync(filePath, 'utf8');
+
+      if (ext === 'meta') {
+        try {
+          const meta = YAML.parse(content);
+          if (meta && typeof meta === 'object' && !Array.isArray(meta)) {
+            for (const [metaKey, metaValue] of Object.entries(meta)) {
+              if (metaKey === 'type') {
+                component.metaType = metaValue;
+              } else {
+                component[metaKey] = metaValue;
+              }
+            }
+          }
+        } catch (err) {
+          throw new Error('Failed to parse component metadata ' + filePath + ': ' + err.message);
+        }
+      } else if (type === 'utility' && ext === 'md') {
+        component.prompt = content;
+      } else if (type === 'prompt' && ext === 'md') {
+        component.prompt = content;
+      } else if (ext === 'groovy' || ext === 'md') {
+        component.source = content;
+      } else if (type === 'embeddable' && ext === 'html') {
+        component.html = content;
+      } else if (type === 'embeddable' && ext === 'js') {
+        component.javascript = content;
+      } else if (type === 'htmltemplate' && ext === 'html') {
+        component.html = content;
+      } else if (type === 'htmltemplate' && ext === 'json') {
+        component.previewData = content;
+      } else if (type === 'tool' && ext === 'json') {
+        component.inputSchema = content;
+      } else if (type === 'schema' && ext === 'json') {
+        component.schema = content;
+      }
+    }
+  }
+
+  const components = [];
+  for (const component of byKey.values()) {
+    const fingerprint = {};
+    Object.keys(component).sort().forEach((key) => {
+      if (key !== 'hash') {
+        fingerprint[key] = component[key] == null ? null : component[key];
+      }
+    });
+    component.hash = sha256(stableStringify(fingerprint));
+    components.push(component);
+  }
+
+  return components;
+}
+
+function buildAxios(baseUrl, token) {
+  const headers = token ? { Authorization: 'Bearer ' + token } : {};
+  return axios.create({ baseURL: baseUrl, timeout: 60000, headers });
+}
+
+function describeError(err) {
+  if (!err) {
+    return 'Unknown error';
+  }
+  const parts = [];
+  if (err.response && err.response.data) {
+    const responseData = err.response.data;
+    if (responseData.message) {
+      parts.push(String(responseData.message));
+    } else if (typeof responseData === 'string') {
+      parts.push(responseData);
+    }
+  }
+  if (err.message) {
+    parts.push(String(err.message));
+  }
+  if (Array.isArray(err.errors)) {
+    for (const nested of err.errors) {
+      if (nested && nested.message) {
+        parts.push(String(nested.message));
+      } else if (nested) {
+        parts.push(String(nested));
+      }
+    }
+  }
+  if (err.code) {
+    parts.push(String(err.code));
+  }
+  const unique = [];
+  for (const part of parts.map((value) => value.trim()).filter(Boolean)) {
+    if (!unique.includes(part)) {
+      unique.push(part);
+    }
+  }
+  if (unique.length) {
+    return unique.join(' | ');
+  }
+  if (err.name) {
+    return String(err.name);
+  }
+  return String(err);
+}
+
+function isLikelySandboxNetworkError(err) {
+  const networkCodes = ['ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EHOSTUNREACH', 'ENETUNREACH', 'EPERM'];
+  const directCode = err && err.code ? String(err.code).toUpperCase() : '';
+  if (networkCodes.includes(directCode)) {
+    return true;
+  }
+  if (Array.isArray(err && err.errors)) {
+    return err.errors.some((nested) => {
+      const nestedCode = nested && nested.code ? String(nested.code).toUpperCase() : '';
+      return networkCodes.includes(nestedCode);
+    });
+  }
+  return false;
+}
+
+function sandboxNetworkHint(err) {
+  if (!isLikelySandboxNetworkError(err)) return '';
+  const baseUrl = err && err.config && err.config.baseURL ? err.config.baseURL : DEFAULT_BASE_URL;
+  return ' Network access to ' + baseUrl + ' appears unavailable from the current sandbox. If remits-cli is being run by a local AI agent (for example Codex in tmux), retry the command with escalated permissions or outside the sandbox.';
+}
+
+function saveToolsSnapshot(cwd, data) {
+  const paths = ensureLocalState(cwd);
+  const file = path.join(paths.toolsDir, 'tools.json');
+  fs.writeFileSync(file, JSON.stringify(data, null, 2));
+  return file;
+}
+
+async function loggedPost(api, cwd, endpoint, payload, options = {}) {
+  const requestId = options.requestId || crypto.randomUUID();
+  const started = Date.now();
+  let responseData = null;
+  let error = null;
+  let responseFile = null;
+
+  try {
+    responseData = await api.post(endpoint, payload).then((r) => r.data);
+    if (options.toolResponseFile) {
+      const callId = options.toolCallId || (responseData && responseData.callId) || requestId;
+      responseFile = writeToolResponseFile(cwd, callId, responseData);
+    }
+    return { data: responseData, requestId, responseFile };
+  } catch (err) {
+    responseData = err && err.response ? err.response.data : null;
+    error = err;
+    throw err;
+  } finally {
+    const status = error ? 'error' : 'success';
+    const responseForLog = responseFile
+      ? { responseFile, note: 'Tool response stored externally' }
+      : sanitizeForLog(responseData);
+    appendSessionLog(cwd, {
+      ts: new Date().toISOString(),
+      requestId,
+      endpoint,
+      method: 'POST',
+      status,
+      durationMs: Date.now() - started,
+      request: sanitizeForLog(payload),
+      response: responseForLog,
+      error: error ? describeError(error) : null
+    });
+  }
+}
+
+async function loggedGet(api, cwd, endpoint, params = {}) {
+  const requestId = crypto.randomUUID();
+  const started = Date.now();
+  let responseData = null;
+  let error = null;
+  try {
+    responseData = await api.get(endpoint, { params }).then((r) => r.data);
+    return { data: responseData, requestId };
+  } catch (err) {
+    responseData = err && err.response ? err.response.data : null;
+    error = err;
+    throw err;
+  } finally {
+    appendSessionLog(cwd, {
+      ts: new Date().toISOString(),
+      requestId,
+      endpoint,
+      method: 'GET',
+      status: error ? 'error' : 'success',
+      durationMs: Date.now() - started,
+      request: sanitizeForLog(params),
+      response: sanitizeForLog(responseData),
+      error: error ? describeError(error) : null
+    });
+  }
+}
+
+function resolveSkillTargets(target) {
+  const value = String(target || 'all').toLowerCase();
+  const home = os.homedir();
+  const targets = {
+    codex: path.join(home, '.codex', 'skills', 'remits-cli', 'SKILL.md'),
+    claude: path.join(home, '.claude', 'skills', 'remits-cli', 'SKILL.md'),
+    gemini: path.join(home, '.gemini', 'skills', 'remits-cli.md')
+  };
+
+  if (value === 'all') {
+    return Object.entries(targets);
+  }
+  if (!targets[value]) {
+    throw new Error('Unknown --target value: ' + target + ' (expected codex|claude|gemini|all)');
+  }
+  return [[value, targets[value]]];
+}
+
+function buildSkillSourceBody() {
+  if (!fs.existsSync(SKILL_SOURCE_FILE)) {
+    throw new Error('Skill source file not found: ' + SKILL_SOURCE_FILE);
+  }
+
+  let sourceBody = fs.readFileSync(SKILL_SOURCE_FILE, 'utf8');
+  sourceBody = sourceBody.replace('{{ACCOUNT_REPO_INDEX_PATH}}', ACCOUNT_REPO_INDEX_FILE);
+  return sourceBody;
+}
+
+function syncInstalledSkills(target = 'all') {
+  const targets = resolveSkillTargets(target);
+  const sourceBody = buildSkillSourceBody();
+  const summary = {
+    updated: [],
+    failed: []
+  };
+
+  for (const [agent, targetPath] of targets) {
+    try {
+      ensureDir(path.dirname(targetPath));
+      if (writeFileIfChanged(targetPath, sourceBody)) {
+        summary.updated.push({ agent, path: targetPath });
+      }
+    } catch (error) {
+      summary.failed.push({
+        agent,
+        path: targetPath,
+        reason: error && error.message ? error.message : String(error)
+      });
+    }
+  }
+
+  return summary;
+}
+
+async function installSkillsCommand(flags) {
+  if (!flags.skills) {
+    throw new Error('Missing --skills flag. Usage: remits-cli install --skills');
+  }
+
+  const overwrite = flags.overwrite === true || flags.overwrite === 'true';
+  const targets = resolveSkillTargets(flags.target || 'all');
+  const sourceBody = buildSkillSourceBody();
+
+  const installed = [];
+  const skipped = [];
+
+  for (const [agent, targetPath] of targets) {
+    ensureDir(path.dirname(targetPath));
+    if (fs.existsSync(targetPath) && !overwrite) {
+      skipped.push({ agent, path: targetPath, reason: 'already exists (use --overwrite true)' });
+      continue;
+    }
+    atomicWriteFile(targetPath, sourceBody);
+    installed.push({ agent, path: targetPath });
+  }
+
+  console.log('Skill installation complete.');
+  if (installed.length) {
+    console.log('Installed:');
+    for (const item of installed) {
+      console.log(' -', item.agent + ':', item.path);
+    }
+  }
+  if (skipped.length) {
+    console.log('Skipped:');
+    for (const item of skipped) {
+      console.log(' -', item.agent + ':', item.path, '(' + item.reason + ')');
+    }
+  }
+}
+
+async function authCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  // Explicit --account-id wins over the repo's account-info.json so users can
+  // authenticate into a child account from a parent-account repo.
+  let preAccountId = null;
+  const fromFlag = Number(flags['account-id']);
+  if (Number.isFinite(fromFlag) && fromFlag > 0) preAccountId = fromFlag;
+  if (!preAccountId) {
+    try { preAccountId = loadAccountId(cwd); } catch (_) { /* not in repo */ }
+  }
+  const explicitBaseUrl = flags['base-url'] ? normalizeBaseUrl(flags['base-url']) : null;
+  const existingSession = readSession({
+    accountId: preAccountId,
+    baseUrl: explicitBaseUrl
+  }, {
+    strictBaseUrl: Boolean(explicitBaseUrl)
+  }) || {};
+  const dataMode = resolveDataMode(flags, existingSession);
+  const baseUrl = explicitBaseUrl || normalizeBaseUrl(existingSession.baseUrl || DEFAULT_BASE_URL);
+  const accountId = preAccountId || resolvePreferredAccountId(cwd, flags, {});
+  const preferredPort = Number(flags.port || 8765);
+  const state = crypto.randomUUID();
+  const callback = await new Promise((resolve, reject) => {
+    const createServer = () => {
+      const server = http.createServer((req, res) => {
+        const requestPort = server.address() && typeof server.address() === 'object'
+          ? server.address().port
+          : preferredPort;
+        const reqUrl = new URL(req.url, 'http://localhost:' + requestPort);
+        if (reqUrl.pathname !== '/callback') {
+          res.statusCode = 404;
+          res.end('Not found');
+          return;
+        }
+
+        const payload = {
+          token: reqUrl.searchParams.get('token'),
+          state: reqUrl.searchParams.get('state'),
+          userId: reqUrl.searchParams.get('userId'),
+          userUuid: reqUrl.searchParams.get('userUuid')
+        };
+
+        res.statusCode = 200;
+        res.setHeader('Content-Type', 'text/html');
+        res.end('<html><body><h2>Remits CLI Auth Complete</h2><p>You can close this tab.</p></body></html>');
+        server.close();
+        callbackPromiseResolve(payload);
+      });
+
+      let callbackPromiseResolve;
+      const callbackPromise = new Promise((resolvePayload) => {
+        callbackPromiseResolve = resolvePayload;
+      });
+
+      const listen = (port, allowFallback) => {
+        server.once('error', (err) => {
+          if (allowFallback && err && err.code === 'EADDRINUSE') {
+            const fallbackServer = createServer();
+            fallbackServer.listen(0, false);
+            return;
+          }
+          reject(err);
+        });
+
+        server.listen(port, '127.0.0.1', () => {
+          const address = server.address();
+          const boundPort = address && typeof address === 'object' ? address.port : port;
+          resolve({
+            port: boundPort,
+            callbackPromise
+          });
+        });
+      };
+
+      return { listen };
+    };
+
+    createServer().listen(preferredPort, true);
+  });
+  const port = callback.port;
+  const redirectUri = 'http://localhost:' + port + '/callback';
+  if (port !== preferredPort) {
+    console.log('Preferred auth callback port', preferredPort, 'is unavailable. Using', port);
+  }
+
+  const params = new URLSearchParams();
+  params.set('redirect_uri', redirectUri);
+  params.set('state', state);
+  if (accountId) {
+    params.set('accountId', String(accountId));
+  }
+  params.set('dataMode', dataMode);
+
+  const loginUrl = baseUrl.replace(/\/$/, '') + '/cli/auth?' + params.toString();
+  console.log('Opening browser for auth:', loginUrl);
+  if (openBrowser) {
+    await openBrowser(loginUrl);
+  } else {
+    console.log('Browser auto-open is unavailable. Open this URL manually:', loginUrl);
+  }
+
+  const timeoutPromise = new Promise((_, reject) =>
+    setTimeout(() => reject(new Error('Auth callback timeout (120s)')), 120000)
+  );
+  const result = await Promise.race([callback.callbackPromise, timeoutPromise]);
+
+  if (result.state !== state) {
+    throw new Error('Invalid auth callback state');
+  }
+
+  const api = buildAxios(baseUrl, result.token);
+  const me = await loggedGet(api, cwd, '/cli/auth', {
+    accountId: accountId || undefined,
+    dataMode
+  }).then((r) => r.data);
+
+  const resolvedAccountId = me.account ? me.account.id : Number(accountId);
+  const session = {
+    ...existingSession,
+    baseUrl,
+    token: result.token,
+    accountId: resolvedAccountId,
+    user: me.user,
+    websocketTopic: me.websocketTopic,
+    dataMode: normalizeDataMode(me.dataMode || dataMode),
+    updatedAt: new Date().toISOString()
+  };
+
+  writeSession(resolvedAccountId, session, {
+    baseUrl,
+    dataMode: session.dataMode
+  });
+  console.log('Authenticated as user', session.user ? session.user.id : 'unknown', 'for account', session.accountId);
+  console.log('Data mode:', session.dataMode);
+
+  try {
+    const toolsData = await loggedPost(api, cwd, '/cli/tools', {
+      token: session.token,
+      accountId: session.accountId,
+      dataMode: session.dataMode
+    }).then((r) => r.data);
+    if (toolsData && toolsData.success) {
+      const toolsFile = saveToolsSnapshot(cwd, {
+        accountId: session.accountId,
+        dataMode: toolsData.dataMode || session.dataMode,
+        fetchedAt: new Date().toISOString(),
+        tools: toolsData.tools || []
+      });
+      console.log('Tools cached at:', toolsFile);
+    }
+  } catch (err) {
+    console.log('Warning: failed to refresh tools after auth:', err.message);
+  }
+
+  // Download the latest front-stage guides and write them into the repo now
+  // that we hold an authenticated session.
+  try {
+    const guideSummary = await downloadAndSyncGuides(cwd, {
+      session,
+      baseUrl,
+      accountId: session.accountId
+    });
+    if (guideSummary && guideSummary.updated && guideSummary.updated.length) {
+      console.log('Guides updated:', guideSummary.updated.length, 'file(s)');
+    }
+  } catch (_) { /* best-effort */ }
+
+  // Ensure the core Remits platform repo is available locally for back-stage
+  // analysis (clone on first authenticated run if missing) and pull it
+  // up-to-date.
+  try { ensurePlatformRepoLocal({ allowClone: true, pull: true }); } catch (_) { /* best-effort */ }
+
+  // Auto-start the background WebSocket listener after successful auth
+  if (!isListenerRunning()) {
+    try {
+      const dashboardUrl = await autoStartServiceIfNeeded();
+      if (dashboardUrl) {
+        console.log('[service] Auto-started in background');
+        console.log('[service] Dashboard:', dashboardUrl);
+      } else {
+        console.log('[service] Auto-start attempt did not stay running. Use `remits-cli start` to inspect startup issues.');
+      }
+    } catch (_) { /* best-effort */ }
+  }
+}
+
+async function pushComponentsCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const { session, accountId } = resolveSessionContext(cwd, flags);
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const branchName = flags.branch || currentBranch(cwd);
+  const dataMode = resolveDataMode(flags, session);
+  const requestedMode = String(flags.mode || 'stage').toLowerCase();
+  const mode = requestedMode === 'push' ? 'stage' : requestedMode;
+  const components = collectComponents(cwd);
+
+  if (requestedMode === 'push') {
+    console.log('Warning: `components push` is deprecated and currently behaves the same as `components stage`.');
+  }
+
+  const api = buildAxios(baseUrl, session.token);
+  const response = await loggedPost(api, cwd, '/cli/components', {
+    token: session.token,
+    accountId,
+    branchName,
+    dataMode,
+    mode,
+    components
+  }).then((r) => r.data);
+
+  console.log('Data mode:', response.dataMode || dataMode);
+  console.log('Mode:', response.mode || mode);
+  console.log('Components sync:', JSON.stringify(response, null, 2));
+}
+
+async function syncComponentsCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const { session, accountId } = resolveSessionContext(cwd, flags);
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const branchName = flags.branch || currentBranch(cwd);
+  const dataMode = resolveDataMode(flags, session);
+  const api = buildAxios(baseUrl, session.token);
+
+  const response = await loggedPost(api, cwd, '/cli/components', {
+    token: session.token,
+    accountId,
+    branchName,
+    dataMode,
+    mode: 'sync',
+    components: []
+  }).then((r) => r.data);
+
+  if (!response.success) {
+    throw new Error(response.message || 'Server sync failed');
+  }
+
+  console.log('Data mode:', response.dataMode || dataMode);
+  console.log('Mode:', response.mode || 'sync');
+  console.log('Components sync:', JSON.stringify(response, null, 2));
+  return response;
+}
+
+async function commitComponentsCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const { accountId } = resolveSessionContext(cwd, flags);
+  const branchName = flags.branch || currentBranch(cwd);
+  const commitMessage = String(flags.message || ('remits-cli commit sync ' + new Date().toISOString()));
+  const allowEmpty = flags['allow-empty'] === true || flags['allow-empty'] === 'true';
+  const skipGit = flags['skip-git'] === true || flags['skip-git'] === 'true';
+
+  if (!skipGit) {
+    console.log('Phase 1/3: local git commit/push');
+    const status = runGit(cwd, 'git status --porcelain');
+    if (status || allowEmpty) {
+      runGit(cwd, 'git add -A');
+      const commitCmd = 'git commit ' + (allowEmpty ? '--allow-empty ' : '') + '-m ' + shellQuote(commitMessage);
+      try {
+        runGit(cwd, commitCmd);
+      } catch (err) {
+        if (!allowEmpty && String(err.message || '').toLowerCase().includes('nothing to commit')) {
+          console.log('No staged changes to commit.');
+        } else {
+          throw err;
+        }
+      }
+    } else {
+      console.log('No local changes detected; skipping local git commit.');
+    }
+
+    try {
+      runGit(cwd, 'git push origin ' + shellQuote(branchName));
+    } catch (err) {
+      runGit(cwd, 'git push --set-upstream origin ' + shellQuote(branchName));
+    }
+  } else {
+    console.log('Skipping local git phase. Prefer `remits-cli components sync` if you only need the server sync step.');
+  }
+
+  console.log('Phase 2/3: server sync');
+  const syncResponse = await syncComponentsCommand({
+    ...flags,
+    branch: branchName,
+    'account-id': accountId
+  });
+
+  if (!skipGit) {
+    console.log('Phase 3/3: local fast-forward pull');
+    runGit(cwd, 'git fetch origin ' + shellQuote(branchName));
+    const expectedSha = syncResponse && syncResponse.sync && syncResponse.sync.postSyncSha;
+    if (expectedSha) {
+      const fetchedSha = currentHeadSha(cwd, 'origin/' + branchName);
+      if (fetchedSha !== expectedSha) {
+        throw new Error(
+          'Remote branch head changed after sync. Expected ' + expectedSha + ' from remits sync, but origin/' + branchName + ' is ' + fetchedSha + '. Stop and investigate before pulling.'
+        );
+      }
+      console.log('Verified remote branch head:', expectedSha);
+    }
+    runGit(cwd, 'git pull --ff-only origin ' + shellQuote(branchName));
+    if (expectedSha) {
+      const localSha = currentHeadSha(cwd);
+      if (localSha !== expectedSha) {
+        throw new Error(
+          'Local HEAD does not match remits sync SHA after pull. Expected ' + expectedSha + ', got ' + localSha + '.'
+        );
+      }
+      console.log('Verified local HEAD matches remits sync SHA:', expectedSha);
+    }
+  }
+}
+
+function webSocketUrl(baseUrl) {
+  const u = new URL(baseUrl);
+  const wsProtocol = u.protocol === 'https:' ? 'wss:' : 'ws:';
+  return wsProtocol + '//' + u.host + '/stomp';
+}
+
+async function waitForStatus(api, cwd, accountId, branchName, taskId, token, dataMode) {
+  let pollDelayMs = 1000;
+  while (true) {
+    const status = await loggedPost(api, cwd, '/cli/test', {
+      token,
+      command: 'status',
+      accountId,
+      branchName,
+      taskId,
+      dataMode
+    }).then((r) => r.data);
+
+    if (status.status === 'completed' || status.status === 'failed') {
+      return status;
+    }
+    await new Promise((r) => setTimeout(r, pollDelayMs));
+    pollDelayMs = Math.min(5000, pollDelayMs + 500);
+  }
+}
+
+function watchWebsocket(baseUrl, topicId, taskId) {
+  const client = new Client({
+    brokerURL: webSocketUrl(baseUrl),
+    reconnectDelay: 3000,
+    heartbeatIncoming: 10000,
+    heartbeatOutgoing: 10000,
+    debug: () => {}
+  });
+
+  client.onConnect = () => {
+    client.subscribe('/topic/messages/' + topicId, (msg) => {
+      try {
+        const data = JSON.parse(msg.body);
+        if (data.type === 'TestSuite') {
+          const payload = data.payload || {};
+          if (payload.taskId && taskId && payload.taskId !== taskId) {
+            return;
+          }
+          if (payload.tests || payload.name || payload.total != null) {
+            console.log('[ws][TestSuite]', JSON.stringify(payload));
+          }
+        }
+      } catch (err) {
+        console.error('[ws] parse error:', err.message);
+      }
+    });
+  };
+
+  client.activate();
+  return () => {
+    client.deactivate();
+  };
+}
+
+async function testCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const { session, accountId } = resolveSessionContext(cwd, flags);
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const branchName = flags.branch || currentBranch(cwd);
+  const dataMode = resolveDataMode(flags, session);
+  const testRef = flags.test || flags['test-id'] || flags.name;
+
+  if (!testRef) {
+    throw new Error('Missing --test <id-or-name>');
+  }
+
+  const names = flags.names ? String(flags.names).split(',').map((s) => s.trim()).filter(Boolean) : [];
+
+  const api = buildAxios(baseUrl, session.token);
+  const start = await loggedPost(api, cwd, '/cli/test', {
+    token: session.token,
+    accountId,
+    branchName,
+    dataMode,
+    testId: /^\d+$/.test(String(testRef)) ? Number(testRef) : undefined,
+    testName: /^\d+$/.test(String(testRef)) ? undefined : String(testRef),
+    tests: names
+  }).then((r) => r.data);
+
+  if (!start.success) {
+    throw new Error('Failed to start test run');
+  }
+
+  console.log('Test run started:', start.taskId);
+  runtimeState.currentTestTaskId = start.taskId;
+
+  let stopWs = null;
+  if (flags.watch !== 'false') {
+    const topic = session.websocketTopic || start.websocketTopic || (session.user && String(session.user.uuid || '').replace(/-/g, ''));
+    if (topic) {
+      stopWs = watchWebsocket(baseUrl, topic, start.taskId);
+    }
+  }
+
+  const status = await waitForStatus(api, cwd, accountId, branchName, start.taskId, session.token, dataMode);
+  if (stopWs) {
+    stopWs();
+  }
+  if (runtimeState.currentTestTaskId === start.taskId) {
+    runtimeState.currentTestTaskId = null;
+  }
+
+  console.log('Final status:', JSON.stringify(status, null, 2));
+  if (status.status !== 'completed') {
+    process.exitCode = 1;
+  } else if (status.result && status.result.failed > 0) {
+    process.exitCode = 1;
+  }
+}
+
+async function tokenCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const { session, accountId } = resolveSessionContext(cwd, flags);
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const branchName = flags.branch || currentBranch(cwd);
+  const dataMode = resolveDataMode(flags, session);
+
+  const api = buildAxios(baseUrl, session.token);
+  const data = await loggedPost(api, cwd, '/cli/token', {
+    token: session.token,
+    accountId,
+    branchName,
+    dataMode
+  }).then((r) => r.data);
+
+  if (!data.success) {
+    throw new Error('Failed to generate token key');
+  }
+
+  const base = baseUrl.replace(/\/$/, '');
+  const embeddablePath = flags.path || flags['embeddable-path'];
+  const embeddableUrl = embeddablePath
+    ? (base + '/s/' + data.tokenKey + '/' + String(embeddablePath).replace(/^\/+/, ''))
+    : null;
+
+  const output = {
+    success: true,
+    tokenKey: data.tokenKey,
+    accountId: data.accountId,
+    branchName: data.branchName,
+    dataMode: data.dataMode || dataMode,
+    shortBasePath: data.shortBasePath,
+    embeddableUrl
+  };
+
+  console.log(JSON.stringify(output, null, 2));
+}
+
+async function toolsCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const { session, accountId } = resolveSessionContext(cwd, flags);
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const dataMode = resolveDataMode(flags, session);
+  const api = buildAxios(baseUrl, session.token);
+
+  const data = await loggedPost(api, cwd, '/cli/tools', {
+    token: session.token,
+    accountId,
+    dataMode
+  }).then((r) => r.data);
+
+  if (!data.success) {
+    throw new Error('Failed to fetch tools');
+  }
+
+  const toolsFile = saveToolsSnapshot(cwd, {
+    accountId,
+    dataMode: data.dataMode || dataMode,
+    fetchedAt: new Date().toISOString(),
+    tools: data.tools || []
+  });
+
+  console.log('Tools refreshed.');
+  console.log('Data mode:', data.dataMode || dataMode);
+  console.log('Tools file:', toolsFile);
+  console.log('Tool count:', (data.tools || []).length);
+}
+
+function parseToolInput(flags) {
+  if (flags['input-file']) {
+    const file = path.resolve(process.cwd(), String(flags['input-file']));
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  }
+  if (flags.input) {
+    return JSON.parse(String(flags.input));
+  }
+  return {};
+}
+
+async function toolCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const { session, accountId } = resolveSessionContext(cwd, flags);
+
+  const toolName = flags.name || flags.tool;
+  if (!toolName) {
+    throw new Error('Missing --name <toolName>');
+  }
+
+  // Signal whether --account-id was explicitly passed so the server can apply
+  // the correct precedence: explicit flag > input.accountId > session default.
+  const explicitFlagAccountId = Number(flags && flags['account-id']);
+  const accountIdExplicit = Number.isFinite(explicitFlagAccountId) && explicitFlagAccountId > 0;
+
+  const input = parseToolInput(flags);
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const branchName = flags.branch || currentBranch(cwd);
+  const dataMode = resolveDataMode(flags, session);
+  const callId = crypto.randomUUID();
+  const api = buildAxios(baseUrl, session.token);
+
+  const response = await loggedPost(api, cwd, '/cli/tool', {
+    token: session.token,
+    accountId,
+    accountIdExplicit,
+    branchName,
+    dataMode,
+    name: String(toolName),
+    input,
+    callId
+  }, { toolResponseFile: true, toolCallId: callId });
+
+  const data = response.data;
+  if (!data.success) {
+    throw new Error(data.message || 'Tool execution failed');
+  }
+
+  console.log('Tool call succeeded.');
+  console.log('Call ID:', callId);
+  console.log('Data mode:', dataMode);
+  console.log('Session log:', sessionJsonlFile(cwd));
+  console.log('Tool response file:', response.responseFile);
+}
+
+async function dataModeCommand(flags, subcommand) {
+  const cwd = process.cwd();
+  // Explicit --account-id wins over the repo's account-info.json.
+  let accountId = null;
+  const fromFlag = Number(flags && flags['account-id']);
+  if (Number.isFinite(fromFlag) && fromFlag > 0) accountId = fromFlag;
+  if (!accountId) {
+    try { accountId = loadAccountId(cwd); } catch (_) { /* not in repo */ }
+  }
+  const requestedBaseUrl = flags && flags['base-url'] ? normalizeBaseUrl(flags['base-url']) : null;
+  const session = readSession({
+    accountId,
+    baseUrl: requestedBaseUrl
+  }, {
+    strictBaseUrl: Boolean(requestedBaseUrl)
+  }) || {};
+  if (!accountId && session.accountId) accountId = session.accountId;
+
+  const nextMode = flags.mode || flags.value || flags._[2];
+  if (subcommand === 'set') {
+    if (!nextMode) {
+      throw new Error('Missing mode. Use: remits-cli data-mode set test|prod');
+    }
+    if (!accountId) {
+      throw new Error('Unable to resolve account. Run from an account repo or pass --account-id.');
+    }
+    const dataMode = normalizeDataMode(nextMode);
+    writeSession(accountId, {
+      ...session,
+      dataMode,
+      updatedAt: new Date().toISOString()
+    }, {
+      baseUrl: requestedBaseUrl || session.baseUrl || DEFAULT_BASE_URL,
+      dataMode
+    });
+    console.log('Data mode set to:', dataMode, 'for account', accountId, 'at', normalizeBaseUrl(requestedBaseUrl || session.baseUrl || DEFAULT_BASE_URL));
+    return;
+  }
+
+  const currentMode = resolveDataMode(flags, session);
+  console.log(JSON.stringify({ dataMode: currentMode, accountId: accountId || undefined }, null, 2));
+}
+
+// --- Session migration: convert old session.json to sessions.json ---
+function migrateSessionIfNeeded() {
+  const oldFile = path.join(SESSION_DIR, 'session.json');
+  if (!fs.existsSync(oldFile) || fs.existsSync(SESSIONS_FILE)) {
+    return;
+  }
+  try {
+    const old = JSON.parse(fs.readFileSync(oldFile, 'utf8'));
+    if (old && old.accountId) {
+      writeSession(old.accountId, old, {
+        baseUrl: old.baseUrl || DEFAULT_BASE_URL,
+        dataMode: old.dataMode || DEFAULT_DATA_MODE
+      });
+      console.log('Migrated session.json to sessions.json for account', old.accountId);
+    }
+    fs.renameSync(oldFile, oldFile + '.bak');
+  } catch (_) {
+    // Migration is best-effort
+  }
+}
+
+// --- Config command ---
+async function configCommand(flags, subcommand) {
+  const config = readConfig();
+
+  if (subcommand === 'set') {
+    if (flags.agent) {
+      const agent = String(flags.agent).toLowerCase();
+      if (!SUPPORTED_AGENTS.includes(agent)) {
+        throw new Error('Unsupported agent: ' + agent + '. Supported: ' + SUPPORTED_AGENTS.join(', '));
+      }
+      config.agent = agent;
+    }
+    config.updatedAt = new Date().toISOString();
+    writeConfig(config);
+    console.log('Configuration updated:', JSON.stringify(config, null, 2));
+    return;
+  }
+
+  // Default: show current config
+  console.log(JSON.stringify({
+    agent: config.agent || DEFAULT_AGENT,
+    supportedAgents: SUPPORTED_AGENTS,
+    ...config
+  }, null, 2));
+}
+
+// --- Sessions list command ---
+async function sessionsCommand(flags, subcommand) {
+  const sessions = readAllSessions();
+  const entries = listSessionsFromStore(sessions);
+
+  if (subcommand === 'list' || !subcommand) {
+    if (!entries.length) {
+      console.log('No active sessions. Run: remits-cli auth');
+      return;
+    }
+    console.log('Active sessions:');
+    for (const s of entries) {
+      const user = s.user ? (s.user.name || s.user.email || s.user.id) : 'unknown';
+      console.log('  Account', s.accountId + ':', user, '(' + s.dataMode + ')', '-', s.baseUrl, '-', s.updatedAt);
+    }
+    return;
+  }
+
+  if (subcommand === 'remove') {
+    const id = flags['account-id'] || flags._[2];
+    if (!id) {
+      throw new Error('Missing account id. Usage: remits-cli sessions remove --account-id <ID>');
+    }
+    const requestedBaseUrl = flags['base-url'] ? normalizeBaseUrl(flags['base-url']) : null;
+    const requestedDataMode = hasExplicitDataModeFlag(flags) ? resolveDataMode(flags, null) : null;
+    let removed = 0;
+    for (const [key, session] of Object.entries(sessions)) {
+      if (Number(session.accountId) !== Number(id)) {
+        continue;
+      }
+      if (requestedBaseUrl && normalizeBaseUrl(session.baseUrl) !== requestedBaseUrl) {
+        continue;
+      }
+      if (requestedDataMode && normalizeDataMode(session.dataMode) !== requestedDataMode) {
+        continue;
+      }
+      delete sessions[key];
+      removed += 1;
+    }
+    writeAllSessions(sessions);
+    console.log('Removed', removed, 'session(s) for account', id);
+    return;
+  }
+
+  throw new Error('Unknown sessions subcommand: ' + subcommand + '. Use: list, remove');
+}
+
+// --- Listener PID management ---
+function isListenerRunning() {
+  if (!fs.existsSync(LISTENER_PID_FILE)) {
+    return false;
+  }
+  try {
+    const pid = parseInt(fs.readFileSync(LISTENER_PID_FILE, 'utf8').trim(), 10);
+    if (!Number.isFinite(pid)) return false;
+    process.kill(pid, 0); // Signal 0 checks if process exists
+    return true;
+  } catch (_) {
+    // Process doesn't exist, clean up stale PID file
+    try { fs.unlinkSync(LISTENER_PID_FILE); } catch (_) {}
+    return false;
+  }
+}
+
+function writeListenerPid() {
+  ensureSessionDir();
+  atomicWriteFile(LISTENER_PID_FILE, String(process.pid));
+}
+
+function clearListenerPid() {
+  try { fs.unlinkSync(LISTENER_PID_FILE); } catch (_) {}
+}
+
+function readServiceState() {
+  if (!fs.existsSync(SERVICE_STATE_FILE)) {
+    return {};
+  }
+  try {
+    return JSON.parse(fs.readFileSync(SERVICE_STATE_FILE, 'utf8'));
+  } catch (_) {
+    return {};
+  }
+}
+
+function writeServiceState(data) {
+  ensureSessionDir();
+  atomicWriteFile(SERVICE_STATE_FILE, JSON.stringify(data, null, 2));
+}
+
+function clearServiceState() {
+  try { fs.unlinkSync(SERVICE_STATE_FILE); } catch (_) {}
+}
+
+function readWebsocketState() {
+  if (!fs.existsSync(WEBSOCKET_STATE_FILE)) {
+    return {
+      processedMessageIds: [],
+      lastMessageTimestampByScope: {}
+    };
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(WEBSOCKET_STATE_FILE, 'utf8'));
+    return {
+      processedMessageIds: Array.isArray(data.processedMessageIds) ? data.processedMessageIds : [],
+      lastMessageTimestampByScope: data.lastMessageTimestampByScope && typeof data.lastMessageTimestampByScope === 'object'
+        ? data.lastMessageTimestampByScope
+        : {}
+    };
+  } catch (_) {
+    return {
+      processedMessageIds: [],
+      lastMessageTimestampByScope: {}
+    };
+  }
+}
+
+function writeWebsocketState(data) {
+  ensureSessionDir();
+  atomicWriteFile(WEBSOCKET_STATE_FILE, JSON.stringify(data, null, 2));
+}
+
+function websocketScopeKey(baseUrl, userId) {
+  return String(baseUrl || '') + '|' + String(userId || '');
+}
+
+const websocketStateStore = readWebsocketState();
+const processedMessageIds = new Set(websocketStateStore.processedMessageIds || []);
+let processedMessageIdOrder = Array.isArray(websocketStateStore.processedMessageIds)
+  ? websocketStateStore.processedMessageIds.slice(-MAX_TRACKED_MESSAGE_IDS)
+  : [];
+const lastMessageTimestampByScope = {
+  ...(websocketStateStore.lastMessageTimestampByScope || {})
+};
+
+function persistWebsocketState() {
+  writeWebsocketState({
+    processedMessageIds: processedMessageIdOrder.slice(-MAX_TRACKED_MESSAGE_IDS),
+    lastMessageTimestampByScope
+  });
+}
+
+function rememberProcessedMessageId(messageId) {
+  if (!messageId) return;
+  const normalized = String(messageId);
+  if (processedMessageIds.has(normalized)) {
+    return;
+  }
+  processedMessageIds.add(normalized);
+  processedMessageIdOrder.push(normalized);
+  if (processedMessageIdOrder.length > MAX_TRACKED_MESSAGE_IDS) {
+    const removed = processedMessageIdOrder.splice(0, processedMessageIdOrder.length - MAX_TRACKED_MESSAGE_IDS);
+    for (const oldId of removed) {
+      processedMessageIds.delete(oldId);
+    }
+  }
+  persistWebsocketState();
+}
+
+function hasProcessedMessageId(messageId) {
+  if (!messageId) return false;
+  return processedMessageIds.has(String(messageId));
+}
+
+function updateLastMessageTimestamp(baseUrl, userIds, timestamp) {
+  const numericTimestamp = Number(timestamp);
+  if (!Number.isFinite(numericTimestamp) || numericTimestamp <= 0) {
+    return;
+  }
+  for (const userId of userIds || []) {
+    if (!userId) continue;
+    const key = websocketScopeKey(baseUrl, userId);
+    const current = Number(lastMessageTimestampByScope[key] || 0);
+    if (!current || numericTimestamp > current) {
+      lastMessageTimestampByScope[key] = numericTimestamp;
+    }
+  }
+  persistWebsocketState();
+}
+
+function lastMessageTimestampForScope(baseUrl, userId) {
+  return Number(lastMessageTimestampByScope[websocketScopeKey(baseUrl, userId)] || 0);
+}
+
+function summarizeWebsocketPayload(payload) {
+  const safePayload = sanitizeForLog(payload);
+  if (safePayload && typeof safePayload === 'object' && !Array.isArray(safePayload)) {
+    return safePayload;
+  }
+  return { value: safePayload };
+}
+
+function recordWebsocketMessage(baseUrl, topic, data, options = {}) {
+  if (!runtimeState.websocket[baseUrl]) {
+    runtimeState.websocket[baseUrl] = {
+      status: 'connected',
+      connectedAt: null,
+      disconnectedAt: null,
+      lastMessageAt: null,
+      lastError: null,
+      topics: {},
+      recentMessages: []
+    };
+  }
+  if (!Array.isArray(runtimeState.websocket[baseUrl].recentMessages)) {
+    runtimeState.websocket[baseUrl].recentMessages = [];
+  }
+
+  const message = data && typeof data === 'object' ? data : {};
+  const entry = {
+    receivedAt: new Date().toISOString(),
+    source: options.source || 'live',
+    topic: topic || null,
+    messageId: message.messageId || null,
+    timestamp: message.timestamp || null,
+    type: message.type || null,
+    duplicate: Boolean(options.duplicate),
+    accountIds: Array.isArray(options.accountIds) ? options.accountIds : [],
+    payload: summarizeWebsocketPayload(message.payload || {})
+  };
+
+  runtimeState.websocket[baseUrl].recentMessages.unshift(entry);
+  if (runtimeState.websocket[baseUrl].recentMessages.length > MAX_RECENT_WEBSOCKET_MESSAGES) {
+    runtimeState.websocket[baseUrl].recentMessages.length = MAX_RECENT_WEBSOCKET_MESSAGES;
+  }
+}
+
+async function waitForDashboardUrl(timeoutMs = 5000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const state = readServiceState();
+    if (state && state.dashboardUrl) {
+      return state.dashboardUrl;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return null;
+}
+
+async function waitForServiceStart(expectedPid, timeoutMs = 5000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const state = readServiceState();
+    if (state && Number(state.pid) === Number(expectedPid) && state.dashboardUrl) {
+      try {
+        process.kill(Number(expectedPid), 0);
+        return state.dashboardUrl;
+      } catch (_) {
+        return null;
+      }
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return null;
+}
+
+async function autoStartServiceIfNeeded() {
+  if (isListenerRunning()) {
+    return readServiceState().dashboardUrl || null;
+  }
+  const sessions = readAllSessions();
+  const entries = listenerSessionEntriesFromStore(sessions);
+  if (!entries.length) {
+    return null;
+  }
+  clearServiceState();
+  const { spawn } = require('child_process');
+  const child = spawn(process.execPath, [__filename, 'start', '--foreground', 'true'], {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env }
+  });
+  child.unref();
+  return waitForServiceStart(child.pid, 3000);
+}
+
+let managedClients = [];
+let dashboardServer = null;
+let runtimeState = {
+  service: {
+    startedAt: null,
+    pid: null,
+    dashboardPort: null,
+    dashboardUrl: null
+  },
+  discovery: {
+    scannedAt: null,
+    roots: [],
+    matches: 0,
+    repoCount: 0
+  },
+  websocket: {},
+  lastAction: null
+};
+
+function listenerSessionEntriesFromStore(store) {
+  return listSessionsFromStore(store).filter((session) => session && session.token && session.websocketTopic);
+}
+
+function listenerSessionSignature(entries) {
+  return entries
+    .map((session) => stableStringify({
+      accountId: Number(session.accountId),
+      baseUrl: normalizeBaseUrl(session.baseUrl || DEFAULT_BASE_URL),
+      websocketTopic: String(session.websocketTopic || ''),
+      userId: session.user && session.user.id != null ? String(session.user.id) : '',
+      tokenHash: sha256(String(session.token || ''))
+    }))
+    .sort()
+    .join('|');
+}
+
+function groupSessionsByBaseUrl(entries) {
+  const grouped = {};
+  for (const session of entries || []) {
+    const baseUrl = normalizeBaseUrl(session.baseUrl || DEFAULT_BASE_URL);
+    if (!grouped[baseUrl]) {
+      grouped[baseUrl] = [];
+    }
+    grouped[baseUrl].push(session);
+  }
+  return grouped;
+}
+
+function ensureRuntimeWebsocketEntry(baseUrl) {
+  const normalizedBaseUrl = normalizeBaseUrl(baseUrl || DEFAULT_BASE_URL);
+  if (!runtimeState.websocket[normalizedBaseUrl]) {
+    runtimeState.websocket[normalizedBaseUrl] = {
+      status: 'connecting',
+      connectedAt: null,
+      disconnectedAt: null,
+      lastMessageAt: null,
+      lastError: null,
+      topics: {},
+      recentMessages: []
+    };
+  }
+  if (!runtimeState.websocket[normalizedBaseUrl].topics || typeof runtimeState.websocket[normalizedBaseUrl].topics !== 'object') {
+    runtimeState.websocket[normalizedBaseUrl].topics = {};
+  }
+  if (!Array.isArray(runtimeState.websocket[normalizedBaseUrl].recentMessages)) {
+    runtimeState.websocket[normalizedBaseUrl].recentMessages = [];
+  }
+  return runtimeState.websocket[normalizedBaseUrl];
+}
+
+function websocketReadyStateName(readyState) {
+  switch (readyState) {
+    case WebSocket.CONNECTING:
+      return 'CONNECTING';
+    case WebSocket.OPEN:
+      return 'OPEN';
+    case WebSocket.CLOSING:
+      return 'CLOSING';
+    case WebSocket.CLOSED:
+      return 'CLOSED';
+    default:
+      return 'UNKNOWN';
+  }
+}
+
+function describeWebsocketCloseEvent(event) {
+  if (!event || typeof event !== 'object') {
+    return 'WebSocket closed';
+  }
+  const parts = [];
+  if (event.code != null) {
+    parts.push('code=' + String(event.code));
+  }
+  if (event.reason) {
+    parts.push('reason=' + String(event.reason));
+  }
+  if (event.wasClean != null) {
+    parts.push('clean=' + String(Boolean(event.wasClean)));
+  }
+  return parts.length ? parts.join(', ') : 'WebSocket closed';
+}
+
+function describeWebsocketErrorEvent(event) {
+  if (!event) {
+    return 'WebSocket error';
+  }
+  if (event.message) {
+    return String(event.message);
+  }
+  if (event.error && event.error.message) {
+    return String(event.error.message);
+  }
+  if (event.type) {
+    return 'WebSocket ' + String(event.type);
+  }
+  return 'WebSocket error';
+}
+
+function updateRuntimeServiceState() {
+  writeServiceState({
+    pid: process.pid,
+    startedAt: runtimeState.service.startedAt,
+    dashboardPort: runtimeState.service.dashboardPort,
+    dashboardUrl: runtimeState.service.dashboardUrl,
+    discovery: runtimeState.discovery,
+    websocket: runtimeState.websocket,
+    updatedAt: new Date().toISOString()
+  });
+}
+
+function recordDiscoverySummary(summary) {
+  runtimeState.discovery = {
+    scannedAt: summary && summary.scannedAt ? summary.scannedAt : new Date().toISOString(),
+    roots: summary && summary.roots ? summary.roots : [],
+    matches: summary && Number.isFinite(summary.matches) ? summary.matches : 0,
+    repoCount: summary && Number.isFinite(summary.repoCount) ? summary.repoCount : countAccountRepos()
+  };
+  updateRuntimeServiceState();
+}
+
+function fileStat(file) {
+  try {
+    return fs.statSync(file);
+  } catch (_) {
+    return null;
+  }
+}
+
+function truncateText(value, maxChars = 20000) {
+  const text = String(value || '');
+  if (text.length <= maxChars) {
+    return text;
+  }
+  return text.slice(0, maxChars) + '\n...[truncated ' + (text.length - maxChars) + ' chars]';
+}
+
+function readJsonFilePretty(file) {
+  if (!fs.existsSync(file)) {
+    return null;
+  }
+  try {
+    return JSON.stringify(JSON.parse(fs.readFileSync(file, 'utf8')), null, 2);
+  } catch (_) {
+    return truncateText(fs.readFileSync(file, 'utf8'));
+  }
+}
+
+function tailTextFile(file, maxLines = 80) {
+  if (!fs.existsSync(file)) {
+    return null;
+  }
+  const text = fs.readFileSync(file, 'utf8');
+  const lines = text.split('\n');
+  return truncateText(lines.slice(-maxLines).join('\n'));
+}
+
+function readJsonLinesFile(file, maxEntries = 80) {
+  if (!file || !fs.existsSync(file)) {
+    return [];
+  }
+  try {
+    const lines = fs.readFileSync(file, 'utf8')
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .slice(-maxEntries);
+    return lines.map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch (_) {
+        return null;
+      }
+    }).filter(Boolean);
+  } catch (_) {
+    return [];
+  }
+}
+
+function slugify(value) {
+  return String(value || 'issue')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'issue';
+}
+
+function detectIssueSignals(repoEntries, globalFiles) {
+  const issues = [];
+  const tmuxLog = (globalFiles || []).find((file) => file.label === 'tmux-activity.log (tail)');
+  if (tmuxLog && tmuxLog.content) {
+    const errorLines = tmuxLog.content
+      .split('\n')
+      .filter((line) => /\[error\]/i.test(line))
+      .slice(-8);
+    if (errorLines.length) {
+      issues.push({
+        id: 'tmux-activity-errors',
+        severity: 'warn',
+        scope: 'global',
+        title: 'Recent service or tmux errors detected',
+        summary: 'The global remits-cli activity log contains recent error-level events.',
+        evidence: errorLines,
+        recommendation: 'Review the activity tail and export an escalation bundle if this reflects unexpected platform or dispatch behavior.'
+      });
+    }
+  }
+
+  for (const repo of repoEntries || []) {
+    const sessionLogFile = (repo.files || []).find((file) => file.label === '.remits-cli/session log (tail)');
+    if (!sessionLogFile || !sessionLogFile.path || !fs.existsSync(sessionLogFile.path)) {
+      continue;
+    }
+    const entries = readJsonLinesFile(sessionLogFile.path, 80);
+    const problemEntries = entries.filter((entry) => {
+      const responseText = JSON.stringify(entry.response || {});
+      const errorText = String(entry.error || '');
+      return entry.status === 'error' ||
+        /500|Internal Server Error/i.test(responseText) ||
+        /500|Internal Server Error/i.test(errorText);
+    }).slice(-6);
+
+    if (problemEntries.length) {
+      const evidence = problemEntries.map((entry) => {
+        return [
+          entry.ts || 'unknown-ts',
+          entry.endpoint || 'unknown-endpoint',
+          entry.status || 'unknown-status',
+          entry.error || JSON.stringify(entry.response || {})
+        ].join(' | ');
+      });
+      issues.push({
+        id: 'repo-' + repo.accountId + '-session-errors',
+        severity: evidence.some((line) => /500|Internal Server Error/i.test(line)) ? 'bad' : 'warn',
+        scope: 'repo',
+        repoAccountId: repo.accountId,
+        repoName: repo.name || null,
+        title: 'Repo session log shows recent remits-cli errors',
+        summary: 'Recent `/cli/*` activity for this repo includes failed requests or platform error responses.',
+        evidence,
+        recommendation: 'Inspect the repo session log and exported artifacts before escalating to a Remits system admin.'
+      });
+    }
+  }
+
+  return issues;
+}
+
+function copyFileIfExists(source, destination) {
+  if (!source || !fs.existsSync(source)) {
+    return false;
+  }
+  ensureDir(path.dirname(destination));
+  fs.copyFileSync(source, destination);
+  return true;
+}
+
+function exportIssueBundle(snapshot) {
+  ensureDir(ISSUES_DIR);
+  const primaryIssue = (snapshot.issues && snapshot.issues[0]) || null;
+  const primaryAccountId = primaryIssue && primaryIssue.repoAccountId ? primaryIssue.repoAccountId : 'global';
+  const slug = slugify(primaryIssue ? primaryIssue.title : 'remits-cli-issue');
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const bundleDir = path.join(ISSUES_DIR, timestamp + '-account-' + primaryAccountId + '-' + slug);
+  ensureDir(bundleDir);
+
+  const summaryLines = [
+    '# Remits CLI Issue Export',
+    '',
+    'Generated: ' + new Date().toISOString(),
+    'Bundle Directory: ' + bundleDir,
+    '',
+    '## Why This Was Exported',
+    '',
+    'The control center detected issue signals that may indicate a Remits platform bug, 500 response, websocket/dispatch failure, or another unexpected system-level problem.',
+    '',
+    '## Operator Notes',
+    '',
+    '- What were you trying to do?',
+    '- Why were you trying to do it?',
+    '- What did you expect to happen?',
+    '- What actually happened?',
+    '',
+    '## Detected Issues',
+    ''
+  ];
+
+  if (snapshot.issues && snapshot.issues.length) {
+    snapshot.issues.forEach((issue, index) => {
+      summaryLines.push((index + 1) + '. ' + issue.title);
+      summaryLines.push('   Severity: ' + issue.severity);
+      summaryLines.push('   Scope: ' + issue.scope + (issue.repoAccountId ? ' account ' + issue.repoAccountId : ''));
+      summaryLines.push('   Summary: ' + issue.summary);
+      summaryLines.push('   Recommendation: ' + issue.recommendation);
+      if (issue.evidence && issue.evidence.length) {
+        summaryLines.push('   Evidence:');
+        issue.evidence.forEach((line) => summaryLines.push('   - ' + line));
+      }
+      summaryLines.push('');
+    });
+  } else {
+    summaryLines.push('No automatic issue signals were detected at export time, but the bundle was created manually for further review.');
+    summaryLines.push('');
+  }
+
+  summaryLines.push('## Included Files');
+  summaryLines.push('');
+  summaryLines.push('- `context.json`');
+  summaryLines.push('- `snapshot.json`');
+  summaryLines.push('- `global/` copies of important remits-cli state files');
+  summaryLines.push('- `repos/` copies of indexed repo remits-cli files when present');
+  summaryLines.push('');
+  summaryLines.push('## Guidance For Remits System Admin');
+  summaryLines.push('');
+  summaryLines.push('Use `snapshot.json` and `context.json` as the structured overview, then inspect the copied session/activity files to correlate the exact failing command or dispatch behavior.');
+  summaryLines.push('');
+
+  fs.writeFileSync(path.join(bundleDir, 'summary.md'), summaryLines.join('\n'));
+  fs.writeFileSync(path.join(bundleDir, 'context.json'), JSON.stringify({
+    exportedAt: new Date().toISOString(),
+    cwd: process.cwd(),
+    service: snapshot.service,
+    discovery: snapshot.discovery,
+    issueCount: (snapshot.issues || []).length,
+    tmux: {
+      available: snapshot.tmux && snapshot.tmux.available,
+      sessionExists: snapshot.tmux && snapshot.tmux.sessionExists,
+      sessionName: snapshot.tmux && snapshot.tmux.sessionName,
+      livePaneCount: snapshot.tmux && snapshot.tmux.livePanes ? snapshot.tmux.livePanes.length : 0
+    },
+    repos: (snapshot.repos || []).map((repo) => ({
+      accountId: repo.accountId,
+      name: repo.name,
+      type: repo.type,
+      directory: repo.directory
+    }))
+  }, null, 2));
+  fs.writeFileSync(path.join(bundleDir, 'snapshot.json'), JSON.stringify(snapshot, null, 2));
+
+  const globalDir = path.join(bundleDir, 'global');
+  ensureDir(globalDir);
+  copyFileIfExists(SESSIONS_FILE, path.join(globalDir, 'sessions.json'));
+  copyFileIfExists(CONFIG_FILE, path.join(globalDir, 'config.json'));
+  copyFileIfExists(SERVICE_STATE_FILE, path.join(globalDir, 'service-state.json'));
+  copyFileIfExists(ACCOUNT_REPO_INDEX_FILE, path.join(globalDir, 'account-repos.json'));
+  copyFileIfExists(DISPATCH_STATE_FILE, path.join(globalDir, 'dispatch-panes.json'));
+  copyFileIfExists(TMUX_ACTIVITY_LOG_FILE, path.join(globalDir, 'tmux-activity.log'));
+
+  const reposDir = path.join(bundleDir, 'repos');
+  ensureDir(reposDir);
+  for (const repo of snapshot.repos || []) {
+    const repoDir = path.join(reposDir, String(repo.accountId));
+    ensureDir(repoDir);
+    for (const file of repo.files || []) {
+      if (!file.path) continue;
+      const ext = path.extname(file.path || '') || '.txt';
+      copyFileIfExists(file.path, path.join(repoDir, slugify(file.label) + ext));
+    }
+  }
+
+  return bundleDir;
+}
+
+function escapeHtml(value) {
+  return String(value == null ? '' : value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function renderActionButton(action, label) {
+  return '<form method="POST" action="/action" style="display:inline-block;margin:0 8px 8px 0;">' +
+    '<input type="hidden" name="action" value="' + escapeHtml(action) + '">' +
+    '<button type="submit" style="padding:8px 12px;border:1px solid #222;background:#fff7e6;cursor:pointer;">' + escapeHtml(label) + '</button>' +
+    '</form>';
+}
+
+function buildGlobalFileSnapshot() {
+  const files = [
+    { label: 'sessions.json', path: SESSIONS_FILE, mode: 'json' },
+    { label: 'config.json', path: CONFIG_FILE, mode: 'json' },
+    { label: 'service-state.json', path: SERVICE_STATE_FILE, mode: 'json' },
+    { label: 'websocket-state.json', path: WEBSOCKET_STATE_FILE, mode: 'json' },
+    { label: 'dispatch-panes.json', path: DISPATCH_STATE_FILE, mode: 'json' },
+    { label: 'account-repos.json', path: ACCOUNT_REPO_INDEX_FILE, mode: 'json' },
+    { label: 'tmux-activity.log (tail)', path: TMUX_ACTIVITY_LOG_FILE, mode: 'tail' }
+  ];
+
+  return files.map((file) => {
+    const stat = fileStat(file.path);
+    return {
+      ...file,
+      exists: Boolean(stat),
+      size: stat ? stat.size : 0,
+      updatedAt: stat ? stat.mtime.toISOString() : null,
+      content: file.mode === 'tail' ? tailTextFile(file.path) : readJsonFilePretty(file.path)
+    };
+  });
+}
+
+function buildRepoSnapshot(entry) {
+  const directory = entry.directory;
+  const localPaths = localStatePaths(directory);
+  const currentSessionName = fs.existsSync(localPaths.currentSessionFile)
+    ? fs.readFileSync(localPaths.currentSessionFile, 'utf8').trim()
+    : '';
+  const currentSessionLog = currentSessionName
+    ? path.join(localPaths.sessionsDir, currentSessionName + '.jsonl')
+    : null;
+  const repoFiles = [
+    { label: 'account-info.json', path: entry.accountInfoPath || path.join(directory, 'account-info.json'), mode: 'json' },
+    { label: '.remits-cli/current-session.txt', path: localPaths.currentSessionFile, mode: 'text' },
+    { label: '.remits-cli/tools/tools.json', path: path.join(localPaths.toolsDir, 'tools.json'), mode: 'json' },
+    { label: '.remits-cli/session log (tail)', path: currentSessionLog, mode: 'tail' }
+  ];
+
+  return {
+    ...entry,
+    exists: fs.existsSync(directory),
+    files: repoFiles.map((file) => {
+      const stat = file.path ? fileStat(file.path) : null;
+      let content = null;
+      if (file.path) {
+        if (file.mode === 'json') content = readJsonFilePretty(file.path);
+        if (file.mode === 'tail') content = tailTextFile(file.path, 40);
+        if (file.mode === 'text' && fs.existsSync(file.path)) content = truncateText(fs.readFileSync(file.path, 'utf8'));
+      }
+      return {
+        ...file,
+        exists: Boolean(stat),
+        size: stat ? stat.size : 0,
+        updatedAt: stat ? stat.mtime.toISOString() : null,
+        content
+      };
+    })
+  };
+}
+
+function collectDashboardSnapshot() {
+  const accountRepoIndex = readAccountRepoIndex();
+  const repoEntries = listAccountRepoEntries(accountRepoIndex)
+    .sort((a, b) => String(a.name || '').localeCompare(String(b.name || '')))
+    .map(buildRepoSnapshot);
+  const platformRepo = getPlatformRepoEntry(accountRepoIndex);
+  const globalFiles = buildGlobalFileSnapshot();
+  const issues = detectIssueSignals(repoEntries, globalFiles);
+
+  const paneState = fs.existsSync(DISPATCH_STATE_FILE) ? readJsonFilePretty(DISPATCH_STATE_FILE) : null;
+  const livePanes = [];
+  try {
+    if (isTmuxAvailable() && tmuxSessionExists()) {
+      const output = execSync(
+        'tmux list-panes -t ' + shellQuote(TMUX_SESSION_NAME) + ' -F ' + shellQuote('#{session_name}\t#{window_name}\t#{pane_id}\t#{pane_current_path}\t#{pane_dead}'),
+        { stdio: ['ignore', 'pipe', 'ignore'] }
+      ).toString();
+      for (const line of output.split('\n').map((value) => value.trim()).filter(Boolean)) {
+        const parts = line.split('\t');
+        livePanes.push({
+          session: parts[0] || null,
+          window: parts[1] || null,
+          paneId: parts[2] || null,
+          currentPath: parts[3] || null,
+          dead: parts[4] === '1'
+        });
+      }
+    }
+  } catch (_) {
+    // Dashboard should remain readable even if tmux inspection fails.
+  }
+
+  return {
+    generatedAt: new Date().toISOString(),
+    service: {
+      running: isListenerRunning(),
+      pid: fs.existsSync(LISTENER_PID_FILE) ? fs.readFileSync(LISTENER_PID_FILE, 'utf8').trim() : null,
+      startedAt: runtimeState.service.startedAt,
+      dashboardUrl: runtimeState.service.dashboardUrl
+    },
+    websocket: {
+      connections: runtimeState.websocket
+    },
+    tmux: {
+      available: isTmuxAvailable(),
+      terminalLaunchSupported: canLaunchTerminalForTmux(),
+      sessionName: TMUX_SESSION_NAME,
+      sessionExists: tmuxSessionExists(),
+      trackedPanes: paneState,
+      livePanes
+    },
+    discovery: runtimeState.discovery,
+    globalFiles,
+    repos: repoEntries,
+    platformRepo,
+    issues,
+    lastAction: runtimeState.lastAction
+  };
+}
+
+function renderDashboardHtml(snapshot) {
+  const initialState = JSON.stringify(snapshot)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026');
+  return '<!DOCTYPE html>' +
+    '<html><head><meta charset="utf-8">' +
+    '<title>Remits CLI Control Center</title>' +
+    '<meta name="viewport" content="width=device-width, initial-scale=1">' +
+    '<style>' +
+      ':root{--bg:#f5f1e8;--surface:#fffdf8;--surface-strong:#fff;--ink:#1f1c16;--muted:#6f685d;--line:#d9d0c0;--line-strong:#bbaa93;--green:#1f8f58;--green-soft:#e8f6ee;--yellow:#c38a16;--yellow-soft:#fff6db;--red:#c1493d;--red-soft:#fdeae7;--blue:#2456d3;--blue-soft:#eaf0ff;}' +
+      '*{box-sizing:border-box;}body{margin:0;font-family:Menlo,Monaco,monospace;background:radial-gradient(circle at top left,#fffdf8 0,#f5f1e8 48%,#ece4d7 100%);color:var(--ink);}h1,h2,h3,h4,summary{font-family:Georgia,serif;}button{font:inherit;}a{color:var(--blue);}main{max-width:1440px;margin:0 auto;padding:24px;}header.hero{display:flex;justify-content:space-between;gap:16px;align-items:flex-start;margin-bottom:20px;padding:24px;border:1px solid var(--line);border-radius:22px;background:linear-gradient(135deg,#fffefb 0,#f8f1e3 100%);box-shadow:0 14px 40px rgba(72,53,22,.08);}header.hero p{margin:8px 0 0 0;max-width:760px;color:var(--muted);line-height:1.5;} .hero-meta{display:flex;gap:10px;flex-wrap:wrap;justify-content:flex-end;} .pill{display:inline-flex;align-items:center;gap:8px;padding:8px 12px;border:1px solid var(--line);border-radius:999px;background:rgba(255,255,255,.75);font-size:12px;} .status-grid,.section-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:16px;} .section-grid{margin-top:18px;} .status-card,.panel,.action-card{border:1px solid var(--line);border-radius:18px;background:var(--surface-strong);box-shadow:0 10px 28px rgba(72,53,22,.06);} .status-card{padding:18px;position:relative;overflow:hidden;} .status-card::after{content:"";position:absolute;inset:auto -40px -40px auto;width:120px;height:120px;border-radius:999px;background:rgba(0,0,0,.03);} .status-head{display:flex;align-items:center;gap:12px;margin-bottom:12px;} .status-dot{width:14px;height:14px;border-radius:50%;display:inline-block;box-shadow:0 0 0 4px rgba(0,0,0,.04);} .ok .status-dot{background:var(--green);} .warn .status-dot{background:var(--yellow);} .bad .status-dot{background:var(--red);} .status-value{font-size:30px;line-height:1;font-family:Georgia,serif;} .status-label{font-size:12px;text-transform:uppercase;letter-spacing:.08em;color:var(--muted);} .status-sub{margin-top:10px;color:var(--muted);font-size:13px;line-height:1.45;} .status-card.ok{background:linear-gradient(180deg,var(--surface-strong),var(--green-soft));} .status-card.warn{background:linear-gradient(180deg,var(--surface-strong),var(--yellow-soft));} .status-card.bad{background:linear-gradient(180deg,var(--surface-strong),var(--red-soft));}' +
+      '.action-card{padding:18px;margin:18px 0 0 0;background:linear-gradient(180deg,#fffdf9,#f7f1e6);} .action-row{display:flex;flex-wrap:wrap;gap:10px;margin-top:12px;} .action-btn{padding:10px 14px;border-radius:12px;border:1px solid var(--line-strong);background:var(--surface-strong);cursor:pointer;transition:transform .12s ease,background .12s ease,border-color .12s ease;} .action-btn:hover{transform:translateY(-1px);background:#fff7ea;} .action-btn:disabled{opacity:.55;cursor:wait;transform:none;} .panel{padding:18px;} .panel h2{margin:0 0 12px 0;font-size:22px;} .muted{color:var(--muted);} .summary-list{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:12px;margin-top:8px;} .summary-item{padding:12px;border:1px solid var(--line);border-radius:14px;background:#fcfaf4;} .summary-item .k{display:block;font-size:11px;text-transform:uppercase;letter-spacing:.08em;color:var(--muted);margin-bottom:6px;} .summary-item .v{font-size:18px;font-family:Georgia,serif;}' +
+      '.accordion{display:grid;gap:14px;} details.group,details.item{border:1px solid var(--line);border-radius:16px;background:#fffdf9;overflow:hidden;} details.group[open],details.item[open]{border-color:var(--line-strong);box-shadow:0 10px 24px rgba(72,53,22,.05);} summary{list-style:none;cursor:pointer;padding:16px 18px;display:flex;align-items:center;justify-content:space-between;gap:16px;} summary::-webkit-details-marker{display:none;} .summary-main{display:flex;align-items:center;gap:12px;min-width:0;} .summary-text{display:flex;flex-direction:column;gap:4px;min-width:0;} .summary-title{font-size:18px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;} .summary-meta{font-size:12px;color:var(--muted);} .summary-caret{color:var(--muted);font-size:18px;} details[open] > summary .summary-caret{transform:rotate(90deg);} .group-body,.item-body{padding:0 18px 18px 18px;} .mini-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:10px;margin-bottom:14px;} .mini-card{padding:12px;border:1px solid var(--line);border-radius:12px;background:#fcfaf4;} .mini-card strong{display:block;font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:var(--muted);margin-bottom:6px;} .code-block{white-space:pre-wrap;overflow:auto;max-height:320px;padding:14px;border:1px solid var(--line);border-radius:12px;background:#f7f4ee;font-size:12px;line-height:1.45;} .code-block.log{max-height:420px;background:#1f1c16;color:#f4ead7;border-color:#3f382d;} .stack{display:grid;gap:12px;} .badge{display:inline-flex;align-items:center;gap:6px;padding:5px 9px;border-radius:999px;border:1px solid var(--line);font-size:11px;text-transform:uppercase;letter-spacing:.08em;} .badge.ok{background:var(--green-soft);border-color:#b9dfc9;color:#175a39;} .badge.warn{background:var(--yellow-soft);border-color:#edd69c;color:#895c08;} .badge.bad{background:var(--red-soft);border-color:#efc1bb;color:#8b322a;} .repo-files{display:grid;gap:12px;} .empty{padding:18px;border:1px dashed var(--line-strong);border-radius:16px;background:#fcfaf4;color:var(--muted);} .toast{position:fixed;right:18px;bottom:18px;padding:12px 14px;border-radius:14px;border:1px solid var(--line-strong);background:#fffdf8;box-shadow:0 14px 24px rgba(72,53,22,.16);display:none;max-width:360px;} .toast.show{display:block;} @media (max-width:900px){main{padding:16px;}header.hero{flex-direction:column;} .hero-meta{justify-content:flex-start;}}' +
+    '</style>' +
+    '</head><body>' +
+    '<main>' +
+      '<header class="hero">' +
+        '<div>' +
+          '<h1 style="margin:0;">Remits CLI Control Center</h1>' +
+          '<p>Human-friendly overview of remits-cli integration state. The dashboard refreshes in place, preserves scroll inside logs, and keeps verbose internals collapsed until you want them.</p>' +
+        '</div>' +
+        '<div class="hero-meta">' +
+          '<span class="pill"><strong>Live</strong><span id="refresh-label">Updating every 5s</span></span>' +
+          '<span class="pill"><strong>Generated</strong><span id="generated-at">n/a</span></span>' +
+        '</div>' +
+      '</header>' +
+      '<section id="status-grid" class="status-grid"></section>' +
+      '<section class="action-card">' +
+        '<h2 style="margin:0;">Controls</h2>' +
+        '<div class="muted">Use these actions to repair or refresh the local integration without leaving the dashboard, or export a consistent escalation bundle for a Remits system admin.</div>' +
+        '<div class="action-row">' +
+          '<button class="action-btn" data-action="export-issues">Export Issue Bundle</button>' +
+          '<button class="action-btn" data-action="rescan-repos">Rescan Account Repos</button>' +
+          '<button class="action-btn" data-action="reconnect-websockets">Reconnect Websockets</button>' +
+          '<button class="action-btn" data-action="open-tmux">Open Tmux Terminal</button>' +
+          '<button class="action-btn" data-action="start-tmux">Ensure Tmux Session</button>' +
+          '<button class="action-btn" data-action="stop-tmux">Kill Tmux Session</button>' +
+        '</div>' +
+      '</section>' +
+      '<div class="section-grid">' +
+        '<section class="panel">' +
+          '<h2>High-Level Summary</h2>' +
+          '<div id="summary-grid" class="summary-list"></div>' +
+        '</section>' +
+        '<section class="panel">' +
+          '<h2>Latest Action</h2>' +
+          '<div id="last-action" class="empty">No dashboard actions have been triggered yet.</div>' +
+        '</section>' +
+      '</div>' +
+      '<div class="section-grid">' +
+        '<section class="panel"><h2>Issues & Escalation</h2><div id="issues-section" class="accordion"></div></section>' +
+      '</div>' +
+      '<div class="section-grid">' +
+        '<section class="panel"><h2>Websocket Connections</h2><div id="websocket-section" class="accordion"></div></section>' +
+        '<section class="panel"><h2>Tmux</h2><div id="tmux-section" class="accordion"></div></section>' +
+      '</div>' +
+      '<div class="section-grid">' +
+        '<section class="panel"><h2>Global Files</h2><div id="global-files" class="accordion"></div></section>' +
+        '<section class="panel"><h2>Indexed Repos</h2><div id="repo-section" class="accordion"></div></section>' +
+      '</div>' +
+    '</main>' +
+    '<div id="toast" class="toast"></div>' +
+    '<script id="initial-state" type="application/json">' + initialState + '</script>' +
+    '<script>' +
+      '(function(){' +
+        'const refreshMs=5000;' +
+        'let dashboardState=JSON.parse(document.getElementById("initial-state").textContent);' +
+        'let actionInFlight=false;' +
+        'let saveScrollState=function(){const state={};document.querySelectorAll("[data-scroll-key]").forEach(function(node){state[node.getAttribute("data-scroll-key")]={top:node.scrollTop,height:node.scrollHeight};});return state;};' +
+        'let restoreScrollState=function(prev){document.querySelectorAll("[data-scroll-key]").forEach(function(node){const key=node.getAttribute("data-scroll-key");const prior=prev[key];if(!prior)return;const wasNearBottom=prior.height-prior.top-node.clientHeight<24;if(wasNearBottom){node.scrollTop=node.scrollHeight;}else{node.scrollTop=Math.min(prior.top,node.scrollHeight);}});};' +
+        'let saveDetailsState=function(){const state={};document.querySelectorAll("details[data-key]").forEach(function(node){state[node.getAttribute("data-key")]=node.open;});return state;};' +
+        'let restoreDetailsState=function(prev){document.querySelectorAll("details[data-key]").forEach(function(node){const key=node.getAttribute("data-key");if(Object.prototype.hasOwnProperty.call(prev,key)){node.open=prev[key];}});};' +
+        'function escapeHtml(value){return String(value==null?"":value).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/\\x27/g,"&#39;");}' +
+        'function formatTime(value){if(!value)return "n/a";try{return new Date(value).toLocaleString();}catch(_){return value;}}' +
+        'function statusTone(kind){return kind===true||kind==="connected"||kind==="running"?"ok":kind==="connecting"||kind==="partial"?"warn":"bad";}' +
+        'function badge(label,tone){return \'<span class="badge \'+tone+\'">\'+escapeHtml(label)+\'</span>\';}' +
+        'function summaryItem(key,value){return \'<div class="summary-item"><span class="k">\'+escapeHtml(key)+\'</span><span class="v">\'+escapeHtml(value)+\'</span></div>\';}' +
+        'function codeBlock(key,content,extraClass){return \'<pre class="code-block \'+(extraClass||"")+\'" data-scroll-key="\'+escapeHtml(key)+\'">\'+escapeHtml(content||"[missing]")+\'</pre>\';}' +
+        'function detailsBlock(key,title,meta,bodyHtml,openByDefault){return \'<details class="item" data-key="\'+escapeHtml(key)+\'"\'+(openByDefault?" open":"")+\'><summary><div class="summary-main"><div class="summary-text"><span class="summary-title">\'+escapeHtml(title)+\'</span><span class="summary-meta">\'+meta+\'</span></div></div><span class="summary-caret">›</span></summary><div class="item-body">\'+bodyHtml+\'</div></details>\';}' +
+        'function renderStatusCards(state){const wsValues=Object.values((state.websocket&&state.websocket.connections)||{});const connectedCount=wsValues.filter(function(entry){return entry.status==="connected";}).length;const warnCount=wsValues.filter(function(entry){return entry.status==="connecting";}).length;const errorCount=wsValues.filter(function(entry){return entry.status==="error"||entry.status==="disconnected";}).length;const repoCount=(state.repos||[]).length;const issueCount=(state.issues||[]).length;const criticalIssueCount=(state.issues||[]).filter(function(issue){return issue.severity==="bad";}).length;const tmuxHealthy=state.tmux&&state.tmux.available&&state.tmux.sessionExists;const cards=[' +
+          '{title:"Service",value:state.service&&state.service.running?"Running":"Stopped",label:"Daemon status",tone:statusTone(state.service&&state.service.running),sub:(state.service&&state.service.dashboardUrl?state.service.dashboardUrl:"No dashboard URL yet")},' +
+          '{title:"Websockets",value:String(connectedCount)+"/"+String(wsValues.length||0),label:"Connected topics groups",tone:errorCount? "bad" : (warnCount? "warn" : "ok"),sub: errorCount? String(errorCount)+" unhealthy connection(s)" : (warnCount? String(warnCount)+" connecting" : "All connections healthy")},' +
+          '{title:"Tmux",value:tmuxHealthy?"Ready":"Attention",label:"Dispatch workspace",tone:tmuxHealthy?"ok":(state.tmux&&state.tmux.available?"warn":"bad"),sub:state.tmux&&state.tmux.available?(state.tmux.sessionExists?String((state.tmux.livePanes||[]).length)+" live pane(s)":"tmux installed, session missing"):"tmux not installed"},' +
+          '{title:"Issues",value:String(issueCount),label:"Detected escalation signals",tone:criticalIssueCount?"bad":(issueCount?"warn":"ok"),sub:issueCount?(criticalIssueCount?String(criticalIssueCount)+" critical signal(s)":"Review before continuing"):"No issue signals detected"},' +
+          '{title:"Repos",value:String(repoCount),label:"Indexed account repos",tone:repoCount?"ok":"warn",sub:"Last scan: "+formatTime(state.discovery&&state.discovery.scannedAt)}' +
+        '];document.getElementById("status-grid").innerHTML=cards.map(function(card){return \'<section class="status-card \'+card.tone+\'"><div class="status-head"><span class="status-dot"></span><div><div class="status-label">\'+escapeHtml(card.title)+\'</div><div class="status-value">\'+escapeHtml(card.value)+\'</div></div></div><div class="status-sub"><strong>\'+escapeHtml(card.label)+\':</strong> \'+escapeHtml(card.sub)+\'</div></section>\';}).join("");}' +
+        'function renderSummary(state){const ws=Object.values((state.websocket&&state.websocket.connections)||{});const topics=ws.reduce(function(sum,entry){return sum+Object.keys(entry.topics||{}).length;},0);const tracked=state.tmux&&state.tmux.trackedPanes?Object.keys(JSON.parse(state.tmux.trackedPanes||"{}")).length:0;document.getElementById("summary-grid").innerHTML=[' +
+          'summaryItem("PID",state.service&&state.service.pid||"n/a"),' +
+          'summaryItem("Dashboard",state.service&&state.service.dashboardUrl||"n/a"),' +
+          'summaryItem("Repo Matches",String(state.discovery&&state.discovery.matches||0)),' +
+          'summaryItem("Connections",String(ws.length)),' +
+          'summaryItem("Topics",String(topics)),' +
+          'summaryItem("Tracked Panes",String(tracked))' +
+        '].join("");}' +
+        'function renderLastAction(state){const target=document.getElementById("last-action");if(!state.lastAction){target.className="empty";target.textContent="No dashboard actions have been triggered yet.";return;}target.className="summary-item";target.innerHTML=\'<span class="k">Last Action</span><span class="v">\'+escapeHtml(state.lastAction.action||"unknown")+\'</span><div class="muted" style="margin-top:8px;">\'+escapeHtml(formatTime(state.lastAction.at))+\'</div>\'+(state.lastAction.bundlePath?\'<div class="muted" style="margin-top:8px;word-break:break-word;"><strong>Bundle:</strong> \'+escapeHtml(state.lastAction.bundlePath)+\'</div>\':"");}' +
+        'function renderIssues(state){const target=document.getElementById("issues-section");const issues=state.issues||[];if(!issues.length){target.innerHTML=\'<div class="empty">No automatic issue signals are currently detected. If something still feels wrong, you can still click "Export Issue Bundle" to prepare a package for a Remits system admin.</div>\';return;}target.innerHTML=issues.map(function(issue,index){const tone=issue.severity==="bad"?"bad":"warn";const meta=badge(issue.severity==="bad"?"critical":"warning",tone)+\' <span class="muted">\'+escapeHtml(issue.scope+(issue.repoAccountId?(" account "+issue.repoAccountId):""))+\'</span>\';const evidence=(issue.evidence||[]).map(function(line){return "<li>"+escapeHtml(line)+"</li>";}).join("");const body=\'<div class="stack"><div class="muted">\'+escapeHtml(issue.summary||"")+\'</div><div class="mini-card"><strong>Recommendation</strong>\'+escapeHtml(issue.recommendation||"") + \'</div><div><strong style="display:block;margin-bottom:8px;">Evidence</strong><ul style="margin:0;padding-left:18px;display:grid;gap:8px;">\'+(evidence||"<li>No evidence lines captured.</li>")+\'</ul></div></div>\';return detailsBlock("issue:"+issue.id,(index+1)+". "+issue.title,meta,body,index===0);}).join("");}' +
+        'function renderWebsockets(state){const entries=Object.entries((state.websocket&&state.websocket.connections)||{});const target=document.getElementById("websocket-section");if(!entries.length){target.innerHTML=\'<div class="empty">No websocket connections are registered yet.</div>\';return;}target.innerHTML=entries.map(function(pair){const baseUrl=pair[0];const info=pair[1]||{};const topicEntries=Object.entries(info.topics||{});const recentMessages=Array.isArray(info.recentMessages)?info.recentMessages:[];const tone=info.status==="connected"?"ok":(info.status==="connecting"?"warn":"bad");const summaryMeta=badge(info.status||"unknown",tone)+\' <span class="muted">\' + escapeHtml(String(topicEntries.length)) + \' topic(s)</span>\' + \' <span class="muted">\' + escapeHtml(String(recentMessages.length)) + \' recent message(s)</span>\';const topicBody=topicEntries.length?topicEntries.map(function(topicPair){const topic=topicPair[0];const topicInfo=topicPair[1]||{};const mini=\'<div class="mini-grid"><div class="mini-card"><strong>Accounts</strong>\'+escapeHtml((topicInfo.accountIds||[]).join(", ")||"n/a")+\'</div><div class="mini-card"><strong>Subscribed</strong>\'+escapeHtml(formatTime(topicInfo.subscribedAt))+\'</div><div class="mini-card"><strong>Last Message</strong>\'+escapeHtml(formatTime(topicInfo.lastMessageAt))+\'</div></div>\';return detailsBlock("ws-topic:"+baseUrl+":"+topic,topic,"topic subscription",mini,false);}).join(""):\'<div class="empty">No topic subscriptions recorded.</div>\';const messageBody=recentMessages.length?recentMessages.map(function(message,index){const messageMeta=badge(message.duplicate?"duplicate":"handled",message.duplicate?"warn":"ok")+\' <span class="muted">\'+escapeHtml(message.source||"live")+\'</span>\' + \' <span class="muted">\'+escapeHtml(message.type||"unknown-type")+\'</span>\';const body=\'<div class="stack"><div class="mini-grid"><div class="mini-card"><strong>Message ID</strong>\'+escapeHtml(message.messageId||"n/a")+\'</div><div class="mini-card"><strong>Timestamp</strong>\'+escapeHtml(message.timestamp?String(message.timestamp):"n/a")+\'</div><div class="mini-card"><strong>Received</strong>\'+escapeHtml(formatTime(message.receivedAt))+\'</div><div class="mini-card"><strong>Accounts</strong>\'+escapeHtml((message.accountIds||[]).join(", ")||"n/a")+\'</div></div>\'+codeBlock("ws-msg:"+baseUrl+":"+(message.messageId||index),JSON.stringify(message.payload||{},null,2)) + \'</div>\';return detailsBlock("ws-message:"+baseUrl+":"+(message.messageId||index),(message.type||"message")+" "+(message.messageId||""),messageMeta,body,false);}).join(""):\'<div class="empty">No recent websocket messages have been recorded yet.</div>\';const body=\'<div class="stack"><div class="mini-grid"><div class="mini-card"><strong>Status</strong>\'+escapeHtml(info.status||"unknown")+\'</div><div class="mini-card"><strong>Connected</strong>\'+escapeHtml(formatTime(info.connectedAt))+\'</div><div class="mini-card"><strong>Last Message</strong>\'+escapeHtml(formatTime(info.lastMessageAt))+\'</div><div class="mini-card"><strong>Last Error</strong>\'+escapeHtml(info.lastError||"none")+\'</div></div><div class="stack">\'+detailsBlock("ws-recent:"+baseUrl,"Recent messages","latest live and missed-message traffic",messageBody,false)+topicBody+\'</div></div>\';return detailsBlock("ws:"+baseUrl,baseUrl,summaryMeta,body,entries.length===1);}).join("");}' +
+        'function renderTmux(state){const target=document.getElementById("tmux-section");const panes=state.tmux&&state.tmux.livePanes||[];const trackedText=state.tmux&&state.tmux.trackedPanes?state.tmux.trackedPanes:"{}";const launchSupported=state.tmux&&state.tmux.terminalLaunchSupported;const attachCommand="tmux attach -t "+(state.tmux&&state.tmux.sessionName||"remits-listener");const health=\'<div class="mini-grid"><div class="mini-card"><strong>tmux Installed</strong>\'+escapeHtml(String(state.tmux&&state.tmux.available))+\'</div><div class="mini-card"><strong>Session Exists</strong>\'+escapeHtml(String(state.tmux&&state.tmux.sessionExists))+\'</div><div class="mini-card"><strong>Session Name</strong>\'+escapeHtml(state.tmux&&state.tmux.sessionName||"n/a")+\'</div><div class="mini-card"><strong>Live Panes</strong>\'+escapeHtml(String(panes.length))+\'</div><div class="mini-card"><strong>Open from Dashboard</strong>\'+escapeHtml(launchSupported?"supported":"not supported")+\'</div></div><div class="muted" style="margin-bottom:14px;">\'+escapeHtml(launchSupported?"Use the Open Tmux Terminal button to bring Terminal forward and attach automatically.":"Dashboard-to-terminal launch is not supported on this platform. Run the attach command manually.")+\'</div>\';const quickAttach=detailsBlock("tmux:attach","Quick attach command","manual fallback",codeBlock("tmux-attach-cmd",attachCommand),false);const paneSection=detailsBlock("tmux:panes","Live panes",escapeHtml(String(panes.length))+" pane(s)",codeBlock("tmux-live-panes",JSON.stringify(panes,null,2),"log"),false);const trackedSection=detailsBlock("tmux:tracked","Tracked pane routing","ticket/task to pane mapping",codeBlock("tmux-tracked",trackedText),false);const logFile=(state.globalFiles||[]).find(function(file){return file.label==="tmux-activity.log (tail)";});const logSection=detailsBlock("tmux:activity","Activity tail","stream of tmux and websocket events",codeBlock("tmux-log",logFile&&logFile.content||"[missing]","log"),true);target.innerHTML=health+quickAttach+paneSection+trackedSection+logSection;const openButton=document.querySelector(\'[data-action="open-tmux"]\');if(openButton){openButton.disabled=!launchSupported||!(state.tmux&&state.tmux.available);}}' +
+        'function renderGlobalFiles(state){const target=document.getElementById("global-files");const files=(state.globalFiles||[]).filter(function(file){return file.label!=="tmux-activity.log (tail)";});if(!files.length){target.innerHTML=\'<div class="empty">No global files found.</div>\';return;}target.innerHTML=files.map(function(file){const tone=file.exists?"ok":"warn";const meta=badge(file.exists?"present":"missing",tone)+\' <span class="muted">\'+escapeHtml(file.updatedAt?formatTime(file.updatedAt):"not found")+\'</span>\';const body=\'<div class="stack"><div class="mini-grid"><div class="mini-card"><strong>Path</strong>\'+escapeHtml(file.path||"")+\'</div><div class="mini-card"><strong>Size</strong>\'+escapeHtml(String(file.size||0))+\' bytes</div><div class="mini-card"><strong>Updated</strong>\'+escapeHtml(formatTime(file.updatedAt))+\'</div></div>\'+codeBlock("global:"+file.label,file.content)+(file.label==="service-state.json"?\'<div class="muted">Use this file to discover the dashboard URL and runtime websocket summary.</div>\':"")+\'</div>\';return detailsBlock("global:"+file.label,file.label,meta,body,false);}).join("");}' +
+        'function renderRepos(state){const target=document.getElementById("repo-section");const repos=state.repos||[];if(!repos.length){target.innerHTML=\'<div class="empty">No indexed account repos were found. Use "Rescan Account Repos" to rebuild the index.</div>\';return;}target.innerHTML=repos.map(function(repo){const tone=repo.exists?"ok":"warn";const meta=badge(repo.exists?"available":"missing",tone)+\' <span class="muted">type: \'+escapeHtml(repo.type||"n/a")+\'</span>\';const files=(repo.files||[]).map(function(file){const fileMeta=badge(file.exists?"present":"missing",file.exists?"ok":"warn")+\' <span class="muted">\'+escapeHtml(file.updatedAt?formatTime(file.updatedAt):"not found")+\'</span>\';const body=\'<div class="stack"><div class="mini-grid"><div class="mini-card"><strong>Path</strong>\'+escapeHtml(file.path||"")+\'</div><div class="mini-card"><strong>Size</strong>\'+escapeHtml(String(file.size||0))+\' bytes</div><div class="mini-card"><strong>Updated</strong>\'+escapeHtml(formatTime(file.updatedAt))+\'</div></div>\'+codeBlock("repo:"+repo.accountId+":"+file.label,file.content,file.label.indexOf("session log")>=0?"log":"")+\'</div>\';return detailsBlock("repo-file:"+repo.accountId+":"+file.label,file.label,fileMeta,body,false);}).join("");const body=\'<div class="stack"><div class="mini-grid"><div class="mini-card"><strong>Directory</strong>\'+escapeHtml(repo.directory||"")+\'</div><div class="mini-card"><strong>Source</strong>\'+escapeHtml(repo.source||"n/a")+\'</div><div class="mini-card"><strong>Platform Account</strong>\'+escapeHtml(String(repo.platformAccountId||"n/a"))+\'</div></div><div class="repo-files">\'+files+\'</div></div>\';return detailsBlock("repo:"+repo.accountId,(repo.name||"Unknown")+" ("+repo.accountId+")",meta,body,false);}).join("");}' +
+        'function renderAll(state){const detailState=saveDetailsState();const scrollState=saveScrollState();dashboardState=state;document.getElementById("generated-at").textContent=formatTime(state.generatedAt);renderStatusCards(state);renderSummary(state);renderLastAction(state);renderIssues(state);renderWebsockets(state);renderTmux(state);renderGlobalFiles(state);renderRepos(state);restoreDetailsState(detailState);restoreScrollState(scrollState);}' +
+        'async function fetchState(){const res=await fetch("/api/state",{cache:"no-store"});if(!res.ok)throw new Error("State refresh failed with "+res.status);return res.json();}' +
+        'function showToast(message){const toast=document.getElementById("toast");toast.textContent=message;toast.classList.add("show");clearTimeout(showToast._timer);showToast._timer=setTimeout(function(){toast.classList.remove("show");},2400);}' +
+        'async function triggerAction(action,button){if(actionInFlight)return;actionInFlight=true;button.disabled=true;try{const res=await fetch("/action",{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded","Accept":"application/json"},body:"action="+encodeURIComponent(action)});if(!res.ok)throw new Error("Action failed with "+res.status);const payload=await res.json();renderAll(payload.state);if(payload.result&&payload.result.bundlePath){showToast("Issue bundle prepared at "+payload.result.bundlePath);}else{showToast(action.replace(/-/g," ")+" complete");}}catch(err){showToast(err.message||String(err));}finally{actionInFlight=false;button.disabled=false;}}' +
+        'document.querySelectorAll("[data-action]").forEach(function(button){button.addEventListener("click",function(){triggerAction(button.getAttribute("data-action"),button);});});' +
+        'renderAll(dashboardState);' +
+        'setInterval(function(){fetchState().then(renderAll).catch(function(err){showToast(err.message||String(err));});},refreshMs);' +
+      '})();' +
+    '</script>' +
+    '</body></html>';
+}
+
+async function reconnectManagedWebsockets() {
+  const clients = managedClients.slice();
+  for (const managedClient of clients) {
+    if (!managedClient || !managedClient.client) {
+      continue;
+    }
+    try {
+      await managedClient.client.deactivate();
+    } catch (_) {
+      // Continue reconnecting the rest.
+    }
+  }
+  for (const managedClient of clients) {
+    if (!managedClient || !managedClient.client) {
+      continue;
+    }
+    try {
+      managedClient.lastConnectAttemptAt = Date.now();
+      managedClient.client.activate();
+    } catch (_) {
+      // Continue reconnecting the rest.
+    }
+  }
+}
+
+function startDashboardServer(preferredPort) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer(async (req, res) => {
+      const requestUrl = new URL(req.url, 'http://' + DASHBOARD_HOST + ':' + (runtimeState.service.dashboardPort || preferredPort));
+      if (req.method === 'GET' && requestUrl.pathname === '/api/state') {
+        res.statusCode = 200;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify(collectDashboardSnapshot(), null, 2));
+        return;
+      }
+
+      if (req.method === 'POST' && requestUrl.pathname === '/action') {
+        let body = '';
+        req.on('data', (chunk) => {
+          body += chunk.toString();
+        });
+        req.on('end', async () => {
+          const params = new URLSearchParams(body);
+          const action = params.get('action');
+          let actionResult = null;
+          runtimeState.lastAction = {
+            action,
+            at: new Date().toISOString()
+          };
+          if (action === 'export-issues') {
+            const bundlePath = exportIssueBundle(collectDashboardSnapshot());
+            actionResult = { bundlePath };
+            runtimeState.lastAction.bundlePath = bundlePath;
+          } else if (action === 'rescan-repos') {
+            recordDiscoverySummary(discoverAccountRepos());
+          } else if (action === 'open-tmux') {
+            openTmuxSessionForUser();
+          } else if (action === 'start-tmux') {
+            ensureTmuxSession(os.homedir());
+          } else if (action === 'stop-tmux') {
+            killTmuxSession();
+          } else if (action === 'reconnect-websockets') {
+            await reconnectManagedWebsockets();
+          }
+          const wantsJson = String(req.headers.accept || '').includes('application/json');
+          if (wantsJson) {
+            res.statusCode = 200;
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify({
+              success: true,
+              action,
+              result: actionResult,
+              state: collectDashboardSnapshot()
+            }));
+            return;
+          }
+          res.statusCode = 302;
+          res.setHeader('Location', '/');
+          res.end('');
+        });
+        return;
+      }
+
+      if (req.method === 'GET' && requestUrl.pathname === '/') {
+        res.statusCode = 200;
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.end(renderDashboardHtml(collectDashboardSnapshot()));
+        return;
+      }
+
+      res.statusCode = 404;
+      res.end('Not found');
+    });
+
+    const bind = (port, allowFallback) => {
+      server.once('error', (err) => {
+        if (allowFallback && err && err.code === 'EADDRINUSE') {
+          bind(0, false);
+          return;
+        }
+        reject(err);
+      });
+      server.listen(port, DASHBOARD_HOST, () => {
+        const address = server.address();
+        const port = address && typeof address === 'object' ? address.port : preferredPort;
+        dashboardServer = server;
+        runtimeState.service.dashboardPort = port;
+        runtimeState.service.dashboardUrl = 'http://' + DASHBOARD_HOST + ':' + port + '/';
+        updateRuntimeServiceState();
+        resolve(server);
+      });
+    };
+
+    bind(preferredPort, true);
+  });
+}
+
+// --- Agent CLI dispatch via tmux ---
+const TMUX_SESSION_NAME = 'remits-listener';
+const DISPATCH_STATE_FILE = path.join(SESSION_DIR, 'dispatch-panes.json');
+
+// In-memory map of support-ticket routing key -> tmux pane ID (persisted for crash recovery)
+let paneMap = {};
+
+function dispatchTicketId(message) {
+  if (!message || typeof message !== 'object') return null;
+  if (message.ticketId !== undefined && message.ticketId !== null && String(message.ticketId).trim()) {
+    return String(message.ticketId).trim();
+  }
+  return null;
+}
+
+function dispatchRoutingKey(message) {
+  const ticketId = dispatchTicketId(message);
+  if (ticketId) return 'ticket:' + ticketId;
+  if (message && message.taskId !== undefined && message.taskId !== null && String(message.taskId).trim()) {
+    return 'task:' + String(message.taskId).trim();
+  }
+  return null;
+}
+
+function loadPaneMap() {
+  if (fs.existsSync(DISPATCH_STATE_FILE)) {
+    try {
+      paneMap = JSON.parse(fs.readFileSync(DISPATCH_STATE_FILE, 'utf8'));
+    } catch (_) {
+      paneMap = {};
+    }
+  }
+}
+
+function savePaneMap() {
+  ensureSessionDir();
+  atomicWriteFile(DISPATCH_STATE_FILE, JSON.stringify(paneMap, null, 2));
+}
+
+function isTmuxAvailable() {
+  try {
+    execSync('which tmux', { stdio: 'ignore' });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function tmuxSessionExists() {
+  try {
+    execSync('tmux has-session -t ' + shellQuote(TMUX_SESSION_NAME), { stdio: 'ignore' });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function tmuxPaneIsAlive(paneId) {
+  try {
+    // Check both that the pane exists AND that it's not dead
+    const output = execSync(
+      'tmux list-panes -a -F ' + shellQuote('#{pane_id} #{pane_dead}'),
+      { stdio: ['ignore', 'pipe', 'ignore'] }
+    ).toString();
+    const lines = output.split('\n').map((l) => l.trim()).filter(Boolean);
+    for (const line of lines) {
+      const [id, dead] = line.split(' ');
+      if (id === paneId) {
+        return dead !== '1';
+      }
+    }
+    return false; // pane not found at all
+  } catch (_) {
+    return false;
+  }
+}
+
+function killPane(paneId) {
+  try {
+    execSync('tmux kill-pane -t ' + shellQuote(paneId), { stdio: 'ignore' });
+    appendGlobalActivityLog('tmux', 'pane.killed', { paneId });
+  } catch (_) {}
+}
+
+function killTmuxSession() {
+  if (!tmuxSessionExists()) return;
+  try {
+    execSync('tmux kill-session -t ' + shellQuote(TMUX_SESSION_NAME), { stdio: 'ignore' });
+    appendGlobalActivityLog('tmux', 'session.killed', { sessionName: TMUX_SESSION_NAME });
+  } catch (_) {}
+}
+
+function configureTmuxSession() {
+  const commands = [
+    'tmux set-option -t ' + shellQuote(TMUX_SESSION_NAME) + ' mouse on',
+    'tmux set-option -t ' + shellQuote(TMUX_SESSION_NAME) + ' history-limit 100000',
+    'tmux set-window-option -t ' + shellQuote(TMUX_SESSION_NAME) + ' remain-on-exit on',
+    'tmux set-window-option -t ' + shellQuote(TMUX_SESSION_NAME) + ' scroll-on-clear on',
+    'tmux set-window-option -t ' + shellQuote(TMUX_SESSION_NAME) + ' automatic-rename off'
+  ];
+  for (const command of commands) {
+    try {
+      execSync(command, { stdio: 'ignore' });
+    } catch (_) {}
+  }
+}
+
+function ensureTmuxSession(accountDir) {
+  if (!isTmuxAvailable()) {
+    appendGlobalActivityLog('tmux', 'session.create_skipped.tmux_unavailable', { accountDir }, 'error');
+    return false;
+  }
+  if (tmuxSessionExists()) return;
+  execSync(
+    'tmux new-session -d -s ' + shellQuote(TMUX_SESSION_NAME) + ' -n ' + shellQuote('listener') + ' -c ' + shellQuote(accountDir),
+    { stdio: 'ignore' }
+  );
+  configureTmuxSession();
+  console.log('[listener] Created tmux session:', TMUX_SESSION_NAME);
+  appendGlobalActivityLog('tmux', 'session.created', {
+    sessionName: TMUX_SESSION_NAME,
+    accountDir
+  });
+  return true;
+}
+
+function canLaunchTerminalForTmux() {
+  return process.platform === 'darwin';
+}
+
+function openTmuxSessionForUser() {
+  if (!isTmuxAvailable()) {
+    throw new Error('tmux is not installed');
+  }
+
+  if (!tmuxSessionExists()) {
+    ensureTmuxSession(os.homedir());
+  }
+
+  const attachCommand = 'tmux attach -t ' + TMUX_SESSION_NAME + ' || tmux new-session -A -s ' + TMUX_SESSION_NAME;
+
+  if (process.platform === 'darwin') {
+    const osaScript = [
+      'tell application "Terminal"',
+      'activate',
+      'do script ' + JSON.stringify(attachCommand),
+      'end tell'
+    ].join('\n');
+    execSync('osascript -e ' + shellQuote(osaScript), { stdio: 'ignore' });
+    appendGlobalActivityLog('tmux', 'terminal.opened', {
+      sessionName: TMUX_SESSION_NAME,
+      command: attachCommand
+    });
+    return {
+      success: true,
+      method: 'terminal',
+      command: attachCommand
+    };
+  }
+
+  throw new Error('Opening a terminal window is not supported on this platform yet. Run `' + attachCommand + '` manually.');
+}
+
+function dispatchWindowName(accountId, routingKey) {
+  const base = routingKey || ('account:' + accountId) || 'dispatch';
+  return base
+    .replace(/[^a-zA-Z0-9:_-]+/g, '-')
+    .slice(0, 40) || 'dispatch';
+}
+
+function resolveAgentCommand(agent, prompt) {
+  const escapedPrompt = prompt.replace(/'/g, "'\"'\"'");
+  // All agents are launched in interactive mode so the user can watch and interact.
+  // claude: positional arg starts interactive session with initial prompt
+  // codex: positional arg starts interactive session with initial prompt
+  // gemini: positional arg starts interactive session with initial prompt
+  switch (agent) {
+    case 'claude':
+      return "claude '" + escapedPrompt + "'";
+    case 'codex':
+      return "codex '" + escapedPrompt + "'";
+    case 'gemini':
+      return "gemini '" + escapedPrompt + "'";
+    default:
+      return "claude '" + escapedPrompt + "'";
+  }
+}
+
+function resolveAccountDir(accountId) {
+  if (!fs.existsSync(ACCOUNT_REPO_INDEX_FILE)) return null;
+  try {
+    const index = JSON.parse(fs.readFileSync(ACCOUNT_REPO_INDEX_FILE, 'utf8'));
+    const entry = index[String(accountId)];
+    if (entry && entry.directory && fs.existsSync(entry.directory)) {
+      return entry.directory;
+    }
+  } catch (_) {}
+  return null;
+}
+
+function normalizeDispatchAccountId(value) {
+  if (value === undefined || value === null) return null;
+  const trimmed = String(value).trim();
+  return trimmed ? trimmed : null;
+}
+
+function resolveDispatchAccountId(message, fallbackAccountId) {
+  const candidates = [
+    normalizeDispatchAccountId(message && message.implementationAccountId),
+    normalizeDispatchAccountId(message && message.accountId),
+    normalizeDispatchAccountId(fallbackAccountId)
+  ].filter(Boolean);
+
+  const uniqueCandidates = [];
+  for (const candidate of candidates) {
+    if (!uniqueCandidates.includes(candidate)) {
+      uniqueCandidates.push(candidate);
+    }
+  }
+
+  for (const candidate of uniqueCandidates) {
+    if (resolveAccountDir(candidate)) {
+      return candidate;
+    }
+  }
+
+  return uniqueCandidates[0] || null;
+}
+
+function sendKeysToPane(paneId, text) {
+  // Paste through a tmux buffer so multiline follow-ups are injected reliably
+  // into interactive agent UIs, then submit them explicitly.
+  const bufferName = 'remits-cli-' + crypto.randomUUID();
+  try {
+    execSync(
+      'tmux load-buffer -b ' + shellQuote(bufferName) + ' -',
+      { input: text, stdio: ['pipe', 'ignore', 'ignore'] }
+    );
+    execSync(
+      'tmux paste-buffer -d -b ' + shellQuote(bufferName) + ' -t ' + shellQuote(paneId),
+      { stdio: 'ignore' }
+    );
+    execSync(
+      'tmux send-keys -t ' + shellQuote(paneId) + ' Enter',
+      { stdio: 'ignore' }
+    );
+  } finally {
+    try {
+      execSync('tmux delete-buffer -b ' + shellQuote(bufferName), { stdio: 'ignore' });
+    } catch (_) {}
+  }
+}
+
+function buildDispatchPrompt(message, options) {
+  const dispatchOptions = options && typeof options === 'object' ? options : {};
+  const textPrompt = message && (message.prompt || message.message);
+  const context = message && typeof message === 'object' ? Object.assign({}, message) : {};
+  delete context.prompt;
+  delete context.message;
+
+  const instructionLines = [
+    'This message was delivered by the remits-cli tool from an inbound platform message.',
+    'When triaging and handling this request, load and use the remits-cli skill.'
+  ];
+
+  if (dispatchOptions.noAccountDir === true) {
+    instructionLines.push('remits-cli dispatch status: no_account_dir.');
+    instructionLines.push('The listener could not resolve an account directory from the ticket payload, but you should still handle the request and work with the user to gather any additional account details if needed.');
+  }
+
+  if (textPrompt) {
+    instructionLines.push('');
+    instructionLines.push('Inbound message:');
+    instructionLines.push(textPrompt);
+  }
+
+  if (Object.keys(context).length) {
+    instructionLines.push('');
+    instructionLines.push('Dispatch context:');
+    instructionLines.push('```json');
+    instructionLines.push(JSON.stringify(context, null, 2));
+    instructionLines.push('```');
+  }
+
+  return instructionLines.join('\n');
+}
+
+function dispatchToAgent(accountId, message) {
+  const accountDir = resolveAccountDir(accountId);
+
+  if (!isTmuxAvailable()) {
+    console.error('[listener] tmux is not installed. Cannot dispatch agent session.');
+    appendGlobalActivityLog('tmux', 'dispatch.skipped.tmux_unavailable', {
+      accountId,
+      accountDir,
+      message: summarizeDispatchMessage(message)
+    }, 'error');
+    return;
+  }
+
+  const ticketId = dispatchTicketId(message);
+  const routingKey = dispatchRoutingKey(message);
+  const prompt = buildDispatchPrompt(message, {
+    noAccountDir: !accountDir
+  });
+
+  if (!accountDir) {
+    console.error('[listener] No known directory for account', accountId, '- dispatching anyway');
+    appendGlobalActivityLog('tmux', 'dispatch.no_account_dir', {
+      accountId,
+      message: summarizeDispatchMessage(message)
+    }, 'error');
+  }
+
+  // If this ticket already has a tracked pane, check its state
+  if (routingKey && paneMap[routingKey]) {
+    const existingPaneId = paneMap[routingKey];
+    if (tmuxPaneIsAlive(existingPaneId)) {
+      // Pane is alive, so deliver the follow-up to the existing ticket workstream
+      console.log('[listener] Delivering follow-up for', routingKey, 'to existing pane', existingPaneId);
+      appendGlobalActivityLog('tmux', 'dispatch.follow_up', {
+        accountId,
+        accountDir,
+        ticketId,
+        routingKey,
+        paneId: existingPaneId,
+        message: summarizeDispatchMessage(message)
+      });
+      try {
+        sendKeysToPane(existingPaneId, prompt);
+        return;
+      } catch (err) {
+        console.error('[listener] Failed to send to pane', existingPaneId, ':', err.message, '- creating new pane');
+        appendGlobalActivityLog('tmux', 'dispatch.follow_up_failed', {
+          accountId,
+          accountDir,
+          ticketId,
+          routingKey,
+          paneId: existingPaneId,
+          error: err.message,
+          message: summarizeDispatchMessage(message)
+        }, 'error');
+      }
+    }
+    // Pane is dead or gone, so replace it for this ticket/task routing key.
+    console.log('[listener] Pane', existingPaneId, 'for', routingKey, 'is dead or gone - replacing');
+    appendGlobalActivityLog('tmux', 'dispatch.pane_replaced', {
+      accountId,
+      accountDir,
+      ticketId,
+      routingKey,
+      paneId: existingPaneId,
+      message: summarizeDispatchMessage(message)
+    });
+    killPane(existingPaneId);
+    delete paneMap[routingKey];
+    savePaneMap();
+  }
+
+  // Create a new pane for this task
+  try {
+    const paneDir = accountDir || os.homedir();
+    ensureTmuxSession(paneDir);
+
+    const agent = getPreferredAgent();
+    const agentCmd = resolveAgentCommand(agent, prompt);
+    const windowName = dispatchWindowName(accountId, routingKey);
+
+    // Wrap in a login shell so the pane inherits the user's full PATH
+    // (the daemonized listener process has a minimal environment)
+    const userShell = process.env.SHELL || '/bin/zsh';
+    const loginCmd = userShell + ' -l -c ' + shellQuote(agentCmd);
+
+    // Create a dedicated window for this workstream so full-screen agent UIs
+    // remain readable and easy to inspect.
+    const paneInfo = execSync(
+      'tmux new-window -t ' + shellQuote(TMUX_SESSION_NAME) +
+      ' -n ' + shellQuote(windowName) +
+      ' -c ' + shellQuote(paneDir) +
+      ' -P -F ' + shellQuote('#{pane_id}') +
+      ' ' + shellQuote(loginCmd),
+      { stdio: ['ignore', 'pipe', 'ignore'] }
+    ).toString().trim();
+
+    console.log('[listener] Dispatched', routingKey || '(untracked message)', 'to', agent, 'in pane', paneInfo, 'at', accountDir);
+    appendGlobalActivityLog('tmux', 'dispatch.created', {
+      accountId,
+      accountDir: paneDir,
+      resolvedAccountDir: accountDir,
+      ticketId,
+      routingKey,
+      paneId: paneInfo,
+      agent,
+      message: summarizeDispatchMessage(message)
+    });
+
+    if (routingKey) {
+      paneMap[routingKey] = paneInfo;
+      savePaneMap();
+    }
+  } catch (err) {
+    console.error('[listener] Failed to create tmux pane:', err.message);
+    appendGlobalActivityLog('tmux', 'dispatch.create_failed', {
+      accountId,
+      accountDir,
+      ticketId,
+      routingKey,
+      error: err.message,
+      agent: getPreferredAgent(),
+      message: summarizeDispatchMessage(message)
+    }, 'error');
+  }
+}
+
+function publishMissedMessageRequest(client, baseUrl, userId) {
+  if (!userId) {
+    return;
+  }
+  const since = lastMessageTimestampForScope(baseUrl, userId);
+  client.publish({
+    destination: '/app/missed-messages',
+    body: JSON.stringify({
+      userId: String(userId),
+      since
+    })
+  });
+  appendGlobalActivityLog('listener', 'websocket.missed_messages.requested', {
+    baseUrl,
+    userId,
+    since
+  });
+}
+
+function acknowledgeWebsocketMessage(client, messageId, userIds = []) {
+  if (!messageId) {
+    return;
+  }
+  const primaryUserId = userIds.find(Boolean);
+  const body = primaryUserId
+    ? { messageId, userId: String(primaryUserId) }
+    : { messageId };
+  client.publish({
+    destination: '/app/ack',
+    body: JSON.stringify(body)
+  });
+}
+
+function processInboundWebsocketMessage(client, baseUrl, topic, accountIds, userIds, source, rawMessage) {
+  const data = rawMessage && typeof rawMessage === 'object' ? rawMessage : {};
+  const messageId = data.messageId ? String(data.messageId) : null;
+  const duplicate = messageId ? hasProcessedMessageId(messageId) : false;
+
+  recordWebsocketMessage(baseUrl, topic, data, {
+    source,
+    duplicate,
+    accountIds
+  });
+
+  if (messageId) {
+    acknowledgeWebsocketMessage(client, messageId, userIds);
+  }
+
+  updateLastMessageTimestamp(baseUrl, userIds, data.timestamp);
+  runtimeState.websocket[baseUrl].lastMessageAt = new Date().toISOString();
+  if (runtimeState.websocket[baseUrl].topics[topic]) {
+    runtimeState.websocket[baseUrl].topics[topic].lastMessageAt = runtimeState.websocket[baseUrl].lastMessageAt;
+  }
+
+  if (duplicate) {
+    appendGlobalActivityLog('listener', 'websocket.duplicate_ignored', {
+      baseUrl,
+      topic,
+      messageId,
+      source
+    });
+    updateRuntimeServiceState();
+    return;
+  }
+
+  if (messageId) {
+    rememberProcessedMessageId(messageId);
+  }
+
+  if (data.type === 'TestSuite') {
+    const payload = data.payload || {};
+    const payloadTaskId = payload.taskId || null;
+    const currentTestTaskId = runtimeState.currentTestTaskId || null;
+    if (payloadTaskId && currentTestTaskId && payloadTaskId !== currentTestTaskId) {
+      updateRuntimeServiceState();
+      return;
+    }
+    if (payload.tests || payload.name || payload.total != null) {
+      const acctId = payload.accountId || accountIds[0];
+      console.log('[ws][TestSuite][account:' + acctId + ']', JSON.stringify(payload));
+    }
+  } else if (data.type === 'remits-cli') {
+    const payload = data.payload || data;
+    const dispatchAccountId = resolveDispatchAccountId(payload, accountIds[0]);
+    console.log('[ws][remits-cli][account:' + dispatchAccountId + ']', JSON.stringify(payload));
+    appendGlobalActivityLog('tmux', 'dispatch.received', {
+      baseUrl,
+      topic,
+      accountId: dispatchAccountId,
+      source,
+      messageId,
+      message: summarizeDispatchMessage(payload)
+    });
+    dispatchToAgent(dispatchAccountId, payload);
+  }
+
+  updateRuntimeServiceState();
+}
+
+function createManagedWebsocketClient(baseUrl, urlSessions) {
+  const normalizedBaseUrl = normalizeBaseUrl(baseUrl || DEFAULT_BASE_URL);
+  const managedClient = {
+    baseUrl: normalizedBaseUrl,
+    urlSessions: Array.isArray(urlSessions) ? urlSessions.slice() : [],
+    client: null,
+    lastConnectAttemptAt: null,
+    lastConnectedAt: null,
+    lastDisconnectedAt: null
+  };
+
+  ensureRuntimeWebsocketEntry(normalizedBaseUrl);
+  runtimeState.websocket[normalizedBaseUrl] = {
+    ...runtimeState.websocket[normalizedBaseUrl],
+    status: 'connecting',
+    connectedAt: runtimeState.websocket[normalizedBaseUrl].connectedAt || null,
+    disconnectedAt: runtimeState.websocket[normalizedBaseUrl].disconnectedAt || null,
+    lastError: null
+  };
+
+  const client = new Client({
+    brokerURL: webSocketUrl(normalizedBaseUrl),
+    reconnectDelay: WEBSOCKET_RECONNECT_DELAY_MS,
+    heartbeatIncoming: WEBSOCKET_HEARTBEAT_MS,
+    heartbeatOutgoing: WEBSOCKET_HEARTBEAT_MS,
+    connectionTimeout: WEBSOCKET_CONNECTION_TIMEOUT_MS,
+    discardWebsocketOnCommFailure: true,
+    debug: () => {},
+    beforeConnect: () => {
+      managedClient.lastConnectAttemptAt = Date.now();
+      ensureRuntimeWebsocketEntry(normalizedBaseUrl);
+      runtimeState.websocket[normalizedBaseUrl] = {
+        ...runtimeState.websocket[normalizedBaseUrl],
+        status: 'connecting',
+        lastError: null
+      };
+      updateRuntimeServiceState();
+    }
+  });
+
+  client.onConnect = () => {
+    managedClient.lastConnectedAt = Date.now();
+    ensureRuntimeWebsocketEntry(normalizedBaseUrl);
+    runtimeState.websocket[normalizedBaseUrl] = {
+      ...runtimeState.websocket[normalizedBaseUrl],
+      status: 'connected',
+      connectedAt: new Date().toISOString(),
+      disconnectedAt: null,
+      lastError: null,
+      topics: {}
+    };
+    console.log('[listener] Connected to', normalizedBaseUrl);
+    appendGlobalActivityLog('listener', 'websocket.connected', { baseUrl: normalizedBaseUrl });
+    updateRuntimeServiceState();
+
+    const subscribedTopics = new Set();
+    const accountsByTopic = {};
+    const userIds = [];
+    for (const session of managedClient.urlSessions) {
+      if (!session || !session.websocketTopic) {
+        continue;
+      }
+      if (!accountsByTopic[session.websocketTopic]) {
+        accountsByTopic[session.websocketTopic] = [];
+      }
+      accountsByTopic[session.websocketTopic].push(session.accountId);
+      const userId = session.user && session.user.id ? String(session.user.id) : null;
+      if (userId && !userIds.includes(userId)) {
+        userIds.push(userId);
+      }
+    }
+
+    for (const [topic, accountIds] of Object.entries(accountsByTopic)) {
+      if (subscribedTopics.has(topic)) {
+        continue;
+      }
+      subscribedTopics.add(topic);
+      runtimeState.websocket[normalizedBaseUrl].topics[topic] = {
+        accountIds,
+        subscribedAt: new Date().toISOString(),
+        lastMessageAt: null
+      };
+      client.subscribe('/topic/messages/' + topic, (msg) => {
+        try {
+          const data = JSON.parse(msg.body);
+          processInboundWebsocketMessage(client, normalizedBaseUrl, topic, accountIds, userIds, 'live', data);
+        } catch (err) {
+          console.error('[ws] parse error:', err.message);
+          runtimeState.websocket[normalizedBaseUrl] = {
+            ...runtimeState.websocket[normalizedBaseUrl],
+            lastError: err.message
+          };
+          appendGlobalActivityLog('listener', 'websocket.parse_error', {
+            baseUrl: normalizedBaseUrl,
+            topic,
+            error: err.message
+          }, 'error');
+          updateRuntimeServiceState();
+        }
+      });
+      console.log('[listener] Subscribed to topic', topic, '(accounts:', accountIds.join(', ') + ')');
+      appendGlobalActivityLog('listener', 'websocket.subscribed', {
+        baseUrl: normalizedBaseUrl,
+        topic,
+        accountIds
+      });
+      updateRuntimeServiceState();
+    }
+
+    for (const userId of userIds) {
+      publishMissedMessageRequest(client, normalizedBaseUrl, userId);
+    }
+  };
+
+  client.onDisconnect = () => {
+    managedClient.lastDisconnectedAt = Date.now();
+    ensureRuntimeWebsocketEntry(normalizedBaseUrl);
+    runtimeState.websocket[normalizedBaseUrl] = {
+      ...runtimeState.websocket[normalizedBaseUrl],
+      status: 'disconnected',
+      disconnectedAt: new Date().toISOString()
+    };
+    console.log('[listener] Disconnected from', normalizedBaseUrl, '- will reconnect');
+    appendGlobalActivityLog('listener', 'websocket.disconnected', { baseUrl: normalizedBaseUrl });
+    updateRuntimeServiceState();
+  };
+
+  client.onStompError = (frame) => {
+    const error = frame && frame.headers && frame.headers.message ? frame.headers.message : 'Unknown STOMP error';
+    ensureRuntimeWebsocketEntry(normalizedBaseUrl);
+    runtimeState.websocket[normalizedBaseUrl] = {
+      ...runtimeState.websocket[normalizedBaseUrl],
+      status: 'error',
+      lastError: error
+    };
+    console.error('[listener] STOMP error:', error);
+    appendGlobalActivityLog('listener', 'websocket.stomp_error', {
+      baseUrl: normalizedBaseUrl,
+      error
+    }, 'error');
+    updateRuntimeServiceState();
+  };
+
+  client.onWebSocketClose = (event) => {
+    managedClient.lastDisconnectedAt = Date.now();
+    const detail = describeWebsocketCloseEvent(event);
+    ensureRuntimeWebsocketEntry(normalizedBaseUrl);
+    runtimeState.websocket[normalizedBaseUrl] = {
+      ...runtimeState.websocket[normalizedBaseUrl],
+      status: 'disconnected',
+      disconnectedAt: new Date().toISOString(),
+      lastError: detail
+    };
+    appendGlobalActivityLog('listener', 'websocket.closed', {
+      baseUrl: normalizedBaseUrl,
+      detail
+    }, event && event.wasClean === false ? 'error' : 'info');
+    updateRuntimeServiceState();
+  };
+
+  client.onWebSocketError = (event) => {
+    const detail = describeWebsocketErrorEvent(event);
+    ensureRuntimeWebsocketEntry(normalizedBaseUrl);
+    runtimeState.websocket[normalizedBaseUrl] = {
+      ...runtimeState.websocket[normalizedBaseUrl],
+      status: 'error',
+      lastError: detail
+    };
+    appendGlobalActivityLog('listener', 'websocket.error', {
+      baseUrl: normalizedBaseUrl,
+      detail
+    }, 'error');
+    updateRuntimeServiceState();
+  };
+
+  managedClient.client = client;
+  return managedClient;
+}
+
+async function deactivateManagedWebsocketClient(managedClient) {
+  if (!managedClient || !managedClient.client) {
+    return;
+  }
+  try {
+    await managedClient.client.deactivate();
+  } catch (_) {
+    // Best effort during shutdown/replacement.
+  }
+}
+
+async function replaceManagedWebsocketClients(entries, reason) {
+  const nextGroups = groupSessionsByBaseUrl(entries);
+  const nextManagedClients = Object.entries(nextGroups).map(([baseUrl, urlSessions]) => createManagedWebsocketClient(baseUrl, urlSessions));
+  const previousClients = managedClients.slice();
+  managedClients = nextManagedClients;
+  runtimeState.websocket = {};
+  for (const managedClient of nextManagedClients) {
+    ensureRuntimeWebsocketEntry(managedClient.baseUrl);
+  }
+  updateRuntimeServiceState();
+
+  for (const managedClient of previousClients) {
+    await deactivateManagedWebsocketClient(managedClient);
+  }
+  for (const managedClient of nextManagedClients) {
+    managedClient.lastConnectAttemptAt = Date.now();
+    managedClient.client.activate();
+  }
+
+  appendGlobalActivityLog('listener', 'websocket.clients.replaced', {
+    reason,
+    connectionCount: nextManagedClients.length
+  });
+}
+
+function pruneDeadPaneMappings() {
+  const removed = [];
+  for (const [routingKey, paneId] of Object.entries(paneMap)) {
+    if (tmuxPaneIsAlive(paneId)) {
+      continue;
+    }
+    delete paneMap[routingKey];
+    removed.push({ routingKey, paneId });
+  }
+  if (removed.length) {
+    savePaneMap();
+    appendGlobalActivityLog('tmux', 'dispatch_state.pruned', {
+      removed
+    });
+  }
+}
+
+function ensureTmuxSessionHealthy(defaultDir) {
+  if (!isTmuxAvailable()) {
+    return;
+  }
+  if (tmuxSessionExists()) {
+    pruneDeadPaneMappings();
+    return;
+  }
+  const hadPaneMappings = Object.keys(paneMap).length > 0;
+  if (hadPaneMappings) {
+    paneMap = {};
+    savePaneMap();
+    appendGlobalActivityLog('tmux', 'dispatch_state.cleared.missing_session', {
+      sessionName: TMUX_SESSION_NAME
+    }, 'error');
+  }
+  ensureTmuxSession(defaultDir || os.homedir());
+}
+
+async function runManagedWebsocketWatchdog() {
+  const now = Date.now();
+  for (const managedClient of managedClients) {
+    if (!managedClient || !managedClient.client) {
+      continue;
+    }
+    const state = ensureRuntimeWebsocketEntry(managedClient.baseUrl);
+    const socket = managedClient.client.webSocket;
+    const readyState = socket && typeof socket.readyState === 'number' ? socket.readyState : null;
+    const disconnectedAtMs = state.disconnectedAt ? Date.parse(state.disconnectedAt) : 0;
+    const lastConnectAttemptAge = managedClient.lastConnectAttemptAt ? (now - managedClient.lastConnectAttemptAt) : 0;
+    const connectedReadyMismatch = state.status === 'connected' && readyState != null && readyState !== WebSocket.OPEN;
+    const stalledConnecting = state.status === 'connecting' && lastConnectAttemptAge > (WEBSOCKET_CONNECTION_TIMEOUT_MS + WEBSOCKET_WATCHDOG_GRACE_MS);
+    const prolongedOutage = (state.status === 'disconnected' || state.status === 'error') &&
+      disconnectedAtMs > 0 &&
+      (now - disconnectedAtMs) > WEBSOCKET_WATCHDOG_GRACE_MS;
+
+    if (!connectedReadyMismatch && !stalledConnecting && !prolongedOutage) {
+      continue;
+    }
+
+    const reason = connectedReadyMismatch
+      ? 'socket_state_mismatch:' + websocketReadyStateName(readyState)
+      : (stalledConnecting ? 'connect_timeout' : 'prolonged_outage');
+    appendGlobalActivityLog('listener', 'websocket.watchdog.reconnect', {
+      baseUrl: managedClient.baseUrl,
+      reason,
+      websocketStatus: state.status,
+      readyState: websocketReadyStateName(readyState)
+    }, 'error');
+    try {
+      await managedClient.client.deactivate();
+    } catch (_) {
+      // Continue into activate so the watchdog can still try to recover.
+    }
+    managedClient.lastConnectAttemptAt = Date.now();
+    try {
+      managedClient.client.activate();
+    } catch (err) {
+      appendGlobalActivityLog('listener', 'websocket.watchdog.activate_failed', {
+        baseUrl: managedClient.baseUrl,
+        reason,
+        error: describeError(err)
+      }, 'error');
+    }
+  }
+}
+
+// --- Persistent WebSocket listener ---
+async function listenCommand(flags) {
+  if (isListenerRunning()) {
+    const state = readServiceState();
+    console.log('remits-cli service is already running. Restarting.');
+    if (state.dashboardUrl) {
+      console.log('Existing control center:', state.dashboardUrl);
+    }
+    await listenStopCommand();
+    const stopped = await waitForListenerStopped(5000);
+    if (!stopped) {
+      throw new Error('Failed to stop the existing remits-cli service before restart.');
+    }
+  }
+
+  const sessions = readAllSessions();
+  const entries = listenerSessionEntriesFromStore(sessions);
+
+  if (!entries.length) {
+    throw new Error('No authenticated sessions with WebSocket topics. Run: remits-cli auth');
+  }
+
+  // Determine if we should daemonize
+  const foreground = flags.foreground === true || flags.foreground === 'true';
+
+  if (!foreground) {
+    const discovery = discoverAccountRepos();
+    // Fork into background
+    const { spawn } = require('child_process');
+    const child = spawn(process.execPath, [__filename, 'start', '--foreground', 'true'], {
+      detached: true,
+      stdio: 'ignore',
+      env: { ...process.env }
+    });
+    child.unref();
+    // Summarize connections and topics for the user
+    const urlGroups = {};
+    for (const s of entries) {
+      const url = s.baseUrl || DEFAULT_BASE_URL;
+      if (!urlGroups[url]) urlGroups[url] = {};
+      if (!urlGroups[url][s.websocketTopic]) urlGroups[url][s.websocketTopic] = [];
+      urlGroups[url][s.websocketTopic].push(s.accountId);
+    }
+    const connectionCount = Object.keys(urlGroups).length;
+    const topicCount = Object.values(urlGroups).reduce((sum, topics) => sum + Object.keys(topics).length, 0);
+
+    console.log('remits-cli service started in background (pid: ' + child.pid + ')');
+    appendGlobalActivityLog('listener', 'background.started', {
+      pid: child.pid,
+      connectionCount,
+      topicCount,
+      accountCount: entries.length,
+      repoCount: discovery.repoCount
+    });
+    const dashboardUrl = await waitForDashboardUrl(5000);
+    console.log(connectionCount + ' connection(s), ' + topicCount + ' topic(s), ' + entries.length + ' account(s)');
+    console.log('Discovered repo index entries:', discovery.repoCount);
+    if (dashboardUrl) {
+      console.log('Control center:', dashboardUrl);
+      if (openBrowser) {
+        try {
+          await openBrowser(dashboardUrl);
+        } catch (_) {
+          // Best-effort browser open; the URL is still printed for manual use.
+        }
+      }
+    } else {
+      console.log('Control center: waiting for dashboard URL, check `remits-cli status` in a moment.');
+    }
+    for (const [url, topics] of Object.entries(urlGroups)) {
+      console.log('  ' + url);
+      for (const [topic, accountIds] of Object.entries(topics)) {
+        console.log('    topic ' + topic + ' -> accounts: ' + accountIds.join(', '));
+      }
+    }
+    console.log('Use: remits-cli stop  to stop');
+    console.log('Use: remits-cli status  to check');
+    return;
+  }
+
+  // Foreground mode — this is the actual long-running listener
+  // Clean slate: kill any leftover tmux session and pane state from a previous run
+  killTmuxSession();
+  paneMap = {};
+  savePaneMap();
+
+  writeListenerPid();
+  runtimeState.service.startedAt = new Date().toISOString();
+  runtimeState.service.pid = process.pid;
+  recordDiscoverySummary(discoverAccountRepos());
+  const dashboardPort = Number(flags.port || flags.dashboardPort || DEFAULT_DASHBOARD_PORT);
+  await startDashboardServer(dashboardPort);
+
+  // Create the tmux session immediately so the user can attach right away
+  try {
+    const defaultDir = os.homedir();
+    execSync(
+      'tmux new-session -d -s ' + shellQuote(TMUX_SESSION_NAME) + ' -n ' + shellQuote('listener') + ' -c ' + shellQuote(defaultDir),
+      { stdio: 'ignore' }
+    );
+    configureTmuxSession();
+    appendGlobalActivityLog('tmux', 'session.created', {
+      sessionName: TMUX_SESSION_NAME,
+      accountDir: defaultDir,
+      source: 'listener.start'
+    });
+  } catch (err) {
+    console.error('[listener] Failed to create tmux session:', err.message);
+    appendGlobalActivityLog('tmux', 'session.create_failed', {
+      sessionName: TMUX_SESSION_NAME,
+      error: err.message
+    }, 'error');
+  }
+
+  // Clean up on exit — kill tmux session and clear state
+  let refreshInterval = null;
+  const cleanup = () => {
+    appendGlobalActivityLog('listener', 'cleanup', { pid: process.pid });
+    if (refreshInterval) {
+      clearInterval(refreshInterval);
+    }
+    for (const managedClient of managedClients) {
+      try {
+        if (managedClient && managedClient.client) {
+          managedClient.client.deactivate();
+        }
+      } catch (_) {}
+    }
+    managedClients = [];
+    if (dashboardServer) {
+      try {
+        dashboardServer.close();
+      } catch (_) {}
+      dashboardServer = null;
+    }
+    killTmuxSession();
+    paneMap = {};
+    savePaneMap();
+    clearListenerPid();
+    clearServiceState();
+    process.exit(0);
+  };
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+
+  console.log('[listener] Starting remits-cli service (pid: ' + process.pid + ')');
+  console.log('[dashboard] ' + runtimeState.service.dashboardUrl);
+  appendGlobalActivityLog('listener', 'foreground.started', {
+    pid: process.pid,
+    accountCount: entries.length,
+    logFile: TMUX_ACTIVITY_LOG_FILE,
+    dashboardUrl: runtimeState.service.dashboardUrl
+  });
+
+  let activeSessionSignature = listenerSessionSignature(entries);
+  await replaceManagedWebsocketClients(entries, 'listener.start');
+
+  // Periodically check for new/changed sessions and update subscriptions
+  let maintenanceInFlight = false;
+  refreshInterval = setInterval(async () => {
+    if (maintenanceInFlight) {
+      return;
+    }
+    maintenanceInFlight = true;
+    try {
+      ensureTmuxSessionHealthy(os.homedir());
+
+      const currentEntries = listenerSessionEntriesFromStore(readAllSessions());
+      const currentSignature = listenerSessionSignature(currentEntries);
+      if (currentSignature !== activeSessionSignature) {
+        console.log('[listener] Session set changed. Refreshing websocket clients.');
+        appendGlobalActivityLog('listener', 'sessions.changed', {
+          previousConnectionCount: managedClients.length,
+          nextConnectionCount: Object.keys(groupSessionsByBaseUrl(currentEntries)).length
+        });
+        await replaceManagedWebsocketClients(currentEntries, 'sessions.changed');
+        activeSessionSignature = currentSignature;
+      }
+
+      await runManagedWebsocketWatchdog();
+      updateRuntimeServiceState();
+    } catch (err) {
+      appendGlobalActivityLog('listener', 'maintenance.failed', {
+        error: describeError(err)
+      }, 'error');
+    } finally {
+      maintenanceInFlight = false;
+    }
+  }, SERVICE_MAINTENANCE_INTERVAL_MS);
+
+  // Keep the process alive
+  await new Promise(() => {});
+}
+
+async function listenStopCommand() {
+  // Kill the WebSocket listener process
+  if (fs.existsSync(LISTENER_PID_FILE)) {
+    try {
+      const pid = parseInt(fs.readFileSync(LISTENER_PID_FILE, 'utf8').trim(), 10);
+      process.kill(pid, 'SIGTERM');
+      console.log('remits-cli service stopped (pid: ' + pid + ')');
+      appendGlobalActivityLog('listener', 'stopped', { pid });
+    } catch (err) {
+      console.log('remits-cli service process not found. Cleaned up PID file.');
+      appendGlobalActivityLog('listener', 'stop.missing_process', { error: err.message }, 'error');
+    }
+    clearListenerPid();
+  } else {
+    console.log('No remits-cli service process was running.');
+    appendGlobalActivityLog('listener', 'stop.no_process');
+  }
+
+  // Kill the tmux session and clear pane tracking
+  if (tmuxSessionExists()) {
+    killTmuxSession();
+    console.log('Killed tmux session:', TMUX_SESSION_NAME);
+  }
+  if (fs.existsSync(DISPATCH_STATE_FILE)) {
+    atomicWriteFile(DISPATCH_STATE_FILE, '{}');
+    appendGlobalActivityLog('tmux', 'dispatch_state.cleared', {
+      file: DISPATCH_STATE_FILE
+    });
+  }
+  clearServiceState();
+}
+
+async function waitForListenerStopped(timeoutMs = 5000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isListenerRunning()) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return !isListenerRunning();
+}
+
+async function listenStatusCommand() {
+  const state = readServiceState();
+  if (isListenerRunning()) {
+    const pid = fs.readFileSync(LISTENER_PID_FILE, 'utf8').trim();
+    console.log('remits-cli service is running (pid: ' + pid + ')');
+    if (state.dashboardUrl) {
+      console.log('Dashboard:', state.dashboardUrl);
+    }
+    if (state.discovery && Number.isFinite(state.discovery.repoCount)) {
+      console.log('Indexed repos:', state.discovery.repoCount);
+    }
+  } else {
+    console.log('remits-cli service is not running.');
+  }
+}
+
+function npmCommand() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function remitsCliCommand() {
+  return process.platform === 'win32' ? 'remits-cli.cmd' : 'remits-cli';
+}
+
+function parseSemver(version) {
+  const match = String(version || '').trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ? match[4].split('.') : []
+  };
+}
+
+function comparePrereleaseIdentifiers(left, right) {
+  const leftNumber = /^\d+$/.test(left);
+  const rightNumber = /^\d+$/.test(right);
+  if (leftNumber && rightNumber) return Number(left) - Number(right);
+  if (leftNumber) return -1;
+  if (rightNumber) return 1;
+  return left.localeCompare(right);
+}
+
+function compareSemver(leftVersion, rightVersion) {
+  const left = parseSemver(leftVersion);
+  const right = parseSemver(rightVersion);
+  if (!left || !right) return String(leftVersion || '').localeCompare(String(rightVersion || ''));
+  for (const key of ['major', 'minor', 'patch']) {
+    if (left[key] !== right[key]) return left[key] - right[key];
+  }
+  if (!left.prerelease.length && right.prerelease.length) return 1;
+  if (left.prerelease.length && !right.prerelease.length) return -1;
+  const max = Math.max(left.prerelease.length, right.prerelease.length);
+  for (let i = 0; i < max; i++) {
+    if (left.prerelease[i] === undefined) return -1;
+    if (right.prerelease[i] === undefined) return 1;
+    const comparison = comparePrereleaseIdentifiers(left.prerelease[i], right.prerelease[i]);
+    if (comparison !== 0) return comparison;
+  }
+  return 0;
+}
+
+function acquireAutoUpdateLock() {
+  ensureSessionDir();
+  try {
+    fs.mkdirSync(AUTO_UPDATE_LOCK_DIR);
+    return true;
+  } catch (err) {
+    if (err && err.code === 'EEXIST') {
+      try {
+        const ageMs = Date.now() - fs.statSync(AUTO_UPDATE_LOCK_DIR).mtimeMs;
+        if (ageMs > 10 * 60 * 1000) {
+          fs.rmSync(AUTO_UPDATE_LOCK_DIR, { recursive: true, force: true });
+          fs.mkdirSync(AUTO_UPDATE_LOCK_DIR);
+          return true;
+        }
+      } catch (_) {}
+      return false;
+    }
+    return false;
+  }
+}
+
+function releaseAutoUpdateLock() {
+  try {
+    fs.rmSync(AUTO_UPDATE_LOCK_DIR, { recursive: true, force: true });
+  } catch (_) {}
+}
+
+function shouldAutoUpdate(command, flags) {
+  if (!command || command === 'help' || command === '--help') return false;
+  if (flags && flags['no-auto-update']) return false;
+  if (process.env.REMITS_CLI_AUTO_UPDATE && AUTO_UPDATE_DISABLED_VALUES.has(String(process.env.REMITS_CLI_AUTO_UPDATE).toLowerCase())) {
+    return false;
+  }
+  if (process.env.REMITS_CLI_AUTO_UPDATED === '1') return false;
+  return true;
+}
+
+function autoUpdateIfNeeded(originalArgv, options = {}) {
+  const requireSuccess = Boolean(options.requireSuccess);
+  let lockAcquired = false;
+  try {
+    lockAcquired = acquireAutoUpdateLock();
+    if (!lockAcquired) {
+      if (requireSuccess) {
+        throw new Error('Auto-update lock is busy; unable to verify the latest remits-cli version before starting.');
+      }
+      return false;
+    }
+    const pkg = require(path.join(__dirname, 'package.json'));
+    const currentVersion = pkg.version;
+    const latest = execFileSync(npmCommand(), ['view', REMITS_CLI_PACKAGE_NAME, 'version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+    if (latest && compareSemver(latest, currentVersion) > 0) {
+      console.log('[update] New version available: ' + currentVersion + ' -> ' + latest + '. Installing...');
+      const install = spawnSync(npmCommand(), ['install', '-g', REMITS_CLI_PACKAGE_NAME + '@latest'], {
+        stdio: 'inherit',
+        env: process.env
+      });
+      if (install.error || install.status !== 0) {
+        if (requireSuccess) {
+          throw new Error('Auto-update failed; remits-cli start requires the latest published version before continuing.');
+        }
+        console.log('[update] Update failed; continuing with version ' + currentVersion + '.');
+        return false;
+      }
+      console.log('[update] Updated to ' + latest + '. Re-running command...');
+      const rerun = spawnSync(remitsCliCommand(), originalArgv, {
+        stdio: 'inherit',
+        env: Object.assign({}, process.env, { REMITS_CLI_AUTO_UPDATED: '1' })
+      });
+      if (rerun.error) {
+        if (requireSuccess) {
+          throw new Error('Auto-update succeeded but re-running the updated remits-cli command failed.');
+        }
+        console.log('[update] Re-run failed; continuing with version ' + currentVersion + '.');
+        return false;
+      }
+      process.exitCode = rerun.status === null ? 1 : rerun.status;
+      return true;
+    }
+    return false;
+  } catch (err) {
+    if (requireSuccess) {
+      throw err;
+    }
+    // Best-effort: network, npm, and permission failures should not block CLI usage.
+    return false;
+  } finally {
+    if (lockAcquired) releaseAutoUpdateLock();
+  }
+}
+
+async function main() {
+  migrateSessionIfNeeded();
+  const originalArgv = process.argv.slice(2);
+  const args = parseArgs(originalArgv);
+  const [command, subcommand] = args._;
+
+  if (shouldAutoUpdate(command, args)) {
+    const requireSuccessfulAutoUpdate = command === 'start';
+    if (autoUpdateIfNeeded(originalArgv, { requireSuccess: requireSuccessfulAutoUpdate })) return;
+  }
+
+  // Best-effort: update account-repo index whenever running from inside a remits repo
+  try { updateAccountRepoIndex(process.cwd()); } catch (_) { /* not in account repo */ }
+
+  // Auto-start the background service if not already running.
+  // Skip for lifecycle subcommands and help.
+  const isLifecycleCmd = command === 'listen' || command === 'start' || command === 'stop' || command === 'status';
+  const isHelpCmd = !command || command === 'help' || command === '--help';
+  if (!isHelpCmd && !isLifecycleCmd && !isListenerRunning()) {
+    try {
+      const dashboardUrl = await autoStartServiceIfNeeded();
+      if (dashboardUrl) {
+        console.log('[service] Auto-started in background');
+        console.log('[service] Dashboard:', dashboardUrl);
+      }
+    } catch (_) { /* best-effort */ }
+  }
+
+  // Guides are no longer bundled with the CLI. For account-work commands, make
+  // sure the repo has the latest guides — authenticating first if needed — so
+  // only platform-authenticated users ever receive them. `auth` syncs its own
+  // guides, so it is excluded here.
+  const GUIDE_SYNC_COMMANDS = new Set(['components', 'test', 'token', 'tools', 'tool']);
+  if (GUIDE_SYNC_COMMANDS.has(command)) {
+    try { await ensureGuidesSynced(process.cwd(), args); } catch (_) { /* best-effort */ }
+  }
+
+  if (!command || command === 'help' || command === '--help') {
+    console.log('Usage: remits-cli <command>');
+    console.log('Global options: --no-auto-update');
+    console.log('  remits-cli auth [--base-url URL] [--account-id ID] [--port 8765] [--data-mode test|prod]');
+    console.log('  remits-cli sessions [list|remove] [--account-id ID] [--base-url URL] [--data-mode test|prod]');
+    console.log('  remits-cli config [set] [--agent claude|codex|gemini]');
+    console.log('  remits-cli start [--foreground true] [--port 8787]');
+    console.log('  remits-cli stop');
+    console.log('  remits-cli status');
+    console.log('  remits-cli listen [stop|status] [--foreground true]  # compatibility alias');
+    console.log('  remits-cli data-mode [set test|prod]');
+    console.log('  remits-cli install --skills [--target codex|claude|gemini|all] [--overwrite true]');
+    console.log('  remits-cli tools [--base-url URL] [--account-id ID] [--data-mode test|prod]');
+    console.log('  remits-cli tool --name <toolName> [--base-url URL] [--input \"{...}\"|--input-file file.json] [--data-mode test|prod]');
+    console.log('  remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod]');
+    console.log('  remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod]');
+    console.log('  remits-cli components commit [--message \"msg\"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod]');
+    console.log('  remits-cli test run --test <id|name> [--base-url URL] [--names name1,name2] [--watch true|false] [--data-mode test|prod]');
+    console.log('  remits-cli token [--base-url URL] [--branch BRANCH] [--path embeddable/path] [--data-mode test|prod]');
+    process.exit(0);
+  }
+
+  if (command === 'auth') {
+    await authCommand(args);
+    return;
+  }
+
+  if (command === 'components' && (subcommand === 'push' || subcommand === 'stage')) {
+    if (subcommand === 'push' && !args.mode) {
+      args.mode = 'push';
+    }
+    await pushComponentsCommand(args);
+    return;
+  }
+
+  if (command === 'components' && subcommand === 'sync') {
+    await syncComponentsCommand(args);
+    return;
+  }
+
+  if (command === 'components' && subcommand === 'commit') {
+    await commitComponentsCommand(args);
+    return;
+  }
+
+  if (command === 'data-mode' || command === 'datamode' || command === 'data-model' || command === 'datamodel') {
+    await dataModeCommand(args, subcommand);
+    return;
+  }
+
+  if (command === 'sessions') {
+    await sessionsCommand(args, subcommand);
+    return;
+  }
+
+  if (command === 'config') {
+    await configCommand(args, subcommand);
+    return;
+  }
+
+  if (command === 'listen') {
+    if (subcommand === 'stop') {
+      await listenStopCommand();
+      return;
+    }
+    if (subcommand === 'status') {
+      await listenStatusCommand();
+      return;
+    }
+    await listenCommand(args);
+    return;
+  }
+
+  if (command === 'start') {
+    await listenCommand(args);
+    return;
+  }
+
+  if (command === 'stop') {
+    await listenStopCommand();
+    return;
+  }
+
+  if (command === 'status') {
+    await listenStatusCommand();
+    return;
+  }
+
+  if (command === 'install') {
+    await installSkillsCommand(args);
+    return;
+  }
+
+  if (command === 'test' && subcommand === 'run') {
+    await testCommand(args);
+    return;
+  }
+
+  if (command === 'token') {
+    await tokenCommand(args);
+    return;
+  }
+
+  if (command === 'tools') {
+    await toolsCommand(args);
+    return;
+  }
+
+  if (command === 'tool') {
+    await toolCommand(args);
+    return;
+  }
+
+  throw new Error('Unknown command: ' + args._.join(' '));
+}
+
+main().catch((err) => {
+  console.error('remits-cli error:', describeError(err) + sandboxNetworkHint(err));
+  process.exit(1);
+});