@hermespilot/link 0.3.8 → 0.4.0

package/dist/{chunk-RJB5VUT4.js → chunk-FWPHQZP6.js}

@@ -4,7 +4,7 @@ import Router from "@koa/router";
 
 // src/conversations/conversation-service.ts
 import { EventEmitter } from "events";
-import { randomUUID as randomUUID7 } from "crypto";
+import { randomUUID as randomUUID8 } from "crypto";
 
 // src/database/link-database.ts
 import { mkdir } from "fs/promises";
@@ -3883,7 +3883,7 @@ async function listCronOutputFiles(profileName, jobId) {
       mtimeMs: fileStat.mtimeMs
     });
   }
-  return files.sort((left, right) => left.mtimeMs - right.mtimeMs).map(({ path: path25, mtime }) => ({ path: path25, mtime }));
+  return files.sort((left, right) => left.mtimeMs - right.mtimeMs).map(({ path: path26, mtime }) => ({ path: path26, mtime }));
 }
 async function readCronOutput(outputPath) {
   const content = await readFile3(outputPath, "utf8");
@@ -3970,7 +3970,7 @@ import os2 from "os";
 import path5 from "path";
 
 // src/constants.ts
-var LINK_VERSION = "0.3.8";
+var LINK_VERSION = "0.4.0";
 var LINK_COMMAND = "hermeslink";
 var LINK_DEFAULT_PORT = 52379;
 var LINK_RUNTIME_DIR_NAME = ".hermeslink";
@@ -4455,6 +4455,9 @@ var DEFAULT_START_TIMEOUT_MS = 12e3;
 var HEALTH_TIMEOUT_MS = 1500;
 var MIN_API_SERVER_VERSION = "0.4.0";
 var PROFILE_NAME_PATTERN = /^[a-zA-Z0-9._-]{1,64}$/u;
+var DASHBOARD_STATUS_URL = "http://127.0.0.1:9119/api/status";
+var DASHBOARD_STATUS_TIMEOUT_MS = 1500;
+var MAX_VERSION_LOG_OUTPUT_LENGTH = 1200;
 var gatewayStartInFlightByProfile = /* @__PURE__ */ new Map();
 async function ensureHermesApiServerAvailable(options = {}) {
   const profileName = normalizeProfileName(options.profileName);
@@ -4571,29 +4574,57 @@ async function reloadHermesGateway(options = {}) {
   }
   return ensureHermesApiServerAvailable({ ...options, forceRestart: true });
 }
-async function readHermesVersion() {
-  const { stdout } = await execHermesVersion();
-  const raw = stdout.trim();
-  const version = parseHermesVersion(raw);
-  return {
-    raw,
-    version,
-    supportsApiServer: version ? compareSemver(version, MIN_API_SERVER_VERSION) >= 0 : null
-  };
-}
-async function execHermesVersion() {
+async function readHermesVersion(options = {}) {
   try {
-    return await execFileAsync2(resolveHermesBin(), ["version"], {
-      timeout: 5e3,
-      windowsHide: true
-    });
-  } catch {
-    return await execFileAsync2(resolveHermesBin(), ["--version"], {
-      timeout: 5e3,
-      windowsHide: true
+    const { stdout } = await execHermesVersion(options.logger);
+    const raw = stdout.trim();
+    const version = parseHermesVersion(raw);
+    return buildHermesVersionInfo(raw, version);
+  } catch (cliError) {
+    const dashboardStatusUrl = options.dashboardStatusUrl ?? DASHBOARD_STATUS_URL;
+    void options.logger?.warn("hermes_version_dashboard_fallback_requested", {
+      dashboard_status_url: dashboardStatusUrl,
+      reason: cliError instanceof Error ? cliError.message : String(cliError)
     });
+    try {
+      const fallback = await readHermesDashboardVersion({
+        fetchImpl: options.fetchImpl,
+        statusUrl: dashboardStatusUrl,
+        timeoutMs: options.dashboardTimeoutMs
+      });
+      void options.logger?.info("hermes_version_dashboard_fallback_succeeded", {
+        dashboard_status_url: dashboardStatusUrl,
+        hermes_version: fallback.version
+      });
+      return fallback;
+    } catch (dashboardError) {
+      void options.logger?.warn("hermes_version_dashboard_fallback_failed", {
+        dashboard_status_url: dashboardStatusUrl,
+        error: dashboardError instanceof Error ? dashboardError.message : String(dashboardError)
+      });
+      throw new Error(
+        `Hermes version detection failed. CLI: ${cliError instanceof Error ? cliError.message : String(cliError)}; dashboard fallback: ${dashboardError instanceof Error ? dashboardError.message : String(dashboardError)}`
+      );
+    }
   }
 }
+async function execHermesVersion(logger) {
+  const hermesBin = resolveHermesBin();
+  const failures = [];
+  for (const args of [["version"], ["--version"]]) {
+    try {
+      return await execFileAsync2(hermesBin, args, {
+        timeout: 5e3,
+        windowsHide: true
+      });
+    } catch (error) {
+      const failure = describeVersionCommandFailure(hermesBin, args, error);
+      failures.push(failure.summary);
+      void logger?.warn("hermes_version_cli_command_failed", failure.fields);
+    }
+  }
+  throw new Error(failures.join("; "));
+}
 function assertHermesRunsApiSupported(version, status) {
   if (status !== 404) {
     return;
@@ -4617,7 +4648,7 @@ async function startHermesGatewayOnce(paths, profileName, logger) {
   return await gatewayStartInFlightByProfile.get(profileName);
 }
 async function startHermesGateway(paths, profileName, logger) {
-  const version = await readHermesVersion().catch((error) => {
+  const version = await readHermesVersion({ logger }).catch((error) => {
     void logger?.error("gateway_hermes_cli_unavailable", {
       error: error instanceof Error ? error.message : String(error)
     });
@@ -4729,7 +4760,7 @@ async function restartHermesGatewayServiceIfAvailable(options) {
   return {
     pid: null,
     logPath,
-    version: await readHermesVersion().catch(() => null),
+    version: await readHermesVersion({ logger: options.logger }).catch(() => null),
     ...logHint ? { logHint } : {}
   };
 }
@@ -4972,6 +5003,72 @@ function parseHermesVersion(value) {
   const match = /\bv?(\d+\.\d+\.\d+)\b/u.exec(value);
   return match?.[1] ?? null;
 }
+function buildHermesVersionInfo(raw, version) {
+  return {
+    raw,
+    version,
+    supportsApiServer: version ? compareSemver(version, MIN_API_SERVER_VERSION) >= 0 : null
+  };
+}
+async function readHermesDashboardVersion(options = {}) {
+  const fetcher = options.fetchImpl ?? fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(),
+    options.timeoutMs ?? DASHBOARD_STATUS_TIMEOUT_MS
+  );
+  try {
+    const response = await fetcher(options.statusUrl ?? DASHBOARD_STATUS_URL, {
+      method: "GET",
+      headers: { accept: "application/json" },
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      throw new Error(`Hermes dashboard returned HTTP ${response.status}`);
+    }
+    const payload = await response.json().catch(() => null);
+    const record = toRecord2(payload);
+    const versionText = readString4(record, "version");
+    if (!versionText) {
+      throw new Error("Hermes dashboard status did not include a version");
+    }
+    const raw = truncateVersionLogOutput(JSON.stringify(record));
+    const version = parseHermesVersion(versionText) ?? parseHermesVersion(raw);
+    return buildHermesVersionInfo(raw, version);
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error("Hermes dashboard version probe timed out");
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function describeVersionCommandFailure(hermesBin, args, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const output = truncateVersionLogOutput(readExecErrorOutput2(error));
+  return {
+    summary: `${hermesBin} ${args.join(" ")} failed: ${message}`,
+    fields: {
+      hermes_bin: hermesBin,
+      command: args.join(" "),
+      error: message,
+      ...output ? { output } : {}
+    }
+  };
+}
+function readExecErrorOutput2(error) {
+  if (typeof error !== "object" || error === null) {
+    return "";
+  }
+  const stdout = "stdout" in error && error.stdout != null ? String(error.stdout) : "";
+  const stderr = "stderr" in error && error.stderr != null ? String(error.stderr) : "";
+  return `${stdout}
+${stderr}`.trim();
+}
+function truncateVersionLogOutput(value) {
+  return value.length > MAX_VERSION_LOG_OUTPUT_LENGTH ? `${value.slice(0, MAX_VERSION_LOG_OUTPUT_LENGTH)}...` : value;
+}
 function compareSemver(left, right) {
   const leftParts = left.split(".").map((part) => Number.parseInt(part, 10));
   const rightParts = right.split(".").map((part) => Number.parseInt(part, 10));
@@ -6663,6 +6760,70 @@ function safePathSegment(value, fallback) {
   return safe.length > 0 ? safe.slice(0, 120) : fallback;
 }
 
+// src/conversations/conversation-clear-plans.ts
+import { randomUUID as randomUUID5 } from "crypto";
+import { mkdir as mkdir7 } from "fs/promises";
+import path11 from "path";
+var PLAN_ID_PATTERN = /^clear_[a-f0-9]{32}$/u;
+var ConversationClearPlanStore = class {
+  constructor(paths) {
+    this.paths = paths;
+  }
+  paths;
+  async create(conversationIds) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const plan = {
+      id: `clear_${randomUUID5().replaceAll("-", "")}`,
+      status: "prepared",
+      created_at: now,
+      updated_at: now,
+      total_count: conversationIds.length,
+      deleted_count: 0,
+      failed_count: 0,
+      conversation_ids: conversationIds,
+      conversations: []
+    };
+    await this.write(plan);
+    return plan;
+  }
+  async read(planId) {
+    const normalizedPlanId = normalizePlanId(planId);
+    const plan = await readJsonFile(
+      this.planPath(normalizedPlanId)
+    );
+    if (!plan) {
+      throw new LinkHttpError(
+        404,
+        "conversation_clear_plan_not_found",
+        "Conversation clear plan was not found"
+      );
+    }
+    return plan;
+  }
+  async write(plan) {
+    const normalizedPlanId = normalizePlanId(plan.id);
+    await mkdir7(this.plansDir(), { recursive: true, mode: 448 });
+    await writeJsonFile(this.planPath(normalizedPlanId), plan);
+  }
+  plansDir() {
+    return path11.join(this.paths.indexesDir, "conversation-clear-plans");
+  }
+  planPath(planId) {
+    return path11.join(this.plansDir(), `${planId}.json`);
+  }
+};
+function normalizePlanId(planId) {
+  const normalized = planId.trim();
+  if (!PLAN_ID_PATTERN.test(normalized)) {
+    throw new LinkHttpError(
+      400,
+      "conversation_clear_plan_id_invalid",
+      "Conversation clear plan id is invalid"
+    );
+  }
+  return normalized;
+}
+
 // src/conversations/conversation-session-ids.ts
 function normalizeHermesSessionIds(values) {
   const seen = /* @__PURE__ */ new Set();
@@ -6713,8 +6874,134 @@ var MAX_UPLOADED_BLOB_BYTES = 50 * 1024 * 1024;
 var ConversationMaintenanceCoordinator = class {
   constructor(deps) {
     this.deps = deps;
+    this.clearPlans = new ConversationClearPlanStore(deps.paths);
   }
   deps;
+  clearPlans;
+  async prepareClearAllConversationPlan() {
+    const targets = [];
+    for (const conversationId of await this.deps.store.listConversationIds()) {
+      const manifest = await this.deps.store.readManifest(conversationId).catch(() => null);
+      if (manifest?.status !== "active") {
+        continue;
+      }
+      targets.push({
+        id: conversationId,
+        updatedAt: manifest.updated_at
+      });
+    }
+    targets.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+    return this.clearPlans.create(
+      targets.map((target) => target.id)
+    );
+  }
+  async readClearAllConversationPlan(planId) {
+    return this.clearPlans.read(planId);
+  }
+  async executeClearAllConversationPlan(planId) {
+    let plan = await this.clearPlans.read(planId);
+    if (plan.status === "completed") {
+      return plan;
+    }
+    if (plan.status === "failed") {
+      throw new LinkHttpError(
+        409,
+        "conversation_clear_plan_already_failed",
+        "Conversation clear plan has already failed"
+      );
+    }
+    const results = [];
+    if (plan.status !== "executing") {
+      plan = await this.writeClearPlan({
+        ...plan,
+        status: "executing",
+        updated_at: (/* @__PURE__ */ new Date()).toISOString(),
+        conversations: results,
+        deleted_count: 0,
+        failed_count: 0
+      });
+    }
+    for (const conversationId of plan.conversation_ids) {
+      try {
+        const deleted = await this.deleteConversation(conversationId);
+        results.push({ ...deleted, status: "deleted" });
+      } catch (error) {
+        if (error instanceof LinkHttpError && error.code === "conversation_not_found") {
+          results.push({
+            conversation_id: conversationId,
+            status: "deleted",
+            hermes_deleted: false,
+            deleted_at: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        } else {
+          results.push({
+            conversation_id: conversationId,
+            status: "failed",
+            error: {
+              code: error instanceof LinkHttpError ? error.code : "internal_error",
+              message: error instanceof Error ? error.message : "Internal error"
+            }
+          });
+        }
+      }
+      plan = await this.writeClearPlan({
+        ...plan,
+        updated_at: (/* @__PURE__ */ new Date()).toISOString(),
+        conversations: [...results],
+        deleted_count: results.filter((result) => result.status === "deleted").length,
+        failed_count: results.filter((result) => result.status === "failed").length
+      });
+    }
+    const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+    return this.writeClearPlan({
+      ...plan,
+      status: plan.failed_count === 0 ? "completed" : "failed",
+      updated_at: completedAt,
+      completed_at: completedAt
+    });
+  }
+  async startClearAllConversationPlan(planId) {
+    const plan = await this.clearPlans.read(planId);
+    if (plan.status === "completed" || plan.status === "executing") {
+      return plan;
+    }
+    if (plan.status === "failed") {
+      throw new LinkHttpError(
+        409,
+        "conversation_clear_plan_already_failed",
+        "Conversation clear plan has already failed"
+      );
+    }
+    const started = await this.writeClearPlan({
+      ...plan,
+      status: "executing",
+      updated_at: (/* @__PURE__ */ new Date()).toISOString(),
+      conversations: [],
+      deleted_count: 0,
+      failed_count: 0
+    });
+    void this.executeClearAllConversationPlan(started.id).catch(
+      async (error) => {
+        const failedAt = (/* @__PURE__ */ new Date()).toISOString();
+        await this.writeClearPlan({
+          ...started,
+          status: "failed",
+          updated_at: failedAt,
+          completed_at: failedAt,
+          failed_count: started.total_count,
+          conversations: started.conversation_ids.map((conversationId) => ({
+            conversation_id: conversationId,
+            status: "failed",
+            error: {
+              code: error instanceof LinkHttpError ? error.code : "internal_error",
+              message: error instanceof Error ? error.message : "Internal error"
+            }
+          }))
+        }).catch(() => void 0);
+      }
+    );
+    return started;
+  }
   async deleteConversation(conversationId) {
     return this.deps.withConversationLock(
       conversationId,
@@ -6920,6 +7207,10 @@ var ConversationMaintenanceCoordinator = class {
   async listConversationBlobIds(conversationId) {
     return listConversationBlobIds(this.deps.paths, conversationId);
   }
+  async writeClearPlan(plan) {
+    await this.clearPlans.write(plan);
+    return plan;
+  }
 };
 function isVoiceAttachmentInput(attachment) {
   return attachment.kind === "voice" || attachment.type === "voice" || attachment.is_voice_note === true || attachment.isVoiceNote === true;
@@ -6999,14 +7290,14 @@ function isUsableLanIpv4(value) {
 
 // src/hermes/session-title.ts
 import { stat as stat7 } from "fs/promises";
-import path11 from "path";
+import path12 from "path";
 async function readHermesSessionTitle(sessionId, paths, profileName) {
   const trimmedSessionId = sessionId.trim();
   if (!trimmedSessionId) {
     return void 0;
   }
   const resolvedProfileName = isValidProfileName(profileName) ? profileName : "default";
-  const dbPath = path11.join(
+  const dbPath = path12.join(
     resolveHermesProfileDir(resolvedProfileName),
     "state.db"
   );
@@ -7027,7 +7318,7 @@ async function readHermesCompressionTip(sessionId, paths, profileName) {
     return void 0;
   }
   const resolvedProfileName = isValidProfileName(profileName) ? profileName : "default";
-  const dbPath = path11.join(
+  const dbPath = path12.join(
     resolveHermesProfileDir(resolvedProfileName),
     "state.db"
   );
@@ -7122,11 +7413,19 @@ var ConversationMetadataCoordinator = class {
     const snapshot = options.snapshot ?? await this.deps.store.readSnapshot(manifest.id).catch(
       () => createEmptySnapshot()
     );
-    const title = await readHermesSessionTitle(
+    const profileName = latestRuntimeRun(snapshot)?.profile ?? manifest.profile_name_snapshot ?? manifest.profile;
+    const compressionRootSessionId = manifest.hermes_lineage?.kind === "compression" ? manifest.hermes_lineage.root_session_id : void 0;
+    const rootTitle = compressionRootSessionId ? await readHermesSessionTitle(
+      compressionRootSessionId,
+      this.deps.paths,
+      profileName
+    ) : void 0;
+    const tipTitle = await readHermesSessionTitle(
       manifest.hermes_session_id,
       this.deps.paths,
-      latestRuntimeRun(snapshot)?.profile
+      profileName
     );
+    const title = rootTitle ?? (compressionRootSessionId ? stripCompressionTitleSuffix(tipTitle) : tipTitle);
     if (!title || title === manifest.title) {
       return manifest;
     }
@@ -7440,9 +7739,18 @@ function canAutoGenerateTitle(manifest) {
 function normalizeConversationTitleSource(title) {
   return isDefaultConversationTitle(title) ? "default" : "hermes";
 }
+function stripCompressionTitleSuffix(value) {
+  const normalized = value?.replace(/\s+/gu, " ").trim();
+  if (!normalized) {
+    return void 0;
+  }
+  const match = /^(.*?) #\d+$/u.exec(normalized);
+  const stripped = match?.[1]?.trim();
+  return stripped || normalized;
+}
 
 // src/conversations/conversation-turns.ts
-import { randomUUID as randomUUID5 } from "crypto";
+import { randomUUID as randomUUID6 } from "crypto";
 var MESSAGE_ORDER_STEP_MS = 10;
 var ASSISTANT_ORDER_OFFSET_MS = 1;
 function createAgentTurnDraft(input) {
@@ -7676,10 +7984,10 @@ function createAssistantMessage(input) {
   };
 }
 function createMessageId() {
-  return `msg_${randomUUID5().replaceAll("-", "")}`;
+  return `msg_${randomUUID6().replaceAll("-", "")}`;
 }
 function createRunId() {
-  return `run_${randomUUID5().replaceAll("-", "")}`;
+  return `run_${randomUUID6().replaceAll("-", "")}`;
 }
 function hasActiveOrQueuedRuns(snapshot) {
   return snapshot.runs.some(
@@ -8794,20 +9102,20 @@ function hydrateAgentEventBlocks(blocks, agentEvents) {
 // src/conversations/conversation-store.ts
 import {
   appendFile as appendFile2,
-  mkdir as mkdir7,
+  mkdir as mkdir8,
   readdir as readdir5,
   readFile as readFile7,
   rm as rm5,
   writeFile as writeFile2
 } from "fs/promises";
-import path12 from "path";
+import path13 from "path";
 var ConversationStore = class {
   constructor(paths) {
     this.paths = paths;
   }
   paths;
   async ensureConversationsDir() {
-    await mkdir7(this.paths.conversationsDir, { recursive: true, mode: 448 });
+    await mkdir8(this.paths.conversationsDir, { recursive: true, mode: 448 });
   }
   async listConversationIds() {
     await this.ensureConversationsDir();
@@ -8822,7 +9130,7 @@ var ConversationStore = class {
     return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
   }
   async createConversation(manifest, snapshot = createEmptySnapshot2()) {
-    await mkdir7(this.conversationDir(manifest.id), {
+    await mkdir8(this.conversationDir(manifest.id), {
       recursive: true,
       mode: 448
     });
@@ -8862,7 +9170,7 @@ var ConversationStore = class {
       conversation_id: conversationId,
       created_at: now
     };
-    await mkdir7(this.conversationDir(conversationId), {
+    await mkdir8(this.conversationDir(conversationId), {
       recursive: true,
       mode: 448
     });
@@ -8916,23 +9224,23 @@ var ConversationStore = class {
     return manifest?.status === "active";
   }
   removeConversationAttachments(conversationId) {
-    return rm5(path12.join(this.conversationDir(conversationId), "attachments"), {
+    return rm5(path13.join(this.conversationDir(conversationId), "attachments"), {
       recursive: true,
       force: true
     });
   }
   conversationDir(conversationId) {
     assertValidConversationId(conversationId);
-    return path12.join(this.paths.conversationsDir, conversationId);
+    return path13.join(this.paths.conversationsDir, conversationId);
   }
   manifestPath(conversationId) {
-    return path12.join(this.conversationDir(conversationId), "manifest.json");
+    return path13.join(this.conversationDir(conversationId), "manifest.json");
   }
   snapshotPath(conversationId) {
-    return path12.join(this.conversationDir(conversationId), "snapshot.json");
+    return path13.join(this.conversationDir(conversationId), "snapshot.json");
   }
   eventsPath(conversationId) {
-    return path12.join(this.conversationDir(conversationId), "events.ndjson");
+    return path13.join(this.conversationDir(conversationId), "events.ndjson");
   }
 };
 function createEmptySnapshot2() {
@@ -8943,14 +9251,14 @@ function isNodeError9(error, code) {
 }
 
 // src/conversations/hermes-session-sync.ts
-import { randomUUID as randomUUID6 } from "crypto";
+import { randomUUID as randomUUID7 } from "crypto";
 import { readdir as readdir7, readFile as readFile9, stat as stat9 } from "fs/promises";
 import os4 from "os";
-import path14 from "path";
+import path15 from "path";
 
 // src/conversations/delivery-import.ts
 import { lstat as lstat2, readFile as readFile8, readdir as readdir6, stat as stat8 } from "fs/promises";
-import path13 from "path";
+import path14 from "path";
 var MAX_IMPORTED_BLOB_BYTES = 100 * 1024 * 1024;
 var MAX_MEDIA_IMPORT_FAILURES = 20;
 var MAX_DELIVERY_FILES = 50;
@@ -9021,16 +9329,16 @@ var SUPPORTED_DELIVERY_EXTENSIONS = /* @__PURE__ */ new Set([
   ".m4a"
 ]);
 function resolveDeliveryStagingTarget(paths, stagingDir) {
-  const resolvedDir = path13.resolve(stagingDir);
-  const relative = path13.relative(path13.resolve(paths.conversationsDir), resolvedDir);
-  if (!relative || relative.startsWith("..") || path13.isAbsolute(relative)) {
+  const resolvedDir = path14.resolve(stagingDir);
+  const relative = path14.relative(path14.resolve(paths.conversationsDir), resolvedDir);
+  if (!relative || relative.startsWith("..") || path14.isAbsolute(relative)) {
     throw new LinkHttpError(
       400,
       "delivery_staging_invalid",
       "delivery staging directory must be inside Hermes Link conversations"
     );
   }
-  const segments = relative.split(path13.sep);
+  const segments = relative.split(path14.sep);
   if (segments.length !== 3 || segments[1] !== DELIVERY_STAGING_SEGMENT || !segments[0] || !segments[2]) {
     throw new LinkHttpError(
       400,
@@ -9066,7 +9374,7 @@ async function collectStagedDeliveryReferences(stagingDir) {
   return entries.filter((entry) => entry.isFile() && !entry.name.startsWith(".")).filter((entry) => isSupportedDeliveryFilename(entry.name)).sort(
     (left, right) => left.name.localeCompare(right.name, "en", { numeric: true })
   ).slice(0, MAX_DELIVERY_FILES).map((entry) => {
-    const sourcePath = path13.join(stagingDir, entry.name);
+    const sourcePath = path14.join(stagingDir, entry.name);
     const mime = inferMimeType(sourcePath);
     return {
       path: sourcePath,
@@ -9252,7 +9560,7 @@ async function writeBlobFromFile(deps, conversationId, source) {
   }
   return deps.writeBlob(conversationId, {
     bytes: await readFile8(sourcePath),
-    filename: path13.basename(sourcePath),
+    filename: path14.basename(sourcePath),
     mime: source.mime ?? inferMimeType(sourcePath)
   });
 }
@@ -9265,7 +9573,7 @@ function describeMediaImportFailure(reference, sourceKey, error) {
   };
 }
 function isSupportedDeliveryFilename(filename) {
-  return SUPPORTED_DELIVERY_EXTENSIONS.has(path13.extname(filename).toLowerCase());
+  return SUPPORTED_DELIVERY_EXTENSIONS.has(path14.extname(filename).toLowerCase());
 }
 function readString8(payload, key) {
   const value = payload[key];
@@ -9322,7 +9630,7 @@ async function syncHermesSessionsIntoConversations(paths, logger, options = {})
   const candidates = [];
   for (const profileName of profileNames) {
     const profileDir = resolveHermesProfileDir(profileName);
-    const dbPath = path14.join(profileDir, "state.db");
+    const dbPath = path15.join(profileDir, "state.db");
     const sessions = await listProfileSessions(dbPath).catch((error) => {
       result.errors.push({
         profile: profileName,
@@ -9352,16 +9660,19 @@ async function syncHermesSessionsIntoConversations(paths, logger, options = {})
   const importableCandidates = candidates.slice(0, maxImports);
   result.skipped_over_limit = Math.max(0, candidates.length - maxImports);
   for (const candidate of importableCandidates) {
-    if (knownHermesSessions.ids.has(candidate.session.id)) {
+    const candidateSessionIds = lineageSessionIds(candidate);
+    const knownConversationIds = findKnownConversationIdsForCandidate(
+      knownHermesSessions,
+      candidate
+    );
+    if (knownConversationIds.length > 0) {
       result.skipped_existing += 1;
-      const reprojected = await reprojectExistingHermesConversation({
+      const reprojected = await mergeExistingHermesConversation({
         paths,
         store,
         logger,
         candidate,
-        conversationIds: knownHermesSessions.conversationIdsBySessionId.get(
-          candidate.session.id
-        ) ?? []
+        conversationIds: knownConversationIds
       }).catch((error) => {
         result.errors.push({
           profile: candidate.profileName,
@@ -9372,14 +9683,22 @@ async function syncHermesSessionsIntoConversations(paths, logger, options = {})
       if (reprojected) {
         result.reprojected_count += 1;
       }
+      for (const sessionId of candidateSessionIds) {
+        knownHermesSessions.sessionIds.add(sessionId);
+      }
+      continue;
+    }
+    if (candidateSessionIds.some(
+      (sessionId) => knownHermesSessions.sessionIds.has(sessionId)
+    )) {
+      result.skipped_existing += 1;
       continue;
     }
     const imported = await importHermesSession({
       paths,
       store,
       logger,
-      candidate,
-      existingHermesSessionIds: knownHermesSessions.ids
+      candidate
     }).catch((error) => {
       result.errors.push({
         profile: candidate.profileName,
@@ -9389,6 +9708,9 @@ async function syncHermesSessionsIntoConversations(paths, logger, options = {})
     });
     if (imported) {
       result.imported_count += 1;
+      for (const sessionId of candidateSessionIds) {
+        knownHermesSessions.sessionIds.add(sessionId);
+      }
     }
   }
   if (result.imported_count > 0 || result.reprojected_count > 0 || result.errors.length > 0) {
@@ -9399,13 +9721,14 @@ async function syncHermesSessionsIntoConversations(paths, logger, options = {})
   return result;
 }
 async function importHermesSession(input) {
-  const { paths, store, logger, candidate, existingHermesSessionIds } = input;
+  const { paths, store, logger, candidate } = input;
   const profile = await resolveConversationProfileTarget(
     paths,
     candidate.profileName
   );
   const sessionId = candidate.session.id;
-  const messages = await readHermesSessionMessages(candidate);
+  const hermesSessionIds = lineageSessionIds(candidate);
+  const messages = await readHermesLineageMessages(candidate);
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const createdAt = isoFromHermesTime(candidate.session.started_at) ?? now;
   const updatedAt = isoFromHermesTime(candidate.session.last_active) ?? isoFromHermesTime(messages.at(-1)?.timestamp) ?? createdAt;
@@ -9422,7 +9745,14 @@ async function importHermesSession(input) {
     }),
     runs: []
   };
-  const title = readString9(candidate.session, "title") ?? firstUserText(snapshot);
+  const title = lineageTitle(candidate) ?? readString9(candidate.session, "title") ?? firstUserText(snapshot);
+  const importedStats = buildImportedHermesStats({
+    candidate,
+    snapshot,
+    profileUid: profile.profileUid,
+    profileName: profile.profileName,
+    updatedAt
+  });
   const manifest = {
     id: conversationId,
     schema_version: 1,
@@ -9431,13 +9761,15 @@ async function importHermesSession(input) {
     title_source: title ? "hermes" : "default",
     status: "active",
     hermes_session_id: sessionId,
-    hermes_session_ids: [sessionId],
+    hermes_session_ids: hermesSessionIds,
+    ...lineageManifestPatch(candidate),
     profile_uid: profile.profileUid,
     profile_name_snapshot: profile.profileName,
     profile: profile.profileName,
     created_at: createdAt,
     updated_at: updatedAt,
-    last_event_seq: 0
+    last_event_seq: 0,
+    stats: importedStats
   };
   await store.createConversation(manifest, snapshot);
   await hydrateImportedConversationMedia({
@@ -9480,59 +9812,288 @@ async function importHermesSession(input) {
     paths,
     toStatsIndexRecord(await store.readManifest(conversationId), stats)
   );
-  existingHermesSessionIds.add(sessionId);
   return true;
 }
-async function reprojectExistingHermesConversation(input) {
+async function mergeExistingHermesConversation(input) {
+  const conversations = await readExistingHermesConversations(
+    input.store,
+    input.conversationIds
+  );
+  const active = conversations.filter((item) => item.manifest.status === "active");
+  const canonical = selectCanonicalHermesConversation(active);
+  if (!canonical) {
+    return false;
+  }
   let changed = false;
-  for (const conversationId of input.conversationIds) {
-    const manifest = await input.store.readManifest(conversationId).catch(() => null);
-    if (!manifest || manifest.status !== "active") {
-      continue;
-    }
-    const snapshot = await input.store.readSnapshot(conversationId).catch(() => null);
-    if (!snapshot) {
+  const candidateMessages = await readHermesLineageMessages(input.candidate);
+  const nextCanonical = await mergeHermesCandidateIntoConversation({
+    ...input,
+    existing: canonical,
+    candidateMessages
+  });
+  changed = nextCanonical || changed;
+  for (const duplicate of active) {
+    if (duplicate.conversationId === canonical.conversationId) {
       continue;
     }
-    const prefix = collectImportedHermesPrefix(snapshot);
-    if (!prefix?.needsUpgrade || prefix.messages.length === 0) {
+    if (!isSafeHermesImportConversation(duplicate) || duplicate.manifest.status !== "active") {
       continue;
     }
-    const profile = await resolveConversationProfileTarget(
-      input.paths,
-      manifest.profile_name_snapshot ?? manifest.profile ?? input.candidate.profileName
-    );
-    const nextSnapshot = {
-      ...snapshot,
+    await softDeleteMergedHermesDuplicate({
+      paths: input.paths,
+      store: input.store,
+      duplicate,
+      candidate: input.candidate
+    });
+    changed = true;
+  }
+  return changed;
+}
+async function mergeHermesCandidateIntoConversation(input) {
+  const { candidate, existing } = input;
+  const profile = await resolveConversationProfileTarget(
+    input.paths,
+    existing.manifest.profile_name_snapshot ?? existing.manifest.profile ?? candidate.profileName
+  );
+  let nextSnapshot = existing.snapshot;
+  const pureImport = isSafeHermesImportConversation(existing);
+  const prefix = collectImportedHermesPrefix(existing.snapshot);
+  if (pureImport || prefix?.needsUpgrade && prefix.messages.length > 0) {
+    const messages = pureImport ? input.candidateMessages : prefix.messages;
+    nextSnapshot = {
+      ...existing.snapshot,
       messages: [
         ...toLinkMessages({
-          conversationId,
+          conversationId: existing.conversationId,
           profileName: profile.profileName,
           profileUid: profile.profileUid,
           profileDisplayName: profile.profileDisplayName,
-          sessionId: input.candidate.session.id,
-          messages: prefix.messages
+          sessionId: candidate.session.id,
+          messages
         }),
-        ...snapshot.messages.slice(prefix.endIndex)
+        ...pureImport ? [] : existing.snapshot.messages.slice(prefix.endIndex)
       ]
     };
-    await input.store.writeSnapshot(conversationId, nextSnapshot);
+    await input.store.writeSnapshot(existing.conversationId, nextSnapshot);
     await hydrateImportedConversationMedia({
       paths: input.paths,
       store: input.store,
       logger: input.logger,
-      conversationId
+      conversationId: existing.conversationId
     });
-    const hydratedSnapshot = await input.store.readSnapshot(conversationId);
-    const stats = buildConversationStats(manifest, hydratedSnapshot);
-    await input.store.writeManifest({ ...manifest, stats });
-    await upsertConversationStats(
-      input.paths,
-      toStatsIndexRecord({ ...manifest, stats }, stats)
-    );
-    changed = true;
+    nextSnapshot = await input.store.readSnapshot(existing.conversationId);
+  }
+  const updatedAt = isoFromHermesTime(candidate.session.last_active) ?? existing.manifest.updated_at;
+  const nextManifest = mergeHermesLineageIntoManifest({
+    manifest: existing.manifest,
+    candidate,
+    snapshot: nextSnapshot,
+    profileUid: profile.profileUid,
+    profileName: profile.profileName,
+    updatedAt
+  });
+  if (manifestEquivalent(existing.manifest, nextManifest)) {
+    return nextSnapshot !== existing.snapshot;
   }
-  return changed;
+  await input.store.writeManifest(nextManifest);
+  await upsertConversationStats(
+    input.paths,
+    toStatsIndexRecord(nextManifest, nextManifest.stats)
+  );
+  return true;
+}
+function findKnownConversationIdsForCandidate(known, candidate) {
+  const conversationIds = [];
+  for (const sessionId of lineageSessionIds(candidate)) {
+    for (const conversationId of known.conversationIdsBySessionId.get(sessionId) ?? []) {
+      if (!conversationIds.includes(conversationId)) {
+        conversationIds.push(conversationId);
+      }
+    }
+  }
+  return conversationIds;
+}
+function lineageSessionIds(candidate) {
+  return normalizeSessionIds([
+    candidate.session._lineage_root_id,
+    ...candidate.session._lineage_session_ids ?? [],
+    candidate.session.id
+  ]);
+}
+function lineageTitle(candidate) {
+  return candidate.session._lineage_title ?? stripCompressionTitleSuffix2(readString9(candidate.session, "title") ?? "");
+}
+function lineageManifestPatch(candidate) {
+  const sessionIds = lineageSessionIds(candidate);
+  const rootSessionId = candidate.session._lineage_root_id ?? sessionIds[0];
+  const currentSessionId = candidate.session.id;
+  if (!rootSessionId || sessionIds.length <= 1 || rootSessionId === currentSessionId) {
+    return {};
+  }
+  return {
+    hermes_lineage: {
+      kind: "compression",
+      root_session_id: rootSessionId,
+      current_session_id: currentSessionId,
+      session_ids: sessionIds
+    }
+  };
+}
+function buildImportedHermesStats(input) {
+  const usage = input.candidate.session._lineage_usage;
+  const base = input.baseStats;
+  const usageInput = usage?.input_tokens ?? 0;
+  const usageOutput = usage?.output_tokens ?? 0;
+  const usageTotal = usage?.total_tokens ?? usageInput + usageOutput;
+  const inputTokens = Math.max(base?.input_tokens ?? 0, usageInput);
+  const outputTokens = Math.max(base?.output_tokens ?? 0, usageOutput);
+  const totalTokens = Math.max(
+    base?.total_tokens ?? 0,
+    usageTotal,
+    inputTokens + outputTokens
+  );
+  const updatedAt = base?.updated_at ? latestTimestamp(base.updated_at, input.updatedAt) : input.updatedAt;
+  return {
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    total_tokens: totalTokens,
+    message_count: Math.max(
+      base?.message_count ?? 0,
+      input.snapshot.messages.length
+    ),
+    run_count: Math.max(base?.run_count ?? 0, usage?.api_call_count ?? 0),
+    profile_uid: base?.profile_uid ?? input.profileUid,
+    profile_name_snapshot: base?.profile_name_snapshot ?? base?.profile ?? input.profileName,
+    profile: base?.profile ?? base?.profile_name_snapshot ?? input.profileName,
+    ...base?.model ?? usage?.model ? { model: base?.model ?? usage?.model } : {},
+    ...base?.provider ?? usage?.provider ? { provider: base?.provider ?? usage?.provider } : {},
+    ...base?.context_window ? { context_window: base.context_window } : {},
+    updated_at: updatedAt
+  };
+}
+async function readExistingHermesConversations(store, conversationIds) {
+  const conversations = [];
+  for (const conversationId of [...new Set(conversationIds)]) {
+    const manifest = await store.readManifest(conversationId).catch(() => null);
+    if (!manifest) {
+      continue;
+    }
+    const snapshot = await store.readSnapshot(conversationId).catch(() => ({
+      schema_version: 1,
+      messages: [],
+      runs: []
+    }));
+    conversations.push({ conversationId, manifest, snapshot });
+  }
+  return conversations;
+}
+function selectCanonicalHermesConversation(conversations) {
+  const ranked = [...conversations].sort((left, right) => {
+    const rightScore = canonicalConversationScore(right);
+    const leftScore = canonicalConversationScore(left);
+    if (rightScore !== leftScore) {
+      return rightScore - leftScore;
+    }
+    return Date.parse(left.manifest.created_at) - Date.parse(right.manifest.created_at) || left.conversationId.localeCompare(right.conversationId);
+  });
+  return ranked[0] ?? null;
+}
+function canonicalConversationScore(item) {
+  let score = 0;
+  if (!isSafeHermesImportConversation(item)) {
+    score += 1e3;
+  }
+  if (item.snapshot.runs.length > 0) {
+    score += 500;
+  }
+  if (item.manifest.title_source === "manual") {
+    score += 200;
+  }
+  if (!hasCompressionTitleSuffix(item.manifest.title)) {
+    score += 100;
+  }
+  if (item.manifest.hermes_lineage?.root_session_id && item.manifest.hermes_session_id === item.manifest.hermes_lineage.root_session_id) {
+    score += 50;
+  }
+  return score;
+}
+function isSafeHermesImportConversation(item) {
+  const snapshot = item.snapshot;
+  if (snapshot.runs.length > 0) {
+    return false;
+  }
+  if (item.manifest.title_source === "manual" || item.manifest.title_source === "generated") {
+    return false;
+  }
+  return snapshot.messages.length === 0 || snapshot.messages.every((message) => isHermesImportedMessage(message));
+}
+async function softDeleteMergedHermesDuplicate(input) {
+  const deletedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const emptySnapshot3 = {
+    schema_version: 1,
+    messages: [],
+    runs: []
+  };
+  const hermesSessionIds = normalizeSessionIds([
+    input.duplicate.manifest.hermes_session_id,
+    ...input.duplicate.manifest.hermes_session_ids ?? [],
+    ...input.duplicate.manifest.hermes_lineage?.session_ids ?? [],
+    ...lineageSessionIds(input.candidate)
+  ]);
+  const nextManifest = {
+    ...input.duplicate.manifest,
+    status: "deleted_soft",
+    hermes_session_ids: hermesSessionIds,
+    ...lineageManifestPatch(input.candidate),
+    updated_at: deletedAt,
+    deleted_at: deletedAt
+  };
+  const stats = buildConversationStats(
+    { ...nextManifest, stats: input.duplicate.manifest.stats },
+    emptySnapshot3
+  );
+  const tombstone = { ...nextManifest, stats };
+  await input.store.writeManifest(tombstone);
+  await input.store.writeSnapshot(input.duplicate.conversationId, emptySnapshot3);
+  await upsertConversationStats(input.paths, toStatsIndexRecord(tombstone, stats));
+}
+function mergeHermesLineageIntoManifest(input) {
+  const hermesSessionIds = normalizeSessionIds([
+    input.manifest.hermes_session_id,
+    ...input.manifest.hermes_session_ids ?? [],
+    ...input.manifest.hermes_lineage?.session_ids ?? [],
+    ...lineageSessionIds(input.candidate)
+  ]);
+  const nextBase = {
+    ...input.manifest,
+    hermes_session_id: input.candidate.session.id,
+    hermes_session_ids: hermesSessionIds,
+    ...lineageManifestPatch(input.candidate),
+    profile_uid: input.manifest.profile_uid ?? input.profileUid,
+    profile_name_snapshot: input.manifest.profile_name_snapshot ?? input.manifest.profile ?? input.profileName,
+    profile: input.manifest.profile ?? input.manifest.profile_name_snapshot ?? input.profileName,
+    updated_at: latestTimestamp(input.manifest.updated_at, input.updatedAt)
+  };
+  const title = lineageTitle(input.candidate);
+  if (title && canSyncHermesTitle(input.manifest)) {
+    nextBase.title = normalizeTitle(title);
+    nextBase.title_source = "hermes";
+  }
+  const baseStats = buildConversationStats(nextBase, input.snapshot);
+  return {
+    ...nextBase,
+    stats: buildImportedHermesStats({
+      candidate: input.candidate,
+      snapshot: input.snapshot,
+      profileUid: input.profileUid,
+      profileName: input.profileName,
+      updatedAt: input.updatedAt,
+      baseStats
+    })
+  };
+}
+function manifestEquivalent(left, right) {
+  return stableJson(left) === stableJson(right);
 }
 function collectImportedHermesPrefix(snapshot) {
   const rows = [];
@@ -10006,7 +10567,7 @@ function latestTimestamp(left, right) {
   return leftTime >= rightTime ? left : right;
 }
 async function readKnownHermesSessions(store) {
-  const ids = /* @__PURE__ */ new Set();
+  const sessionIds = /* @__PURE__ */ new Set();
   const conversationIdsBySessionId = /* @__PURE__ */ new Map();
   for (const conversationId of await store.listConversationIds()) {
     const manifest = await store.readManifest(conversationId).catch(() => null);
@@ -10014,7 +10575,7 @@ async function readKnownHermesSessions(store) {
       continue;
     }
     if (manifest.hermes_session_id) {
-      ids.add(manifest.hermes_session_id);
+      sessionIds.add(manifest.hermes_session_id);
       rememberKnownHermesConversation(
         conversationIdsBySessionId,
         manifest.hermes_session_id,
@@ -10022,7 +10583,22 @@ async function readKnownHermesSessions(store) {
       );
     }
     for (const sessionId of manifest.hermes_session_ids ?? []) {
-      ids.add(sessionId);
+      sessionIds.add(sessionId);
+      rememberKnownHermesConversation(
+        conversationIdsBySessionId,
+        sessionId,
+        conversationId
+      );
+    }
+    for (const sessionId of [
+      manifest.hermes_lineage?.root_session_id,
+      manifest.hermes_lineage?.current_session_id,
+      ...manifest.hermes_lineage?.session_ids ?? []
+    ]) {
+      if (!sessionId) {
+        continue;
+      }
+      sessionIds.add(sessionId);
       rememberKnownHermesConversation(
         conversationIdsBySessionId,
         sessionId,
@@ -10030,7 +10606,7 @@ async function readKnownHermesSessions(store) {
       );
     }
   }
-  return { ids, conversationIdsBySessionId };
+  return { sessionIds, conversationIdsBySessionId };
 }
 function rememberKnownHermesConversation(map, sessionId, conversationId) {
   const current = map.get(sessionId) ?? [];
@@ -10040,7 +10616,7 @@ function rememberKnownHermesConversation(map, sessionId, conversationId) {
 }
 async function discoverHermesProfileNames() {
   const names = /* @__PURE__ */ new Set([DEFAULT_PROFILE_NAME]);
-  const profilesDir = path14.join(os4.homedir(), ".hermes", "profiles");
+  const profilesDir = path15.join(os4.homedir(), ".hermes", "profiles");
   const entries = await readdir7(profilesDir, { withFileTypes: true }).catch(
     (error) => {
       if (isNodeError11(error, "ENOENT")) {
@@ -10148,14 +10724,12 @@ function joinImportedText(left, right) {
 ${right}`;
 }
 function projectCompressionTips(rows) {
-  const byId = /* @__PURE__ */ new Map();
   const childrenByParent = /* @__PURE__ */ new Map();
   for (const row of rows) {
     const id = readString9(row, "id");
     if (!id) {
       continue;
     }
-    byId.set(id, row);
     const parentId = readString9(row, "parent_session_id");
     if (parentId) {
       const children = childrenByParent.get(parentId) ?? [];
@@ -10171,13 +10745,14 @@ function projectCompressionTips(rows) {
     }
     let tip = row;
     const visited = /* @__PURE__ */ new Set([id]);
+    const chain = [row];
     while (readString9(tip, "end_reason") === "compression") {
       const tipId2 = readString9(tip, "id");
       if (!tipId2) {
         break;
       }
-      const next = (childrenByParent.get(tipId2) ?? []).filter((child) => readString9(child, "id")).sort(
-        (left, right) => (readNumber2(right.last_active) ?? 0) - (readNumber2(left.last_active) ?? 0)
+      const next = (childrenByParent.get(tipId2) ?? []).filter((child) => isCompressionContinuation(tip, child)).sort(
+        (left, right) => (readNumber2(right.started_at) ?? 0) - (readNumber2(left.started_at) ?? 0) || (readNumber2(right.last_active) ?? 0) - (readNumber2(left.last_active) ?? 0)
       )[0];
       const nextId = next ? readString9(next, "id") : null;
       if (!next || !nextId || visited.has(nextId)) {
@@ -10185,25 +10760,75 @@ function projectCompressionTips(rows) {
       }
       tip = next;
       visited.add(nextId);
+      chain.push(next);
     }
     const tipId = readString9(tip, "id");
     if (tipId) {
+      const sessionIds = chain.map((item) => readString9(item, "id")).filter((item) => Boolean(item));
       projected.push({
         ...tip,
         id: tipId,
         _lineage_root_id: id,
+        _lineage_session_ids: sessionIds,
+        _lineage_title: readString9(row, "title") ?? stripCompressionTitleSuffix2(readString9(tip, "title") ?? ""),
+        _lineage_usage: aggregateHermesSessionUsage(chain),
         started_at: readNumber2(row.started_at) ?? readNumber2(tip.started_at)
       });
     }
   }
   return projected;
 }
+function isCompressionContinuation(parent, child) {
+  const childId = readString9(child, "id");
+  const parentEndedAt = readNumber2(parent.ended_at);
+  const childStartedAt = readNumber2(child.started_at);
+  return Boolean(childId) && readString9(parent, "end_reason") === "compression" && parentEndedAt !== null && childStartedAt !== null && childStartedAt >= parentEndedAt;
+}
+function aggregateHermesSessionUsage(rows) {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let apiCallCount = 0;
+  let model;
+  let provider;
+  for (const row of rows) {
+    inputTokens += readNumber2(row.input_tokens) ?? 0;
+    outputTokens += readNumber2(row.output_tokens) ?? 0;
+    apiCallCount += readNumber2(row.api_call_count) ?? 0;
+    model = readString9(row, "model") ?? model;
+    provider = readString9(row, "billing_provider") ?? readString9(row, "provider") ?? provider;
+  }
+  return {
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    total_tokens: inputTokens + outputTokens,
+    api_call_count: apiCallCount,
+    ...model ? { model } : {},
+    ...provider ? { provider } : {}
+  };
+}
+async function readHermesLineageMessages(candidate) {
+  const rows = [];
+  for (const sessionId of lineageSessionIds(candidate)) {
+    const messages = await readHermesSessionMessages({
+      ...candidate,
+      session: {
+        ...candidate.session,
+        id: sessionId
+      }
+    });
+    rows.push(...messages);
+  }
+  return rows;
+}
 async function readHermesSessionMessages(candidate) {
   const [dbMessages, jsonlMessages] = await Promise.all([
     readStateDbMessages(candidate.dbPath, candidate.session.id),
     readJsonlMessages(candidate.profileName, candidate.session.id)
   ]);
-  return jsonlMessages.length > dbMessages.length ? jsonlMessages : dbMessages;
+  const selected = jsonlMessages.length > dbMessages.length ? jsonlMessages : dbMessages;
+  return selected.map(
+    (message) => readString9(message, "session_id") ? message : { ...message, session_id: candidate.session.id }
+  );
 }
 async function readStateDbMessages(dbPath, sessionId) {
   if (!await isFile(dbPath)) {
@@ -10241,8 +10866,8 @@ async function readJsonlMessages(profileName, sessionId) {
     return [];
   }
   const profileDir = resolveHermesProfileDir(profileName);
-  const sessionsDir = await readHermesSessionsDir(profileName).then((value) => value.sessionsDir).catch(() => path14.join(profileDir, "sessions"));
-  const transcriptPath = path14.join(sessionsDir, `${sessionId}.jsonl`);
+  const sessionsDir = await readHermesSessionsDir(profileName).then((value) => value.sessionsDir).catch(() => path15.join(profileDir, "sessions"));
+  const transcriptPath = path15.join(sessionsDir, `${sessionId}.jsonl`);
   const raw = await readFile9(transcriptPath, "utf8").catch((error) => {
     if (isNodeError11(error, "ENOENT")) {
       return "";
@@ -10394,9 +11019,10 @@ function formatImportedFilenameList(filenames) {
 function toLinkMessage(input) {
   const role = normalizeMessageRole(input.message.role);
   const text = normalizeContent(input.message.content);
+  const sessionId = readString9(input.message, "session_id") ?? input.sessionId;
   const createdAt = isoFromHermesTime(input.message.timestamp) ?? new Date(Date.now() + input.index).toISOString();
   return {
-    id: `msg_${randomUUID6().replaceAll("-", "")}`,
+    id: `msg_${randomUUID7().replaceAll("-", "")}`,
     schema_version: 1,
     conversation_id: input.conversationId,
     role,
@@ -10412,7 +11038,7 @@ function toLinkMessage(input) {
     parts: text ? [{ type: "text", text }] : [],
     attachments: [],
     hermes: {
-      session_id: input.sessionId,
+      session_id: sessionId,
       message_id: input.message.id,
       imported_from: "hermes",
       import_projection: HERMES_IMPORT_PROJECTION_VERSION
@@ -10448,6 +11074,47 @@ function normalizeTitle(value) {
   const normalized = value?.replace(/\s+/gu, " ").trim();
   return normalized || DEFAULT_CONVERSATION_TITLE;
 }
+function canSyncHermesTitle(manifest) {
+  return manifest.title_source !== "manual" && manifest.title_source !== "generated" && manifest.title_source !== "temporary_user_message" && manifest.title_source !== "temporary_fallback";
+}
+function stripCompressionTitleSuffix2(value) {
+  const normalized = value.replace(/\s+/gu, " ").trim();
+  if (!normalized) {
+    return void 0;
+  }
+  const match = /^(.*?) #\d+$/u.exec(normalized);
+  const stripped = match?.[1]?.trim();
+  return stripped || normalized;
+}
+function hasCompressionTitleSuffix(value) {
+  return / #\d+$/u.test(value.trim());
+}
+function normalizeSessionIds(values) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    const sessionId = value?.trim();
+    if (!sessionId || seen.has(sessionId)) {
+      continue;
+    }
+    seen.add(sessionId);
+  }
+  return [...seen];
+}
+function stableJson(value) {
+  return JSON.stringify(stabilizeJsonValue(value));
+}
+function stabilizeJsonValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => stabilizeJsonValue(item));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const record = value;
+  return Object.fromEntries(
+    Object.keys(record).sort().map((key) => [key, stabilizeJsonValue(record[key])])
+  );
+}
 function normalizeMessageRole(value) {
   switch (value?.trim().toLowerCase()) {
     case "user":
@@ -10527,7 +11194,7 @@ async function isFile(filePath) {
   });
 }
 function createConversationId() {
-  return `conv_${randomUUID6().replaceAll("-", "")}`;
+  return `conv_${randomUUID7().replaceAll("-", "")}`;
 }
 function isoFromHermesTime(value) {
   const numeric = readNumber2(value);
@@ -10671,7 +11338,7 @@ async function createHermesRun(input, options = {}) {
   );
   if (response.status === 404 || response.status === 503) {
     assertHermesRunsApiSupported(
-      await readHermesVersion().catch(() => null),
+      await readHermesVersion({ logger: options.logger }).catch(() => null),
       response.status
     );
     throw new LinkHttpError(
@@ -10698,7 +11365,7 @@ async function streamHermesRunEvents(runId, options = {}) {
     options
   );
   assertHermesRunsApiSupported(
-    await readHermesVersion().catch(() => null),
+    await readHermesVersion({ logger: options.logger }).catch(() => null),
     response.status
   );
   if (!response.ok || !response.body) {
@@ -10741,7 +11408,7 @@ async function streamHermesResponses(input, options = {}) {
   );
   if (response.status === 404 || response.status === 503) {
     assertHermesRunsApiSupported(
-      await readHermesVersion().catch(() => null),
+      await readHermesVersion({ logger: options.logger }).catch(() => null),
       response.status
     );
     throw new LinkHttpError(
@@ -10794,10 +11461,10 @@ async function cancelHermesRun(runId, options = {}) {
     );
   }
 }
-async function callHermesApi(path25, init, options) {
+async function callHermesApi(path26, init, options) {
   const method = init.method ?? "GET";
   const startedAt = Date.now();
-  void options.logger?.debug("hermes_api_request_started", { method, path: path25 });
+  void options.logger?.debug("hermes_api_request_started", { method, path: path26 });
   const availability = await ensureHermesApiServerAvailable({
     fetchImpl: options.fetchImpl,
     logger: options.logger,
@@ -10805,21 +11472,21 @@ async function callHermesApi(path25, init, options) {
   });
   let config = availability.configResult.apiServer;
   const fetcher = options.fetchImpl ?? fetch;
-  const request = () => fetchHermesApi(fetcher, config, path25, init, options);
+  const request = () => fetchHermesApi(fetcher, config, path26, init, options);
   let response;
   try {
     response = await request();
   } catch (error) {
-    logHermesApiError(options.logger, method, path25, startedAt, error);
+    logHermesApiError(options.logger, method, path26, startedAt, error);
     throw error;
   }
   if (response.status !== 401) {
-    logHermesApiResponse(options.logger, method, path25, startedAt, response);
+    logHermesApiResponse(options.logger, method, path26, startedAt, response);
     return response;
   }
   void options.logger?.warn("hermes_api_request_retrying_after_401", {
     method,
-    path: path25,
+    path: path26,
     duration_ms: Date.now() - startedAt
   });
   const refreshedAvailability = await ensureHermesApiServerAvailable({
@@ -10832,20 +11499,20 @@ async function callHermesApi(path25, init, options) {
   try {
     response = await request();
   } catch (error) {
-    logHermesApiError(options.logger, method, path25, startedAt, error);
+    logHermesApiError(options.logger, method, path26, startedAt, error);
     throw error;
   }
-  logHermesApiResponse(options.logger, method, path25, startedAt, response);
+  logHermesApiResponse(options.logger, method, path26, startedAt, response);
   return response;
 }
-async function fetchHermesApi(fetcher, config, path25, init, options) {
+async function fetchHermesApi(fetcher, config, path26, init, options) {
   const headers = new Headers(init.headers);
   headers.set("accept", headers.get("accept") ?? "application/json");
   if (config.key) {
     headers.set("x-api-key", config.key);
     headers.set("authorization", `Bearer ${config.key}`);
   }
-  return await fetcher(`http://127.0.0.1:${config.port}${path25}`, {
+  return await fetcher(`http://127.0.0.1:${config.port}${path26}`, {
     ...init,
     headers
   }).catch((error) => {
@@ -10853,7 +11520,7 @@ async function fetchHermesApi(fetcher, config, path25, init, options) {
       throw error;
     }
     void options.logger?.warn("hermes_api_server_connect_failed", {
-      path: path25,
+      path: path26,
       port: config.port ?? null,
       error: error instanceof Error ? error.message : String(error)
     });
@@ -10864,10 +11531,10 @@ async function fetchHermesApi(fetcher, config, path25, init, options) {
     );
   });
 }
-function logHermesApiResponse(logger, method, path25, startedAt, response) {
+function logHermesApiResponse(logger, method, path26, startedAt, response) {
   const fields = {
     method,
-    path: path25,
+    path: path26,
     status: response.status,
     duration_ms: Date.now() - startedAt
   };
@@ -10887,10 +11554,10 @@ async function logHermesApiFailureResponse(logger, fields, response) {
     ...upstreamError ? { upstream_error: upstreamError } : {}
   });
 }
-function logHermesApiError(logger, method, path25, startedAt, error) {
+function logHermesApiError(logger, method, path26, startedAt, error) {
   void logger?.warn("hermes_api_request_failed", {
     method,
-    path: path25,
+    path: path26,
     duration_ms: Date.now() - startedAt,
     ...error instanceof LinkHttpError ? { status: error.status, code: error.code } : {},
     error: error instanceof Error ? error.message : String(error)
@@ -10953,7 +11620,7 @@ function readString10(payload, key) {
 
 // src/conversations/history-builder.ts
 import { readFile as readFile10, stat as stat10 } from "fs/promises";
-import path15 from "path";
+import path16 from "path";
 var HISTORY_ROLES = /* @__PURE__ */ new Set(["user", "assistant"]);
 var HERMES_HISTORY_COLUMNS = [
   "role",
@@ -11014,13 +11681,13 @@ async function readHermesTranscriptHistory(sessionId, profileName) {
   }
   const normalizedProfileName = isValidProfileName2(profileName) ? profileName : "default";
   const profileDir = resolveHermesProfileDir(normalizedProfileName);
-  const dbPath = path15.join(profileDir, "state.db");
+  const dbPath = path16.join(profileDir, "state.db");
   const sessionsDirConfig = await readHermesSessionsDir(normalizedProfileName).then((value) => ({
     sessionsDir: value.sessionsDir,
     configured: value.configured,
     configError: false
   })).catch(() => ({
-    sessionsDir: path15.join(profileDir, "sessions"),
+    sessionsDir: path16.join(profileDir, "sessions"),
     configured: false,
     configError: true
   }));
@@ -11078,7 +11745,7 @@ async function readHermesJsonlHistory(sessionsDir, sessionId) {
   if (!isValidSessionFileStem(sessionId)) {
     return empty;
   }
-  const transcriptPath = path15.join(sessionsDir, `${sessionId}.jsonl`);
+  const transcriptPath = path16.join(sessionsDir, `${sessionId}.jsonl`);
   const raw = await readFile10(transcriptPath, "utf8").catch((error) => {
     if (isNodeError12(error, "ENOENT")) {
       return "";
@@ -11321,7 +11988,7 @@ function normalizeProfileForCompare(value) {
 // src/hermes/stt.ts
 import { execFile as execFile3 } from "child_process";
 import { access as access2, readFile as readFile11, stat as stat11 } from "fs/promises";
-import path16 from "path";
+import path17 from "path";
 import { promisify as promisify3 } from "util";
 var execFileAsync3 = promisify3(execFile3);
 var STT_RESULT_PREFIX = "__HERMES_LINK_STT__";
@@ -11416,7 +12083,7 @@ async function buildHermesSttEnv(profileName) {
   };
   const devSource = await findDevHermesAgentSource();
   if (devSource) {
-    env.PYTHONPATH = [devSource, env.PYTHONPATH].filter(Boolean).join(path16.delimiter);
+    env.PYTHONPATH = [devSource, env.PYTHONPATH].filter(Boolean).join(path17.delimiter);
   }
   return env;
 }
@@ -11463,14 +12130,14 @@ async function resolveHermesPythonCommand() {
   };
 }
 async function resolveExecutablePath(command) {
-  if (path16.isAbsolute(command)) {
+  if (path17.isAbsolute(command)) {
     return await isExecutableFile(command) ? command : null;
   }
   const pathEnv = process.env.PATH ?? "";
   const extensions = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
-  for (const dir of pathEnv.split(path16.delimiter)) {
+  for (const dir of pathEnv.split(path17.delimiter)) {
     for (const extension of extensions) {
-      const candidate = path16.join(dir, `${command}${extension}`);
+      const candidate = path17.join(dir, `${command}${extension}`);
       if (await isExecutableFile(candidate)) {
         return candidate;
       }
@@ -11510,8 +12177,8 @@ function shebangToPythonCommand(shebang) {
 }
 async function findDevHermesAgentSource() {
   const candidates = [
-    path16.resolve(process.cwd(), "reference/hermes-agent"),
-    path16.resolve(process.cwd(), "../../reference/hermes-agent")
+    path17.resolve(process.cwd(), "reference/hermes-agent"),
+    path17.resolve(process.cwd(), "../../reference/hermes-agent")
   ];
   for (const candidate of candidates) {
     if (await isDirectory(candidate)) {
@@ -13152,7 +13819,7 @@ var ConversationService = class {
   async createConversation(input = {}) {
     await this.store.ensureConversationsDir();
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    const id = `conv_${randomUUID7().replaceAll("-", "")}`;
+    const id = `conv_${randomUUID8().replaceAll("-", "")}`;
     const title = input.title?.trim() || DEFAULT_CONVERSATION_TITLE;
     const profile = await resolveConversationProfileTarget(
       this.paths,
@@ -13239,7 +13906,7 @@ var ConversationService = class {
         manifest.profile_name_snapshot ?? manifest.profile ?? input.profileName
       );
       const message = {
-        id: `msg_${randomUUID7().replaceAll("-", "")}`,
+        id: `msg_${randomUUID8().replaceAll("-", "")}`,
         schema_version: 1,
         conversation_id: manifest.id,
         role: "assistant",
@@ -13703,6 +14370,18 @@ var ConversationService = class {
   async deleteConversation(conversationId) {
     return this.maintenance.deleteConversation(conversationId);
   }
+  prepareClearAllConversationPlan() {
+    return this.maintenance.prepareClearAllConversationPlan();
+  }
+  readClearAllConversationPlan(planId) {
+    return this.maintenance.readClearAllConversationPlan(planId);
+  }
+  executeClearAllConversationPlan(planId) {
+    return this.maintenance.executeClearAllConversationPlan(planId);
+  }
+  startClearAllConversationPlan(planId) {
+    return this.maintenance.startClearAllConversationPlan(planId);
+  }
   async deleteConversations(conversationIds) {
     return this.maintenance.deleteConversations(conversationIds);
   }
@@ -13831,8 +14510,8 @@ function findApproval(snapshot, approvalId) {
 }
 
 // src/identity/identity.ts
-import { generateKeyPairSync, randomUUID as randomUUID8, sign } from "crypto";
-import { mkdir as mkdir8, chmod as chmod2 } from "fs/promises";
+import { generateKeyPairSync, randomUUID as randomUUID9, sign } from "crypto";
+import { mkdir as mkdir9, chmod as chmod2 } from "fs/promises";
 import { z } from "zod";
 var linkIdentitySchema = z.object({
   install_id: z.string().min(1),
@@ -13854,12 +14533,12 @@ async function ensureIdentity(paths = resolveRuntimePaths()) {
   if (existing) {
     return existing;
   }
-  await mkdir8(paths.homeDir, { recursive: true, mode: 448 });
+  await mkdir9(paths.homeDir, { recursive: true, mode: 448 });
   await chmod2(paths.homeDir, 448).catch(() => void 0);
   const { publicKey, privateKey } = generateKeyPairSync("ed25519");
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const identity = {
-    install_id: `install_${randomUUID8().replaceAll("-", "")}`,
+    install_id: `install_${randomUUID9().replaceAll("-", "")}`,
     link_id: null,
     public_key_pem: publicKey.export({ type: "spki", format: "pem" }).toString(),
     private_key_pem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
@@ -13896,7 +14575,7 @@ function getIdentityStatus(identity) {
 }
 
 // src/security/devices.ts
-import { randomBytes as randomBytes2, randomUUID as randomUUID9, timingSafeEqual, createHash as createHash4 } from "crypto";
+import { randomBytes as randomBytes2, randomUUID as randomUUID10, timingSafeEqual, createHash as createHash4 } from "crypto";
 var ACCESS_TOKEN_TTL_MS = 15 * 60 * 1e3;
 var REFRESH_TOKEN_TTL_MS = 90 * 24 * 60 * 60 * 1e3;
 var DEVICE_SEEN_WRITE_INTERVAL_MS = 60 * 60 * 1e3;
@@ -13914,7 +14593,7 @@ async function createDeviceSession(input, paths = resolveRuntimePaths()) {
     }
   }
   const device = {
-    id: `dev_${randomUUID9().replaceAll("-", "")}`,
+    id: `dev_${randomUUID10().replaceAll("-", "")}`,
     label: normalizeDeviceLabel(input.label),
     platform: normalizeDevicePlatform(input.platform),
     model: normalizeDeviceModel(input.model),
@@ -14828,6 +15507,37 @@ function registerConversationRoutes(router, options) {
     await authenticateRequest(ctx, paths);
     ctx.body = { ok: true };
   });
+  router.post("/api/v1/conversations/clear-plans", async (ctx) => {
+    await authenticateRequest(ctx, paths);
+    const plan = await conversations.prepareClearAllConversationPlan();
+    ctx.status = 201;
+    ctx.body = {
+      ok: true,
+      plan
+    };
+  });
+  router.get("/api/v1/conversations/clear-plans/:planId", async (ctx) => {
+    await authenticateRequest(ctx, paths);
+    ctx.set("cache-control", "no-store");
+    ctx.body = {
+      ok: true,
+      plan: await conversations.readClearAllConversationPlan(ctx.params.planId)
+    };
+  });
+  router.post(
+    "/api/v1/conversations/clear-plans/:planId/execute",
+    async (ctx) => {
+      await authenticateRequest(ctx, paths);
+      const plan = await conversations.startClearAllConversationPlan(
+        ctx.params.planId
+      );
+      ctx.status = plan.status === "completed" ? 200 : 202;
+      ctx.body = {
+        ok: true,
+        plan
+      };
+    }
+  );
   router.delete("/api/v1/conversations", async (ctx) => {
     await authenticateRequest(ctx, paths);
     const body = await readJsonBody(ctx.req);
@@ -15051,14 +15761,14 @@ function createHttpErrorMiddleware(logger) {
 // src/hermes/profiles.ts
 import { readdir as readdir9, readFile as readFile12, rename as rename3, rm as rm6, stat as stat12 } from "fs/promises";
 import os5 from "os";
-import path17 from "path";
+import path18 from "path";
 import YAML2 from "yaml";
 var DEFAULT_PROFILE = "default";
 var PROFILE_NAME_PATTERN4 = /^[a-zA-Z0-9._-]{1,64}$/;
 async function listHermesProfiles(paths = resolveRuntimePaths()) {
   const profiles = /* @__PURE__ */ new Map();
   profiles.set(DEFAULT_PROFILE, await profileInfo(DEFAULT_PROFILE, paths));
-  const profilesDir = path17.join(os5.homedir(), ".hermes", "profiles");
+  const profilesDir = path18.join(os5.homedir(), ".hermes", "profiles");
   const entries = await readdir9(profilesDir, { withFileTypes: true }).catch(
     (error) => {
       if (isNodeError14(error, "ENOENT")) {
@@ -15153,7 +15863,7 @@ async function readHermesProfileCapabilities(name) {
   return {
     defaultModel: listedModels?.defaultModel ?? null,
     modelCount: listedModels?.models.length ?? 0,
-    skillCount: await countSkills(path17.join(profileDir, "skills")).catch(
+    skillCount: await countSkills(path18.join(profileDir, "skills")).catch(
       () => 0
     ),
     toolCount: await countConfiguredTools(name).catch(() => 0)
@@ -15209,7 +15919,7 @@ async function countSkills(root) {
   );
   let count = 0;
   for (const entry of entries) {
-    const entryPath = path17.join(root, entry.name);
+    const entryPath = path18.join(root, entry.name);
     if (entry.name === ".git" || entry.name === ".hub") {
       continue;
     }
@@ -15906,12 +16616,12 @@ import { spawn as spawn2 } from "child_process";
 import { EventEmitter as EventEmitter2 } from "events";
 import {
   cp,
-  mkdir as mkdir9,
+  mkdir as mkdir10,
   readFile as readFile13,
   rm as rm7,
   stat as stat13
 } from "fs/promises";
-import path18 from "path";
+import path19 from "path";
 import YAML3 from "yaml";
 var PROFILE_CREATE_LOG_FILE = "profile-create.log";
 var PROFILE_CREATE_LOG_MAX_FILES = 3;
@@ -15959,7 +16669,7 @@ async function startHermesProfileCreation(input, options) {
     signal: null,
     error: null
   };
-  await mkdir9(options.paths.runDir, { recursive: true, mode: 448 });
+  await mkdir10(options.paths.runDir, { recursive: true, mode: 448 });
   await writeProfileCreationState(options.paths, started);
   await writer.write(`
 === profile creation started ${startedAt} ===
@@ -16362,7 +17072,7 @@ function collectEnvKeys(value, keys = /* @__PURE__ */ new Set()) {
   return keys;
 }
 async function writeEnvValues(profileName, values) {
-  const envPath = path18.join(resolveHermesProfileDir(profileName), ".env");
+  const envPath = path19.join(resolveHermesProfileDir(profileName), ".env");
   const existingRaw = await readFile13(envPath, "utf8").catch((error) => {
     if (isNodeError15(error, "ENOENT")) {
       return "";
@@ -16399,8 +17109,8 @@ async function writeEnvValues(profileName, values) {
   await atomicWriteFilePreservingMetadata(envPath, nextRaw);
 }
 async function copySkills(sourceProfile, targetProfile) {
-  const sourceSkills = path18.join(resolveHermesProfileDir(sourceProfile), "skills");
-  const targetSkills = path18.join(resolveHermesProfileDir(targetProfile), "skills");
+  const sourceSkills = path19.join(resolveHermesProfileDir(sourceProfile), "skills");
+  const targetSkills = path19.join(resolveHermesProfileDir(targetProfile), "skills");
   if (!await pathExists(sourceSkills)) {
     return;
   }
@@ -16495,10 +17205,10 @@ async function readProfileCreationLogLines(paths) {
   );
 }
 function profileCreationStatePath(paths) {
-  return path18.join(paths.runDir, "profile-create-state.json");
+  return path19.join(paths.runDir, "profile-create-state.json");
 }
 function profileCreationLogPath(paths) {
-  return path18.join(paths.logsDir, PROFILE_CREATE_LOG_FILE);
+  return path19.join(paths.logsDir, PROFILE_CREATE_LOG_FILE);
 }
 async function clearProfileCreationLogFiles(paths) {
   const primary = profileCreationLogPath(paths);
@@ -16772,7 +17482,7 @@ import {
   readFile as readFile14,
   stat as stat14
 } from "fs/promises";
-import path19 from "path";
+import path20 from "path";
 import YAML4 from "yaml";
 var ENTRY_DELIMITER = "\n\xA7\n";
 var DEFAULT_MEMORY_LIMIT = 2200;
@@ -16989,7 +17699,7 @@ async function saveProviderSettings(profileName, provider, patch) {
   if (provider === "hindsight") {
     await patchJsonProviderConfig(
       profileName,
-      path19.join("hindsight", "config.json"),
+      path20.join("hindsight", "config.json"),
       {
         mode: patch.mode,
         api_url: patch.apiUrl,
@@ -17156,7 +17866,7 @@ async function patchHermesMemoryProvider(profileName, provider) {
   await atomicWriteFilePreservingMetadata(configPath, document.toString());
 }
 function resolveMemoryDir(profileName) {
-  return path19.join(resolveHermesProfileDir(profileName), "memories");
+  return path20.join(resolveHermesProfileDir(profileName), "memories");
 }
 async function readMemoryStore(profileName, target, limits) {
   const filePath = memoryFilePath(profileName, target);
@@ -17217,7 +17927,7 @@ async function writeMemoryEntries(profileName, target, entries) {
   );
 }
 function memoryFilePath(profileName, target) {
-  return path19.join(
+  return path20.join(
     resolveMemoryDir(profileName),
     target === "user" ? "USER.md" : "MEMORY.md"
   );
@@ -17277,7 +17987,7 @@ async function readCustomProviderSetupSummary(profileName) {
     configurable: true,
     configured: true,
     configurationIssue: null,
-    providerConfigPath: path19.join(
+    providerConfigPath: path20.join(
       resolveHermesProfileDir(profileName),
       "<provider>.json"
     ),
@@ -17631,7 +18341,7 @@ async function readProviderSettings(profileName, provider) {
       stringSetting(
         "dbPath",
         "SQLite \u6570\u636E\u5E93\u8DEF\u5F84",
-        config.db_path ?? path19.join(resolveHermesProfileDir(profileName), "memory_store.db")
+        config.db_path ?? path20.join(resolveHermesProfileDir(profileName), "memory_store.db")
       ),
       booleanSetting("autoExtract", "\u4F1A\u8BDD\u7ED3\u675F\u81EA\u52A8\u62BD\u53D6", config.auto_extract ?? false),
       numberSetting("defaultTrust", "\u9ED8\u8BA4\u4FE1\u4EFB\u5206", config.default_trust ?? 0.5),
@@ -17654,7 +18364,7 @@ async function readProviderSettings(profileName, provider) {
       stringSetting(
         "workingDirectory",
         "\u5DE5\u4F5C\u76EE\u5F55",
-        path19.join(resolveHermesProfileDir(profileName), "byterover"),
+        path20.join(resolveHermesProfileDir(profileName), "byterover"),
         false
       )
     ];
@@ -17663,16 +18373,16 @@ async function readProviderSettings(profileName, provider) {
 }
 function memoryProviderConfigPath(profileName, provider) {
   if (provider === "honcho") {
-    return path19.join(resolveHermesProfileDir(profileName), "honcho.json");
+    return path20.join(resolveHermesProfileDir(profileName), "honcho.json");
   }
   if (provider === "mem0") {
-    return path19.join(resolveHermesProfileDir(profileName), "mem0.json");
+    return path20.join(resolveHermesProfileDir(profileName), "mem0.json");
   }
   if (provider === "supermemory") {
-    return path19.join(resolveHermesProfileDir(profileName), "supermemory.json");
+    return path20.join(resolveHermesProfileDir(profileName), "supermemory.json");
   }
   if (provider === "hindsight") {
-    return path19.join(
+    return path20.join(
       resolveHermesProfileDir(profileName),
       "hindsight",
       "config.json"
@@ -17681,13 +18391,13 @@ function memoryProviderConfigPath(profileName, provider) {
   return null;
 }
 function customProviderConfigPath(profileName, provider) {
-  return path19.join(
+  return path20.join(
     resolveHermesProfileDir(profileName),
     `${normalizeCustomProviderId(provider)}.json`
   );
 }
 function customProviderRegistryPath(profileName) {
-  return path19.join(
+  return path20.join(
     resolveHermesProfileDir(profileName),
     CUSTOM_PROVIDER_REGISTRY_FILE
   );
@@ -17739,7 +18449,7 @@ async function saveCustomProviderRegistryEntry(profileName, provider) {
   );
 }
 async function discoverUserMemoryProviderDescriptors(profileName) {
-  const pluginsDir = path19.join(resolveHermesProfileDir(profileName), "plugins");
+  const pluginsDir = path20.join(resolveHermesProfileDir(profileName), "plugins");
   const entries = await readdir10(pluginsDir, { withFileTypes: true }).catch(
     (error) => {
       if (isNodeError16(error, "ENOENT")) {
@@ -17759,7 +18469,7 @@ async function discoverUserMemoryProviderDescriptors(profileName) {
     } catch {
       continue;
     }
-    const providerDir = path19.join(pluginsDir, entry.name);
+    const providerDir = path20.join(pluginsDir, entry.name);
     if (!await isMemoryProviderPluginDir(providerDir)) {
       continue;
     }
@@ -17773,7 +18483,7 @@ async function discoverUserMemoryProviderDescriptors(profileName) {
   return descriptors;
 }
 async function isUserMemoryProviderInstalled(profileName, provider) {
-  const providerDir = path19.join(
+  const providerDir = path20.join(
     resolveHermesProfileDir(profileName),
     "plugins",
     normalizeCustomProviderId(provider)
@@ -17781,7 +18491,7 @@ async function isUserMemoryProviderInstalled(profileName, provider) {
   return isMemoryProviderPluginDir(providerDir);
 }
 async function isMemoryProviderPluginDir(providerDir) {
-  const source = await readFile14(path19.join(providerDir, "__init__.py"), "utf8").catch(
+  const source = await readFile14(path20.join(providerDir, "__init__.py"), "utf8").catch(
     (error) => {
       if (isNodeError16(error, "ENOENT")) {
         return "";
@@ -17793,7 +18503,7 @@ async function isMemoryProviderPluginDir(providerDir) {
   return sample.includes("register_memory_provider") || sample.includes("MemoryProvider");
 }
 async function readPluginMetadata(providerDir) {
-  const raw = await readFile14(path19.join(providerDir, "plugin.yaml"), "utf8").catch(
+  const raw = await readFile14(path20.join(providerDir, "plugin.yaml"), "utf8").catch(
     (error) => {
       if (isNodeError16(error, "ENOENT")) {
         return "";
@@ -17805,10 +18515,10 @@ async function readPluginMetadata(providerDir) {
 }
 async function resolveByteRoverCli() {
   const candidates = [
-    ...(process.env.PATH ?? "").split(path19.delimiter).filter(Boolean).map((dir) => path19.join(dir, "brv")),
-    path19.join(process.env.HOME ?? "", ".brv-cli", "bin", "brv"),
+    ...(process.env.PATH ?? "").split(path20.delimiter).filter(Boolean).map((dir) => path20.join(dir, "brv")),
+    path20.join(process.env.HOME ?? "", ".brv-cli", "bin", "brv"),
     "/usr/local/bin/brv",
-    path19.join(process.env.HOME ?? "", ".npm-global", "bin", "brv")
+    path20.join(process.env.HOME ?? "", ".npm-global", "bin", "brv")
   ].filter(Boolean);
   for (const candidate of candidates) {
     const found = await access3(candidate).then(() => true).catch(() => false);
@@ -17869,7 +18579,7 @@ async function patchHermesMemoryEnv(profileName, patch) {
   if (entries.length === 0) {
     return;
   }
-  const envPath = path19.join(resolveHermesProfileDir(profileName), ".env");
+  const envPath = path20.join(resolveHermesProfileDir(profileName), ".env");
   const existingRaw = await readFile14(envPath, "utf8").catch((error) => {
     if (isNodeError16(error, "ENOENT")) {
       return "";
@@ -17943,7 +18653,7 @@ async function readActiveMemoryProvider(profileName) {
   return provider;
 }
 async function patchJsonProviderConfig(profileName, relativePath, patch) {
-  const configPath = path19.join(
+  const configPath = path20.join(
     resolveHermesProfileDir(profileName),
     relativePath
   );
@@ -17972,7 +18682,7 @@ async function readJsonObject(filePath) {
   } catch {
     throw new HermesMemoryError(
       "memory_provider_config_invalid",
-      `${path19.basename(filePath)} \u4E0D\u662F\u6709\u6548\u7684 JSON \u914D\u7F6E\u6587\u4EF6\u3002`
+      `${path20.basename(filePath)} \u4E0D\u662F\u6709\u6548\u7684 JSON \u914D\u7F6E\u6587\u4EF6\u3002`
     );
   }
 }
@@ -18518,7 +19228,7 @@ function toMemoryHttpError(error) {
 
 // src/hermes/skills.ts
 import { readFile as readFile15, readdir as readdir11 } from "fs/promises";
-import path20 from "path";
+import path21 from "path";
 import YAML5 from "yaml";
 var HermesSkillNotFoundError = class extends Error {
   constructor(skillName) {
@@ -18532,7 +19242,7 @@ var EXCLUDED_SKILL_DIRS = /* @__PURE__ */ new Set([".git", ".github", ".hub"]);
 async function listHermesProfileSkills(profileName, paths = resolveRuntimePaths()) {
   const profile = await readExistingProfile(profileName, paths);
   const profileDir = resolveHermesProfileDir(profile.name);
-  const skillsRoot = path20.join(profileDir, "skills");
+  const skillsRoot = path21.join(profileDir, "skills");
   const [skillFiles, disabled, provenance] = await Promise.all([
     findSkillFiles(skillsRoot),
     readDisabledSkillNames(resolveHermesConfigPath(profile.name)),
@@ -18623,7 +19333,7 @@ async function collectSkillFiles(directory, results) {
     if (EXCLUDED_SKILL_DIRS.has(entry.name)) {
       continue;
     }
-    const entryPath = path20.join(directory, entry.name);
+    const entryPath = path21.join(directory, entry.name);
     if (entry.isDirectory()) {
       await collectSkillFiles(entryPath, results);
       continue;
@@ -18645,10 +19355,10 @@ async function readSkillMetadata(input) {
   if (raw === null) {
     return null;
   }
-  const skillDir = path20.dirname(input.skillFile);
+  const skillDir = path21.dirname(input.skillFile);
   const { frontmatter, body } = parseSkillDocument(raw.slice(0, 4e3));
   const name = normalizeSkillName(
-    readString16(frontmatter.name) ?? path20.basename(skillDir)
+    readString16(frontmatter.name) ?? path21.basename(skillDir)
   );
   if (!name) {
     return null;
@@ -18667,7 +19377,7 @@ async function readSkillMetadata(input) {
     enabled: !input.disabled.has(name),
     source: provenance.source,
     trust: provenance.trust,
-    relativePath: path20.relative(input.skillsRoot, skillDir)
+    relativePath: path21.relative(input.skillsRoot, skillDir)
   };
 }
 function parseSkillDocument(raw) {
@@ -18688,8 +19398,8 @@ function parseSkillDocument(raw) {
   }
 }
 function categoryFromPath(skillsRoot, skillFile) {
-  const relative = path20.relative(skillsRoot, skillFile);
-  const parts = relative.split(path20.sep).filter(Boolean);
+  const relative = path21.relative(skillsRoot, skillFile);
+  const parts = relative.split(path21.sep).filter(Boolean);
   return parts.length >= 3 ? parts[0] : null;
 }
 function firstBodyDescription(body) {
@@ -18736,7 +19446,7 @@ async function readSkillProvenance(root) {
   return provenance;
 }
 async function readBundledSkillNames(root) {
-  const raw = await readFile15(path20.join(root, ".bundled_manifest"), "utf8").catch(
+  const raw = await readFile15(path21.join(root, ".bundled_manifest"), "utf8").catch(
     (error) => {
       if (isNodeError17(error, "ENOENT")) {
         return "";
@@ -18759,7 +19469,7 @@ async function readBundledSkillNames(root) {
   return names;
 }
 async function readHubInstalledSkills(root) {
-  const raw = await readFile15(path20.join(root, ".hub", "lock.json"), "utf8").catch(
+  const raw = await readFile15(path21.join(root, ".hub", "lock.json"), "utf8").catch(
     (error) => {
       if (isNodeError17(error, "ENOENT")) {
         return "";
@@ -19362,8 +20072,8 @@ function readModelList(payload) {
 // src/hermes/updates.ts
 import { EventEmitter as EventEmitter3 } from "events";
 import { spawn as spawn3 } from "child_process";
-import { mkdir as mkdir10, readFile as readFile16, rm as rm8 } from "fs/promises";
-import path21 from "path";
+import { mkdir as mkdir11, readFile as readFile16, rm as rm8 } from "fs/promises";
+import path22 from "path";
 var SERVER_HERMES_RELEASES_LATEST_PATH = "/api/v1/hermes-agent/releases/latest";
 var RELEASE_CACHE_TTL_MS = 6 * 60 * 60 * 1e3;
 var RELEASE_FETCH_TIMEOUT_MS = 5e3;
@@ -19376,7 +20086,10 @@ var runningUpdate = null;
 async function readHermesUpdateCheck(options) {
   const now = options.now ?? (() => /* @__PURE__ */ new Date());
   const [local, remoteResult] = await Promise.all([
-    readHermesVersion().catch((error) => ({
+    readHermesVersion({
+      fetchImpl: options.fetchImpl,
+      logger: options.logger
+    }).catch((error) => ({
       raw: error instanceof Error ? error.message : String(error),
       version: null
     })),
@@ -19423,7 +20136,7 @@ async function startHermesUpdate(options) {
     signal: null,
     error: null
   };
-  await mkdir10(options.paths.runDir, { recursive: true, mode: 448 });
+  await mkdir11(options.paths.runDir, { recursive: true, mode: 448 });
   await writer.write(`
 === hermes update started ${startedAt} ===
 `);
@@ -19629,13 +20342,13 @@ async function readUpdateLogLines(paths) {
   );
 }
 function releaseCachePath(paths) {
-  return path21.join(paths.indexesDir, "hermes-release-check.json");
+  return path22.join(paths.indexesDir, "hermes-release-check.json");
 }
 function updateStatePath(paths) {
-  return path21.join(paths.runDir, "hermes-update-state.json");
+  return path22.join(paths.runDir, "hermes-update-state.json");
 }
 function updateLogPath(paths) {
-  return path21.join(paths.logsDir, UPDATE_LOG_FILE);
+  return path22.join(paths.logsDir, UPDATE_LOG_FILE);
 }
 async function clearUpdateLogFiles(paths) {
   const primary = updateLogPath(paths);
@@ -19727,17 +20440,17 @@ function readString17(payload, key) {
 // src/link/updates.ts
 import { spawn as spawn5 } from "child_process";
 import { EventEmitter as EventEmitter4 } from "events";
-import { mkdir as mkdir13, readFile as readFile18, rm as rm11 } from "fs/promises";
-import path23 from "path";
+import { mkdir as mkdir14, readFile as readFile18, rm as rm11 } from "fs/promises";
+import path24 from "path";
 
 // src/daemon/process.ts
 import { spawn as spawn4 } from "child_process";
-import { mkdir as mkdir12, readFile as readFile17, rm as rm10 } from "fs/promises";
-import path22 from "path";
+import { mkdir as mkdir13, readFile as readFile17, rm as rm10 } from "fs/promises";
+import path23 from "path";
 
 // src/daemon/service.ts
 import { createServer } from "http";
-import { mkdir as mkdir11, rm as rm9, writeFile as writeFile3 } from "fs/promises";
+import { mkdir as mkdir12, rm as rm9, writeFile as writeFile3 } from "fs/promises";
 
 // src/relay/control-client.ts
 import WebSocket from "ws";
@@ -20616,6 +21329,7 @@ function startHermesSessionSyncScheduler(options) {
 }
 
 // src/daemon/service.ts
+var DEFAULT_RELAY_READY_TIMEOUT_MS = 2e3;
 async function startLinkService(options = {}) {
   const paths = options.paths ?? resolveRuntimePaths();
   const logger = createFileLogger({ paths });
@@ -20681,6 +21395,10 @@ async function startLinkService(options = {}) {
   });
   let relay = null;
   if (identity?.link_id) {
+    let resolveRelayReady = null;
+    const relayReady = new Promise((resolve) => {
+      resolveRelayReady = resolve;
+    });
     relay = connectRelayControl({
       relayBaseUrl: config.relayBaseUrl,
       linkId: identity.link_id,
@@ -20690,8 +21408,22 @@ async function startLinkService(options = {}) {
       backoffMaxMs: 3e4,
       onStatus: (status) => {
         void logger.info("relay_status", status);
+        if (status.state === "connected") {
+          resolveRelayReady?.(true);
+          resolveRelayReady = null;
+        } else if (status.state === "failed") {
+          resolveRelayReady?.(false);
+          resolveRelayReady = null;
+        }
       }
     });
+    if (options.waitForRelayReady) {
+      await Promise.race([
+        relayReady,
+        waitForRelayReadyTimeout(options.relayReadyTimeoutMs)
+      ]);
+      resolveRelayReady = null;
+    }
   } else {
     void logger.info("relay_skipped", { reason: "link_not_paired" });
   }
@@ -20726,11 +21458,20 @@ async function startLinkService(options = {}) {
     }
   };
 }
+function waitForRelayReadyTimeout(timeoutMs) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(
+      () => resolve(false),
+      timeoutMs ?? DEFAULT_RELAY_READY_TIMEOUT_MS
+    );
+    timer.unref?.();
+  });
+}
 function pidFilePath(paths = resolveRuntimePaths()) {
   return `${paths.runDir}/hermeslink.pid`;
 }
 async function writePidFile(paths) {
-  await mkdir11(paths.runDir, { recursive: true, mode: 448 });
+  await mkdir12(paths.runDir, { recursive: true, mode: 448 });
   await writeFile3(pidFilePath(paths), `${process.pid}
 `, { mode: 384 });
 }
@@ -20805,8 +21546,8 @@ async function startDaemonProcess(paths = resolveRuntimePaths()) {
       return status;
     }
   }
-  await mkdir12(paths.logsDir, { recursive: true, mode: 448 });
-  await mkdir12(paths.runDir, { recursive: true, mode: 448 });
+  await mkdir13(paths.logsDir, { recursive: true, mode: 448 });
+  await mkdir13(paths.runDir, { recursive: true, mode: 448 });
   const scriptPath = currentCliScriptPath();
   const child = spawn4(process.execPath, [scriptPath, "daemon-supervisor"], {
     detached: true,
@@ -20824,10 +21565,10 @@ async function startDaemonProcess(paths = resolveRuntimePaths()) {
   return await getDaemonStatus(paths);
 }
 async function runDaemonSupervisor(paths = resolveRuntimePaths()) {
-  await mkdir12(paths.logsDir, { recursive: true, mode: 448 });
+  await mkdir13(paths.logsDir, { recursive: true, mode: 448 });
   const log = createRotatingTextLogWriter({
     paths,
-    fileName: path22.basename(daemonLogFile(paths))
+    fileName: path23.basename(daemonLogFile(paths))
   });
   const scriptPath = currentCliScriptPath();
   const child = spawn4(process.execPath, [scriptPath, "daemon", "--foreground"], {
@@ -21068,7 +21809,7 @@ async function startLinkUpdate(options) {
     error: null,
     manual_command: manualCommand
   };
-  await mkdir13(options.paths.runDir, { recursive: true, mode: 448 });
+  await mkdir14(options.paths.runDir, { recursive: true, mode: 448 });
   await writer.write(
     `
 === link update started ${startedAt} target=${targetVersion} ===
@@ -21366,10 +22107,10 @@ async function readUpdateLogLines2(paths) {
   );
 }
 function updateStatePath2(paths) {
-  return path23.join(paths.runDir, "link-update-state.json");
+  return path24.join(paths.runDir, "link-update-state.json");
 }
 function updateLogPath2(paths) {
-  return path23.join(paths.logsDir, UPDATE_LOG_FILE2);
+  return path24.join(paths.logsDir, UPDATE_LOG_FILE2);
 }
 async function clearUpdateLogFiles2(paths) {
   const primary = updateLogPath2(paths);
@@ -21433,10 +22174,21 @@ function readString18(payload, key) {
 }
 
 // src/pairing/pairing.ts
-import path24 from "path";
+import path25 from "path";
 import { rm as rm12 } from "fs/promises";
 
 // src/relay/bootstrap.ts
+var RelayNetworkError = class extends Error {
+  constructor(relayBaseUrl, causeMessage) {
+    super(
+      `Cannot reach Hermes Relay at ${relayBaseUrl}. Please check your network connection, VPN, or proxy settings, then try again.`
+    );
+    this.relayBaseUrl = relayBaseUrl;
+    this.causeMessage = causeMessage;
+  }
+  relayBaseUrl;
+  causeMessage;
+};
 async function bootstrapRelayLink(options) {
   const fetcher = options.fetchImpl ?? fetch;
   const baseUrl = options.relayBaseUrl.replace(/\/+$/u, "");
@@ -21477,14 +22229,23 @@ async function bootstrapRelayLink(options) {
   };
 }
 async function postJson(fetcher, url, token, body) {
-  const response = await fetcher(url, {
-    method: "POST",
-    headers: {
-      authorization: `Bearer ${token}`,
-      "content-type": "application/json"
-    },
-    body: JSON.stringify(body)
-  });
+  let response;
+  try {
+    response = await fetcher(url, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+  } catch (error) {
+    const baseUrl = new URL(url).origin;
+    throw new RelayNetworkError(
+      baseUrl,
+      error instanceof Error ? error.message : String(error)
+    );
+  }
   const payload = await response.json().catch(() => null);
   if (!response.ok) {
     const message = readErrorMessage4(payload) ?? `Relay request failed with HTTP ${response.status}`;
@@ -21512,14 +22273,22 @@ async function preparePairing(paths = resolveRuntimePaths()) {
   const config = await loadConfig(paths);
   const identity = await ensureIdentity(paths);
   const systemInfo = readLinkSystemInfo();
-  const created = await postServerJson(config.serverBaseUrl, "/api/v1/link-pairings", {
-    install_id: identity.install_id,
-    link_id: identity.link_id ?? void 0,
-    display_name: systemInfo.defaultDisplayName,
-    platform: systemInfo.platform,
-    hostname: systemInfo.hostname ?? void 0,
-    public_key_pem: identity.public_key_pem
-  });
+  const created = await postServerJson(
+    config.serverBaseUrl,
+    "/api/v1/link-pairings",
+    {
+      install_id: identity.install_id,
+      link_id: identity.link_id ?? void 0,
+      display_name: systemInfo.defaultDisplayName,
+      platform: systemInfo.platform,
+      hostname: systemInfo.hostname ?? void 0,
+      public_key_pem: identity.public_key_pem
+    },
+    {
+      target: "server",
+      action: "create pairing session"
+    }
+  );
   const relayBaseUrl = created.relayBaseUrl || config.relayBaseUrl;
   let assigned;
   let updatedIdentity;
@@ -21541,28 +22310,43 @@ async function preparePairing(paths = resolveRuntimePaths()) {
       installId: updatedIdentity.install_id,
       publicKeyPem: updatedIdentity.public_key_pem
     });
-    await patchServerJson(config.serverBaseUrl, `/api/v1/link-pairings/${created.sessionId}/link`, created.pairingToken, {
-      install_id: updatedIdentity.install_id,
-      link_id: assigned.linkId,
-      link_version: LINK_VERSION,
-      display_name: systemInfo.defaultDisplayName,
-      platform: systemInfo.platform,
-      hostname: systemInfo.hostname ?? void 0,
-      lan_ips: routes.lanIps,
-      public_ipv4s: routes.publicIpv4s,
-      public_ipv6s: routes.publicIpv6s,
-      preferred_urls: routes.preferredUrls,
-      environment: routes.environment
-    });
+    await patchServerJson(
+      config.serverBaseUrl,
+      `/api/v1/link-pairings/${created.sessionId}/link`,
+      created.pairingToken,
+      {
+        install_id: updatedIdentity.install_id,
+        link_id: assigned.linkId,
+        link_version: LINK_VERSION,
+        display_name: systemInfo.defaultDisplayName,
+        platform: systemInfo.platform,
+        hostname: systemInfo.hostname ?? void 0,
+        lan_ips: routes.lanIps,
+        public_ipv4s: routes.publicIpv4s,
+        public_ipv6s: routes.publicIpv6s,
+        preferred_urls: routes.preferredUrls,
+        environment: routes.environment
+      },
+      {
+        target: "server",
+        action: "finalize pairing"
+      }
+    );
   } catch (error) {
+    const reportedError = error instanceof RelayNetworkError ? createPairingNetworkError({
+      target: "relay",
+      action: "connect to Relay",
+      baseUrl: error.relayBaseUrl,
+      detail: error.causeMessage
+    }) : error;
     await reportPairingErrorToServer({
       serverBaseUrl: config.serverBaseUrl,
       sessionId: created.sessionId,
       source: "link",
       pairingToken: created.pairingToken,
-      error: pairingErrorSnapshot("prepare_pairing", error)
+      error: pairingErrorSnapshot("prepare_pairing", reportedError)
     });
-    throw error;
+    throw reportedError;
   }
   const qrPayload = {
     kind: "hermes_link_pairing",
@@ -21662,6 +22446,10 @@ async function claimPairing(input) {
       {
         claim_token: input.claimToken,
         app_instance_id: input.appInstanceId ?? void 0
+      },
+      {
+        target: "server",
+        action: "verify pairing claim"
       }
     );
   } catch (error) {
@@ -21709,15 +22497,25 @@ async function loadRequiredIdentity2(paths) {
   }
   return identity;
 }
-async function postServerJson(serverBaseUrl, path25, body) {
-  const response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path25}`, {
-    method: "POST",
-    headers: {
-      accept: "application/json",
-      "content-type": "application/json"
-    },
-    body: JSON.stringify(body)
-  });
+async function postServerJson(serverBaseUrl, path26, body, options) {
+  let response;
+  try {
+    response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path26}`, {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+  } catch (error) {
+    throw createPairingNetworkError({
+      target: options.target,
+      action: options.action,
+      baseUrl: serverBaseUrl,
+      detail: error instanceof Error ? error.message : String(error)
+    });
+  }
   return readJsonResponse2(response);
 }
 async function reportPairingErrorToServer(input) {
@@ -21750,16 +22548,26 @@ function pairingErrorSnapshot(stage, error) {
     occurred_at: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-async function patchServerJson(serverBaseUrl, path25, token, body) {
-  const response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path25}`, {
-    method: "PATCH",
-    headers: {
-      accept: "application/json",
-      authorization: `Bearer ${token}`,
-      "content-type": "application/json"
-    },
-    body: JSON.stringify(body)
-  });
+async function patchServerJson(serverBaseUrl, path26, token, body, options) {
+  let response;
+  try {
+    response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path26}`, {
+      method: "PATCH",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+  } catch (error) {
+    throw createPairingNetworkError({
+      target: options.target,
+      action: options.action,
+      baseUrl: serverBaseUrl,
+      detail: error instanceof Error ? error.message : String(error)
+    });
+  }
   return readJsonResponse2(response);
 }
 async function readJsonResponse2(response) {
@@ -21781,11 +22589,20 @@ function readErrorMessage5(payload) {
   const message = error.message;
   return typeof message === "string" ? message : null;
 }
+function createPairingNetworkError(input) {
+  const baseMessage = input.target === "server" ? `HermesPilot Server is unreachable while trying to ${input.action}.` : `Hermes Relay is unreachable while trying to ${input.action}.`;
+  const hint = "If you are using a VPN, proxy, or corporate network, try turning it off and retrying.";
+  return new LinkHttpError(
+    503,
+    input.target === "server" ? "pairing_server_unreachable" : "pairing_relay_unreachable",
+    `${baseMessage} Please check whether ${input.baseUrl} is reachable. ${hint} Detail: ${input.detail}`
+  );
+}
 function pairingClaimPath(sessionId, paths) {
-  return path24.join(paths.pairingDir, `${Buffer.from(sessionId).toString("base64url")}.claimed.json`);
+  return path25.join(paths.pairingDir, `${Buffer.from(sessionId).toString("base64url")}.claimed.json`);
 }
 function pairingSessionPath(sessionId, paths) {
-  return path24.join(paths.pairingDir, `${Buffer.from(sessionId).toString("base64url")}.json`);
+  return path25.join(paths.pairingDir, `${Buffer.from(sessionId).toString("base64url")}.json`);
 }
 function qrPreferredUrls(routes) {
   return routes.preferredUrls.filter((url) => !url.includes("/api/v1/relay/links/")).slice(0, 1);
@@ -21839,6 +22656,7 @@ function registerSystemRoutes(router, options) {
         conversation_events: true,
         conversation_delete: true,
         conversation_bulk_delete: true,
+        conversation_clear_plan: true,
         conversation_cancel: true,
         conversation_rename: true,
         blobs: true,
@@ -22432,12 +23250,16 @@ function registerPairingRoutes(router, options) {
     if (!session) {
       throw new LinkHttpError(404, "pairing_session_not_found", "Pairing session was not found");
     }
+    const state = await readPairingState(sessionId, paths);
+    if (!state.claimed && isExpiredAt(session.expires_at)) {
+      throw new LinkHttpError(404, "pairing_session_expired", "Pairing session has expired");
+    }
     ctx.set("cache-control", "no-store");
     ctx.body = {
       ok: true,
       session: {
         ...session,
-        claimed: Boolean(await readPairingState(sessionId, paths).then((state) => state.claimed))
+        claimed: state.claimed
       }
     };
   });
@@ -22453,6 +23275,8 @@ async function readPairingState(sessionId, paths) {
 }
 async function renderPairingPage(input) {
   const session = input.session;
+  const expiresAtMs = Date.parse(session.expires_at);
+  const isExpired = !input.state.claimed && Number.isFinite(expiresAtMs) && Date.now() >= expiresAtMs;
   const qrPayload = JSON.stringify({
     kind: "hermes_link_pairing",
     version: 1,
@@ -22472,8 +23296,9 @@ async function renderPairingPage(input) {
   const currentUrl = session.local_api_url.replace(/\/+$/u, "");
   const linkIdLabel = escapeHtml(input.linkId ?? session.link_id);
   const expiresLabel = escapeHtml(formatDate(session.expires_at));
-  const statusLabel = input.state.claimed ? "\u5DF2\u5B8C\u6210\u914D\u5BF9" : "\u7B49\u5F85 App \u626B\u7801";
-  const statusHint = input.state.claimed ? "App \u5DF2\u5B8C\u6210\u914D\u5BF9\uFF0C\u8FD9\u4E2A\u9875\u9762\u53EF\u4EE5\u5173\u95ED\u3002" : "\u6253\u5F00 App \u626B\u7801\uFF0C\u6216\u8005\u590D\u5236\u914D\u5BF9\u7801\u624B\u52A8\u8F93\u5165\u3002";
+  const statusLabel = input.state.claimed ? "\u5DF2\u5B8C\u6210\u914D\u5BF9" : isExpired ? "\u914D\u5BF9\u5DF2\u8FC7\u671F" : "\u7B49\u5F85 App \u626B\u7801";
+  const statusHint = input.state.claimed ? "App \u5DF2\u5B8C\u6210\u914D\u5BF9\uFF0C\u8FD9\u4E2A\u9875\u9762\u53EF\u4EE5\u5173\u95ED\u3002" : isExpired ? "\u8FD9\u6B21\u4E8C\u7EF4\u7801\u5DF2\u8FC7\u671F\uFF0C\u8BF7\u91CD\u65B0\u8FD0\u884C hermeslink pair\u3002" : "\u6253\u5F00 App \u626B\u7801\uFF0C\u6216\u8005\u590D\u5236\u914D\u5BF9\u7801\u624B\u52A8\u8F93\u5165\u3002";
+  const statusPillLabel = input.state.claimed ? "\u5DF2\u626B\u7801" : isExpired ? "\u5DF2\u8FC7\u671F" : "\u7B49\u5F85\u4E2D";
   return `<!doctype html>
 <html lang="zh-CN">
 <head>
@@ -22778,7 +23603,7 @@ async function renderPairingPage(input) {
           <div class="card">
             <div class="status">
               <h2 class="status-title" id="statusTitle">${escapeHtml(statusLabel)}</h2>
-              <span class="pill" id="statusPill">${input.state.claimed ? "\u5DF2\u626B\u7801" : "\u7B49\u5F85\u4E2D"}</span>
+              <span class="pill" id="statusPill">${escapeHtml(statusPillLabel)}</span>
             </div>
             <div class="qr-frame">
               <img src="${qrDataUri}" alt="Hermes Link pairing QR code" />
@@ -22795,22 +23620,62 @@ async function renderPairingPage(input) {
   </main>
   <script>
     const sessionId = ${JSON.stringify(session.session_id)};
+    const expiresAtMs = ${Number.isFinite(expiresAtMs) ? String(expiresAtMs) : "Number.NaN"};
+    const initialClaimed = ${JSON.stringify(input.state.claimed)};
+    const statusTitle = document.querySelector('#statusTitle');
+    const statusPill = document.querySelector('#statusPill');
+    const statusHint = document.querySelector('#statusHint');
+    let refreshTimer = null;
+
+    const stopPolling = () => {
+      if (refreshTimer !== null) {
+        clearInterval(refreshTimer);
+        refreshTimer = null;
+      }
+    };
+
+    const markClaimed = () => {
+      statusTitle.textContent = '\u5DF2\u5B8C\u6210\u914D\u5BF9';
+      statusPill.textContent = '\u5DF2\u626B\u7801';
+      statusHint.textContent = 'App \u5DF2\u5B8C\u6210\u914D\u5BF9\uFF0C\u8FD9\u4E2A\u9875\u9762\u53EF\u4EE5\u5173\u95ED\u3002';
+      stopPolling();
+    };
+
+    const markExpired = () => {
+      statusTitle.textContent = '\u914D\u5BF9\u5DF2\u8FC7\u671F';
+      statusPill.textContent = '\u5DF2\u8FC7\u671F';
+      statusHint.textContent = '\u8FD9\u6B21\u4E8C\u7EF4\u7801\u5DF2\u8FC7\u671F\uFF0C\u8BF7\u91CD\u65B0\u8FD0\u884C hermeslink pair\u3002';
+      stopPolling();
+    };
+
     const refresh = async () => {
+      if (Number.isFinite(expiresAtMs) && Date.now() >= expiresAtMs) {
+        markExpired();
+        return;
+      }
       try {
         const response = await fetch('/api/v1/pairing/session?session_id=' + encodeURIComponent(sessionId), {
           headers: { accept: 'application/json' },
         });
+        if (response.status === 404) {
+          markExpired();
+          return;
+        }
         if (!response.ok) return;
         const payload = await response.json();
         if (payload?.session?.claimed) {
-          document.querySelector('#statusPill').textContent = '\u5DF2\u626B\u7801';
-          document.querySelector('#statusTitle').textContent = '\u5DF2\u5B8C\u6210\u914D\u5BF9';
-          document.querySelector('#statusHint').textContent = 'App \u5DF2\u5B8C\u6210\u914D\u5BF9\uFF0C\u8FD9\u4E2A\u9875\u9762\u53EF\u4EE5\u5173\u95ED\u3002';
+          markClaimed();
         }
       } catch (_) {}
     };
-    setInterval(refresh, 1500);
-    refresh();
+    if (initialClaimed) {
+      stopPolling();
+    } else if (Number.isFinite(expiresAtMs) && Date.now() >= expiresAtMs) {
+      markExpired();
+    } else {
+      refreshTimer = window.setInterval(refresh, 1500);
+      refresh();
+    }
   </script>
 </body>
 </html>`;
@@ -22822,6 +23687,10 @@ function formatDate(value) {
   const date = new Date(value);
   return Number.isNaN(date.getTime()) ? value : date.toLocaleString("zh-CN", { hour12: false });
 }
+function isExpiredAt(value) {
+  const expiresAtMs = Date.parse(value);
+  return Number.isFinite(expiresAtMs) && Date.now() >= expiresAtMs;
+}
 
 // src/http/routes/internal.ts
 function registerInternalRoutes(router, options) {
@@ -22916,6 +23785,7 @@ export {
   createFileLogger,
   getLinkLogFile,
   ensureHermesApiServerAvailable,
+  readHermesVersion,
   loadConfig,
   saveConfig,
   normalizeLanHost,
@@ -22929,6 +23799,7 @@ export {
   readPairingClaim,
   clearPairingClaim,
   createApp,
+  connectRelayControl,
   reportLinkStatusToServer,
   startLinkService,
   startDaemonProcess,