relay-companion 0.1.0

package/src/claude-session-writer.js

@@ -0,0 +1,629 @@
+// Claude Desktop / Claude Code native session writer + title-repair loop.
+// Ported faithfully from granular/tools/relay-companion/src/claude-session-writer.js.
+//
+// HOST MECHANICS ARE UNCHANGED: it forges a ~/.claude/projects/<key>/<id>.jsonl
+// transcript (custom-title / ai-title / agent-name rows + one visible assistant
+// turn), writes the Claude Desktop local_<id>.json session metadata, fires
+// `claude://resume?session=...`, and then runs the post-import title-repair loop
+// that fixes the "General coding session" rail-title bug by re-writing the saved
+// metadata title (titleSource:"user") with retries and repairing duplicates.
+//
+// Adaptations (input side only):
+//   - paths -> ./host-paths.js
+//   - title/briefing come from the cloud row via ./relay-briefing.js instead of a
+//     granular packet's displayTitle/renderRelayBriefing.
+
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { relayRowTitle, renderRelayRowSeed } from "./relay-briefing.js";
+import { claudeDesktopSessionsDir, claudeProjectsDir } from "./host-paths.js";
+
+const DEFAULT_CLAUDE_METADATA_MODEL = "claude-opus-4-8";
+const CLAUDE_DESKTOP_LIVE_TITLE_LIMITATION = {
+  attempted: true,
+  supported: "best-effort",
+  reason: "claude-desktop-resume-import-uses-in-memory-session-cache",
+  detail:
+    "Relay writes Claude Code title rows and Claude Desktop metadata before import, then repairs saved metadata after import. Already-open Claude Desktop builds can still cache the imported row before the saved title is observed.",
+};
+
+export function writeClaudeNativeSession({ row, cwd = process.cwd(), seed = renderRelayRowSeed(row) }) {
+  const sessionId = crypto.randomUUID();
+  const createdAt = new Date().toISOString();
+  const title = relayRowTitle(row);
+  // The human reads only `visible`. The agent-only `operatorNote` (real ids + the
+  // tool call to make) goes on a hidden system-meta row that Claude Desktop's
+  // transcript view does not render as a chat bubble (the same way the title rows
+  // above are non-rendered), so the human never sees ids or tool-call syntax.
+  const visible = String(seed?.visible || "").trim();
+  const operatorNote = String(seed?.operatorNote || "").trim();
+  const sessionDir = path.join(claudeProjectsDir(), claudeProjectKey(cwd));
+  const sessionPath = path.join(sessionDir, `${sessionId}.jsonl`);
+  const assistantUuid = crypto.randomUUID();
+  const operatorUuid = crypto.randomUUID();
+  const rows = [
+    { type: "custom-title", customTitle: title, sessionId },
+    { type: "ai-title", aiTitle: title, sessionId },
+    { type: "agent-name", agentName: title, sessionId },
+  ];
+  if (operatorNote) {
+    // Hidden agent-only channel: a system-meta row. isMeta marks it non-visible to
+    // the user; the agent still has it in context. Carries no chat role, so it is
+    // not rendered in the human-visible transcript.
+    rows.push({
+      type: "system",
+      subtype: "relay-operator-note",
+      isMeta: true,
+      isVisibleInTranscriptOnly: false,
+      content: operatorNote,
+      level: "info",
+      uuid: operatorUuid,
+      parentUuid: null,
+      timestamp: createdAt,
+      sessionId,
+    });
+  }
+  rows.push(
+    {
+      parentUuid: operatorNote ? operatorUuid : null,
+      isSidechain: false,
+      message: {
+        model: "relay-companion",
+        id: claudeMessageId(),
+        type: "message",
+        role: "assistant",
+        content: [{ type: "text", text: visible }],
+        stop_reason: "end_turn",
+        stop_sequence: null,
+        usage: {},
+      },
+      requestId: relayRequestId(),
+      type: "assistant",
+      uuid: assistantUuid,
+      timestamp: createdAt,
+      userType: "external",
+      entrypoint: "relay-companion",
+      cwd,
+      sessionId,
+      version: "relay-companion",
+      gitBranch: process.env.GIT_BRANCH || null,
+    },
+    {
+      type: "last-prompt",
+      lastPrompt: `Relay from ${row?.senderName || row?.sender?.name || row?.sender?.handle || "sender"}`,
+      leafUuid: assistantUuid,
+      sessionId,
+    },
+  );
+
+  fs.mkdirSync(sessionDir, { recursive: true });
+  writeJsonlAtomic(sessionPath, rows);
+  const desktopMetadataPath = writeClaudeDesktopSessionMetadata({ sessionId, title, cwd, createdAt });
+  if (process.env.RELAY_IMPORT_CLAUDE_DESKTOP !== "0") {
+    sleepSync(Number(process.env.RELAY_CLAUDE_PREIMPORT_DELAY_MS || 750));
+  }
+  const deepLink = claudeResumeDeepLink(sessionId);
+  const desktopImport = importClaudeDesktopSession({ sessionId });
+  const desktopTitleBeforeRefocus = restoreClaudeDesktopSessionTitle({
+    sessionId,
+    title,
+    cwd,
+    createdAt,
+    metadataPath: desktopMetadataPath,
+    retries: desktopImport.attempted ? 10 : 1,
+  });
+  const desktopRefocus =
+    desktopImport.attempted && desktopImport.status === 0
+      ? importClaudeDesktopSession({ sessionId })
+      : { attempted: false, reason: desktopImport.reason || "import-not-successful", deepLink };
+  const desktopTitle =
+    desktopRefocus.attempted && desktopRefocus.status === 0
+      ? restoreClaudeDesktopSessionTitle({
+          sessionId,
+          title,
+          cwd,
+          createdAt,
+          metadataPath: desktopTitleBeforeRefocus.metadataPath || desktopMetadataPath,
+          retries: 10,
+        })
+      : desktopTitleBeforeRefocus;
+  const desktopRepair = repairClaudeDesktopRelaySessions({ sessionIds: [sessionId] });
+
+  return {
+    sessionId,
+    title,
+    sessionPath,
+    desktopMetadataPath: desktopTitle.metadataPath || desktopMetadataPath,
+    deepLink,
+    desktopImport,
+    desktopTitleBeforeRefocus,
+    desktopTitle,
+    desktopRefocus,
+    desktopRepair,
+    desktopLiveTitle: CLAUDE_DESKTOP_LIVE_TITLE_LIMITATION,
+  };
+}
+
+export function writeClaudeDesktopSessionMetadata({ sessionId, title, cwd, createdAt = new Date().toISOString() }) {
+  const groupDir = findClaudeDesktopSessionGroupDir();
+  if (!groupDir) return null;
+  const nowMs = Date.now();
+  const createdAtMs = Number.isFinite(Date.parse(createdAt)) ? Date.parse(createdAt) : nowMs;
+  const desktopSessionId = `local_${sessionId}`;
+  const metadataPath = path.join(groupDir, `${desktopSessionId}.json`);
+  const metadata = {
+    sessionId: desktopSessionId,
+    cliSessionId: sessionId,
+    cwd,
+    originCwd: cwd,
+    lastFocusedAt: nowMs,
+    createdAt: createdAtMs,
+    lastActivityAt: nowMs,
+    model: process.env.RELAY_CLAUDE_METADATA_MODEL || DEFAULT_CLAUDE_METADATA_MODEL,
+    effort: "high",
+    isArchived: false,
+    title,
+    titleSource: "user",
+    permissionMode: "default",
+    enabledMcpTools: {},
+    remoteMcpServersConfig: [],
+    chromePermissionMode: "skip_all_permission_checks",
+    completedTurns: 1,
+    bridgeSessionIds: [],
+    alwaysAllowedReasons: [],
+    sessionPermissionUpdates: [],
+    classifierSummaryEnabled: true,
+  };
+  writeJsonAtomic(metadataPath, metadata);
+  return metadataPath;
+}
+
+export function restoreClaudeDesktopSessionTitle({
+  sessionId,
+  title,
+  cwd = process.cwd(),
+  createdAt = new Date().toISOString(),
+  metadataPath = null,
+  retries = 10,
+  delayMs = 250,
+} = {}) {
+  if (!sessionId || !title) {
+    return { attempted: false, reason: "missing-session-or-title", metadataPath: metadataPath || null };
+  }
+
+  let currentPath = metadataPath;
+  let lastError = null;
+  let lastSuccess = null;
+  const totalAttempts = Math.max(1, retries);
+  for (let attempt = 0; attempt < totalAttempts; attempt += 1) {
+    if (attempt > 0 || totalAttempts > 1) sleepSync(delayMs);
+    currentPath = currentPath || claudeDesktopSessionMetadataPath(sessionId);
+    if (!currentPath) {
+      lastError = "no-claude-desktop-session-dir";
+      continue;
+    }
+
+    try {
+      const nowMs = Date.now();
+      const createdAtMs = Number.isFinite(Date.parse(createdAt)) ? Date.parse(createdAt) : nowMs;
+      const existing = fs.existsSync(currentPath) ? readJsonIfExists(currentPath, {}) : {};
+      writeJsonAtomic(currentPath, {
+        sessionId: `local_${sessionId}`,
+        cliSessionId: sessionId,
+        cwd,
+        originCwd: cwd,
+        lastFocusedAt: existing.lastFocusedAt || nowMs,
+        createdAt: existing.createdAt || createdAtMs,
+        lastActivityAt: existing.lastActivityAt || nowMs,
+        model: process.env.RELAY_CLAUDE_METADATA_MODEL || existing.model || DEFAULT_CLAUDE_METADATA_MODEL,
+        effort: existing.effort || "high",
+        isArchived: false,
+        permissionMode: existing.permissionMode || "default",
+        enabledMcpTools: existing.enabledMcpTools || {},
+        remoteMcpServersConfig: existing.remoteMcpServersConfig || [],
+        chromePermissionMode: existing.chromePermissionMode || "skip_all_permission_checks",
+        completedTurns: existing.completedTurns || 1,
+        bridgeSessionIds: existing.bridgeSessionIds || [],
+        alwaysAllowedReasons: existing.alwaysAllowedReasons || [],
+        sessionPermissionUpdates: existing.sessionPermissionUpdates || [],
+        classifierSummaryEnabled: existing.classifierSummaryEnabled ?? true,
+        ...existing,
+        title,
+        titleSource: "user",
+      });
+      lastSuccess = {
+        attempted: true,
+        restored: true,
+        metadataPath: currentPath,
+        title,
+        titleSource: "user",
+        attempts: attempt + 1,
+      };
+      if (totalAttempts === 1) return lastSuccess;
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+    }
+  }
+
+  if (lastSuccess) return { ...lastSuccess, attempts: totalAttempts };
+
+  return {
+    attempted: true,
+    restored: false,
+    metadataPath: currentPath || null,
+    title,
+    reason: lastError || "unknown",
+    attempts: Math.max(1, retries),
+  };
+}
+
+export function claudeResumeDeepLink(sessionId) {
+  return `claude://resume?session=${encodeURIComponent(sessionId)}`;
+}
+
+export function importClaudeDesktopSession({ sessionId, activate = process.env.RELAY_ACTIVATE_CLAUDE === "1" } = {}) {
+  const deepLink = claudeResumeDeepLink(sessionId);
+  if (process.env.RELAY_IMPORT_CLAUDE_DESKTOP === "0") {
+    return { attempted: false, reason: "disabled", deepLink };
+  }
+  if (process.platform !== "darwin") {
+    return { attempted: false, reason: "unsupported-platform", deepLink };
+  }
+
+  const args = activate ? [deepLink] : ["-g", deepLink];
+  const result = spawnSync("open", args, { encoding: "utf8", timeout: 5000 });
+  return {
+    attempted: true,
+    deepLink,
+    command: "open",
+    args,
+    status: result.status,
+    signal: result.signal,
+    error: result.error ? result.error.message : null,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+  };
+}
+
+export function isClaudeNativeSessionImported(nativeSession) {
+  if (!nativeSession?.sessionId) return false;
+  const deepLink = nativeSession.deepLink || nativeSession.desktopImport?.deepLink || "";
+  if (!deepLink.startsWith("claude://resume?session=")) return false;
+  const desktopImport = nativeSession.desktopImport;
+  if (!desktopImport) return false;
+  if (desktopImport.attempted) return desktopImport.status === 0 && isClaudeDesktopTitleRestored(nativeSession);
+  return desktopImport.reason === "disabled" || desktopImport.reason === "unsupported-platform";
+}
+
+export function ensureClaudeDesktopImported(nativeSession, { title, cwd, createdAt } = {}) {
+  if (!nativeSession?.sessionId) return nativeSession;
+  const nextTitle = title || nativeSession.title;
+  if (isClaudeNativeSessionImported(nativeSession)) return nativeSession;
+  const desktopImport =
+    nativeSession.desktopImport?.attempted && nativeSession.desktopImport.status === 0
+      ? nativeSession.desktopImport
+      : importClaudeDesktopSession({ sessionId: nativeSession.sessionId });
+  const desktopTitleBeforeRefocus = restoreClaudeDesktopSessionTitle({
+    sessionId: nativeSession.sessionId,
+    title: nextTitle,
+    cwd: cwd || nativeSession.cwd || process.cwd(),
+    createdAt: createdAt || nativeSession.createdAt || new Date().toISOString(),
+    metadataPath: nativeSession.desktopMetadataPath || nativeSession.desktopTitle?.metadataPath || null,
+    retries: desktopImport.attempted ? 10 : 1,
+  });
+  const desktopRefocus =
+    desktopImport.attempted && desktopImport.status === 0
+      ? importClaudeDesktopSession({ sessionId: nativeSession.sessionId })
+      : {
+          attempted: false,
+          reason: desktopImport.reason || "import-not-successful",
+          deepLink: claudeResumeDeepLink(nativeSession.sessionId),
+        };
+  const desktopTitle =
+    desktopRefocus.attempted && desktopRefocus.status === 0
+      ? restoreClaudeDesktopSessionTitle({
+          sessionId: nativeSession.sessionId,
+          title: nextTitle,
+          cwd: cwd || nativeSession.cwd || process.cwd(),
+          createdAt: createdAt || nativeSession.createdAt || new Date().toISOString(),
+          metadataPath: desktopTitleBeforeRefocus.metadataPath || nativeSession.desktopMetadataPath || null,
+          retries: 10,
+        })
+      : desktopTitleBeforeRefocus;
+  const desktopRepair = repairClaudeDesktopRelaySessions({ sessionIds: [nativeSession.sessionId] });
+  return {
+    ...nativeSession,
+    title: nextTitle,
+    deepLink: claudeResumeDeepLink(nativeSession.sessionId),
+    desktopMetadataPath: desktopTitle.metadataPath || nativeSession.desktopMetadataPath || null,
+    desktopImport,
+    desktopTitleBeforeRefocus,
+    desktopTitle,
+    desktopRefocus,
+    desktopRepair,
+    desktopLiveTitle: CLAUDE_DESKTOP_LIVE_TITLE_LIMITATION,
+  };
+}
+
+export function setClaudeNativeSessionAttention(
+  nativeSession,
+  { packetId, title = nativeSession?.title || null, state = "unread", nowMs = Date.now() } = {},
+) {
+  const sessionId = nativeSession?.sessionId;
+  if (!sessionId) return { attempted: false, reason: "missing-session-id" };
+  const metadataPath = nativeSession.desktopMetadataPath || claudeDesktopSessionMetadataPath(sessionId);
+  if (!metadataPath || !fs.existsSync(metadataPath)) {
+    return { attempted: false, reason: "metadata-not-found", metadataPath: metadataPath || null };
+  }
+
+  const metadata = readJsonIfExists(metadataPath, null);
+  if (!metadata) return { attempted: false, reason: "metadata-unreadable", metadataPath };
+
+  const previousAttention = metadata.relayAttention || {};
+  const originalLastActivityAt =
+    previousAttention.originalLastActivityAt ?? (Number.isFinite(metadata.lastActivityAt) ? metadata.lastActivityAt : nowMs);
+  const originalLastFocusedAt =
+    previousAttention.originalLastFocusedAt ?? (Number.isFinite(metadata.lastFocusedAt) ? metadata.lastFocusedAt : null);
+  const timestamp = new Date(nowMs).toISOString();
+  const nextAttention = {
+    ...previousAttention,
+    packetId: packetId || previousAttention.packetId || null,
+    title: title || previousAttention.title || metadata.title || null,
+    state,
+    originalLastActivityAt,
+    originalLastFocusedAt,
+    updatedAt: timestamp,
+  };
+
+  const nextMetadata = {
+    ...metadata,
+    isArchived: false,
+    relayAttention: nextAttention,
+  };
+  if (isRelayTitle(title)) {
+    nextMetadata.title = title;
+    nextMetadata.titleSource = "user";
+  }
+
+  if (state === "unread") {
+    nextAttention.lastAppliedAt = nowMs;
+    nextMetadata.lastActivityAt = Math.max(nowMs, Number(metadata.lastActivityAt) || 0);
+  } else {
+    nextAttention.acknowledgedAt = timestamp;
+    nextMetadata.lastActivityAt = originalLastActivityAt;
+  }
+
+  writeJsonAtomic(metadataPath, nextMetadata);
+  return {
+    attempted: true,
+    metadataPath,
+    sessionId,
+    state,
+    lastActivityAt: nextMetadata.lastActivityAt,
+    originalLastActivityAt,
+  };
+}
+
+export function repairClaudeDesktopRelaySessions({ sessionIds = null } = {}) {
+  const groupDir = findClaudeDesktopSessionGroupDir();
+  if (!groupDir) return { attempted: false, reason: "no-claude-desktop-session-dir", repaired: [], archived: [] };
+  const requested = sessionIds ? new Set(sessionIds) : null;
+  const metadataFiles = childJsonFiles(groupDir)
+    .map((filePath) => ({ filePath, metadata: readJsonIfExists(filePath, null) }))
+    .filter((entry) => entry.metadata?.cliSessionId)
+    .filter((entry) => !requested || requested.has(entry.metadata.cliSessionId));
+  const byCliSession = new Map();
+  for (const entry of metadataFiles) {
+    const list = byCliSession.get(entry.metadata.cliSessionId) || [];
+    list.push(entry);
+    byCliSession.set(entry.metadata.cliSessionId, list);
+  }
+
+  const repaired = [];
+  const archived = [];
+  for (const [sessionId, entries] of byCliSession) {
+    const title = inferRelayTitleForClaudeSession(sessionId, entries);
+    if (!title) continue;
+
+    const canonicalSessionId = `local_${sessionId}`;
+    let canonical = entries.find((entry) => entry.metadata.sessionId === canonicalSessionId);
+    if (!canonical) {
+      const seed = entries[0];
+      const canonicalPath = path.join(groupDir, `${canonicalSessionId}.json`);
+      const metadata = {
+        ...seed.metadata,
+        sessionId: canonicalSessionId,
+        cliSessionId: sessionId,
+        title,
+        titleSource: "user",
+        isArchived: false,
+        lastActivityAt: seed.metadata.lastActivityAt || Date.now(),
+      };
+      writeJsonAtomic(canonicalPath, metadata);
+      canonical = { filePath: canonicalPath, metadata };
+      entries.push(canonical);
+      repaired.push({ sessionId, metadataPath: canonicalPath, title });
+    }
+    const targets = canonical ? [canonical] : entries;
+    for (const entry of targets) {
+      if (entry.metadata.title === title && entry.metadata.titleSource === "user") continue;
+      writeJsonAtomic(entry.filePath, {
+        ...entry.metadata,
+        sessionId: entry.metadata.sessionId || canonicalSessionId,
+        cliSessionId: sessionId,
+        title,
+        titleSource: "user",
+        isArchived: false,
+        lastActivityAt: entry.metadata.lastActivityAt || Date.now(),
+      });
+      appendClaudeSessionTitleRows({ sessionId, title, cwd: entry.metadata.cwd || entry.metadata.originCwd });
+      repaired.push({ sessionId, metadataPath: entry.filePath, title });
+    }
+
+    for (const entry of entries) {
+      if (entry === canonical) continue;
+      const duplicateTitle = isRelayTitle(entry.metadata.title) ? entry.metadata.title : title;
+      if (entry.metadata.isArchived === true) continue;
+      writeJsonAtomic(entry.filePath, {
+        ...entry.metadata,
+        title: duplicateTitle,
+        titleSource: entry.metadata.titleSource || "user",
+        isArchived: true,
+      });
+      archived.push({ sessionId, metadataPath: entry.filePath, title: duplicateTitle });
+    }
+  }
+
+  return { attempted: true, groupDir, repaired, archived };
+}
+
+export function appendClaudeSessionTitleRows({ sessionId, title, cwd = null }) {
+  if (!sessionId || !title) return { appended: false, reason: "missing-session-or-title" };
+  const sessionPath = findClaudeSessionPath({ sessionId, cwd });
+  if (!sessionPath) return { appended: false, reason: "session-transcript-not-found" };
+  const timestamp = new Date().toISOString();
+  appendJsonlAtomic(sessionPath, [
+    { type: "custom-title", customTitle: title, sessionId, uuid: crypto.randomUUID(), timestamp },
+    { type: "ai-title", aiTitle: title, sessionId, uuid: crypto.randomUUID(), timestamp },
+    { type: "agent-name", agentName: title, sessionId, uuid: crypto.randomUUID(), timestamp },
+  ]);
+  return { appended: true, sessionPath, title };
+}
+
+export function claudeProjectKey(cwd) {
+  return path.resolve(String(cwd || process.cwd())).replace(/[^0-9A-Za-z]/g, "-");
+}
+
+function findClaudeDesktopSessionGroupDir() {
+  const root = claudeDesktopSessionsDir();
+  if (!fs.existsSync(root)) return null;
+  const accountDirs = childDirectories(root);
+  for (const accountDir of accountDirs) {
+    const groupDirs = childDirectories(accountDir);
+    if (groupDirs.length) return groupDirs[0];
+  }
+  return null;
+}
+
+function claudeDesktopSessionMetadataPath(sessionId) {
+  const groupDir = findClaudeDesktopSessionGroupDir();
+  if (!groupDir) return null;
+  return path.join(groupDir, `local_${sessionId}.json`);
+}
+
+function inferRelayTitleForClaudeSession(sessionId, entries) {
+  for (const entry of entries) {
+    if (isRelayTitle(entry.metadata.title)) return entry.metadata.title;
+  }
+  const transcriptTitle = readRelayTitleFromClaudeTranscript(sessionId, entries[0]?.metadata?.cwd || entries[0]?.metadata?.originCwd);
+  if (transcriptTitle) return transcriptTitle;
+  return null;
+}
+
+function readRelayTitleFromClaudeTranscript(sessionId, cwd = null) {
+  const sessionPath = findClaudeSessionPath({ sessionId, cwd });
+  if (!sessionPath) return null;
+  let latestTitle = null;
+  for (const line of fs.readFileSync(sessionPath, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    let row = null;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (isRelayTitle(row.customTitle)) latestTitle = row.customTitle;
+    if (isRelayTitle(row.aiTitle)) latestTitle = row.aiTitle;
+    if (isRelayTitle(row.agentName)) latestTitle = row.agentName;
+    const text = row.message?.content?.find?.((item) => item?.type === "text")?.text || "";
+    const heading = text.match(/^#\s*(🔁\s+(?:From|Task:)[^\n]+)/m)?.[1];
+    if (isRelayTitle(heading)) latestTitle = heading;
+  }
+  return latestTitle;
+}
+
+function findClaudeSessionPath({ sessionId, cwd = null }) {
+  if (cwd) {
+    const direct = path.join(claudeProjectsDir(), claudeProjectKey(cwd), `${sessionId}.jsonl`);
+    if (fs.existsSync(direct)) return direct;
+  }
+  const root = claudeProjectsDir();
+  if (!fs.existsSync(root)) return null;
+  for (const dir of childDirectories(root)) {
+    const candidate = path.join(dir, `${sessionId}.jsonl`);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function isRelayTitle(value) {
+  return /^🔁\s+(From\s+.+:|Task:)/u.test(String(value || "").trim());
+}
+
+function childDirectories(dir) {
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(dir, entry.name))
+    .sort();
+}
+
+function childJsonFiles(dir) {
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) => path.join(dir, entry.name))
+    .sort();
+}
+
+function claudeMessageId() {
+  return `msg_01relay${crypto.randomBytes(18).toString("hex")}`;
+}
+
+function relayRequestId() {
+  return `req_relay_${crypto.randomBytes(12).toString("hex")}`;
+}
+
+function writeJsonlAtomic(filePath, rows) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, `${rows.map((row) => JSON.stringify(row)).join("\n")}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, filePath);
+}
+
+function writeJsonAtomic(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, filePath);
+}
+
+function appendJsonlAtomic(filePath, rows) {
+  fs.appendFileSync(filePath, `${rows.map((row) => JSON.stringify(row)).join("\n")}\n`, { mode: 0o600 });
+}
+
+function readJsonIfExists(filePath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function isClaudeDesktopTitleRestored(nativeSession) {
+  const desktopImport = nativeSession.desktopImport;
+  if (!desktopImport?.attempted) return true;
+  const expectedTitle = nativeSession.title || nativeSession.desktopTitle?.title;
+  const metadataPath = nativeSession.desktopTitle?.metadataPath || nativeSession.desktopMetadataPath;
+  if (expectedTitle && metadataPath && fs.existsSync(metadataPath)) {
+    const metadata = readJsonIfExists(metadataPath, null);
+    return metadata?.title === expectedTitle && metadata?.titleSource === "user";
+  }
+  return nativeSession.desktopTitle?.restored === true;
+}
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}