From 4e641f4446a1e843766208674f58481c898a027a Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Mon, 20 Jul 2026 23:56:54 -0700
Subject: [PATCH] Document transcript watcher reconciliation contract

Clarify that bind() is best-effort with reconciliation fallback,
invalidate() detaches from stale identities, and the caller's polling
loop owns transcript liveness. Supports resilience on remote filesystems.
---
 src/main/native-chat/transcript-native-watcher.ts | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/main/native-chat/transcript-native-watcher.ts b/src/main/native-chat/transcript-native-watcher.ts
index bc650e14aa0..8cccd022c57 100644
--- a/src/main/native-chat/transcript-native-watcher.ts
+++ b/src/main/native-chat/transcript-native-watcher.ts
@@ -2,12 +2,19 @@ import { watch, type FSWatcher } from 'node:fs'
 import { basename, dirname } from 'node:path'
 
 export type TranscriptNativeWatcher = {
+  /** Best-effort bind; false keeps the caller in reconciliation-only mode. */
   bind: () => boolean
+  /** Detach from an identity that may no longer represent the watched path. */
   invalidate: () => void
   needsRebind: () => boolean
   dispose: () => void
 }
 
+/**
+ * Optional fs.watch acceleration for transcript reconciliation. Native watches
+ * can fail on otherwise-readable remote filesystems, so binding is retryable
+ * and never owns transcript liveness; the caller's polling loop does.
+ */
 export function createTranscriptNativeWatcher(
   filePath: string,
   onEvent: () => void,