@auraindustry/aurajs 0.0.7 → 0.1.0

package/src/session-client.mjs

@@ -0,0 +1,750 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import net from 'node:net';
+import { tmpdir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  DEFAULT_SESSION_HEIGHT,
+  DEFAULT_SESSION_REQUEST_TIMEOUT_MS,
+  DEFAULT_SESSION_START_TIMEOUT_MS,
+  DEFAULT_SESSION_WIDTH,
+  DEV_SESSION_REGISTRY_SCHEMA_VERSION,
+  DEV_SESSION_REPORT_SCHEMA_VERSION,
+  DEV_SESSION_REQUEST_SCHEMA_VERSION,
+  DEV_SESSION_RESPONSE_SCHEMA_VERSION,
+  orderSessionRecord,
+  orderSessionRegistry,
+  orderSessionReport,
+} from './session-protocol.mjs';
+
+const SESSION_SERVER_PATH = fileURLToPath(new URL('./session-server.mjs', import.meta.url));
+const SESSION_NATIVE_LAUNCHER_PATH = fileURLToPath(new URL('./session-native-launcher.mjs', import.meta.url));
+const SESSION_REFRESH_RETRY_TIMEOUT_MS = 1000;
+const SESSION_REFRESH_RETRY_INTERVAL_MS = 50;
+
+export class SessionError extends Error {
+  constructor(reasonCode, message, details = {}) {
+    super(message);
+    this.name = 'SessionError';
+    this.reasonCode = reasonCode;
+    this.details = details;
+  }
+}
+
+function normalizeNonEmptyString(value) {
+  const normalized = String(value || '').trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function normalizePid(value) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+function createDefaultRegistry() {
+  return {
+    schemaVersion: DEV_SESSION_REGISTRY_SCHEMA_VERSION,
+    currentSessionId: null,
+    sessions: [],
+  };
+}
+
+function sortSessions(records) {
+  return [...records].sort((a, b) => String(a.sessionId).localeCompare(String(b.sessionId)));
+}
+
+export function resolveSessionRoot(projectRoot) {
+  return resolve(projectRoot, '.aura', 'session');
+}
+
+export function resolveSessionRegistryPath(projectRoot) {
+  return resolve(resolveSessionRoot(projectRoot), 'registry.json');
+}
+
+function resolveSessionSocketsDir(projectRoot) {
+  if (process.platform === 'win32') {
+    return null;
+  }
+  return tmpdir();
+}
+
+function resolveSessionLogsDir(projectRoot) {
+  return resolve(resolveSessionRoot(projectRoot), 'logs');
+}
+
+export function resolveSessionLogPath(projectRoot, sessionId) {
+  return resolve(resolveSessionLogsDir(projectRoot), `${sessionId}.log`);
+}
+
+export function resolveSessionSocketPath(projectRoot, sessionId) {
+  if (process.platform === 'win32') {
+    const digest = createHash('sha1')
+      .update(resolve(projectRoot))
+      .digest('hex')
+      .slice(0, 8);
+    return `\\\\.\\pipe\\aurajs-session-${digest}-${sessionId}`;
+  }
+  const digest = createHash('sha1')
+    .update(resolve(projectRoot))
+    .digest('hex')
+    .slice(0, 8);
+  const slug = String(sessionId || 'session')
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .slice(0, 40);
+  return resolve(resolveSessionSocketsDir(projectRoot), `aurajs-${digest}-${slug}.sock`);
+}
+
+function normalizeRegistryPayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return createDefaultRegistry();
+  }
+
+  const sessions = Array.isArray(payload.sessions)
+    ? payload.sessions
+      .filter((entry) => entry && typeof entry === 'object' && !Array.isArray(entry))
+      .map((entry) => orderSessionRecord({
+        sessionId: normalizeNonEmptyString(entry.sessionId),
+        name: normalizeNonEmptyString(entry.name) || normalizeNonEmptyString(entry.sessionId),
+        mode: normalizeNonEmptyString(entry.mode) || 'headless',
+        origin: normalizeNonEmptyString(entry.origin) || 'session.start',
+        launchReasonCode: normalizeNonEmptyString(entry.launchReasonCode)
+          || (normalizeNonEmptyString(entry.mode) === 'native'
+            ? 'session_start_native_detached'
+            : 'session_start_headless_detached'),
+        controllerPid: normalizePid(entry.controllerPid),
+        pid: normalizePid(entry.pid),
+        projectRoot: normalizeNonEmptyString(entry.projectRoot),
+        entryFile: normalizeNonEmptyString(entry.entryFile),
+        socketPath: normalizeNonEmptyString(entry.socketPath),
+        logPath: normalizeNonEmptyString(entry.logPath),
+        createdAt: normalizeNonEmptyString(entry.createdAt),
+      }))
+      .filter((entry) => entry.sessionId && entry.socketPath)
+    : [];
+
+  const currentSessionId = normalizeNonEmptyString(payload.currentSessionId);
+
+  return orderSessionRegistry({
+    schemaVersion: DEV_SESSION_REGISTRY_SCHEMA_VERSION,
+    currentSessionId,
+    sessions: sortSessions(sessions),
+  });
+}
+
+export function readSessionRegistry(projectRoot) {
+  const registryPath = resolveSessionRegistryPath(projectRoot);
+  if (!existsSync(registryPath)) {
+    return createDefaultRegistry();
+  }
+
+  try {
+    const text = readFileSync(registryPath, 'utf8');
+    return normalizeRegistryPayload(JSON.parse(text));
+  } catch {
+    return createDefaultRegistry();
+  }
+}
+
+export function writeSessionRegistry(projectRoot, registry) {
+  const registryPath = resolveSessionRegistryPath(projectRoot);
+  const normalized = normalizeRegistryPayload(registry);
+  mkdirSync(dirname(registryPath), { recursive: true });
+  writeFileSync(registryPath, `${JSON.stringify(normalized, null, 2)}\n`, 'utf8');
+  return normalized;
+}
+
+function cleanupSocketPath(socketPath) {
+  if (!socketPath || process.platform === 'win32') return;
+  if (existsSync(socketPath)) {
+    rmSync(socketPath, { force: true });
+  }
+}
+
+function isProcessRunning(pid) {
+  const normalizedPid = normalizePid(pid);
+  if (!normalizedPid) {
+    return false;
+  }
+
+  try {
+    process.kill(normalizedPid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM' || error?.code === 'EACCES';
+  }
+}
+
+function isForegroundControllerManagedRecord(record) {
+  if (!record || typeof record !== 'object') {
+    return false;
+  }
+  if (normalizeNonEmptyString(record.mode) !== 'native') {
+    return false;
+  }
+  const origin = normalizeNonEmptyString(record.origin);
+  return origin === 'dev' || origin === 'run';
+}
+
+function hasLiveSessionProcess(record) {
+  return isProcessRunning(record?.controllerPid) || isProcessRunning(record?.pid);
+}
+
+function shouldRetrySessionRefresh(record, error) {
+  if (!hasLiveSessionProcess(record)) {
+    return false;
+  }
+  if (!(error instanceof SessionError)) {
+    return true;
+  }
+  return [
+    'session_unavailable',
+    'session_request_timeout',
+    'session_invalid_response',
+  ].includes(error.reasonCode);
+}
+
+function shouldShutdownUnavailableDetachedSession(record) {
+  return normalizeNonEmptyString(record?.origin) === 'session.start' && isProcessRunning(record?.pid);
+}
+
+async function shutdownSessionRecord(record) {
+  try {
+    await sendSessionRequest(record, 'session.shutdown', {});
+  } catch {}
+  const sessionPid = normalizePid(record?.pid);
+  if (sessionPid && isProcessRunning(sessionPid)) {
+    try {
+      process.kill(sessionPid, 'SIGTERM');
+    } catch {}
+    const deadline = Date.now() + 1000;
+    while (Date.now() < deadline && isProcessRunning(sessionPid)) {
+      await sleep(50);
+    }
+    if (isProcessRunning(sessionPid)) {
+      try {
+        process.kill(sessionPid, 'SIGKILL');
+      } catch {}
+    }
+  }
+  cleanupSocketPath(record.socketPath);
+}
+
+async function probeSessionRecord(record) {
+  try {
+    await sendSessionRequest(record, 'session.ping', {});
+    return true;
+  } catch (error) {
+    if (!shouldRetrySessionRefresh(record, error)) {
+      return false;
+    }
+
+    const deadline = Date.now() + SESSION_REFRESH_RETRY_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      await sleep(SESSION_REFRESH_RETRY_INTERVAL_MS);
+      try {
+        await sendSessionRequest(record, 'session.ping', {});
+        return true;
+      } catch (retryError) {
+        if (!shouldRetrySessionRefresh(record, retryError)) {
+          return false;
+        }
+      }
+    }
+
+    return false;
+  }
+}
+
+function createSessionRequest(method, params = {}) {
+  return {
+    schemaVersion: DEV_SESSION_REQUEST_SCHEMA_VERSION,
+    method,
+    params,
+  };
+}
+
+export async function sendSessionRequest(record, method, params = {}) {
+  if (!record || typeof record !== 'object') {
+    throw new SessionError('session_required', 'Session record is required.');
+  }
+  if (!record.socketPath) {
+    throw new SessionError('session_unavailable', 'Session socket path is unavailable.');
+  }
+
+  const request = createSessionRequest(method, params);
+
+  return new Promise((resolveRequest, rejectRequest) => {
+    let settled = false;
+    let buffer = '';
+    const socket = net.createConnection(record.socketPath);
+
+    const fail = (reasonCode, message, details = {}) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      rejectRequest(new SessionError(reasonCode, message, details));
+    };
+
+    const succeed = (response) => {
+      if (settled) return;
+      settled = true;
+      resolveRequest(response);
+    };
+
+    socket.setEncoding('utf8');
+    socket.setTimeout(DEFAULT_SESSION_REQUEST_TIMEOUT_MS, () => {
+      fail('session_request_timeout', `Session request timed out for "${record.sessionId}".`);
+    });
+
+    socket.on('connect', () => {
+      socket.end(`${JSON.stringify(request)}\n`);
+    });
+    socket.on('data', (chunk) => {
+      buffer += chunk;
+    });
+    socket.on('error', (error) => {
+      fail(
+        'session_unavailable',
+        `Failed to connect to session "${record.sessionId}": ${error.message}`,
+        { code: error.code || null },
+      );
+    });
+    socket.on('end', () => {
+      const text = buffer.trim();
+      if (!text) {
+        fail('session_invalid_response', `Session "${record.sessionId}" returned an empty response.`);
+        return;
+      }
+
+      let response;
+      try {
+        response = JSON.parse(text);
+      } catch (error) {
+        fail('session_invalid_response', `Session "${record.sessionId}" returned invalid JSON: ${error.message}`);
+        return;
+      }
+
+      if (!response || typeof response !== 'object' || Array.isArray(response)) {
+        fail('session_invalid_response', `Session "${record.sessionId}" returned an invalid response object.`);
+        return;
+      }
+      if (response.schemaVersion !== DEV_SESSION_RESPONSE_SCHEMA_VERSION) {
+        fail('schema_version_mismatch', `Session response schema "${response.schemaVersion}" is unsupported.`);
+        return;
+      }
+      if (response.ok !== true) {
+        fail(
+          typeof response.reasonCode === 'string' ? response.reasonCode : 'session_request_failed',
+          typeof response.detail === 'string' && response.detail
+            ? response.detail
+            : `Session request "${method}" failed.`,
+          { response },
+        );
+        return;
+      }
+
+      succeed(response);
+    });
+  });
+}
+
+function sleep(ms) {
+  return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+
+function createSessionId(name) {
+  const slug = (normalizeNonEmptyString(name) || 'session')
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[-._]+|[-._]+$/g, '')
+    .slice(0, 24) || 'session';
+  const suffix = randomBytes(3).toString('hex');
+  return `${slug}-${suffix}`;
+}
+
+function createSessionRecord({
+  sessionId,
+  name,
+  projectRoot,
+  file,
+  socketPath,
+  logPath,
+  controllerPid = null,
+  pid,
+  mode = 'headless',
+  origin = 'session.start',
+  launchReasonCode = null,
+}) {
+  const sessionMode = normalizeNonEmptyString(mode) === 'native' ? 'native' : 'headless';
+  return orderSessionRecord({
+    sessionId,
+    name: normalizeNonEmptyString(name) || sessionId,
+    mode: sessionMode,
+    origin: normalizeNonEmptyString(origin) || 'session.start',
+    launchReasonCode: normalizeNonEmptyString(launchReasonCode)
+      || (sessionMode === 'native'
+        ? 'session_start_native_detached'
+        : 'session_start_headless_detached'),
+    controllerPid: normalizePid(controllerPid),
+    pid: normalizePid(pid),
+    projectRoot: resolve(projectRoot),
+    entryFile: resolve(projectRoot, file),
+    socketPath,
+    logPath,
+    createdAt: new Date().toISOString(),
+  });
+}
+
+async function waitForSessionReady(record) {
+  const startedAt = Date.now();
+  let lastError = null;
+
+  while ((Date.now() - startedAt) < DEFAULT_SESSION_START_TIMEOUT_MS) {
+    try {
+      const response = await sendSessionRequest(record, 'session.ping', {});
+      return response.result || null;
+    } catch (error) {
+      lastError = error;
+      await sleep(50);
+    }
+  }
+
+  throw new SessionError(
+    'session_start_timeout',
+    `Timed out waiting for session "${record.sessionId}" to start. See ${record.logPath}.`,
+    { lastError: lastError instanceof Error ? lastError.message : String(lastError) },
+  );
+}
+
+export async function refreshSessionRegistry(projectRoot) {
+  const report = await refreshSessionRegistryWithReport(projectRoot);
+  return report.registry;
+}
+
+export async function refreshSessionRegistryWithReport(projectRoot) {
+  const registry = readSessionRegistry(projectRoot);
+  const activeSessions = [];
+  const staleSessions = [];
+  const reapedForegroundSessions = [];
+
+  for (const record of registry.sessions) {
+    if (isForegroundControllerManagedRecord(record) && record.controllerPid && !isProcessRunning(record.controllerPid)) {
+      await shutdownSessionRecord(record);
+      reapedForegroundSessions.push(record);
+      continue;
+    }
+
+    if (await probeSessionRecord(record)) {
+      activeSessions.push(record);
+      continue;
+    }
+
+    if (shouldShutdownUnavailableDetachedSession(record)) {
+      await shutdownSessionRecord(record);
+    } else {
+      cleanupSocketPath(record.socketPath);
+    }
+    staleSessions.push(record);
+  }
+
+  const nextRegistry = orderSessionRegistry({
+    schemaVersion: DEV_SESSION_REGISTRY_SCHEMA_VERSION,
+    currentSessionId: activeSessions.some((entry) => entry.sessionId === registry.currentSessionId)
+      ? registry.currentSessionId
+      : null,
+    sessions: sortSessions(activeSessions),
+  });
+
+  writeSessionRegistry(projectRoot, nextRegistry);
+  return {
+    registry: nextRegistry,
+    staleSessions: staleSessions.map((record) => orderSessionRecord(record)),
+    reapedForegroundSessions: reapedForegroundSessions.map((record) => orderSessionRecord(record)),
+  };
+}
+
+export async function listSessions(projectRoot) {
+  const registry = await refreshSessionRegistry(projectRoot);
+  const sessions = [];
+
+  for (const record of registry.sessions) {
+    try {
+      const response = await sendSessionRequest(record, 'session.describe', {});
+      sessions.push(orderSessionRecord({
+        ...record,
+        frameIndex: response.result?.frameIndex ?? null,
+        elapsedSeconds: response.result?.elapsedSeconds ?? null,
+        requestCount: response.result?.requestCount ?? null,
+        current: record.sessionId === registry.currentSessionId,
+      }));
+    } catch {
+      sessions.push(orderSessionRecord({
+        ...record,
+        current: record.sessionId === registry.currentSessionId,
+      }));
+    }
+  }
+
+  return orderSessionReport({
+    schemaVersion: DEV_SESSION_REPORT_SCHEMA_VERSION,
+    ok: true,
+    reasonCode: 'session_list_ok',
+    currentSessionId: registry.currentSessionId || null,
+    sessions,
+  });
+}
+
+export async function startSession({
+  projectRoot,
+  file,
+  name = null,
+  mode = 'native',
+  width = DEFAULT_SESSION_WIDTH,
+  height = DEFAULT_SESSION_HEIGHT,
+  nativeLaunch = null,
+}) {
+  const resolvedProjectRoot = resolve(projectRoot || process.cwd());
+  const sessionMode = normalizeNonEmptyString(mode) === 'headless' ? 'headless' : 'native';
+  if (sessionMode === 'native' && process.platform === 'win32') {
+    throw new SessionError(
+      'session_native_unsupported',
+      'Native sessions are not supported on Windows yet. Use "aura session start --headless".',
+    );
+  }
+  const sessionId = createSessionId(name);
+  const socketPath = resolveSessionSocketPath(resolvedProjectRoot, sessionId);
+  const logPath = resolveSessionLogPath(resolvedProjectRoot, sessionId);
+  const launchReasonCode = sessionMode === 'native'
+    ? 'session_start_native_detached'
+    : 'session_start_headless_detached';
+  const record = createSessionRecord({
+    sessionId,
+    name,
+    projectRoot: resolvedProjectRoot,
+    file,
+    socketPath,
+    logPath,
+    pid: null,
+    mode: sessionMode,
+    origin: 'session.start',
+    launchReasonCode,
+  });
+
+  cleanupSocketPath(socketPath);
+  mkdirSync(dirname(logPath), { recursive: true });
+  if (process.platform !== 'win32') {
+    mkdirSync(dirname(socketPath), { recursive: true });
+  }
+
+  const logFd = openSync(logPath, 'a');
+  let child;
+  if (sessionMode === 'headless') {
+    child = spawn(process.execPath, [
+      SESSION_SERVER_PATH,
+      '--project-root', resolvedProjectRoot,
+      '--file', file,
+      '--session-id', sessionId,
+      '--socket-path', socketPath,
+      '--width', String(width),
+      '--height', String(height),
+      ...(normalizeNonEmptyString(name) ? ['--name', name] : []),
+    ], {
+      cwd: resolvedProjectRoot,
+      detached: true,
+      stdio: ['ignore', logFd, logFd],
+      env: process.env,
+    });
+  } else {
+    const launchExecutablePath = normalizeNonEmptyString(nativeLaunch?.launchExecutablePath);
+    const launchArgs = Array.isArray(nativeLaunch?.launchArgs)
+      ? nativeLaunch.launchArgs.map((entry) => String(entry))
+      : [];
+    if (!launchExecutablePath || launchArgs.length === 0) {
+      closeSync(logFd);
+      throw new SessionError(
+        'session_native_launch_invalid',
+        'Native session launch contract is incomplete.',
+      );
+    }
+    child = spawn(process.execPath, [
+      SESSION_NATIVE_LAUNCHER_PATH,
+      '--cwd', resolvedProjectRoot,
+      '--executable', launchExecutablePath,
+      '--',
+      ...launchArgs,
+    ], {
+      cwd: resolvedProjectRoot,
+      detached: true,
+      stdio: ['ignore', logFd, logFd],
+      env: {
+        ...process.env,
+        ...(nativeLaunch?.env && typeof nativeLaunch.env === 'object' ? nativeLaunch.env : {}),
+        AURA_SESSION_ID: sessionId,
+        AURA_SESSION_NAME: normalizeNonEmptyString(name) || sessionId,
+        AURA_SESSION_MODE: sessionMode,
+        AURA_SESSION_PROJECT_ROOT: resolvedProjectRoot,
+        AURA_SESSION_SOCKET_PATH: socketPath,
+        AURA_WINDOW_WIDTH: String(width),
+        AURA_WINDOW_HEIGHT: String(height),
+      },
+    });
+  }
+  closeSync(logFd);
+  child.unref();
+
+  const nextRecord = createSessionRecord({
+    sessionId,
+    name,
+    projectRoot: resolvedProjectRoot,
+    file,
+    socketPath,
+    logPath,
+    pid: child.pid,
+    mode: sessionMode,
+    origin: 'session.start',
+    launchReasonCode,
+  });
+
+  await waitForSessionReady(nextRecord);
+
+  const registry = await refreshSessionRegistry(resolvedProjectRoot);
+  const sessions = registry.sessions.filter((entry) => entry.sessionId !== sessionId);
+  sessions.push(nextRecord);
+  const nextRegistry = writeSessionRegistry(resolvedProjectRoot, {
+    schemaVersion: DEV_SESSION_REGISTRY_SCHEMA_VERSION,
+    currentSessionId: sessionId,
+    sessions: sortSessions(sessions),
+  });
+
+  return orderSessionReport({
+    schemaVersion: DEV_SESSION_REPORT_SCHEMA_VERSION,
+    ok: true,
+    reasonCode: 'session_started',
+    sessionId,
+    currentSessionId: nextRegistry.currentSessionId,
+    session: orderSessionRecord({
+      ...nextRecord,
+      current: true,
+    }),
+  });
+}
+
+export async function resolveSessionRecord(projectRoot, requestedSessionId = null) {
+  const registry = await refreshSessionRegistry(projectRoot);
+  const requestedId = normalizeNonEmptyString(requestedSessionId);
+
+  if (requestedId) {
+    const byId = registry.sessions.find((entry) => entry.sessionId === requestedId);
+    if (!byId) {
+      throw new SessionError('session_not_found', `No active session found for "${requestedId}".`);
+    }
+    return { registry, record: byId };
+  }
+
+  if (registry.currentSessionId) {
+    const current = registry.sessions.find((entry) => entry.sessionId === registry.currentSessionId);
+    if (current) {
+      return { registry, record: current };
+    }
+  }
+
+  if (registry.sessions.length === 1) {
+    return { registry, record: registry.sessions[0] };
+  }
+
+  if (registry.sessions.length === 0) {
+    throw new SessionError('session_required', 'No active session. Use "aura session start" first.');
+  }
+
+  throw new SessionError(
+    'session_required',
+    'Multiple sessions exist and no current session is attached. Use "aura session attach <id>".',
+  );
+}
+
+export async function attachSession(projectRoot, sessionId) {
+  const { registry, record } = await resolveSessionRecord(projectRoot, sessionId);
+  const nextRegistry = writeSessionRegistry(projectRoot, {
+    schemaVersion: DEV_SESSION_REGISTRY_SCHEMA_VERSION,
+    currentSessionId: record.sessionId,
+    sessions: registry.sessions,
+  });
+
+  return orderSessionReport({
+    schemaVersion: DEV_SESSION_REPORT_SCHEMA_VERSION,
+    ok: true,
+    reasonCode: 'session_attached',
+    sessionId: record.sessionId,
+    currentSessionId: nextRegistry.currentSessionId,
+    session: orderSessionRecord({
+      ...record,
+      current: true,
+    }),
+  });
+}
+
+export async function detachSession(projectRoot) {
+  const registry = await refreshSessionRegistry(projectRoot);
+  const nextRegistry = writeSessionRegistry(projectRoot, {
+    schemaVersion: DEV_SESSION_REGISTRY_SCHEMA_VERSION,
+    currentSessionId: null,
+    sessions: registry.sessions,
+  });
+
+  return orderSessionReport({
+    schemaVersion: DEV_SESSION_REPORT_SCHEMA_VERSION,
+    ok: true,
+    reasonCode: 'session_detached',
+    currentSessionId: nextRegistry.currentSessionId,
+  });
+}
+
+export async function closeSession(projectRoot, sessionId = null) {
+  const { registry, record } = await resolveSessionRecord(projectRoot, sessionId);
+  let stale = false;
+
+  try {
+    await sendSessionRequest(record, 'session.shutdown', {});
+  } catch {
+    stale = true;
+  }
+
+  cleanupSocketPath(record.socketPath);
+
+  const nextRegistry = writeSessionRegistry(projectRoot, {
+    schemaVersion: DEV_SESSION_REGISTRY_SCHEMA_VERSION,
+    currentSessionId: registry.currentSessionId === record.sessionId
+      ? null
+      : registry.currentSessionId,
+    sessions: registry.sessions.filter((entry) => entry.sessionId !== record.sessionId),
+  });
+
+  return orderSessionReport({
+    schemaVersion: DEV_SESSION_REPORT_SCHEMA_VERSION,
+    ok: true,
+    reasonCode: stale ? 'session_closed_stale' : 'session_closed',
+    sessionId: record.sessionId,
+    currentSessionId: nextRegistry.currentSessionId,
+    closed: true,
+    stale,
+  });
+}
+
+export function serializeSessionReport(report, compact = false) {
+  const ordered = orderSessionReport(report);
+  return compact
+    ? `${JSON.stringify(ordered)}\n`
+    : `${JSON.stringify(ordered, null, 2)}\n`;
+}