@jaychang1989/dsh-webchat 0.6.0 → 0.7.1

package/README.en.md

@@ -42,7 +42,7 @@ dsh plugin --profile desktop add github:jaychang1989/dsh-webchat
 ## Use
 
 1. Click the "DeepSeek 网页 / DeepSeek Web" entry — the page loads in the center column; there is no second click.
-2. Sign in to DeepSeek once; that holds for the rest of the run.
+2. Sign in to DeepSeek once — the plugin keeps that login across restarts (see below).
 
 Click again to collapse the panel. Switching to another panel (Plugins, Automation Tasks, the task board, a session …) only hides the guest, never unmounts it, so coming back neither reloads the page nor drops the session.
 
@@ -52,10 +52,23 @@ Click again to collapse the panel. Switching to another panel (Plugins, Automati
 - Node.js >= 22
 - The desktop app: only it provides the native guest bridge; plain `dsh web` uses the window fallback
 
+## Staying signed in
+
+The host hands browser guests a **process-lifetime** partition (a fresh random name per run, with no `persist:` prefix), so cookies and site storage would die with the app — DSH's own side-card browser behaves the same way. This plugin takes that over through **two channels**, because the host half does not always reach Electron:
+
+1. **Site storage** (localStorage) and the **page's own cookies**: carried by the guest itself, generically — no key names, no Electron.
+2. **Partition cookies, HttpOnly included**: only the Electron main process can read those. Used when reachable; `session.electron` in `GET /api/dsh-webchat/state` says plainly whether it is.
+
+The order: reserve the lease → restore first (cookies land before the first navigation, so the page's very first request already carries them) → write storage and the page's cookies once the first load finishes → reload once → snapshot as the page is used.
+
+- Location: `%USERPROFILE%\.dsh\dsh-webchat\session.json`
+- **Deleting that file logs the plugin's guest out** — it keeps nothing else behind.
+- The file holds live session credentials in **plain text**. It sits in your own profile directory (user-private by default), but it is not as protected as a browser's encrypted cookie store.
+- If DeepSeek keeps the session in an HttpOnly cookie *and* the host half cannot reach Electron, only the storage part can be kept — signing in again would then still happen.
+
 ## Known limitations
 
-- **Restarting the desktop app means signing in to DeepSeek again.** The host hands out a **process-lifetime** guest partition (a fresh random name per run, with no `persist:` prefix), so the session is not written to disk. That is the host's mechanism, not a choice this plugin makes.
-- The DeepSeek web front end has its own rate limiting and sign-in flow; the plugin only hosts it and does not mediate its requests.
+- The DeepSeek web front end has its own rate limiting and sign-in flow; the plugin only hosts it and keeps the session, and does not mediate its requests.
 - Links the page opens are handled inside the guest; the plugin adds no navigation policy of its own.
 
 ## Troubleshooting
@@ -66,7 +79,8 @@ Click again to collapse the panel. Switching to another panel (Plugins, Automati
 | The center column says "载入失败：…" | The host refused the guest (the bridge threw). The text carries the host's reason |
 | The row opens a browser window instead of a panel | This renderer had no `dshDesktop.browser` (a plain web profile, for instance), so the fallback ran |
 | The row opens but the center column is blank | The panel fills the cell the shell allocates; in a very small window, or with the sidebar dragged extremely narrow, that cell can have no area |
-| It asks for a login again after a restart | See the limitations above — it is the host's partition behaviour |
+| It asks for a login again after a restart | Check `session` in `GET /api/dsh-webchat/state`: an `electron` value other than `ready` means the host half cannot reach Electron (so nothing can be saved), and `saved: null` means no snapshot exists yet. Use the page for a moment and look again ~30s later |
+| You want to sign out for good | Delete `%USERPROFILE%\.dsh\dsh-webchat\session.json` |
 | The page shows "Abnormal usage environment" | DeepSeek's front end checks `navigator.userAgent` for the string `electron` — which the desktop default carries — and then recommends its official product. Since 0.5.2 the guest presents a plain Chrome user agent and the dialog no longer appears |
 
 ## Development and tests
@@ -75,7 +89,7 @@ Click again to collapse the panel. Switching to another panel (Plugins, Automati
 node --test
 ```
 
-Nineteen cases. The host half is driven through a fake context and fake request/response objects; the browser half really executes against a thin React test double plus a DOM stand-in: it checks that the plugin registers its nav row and its page under the slot contract (one shared id), that the label follows the language, that the icon honours the size the shell asks for, and the whole guest lifecycle — reserving a lease, building the webview the way the host requires (`about:blank#<lease>`), setting the user agent before navigating on `dom-ready`, **hiding the guest without detaching it when the panel unmounts and reusing it on remount**, and releasing the lease on plugin disposal; without a bridge it checks the window fallback and its reporting.
+Thirty-four cases. The host half is driven through a fake context, fake request/response objects and injectable Electron/cookie stand-ins: the snapshot round-trip through disk, cookie capture and restore (HttpOnly included, one refused cookie not aborting the rest), the session routes' method guards and partition validation, and a host without Electron reporting why without hurting the page. The browser half really executes against a thin React test double plus a DOM stand-in: the slot contract (one shared id, order, the label thunk, the icon honouring the requested size), the lease and the `about:blank#<lease>` webview, the user agent landing before navigation, **hiding the guest without detaching it on unmount and reusing it on remount**, the login restore writing storage once and reloading once, snapshots while in use and on disposal, and the window fallback.
 
 There is no build step — `lib/index.js` and `lib/client.js` are the hand-written runtime, and the package has **zero runtime dependencies**. The guest mechanism is written up in [MAINTAINING.md](./MAINTAINING.md) (Chinese).
 

package/README.md

@@ -52,10 +52,23 @@ dsh plugin --profile desktop add github:jaychang1989/dsh-webchat
 - Node.js >= 22
 - 桌面端（DSH Desktop）：只有它提供原生访客桥接；纯 `dsh web` 会走窗口降级
 
+## 登录状态
+
+桌面端给浏览器访客的分区是**进程内**的（每次运行随机命名、不带 `persist:`），所以 cookie 和站点存储本来会随退出一起消失——DSH 自带的侧栏浏览器也是这样。本插件把这个接管了，用**两条通道**——因为宿主半区不一定拿得到 Electron：
+
+1. **站点存储**（localStorage）与**页面自己的 cookie**：由页面侧通用搬运，不依赖任何键名，也不依赖 Electron；
+2. **分区 cookie（含 HttpOnly）**：只有宿主的 Electron 主进程读得到。能拿到就走这条；`GET /api/dsh-webchat/state` 的 `session.electron` 会如实说明。
+
+顺序：拿到租约 → 回灌（cookie 在首次导航前写回，页面第一个请求就带着它）→ 首次加载完成后再写入存储与 cookie → 刷新一次 → 之后按使用情况快照。
+
+- 文件位置：`%USERPROFILE%\.dsh\dsh-webchat\session.json`
+- **删掉这个文件就等于退出登录**（本插件不会再有别的残留）。
+- 文件里是**明文**会话凭据。它在你自己的用户目录下（默认只有你的账户可读），但确实不如浏览器那种加密 cookie 库。
+- 如果 DeepSeek 的登录态是 HttpOnly cookie、而宿主又拿不到 Electron，就只能保留存储部分——那种情况下重登仍会发生。
+
 ## 已知限制
 
-- **重启桌面端后需要重新登录 DeepSeek。** 宿主给访客分配的是**进程内**分区（每次运行随机命名、不带 `persist:`），登录态不落盘。这是宿主的机制，插件无法改变。
-- 官方网页端有自己的风控与登录流程，插件只负责把它承载起来，不介入其请求。
+- 官方网页端有自己的风控与登录流程，插件只负责把它承载起来并保留登录态，不介入其请求。
 - 页面里指向外部的链接在访客内处理；插件不追加自己的导航策略。
 
 ## 排查
@@ -66,7 +79,8 @@ dsh plugin --profile desktop add github:jaychang1989/dsh-webchat
 | 中栏提示「载入失败：…」 | 宿主拒绝了访客（桥接返回异常）。文本里带着宿主给的原因 |
 | 这一行点了但中栏没有页面，反而弹出浏览器窗口 | 说明当前渲染进程拿不到 `dshDesktop.browser`（例如在纯 web 环境），插件走了降级路径 |
 | 这一行点了但中栏是空白 | 面板显示的空间是 shell 分配的那个格子；若窗口极小或侧栏被拖到极窄，格子可能没有面积 |
-| 重启后要求重新登录 | 见上面的「已知限制」，属于宿主分区机制 |
+| 重启后要求重新登录 | 先看 `GET /api/dsh-webchat/state` 的 `session`：`electron` 不是 `ready` 说明宿主半区拿不到 Electron（登录态无法保存），`saved` 为 `null` 说明还没产生过快照。正常情况下用一次、等 30 秒再看，文件就会出现 |
+| 想彻底退出登录 | 删掉 `%USERPROFILE%\.dsh\dsh-webchat\session.json` |
 | 页面弹出「使用环境异常」 | DeepSeek 前端会检查 `navigator.userAgent` 里是否含 `electron`（桌面端默认 UA 就含），命中就提示"建议使用官方产品"。0.5.2 起访客改用普通 Chrome UA，不再触发 |
 
 ## 开发与测试
@@ -75,9 +89,9 @@ dsh plugin --profile desktop add github:jaychang1989/dsh-webchat
 node --test
 ```
 
-19 个用例。宿主半区用假 context 与假 request/response 驱动；浏览器半区用一层薄的 React 测试替身 + DOM 桩**真实执行**：验证它按槽位契约注册导航行与页面（同一个 id）、标签随语言变化、图标遵循 shell 要求的尺寸，以及访客生命周期——申请租约、按宿主约定生成 `about:blank#<lease>` 的 webview、`dom-ready` 后先改 UA 再导航、**卸载只隐藏不卸载访客、重挂复用同一个**、插件卸载时释放租约；无桥接环境下验证降级为请求宿主开窗并如实反馈。
+34 个用例。宿主半区用假 context、假 request/response 与可注入的 Electron/cookie 替身驱动：快照落盘往返、cookie 捕获与回灌（含 `HttpOnly`、拒绝一个不合法 cookie 不影响其余）、两条会话路由的方法守卫与分区校验、无 Electron 时如实报错而不影响页面加载。浏览器半区用一层薄的 React 测试替身 + DOM 桩**真实执行**：槽位注册契约（同一个 id、order、label thunk、按 size 出图标）、租约与 `about:blank#<lease>` 的 webview、`dom-ready` 后先改 UA 再导航、**卸载只隐藏不摘除 / 重挂复用同一访客 / 只申请一次租约**、登录态恢复只回灌一次并只刷新一次、使用中与卸载时的快照、无桥接时的降级。
 
-没有构建步骤——`lib/index.js` 与 `lib/client.js` 就是手写的运行时代码（React 取自浏览器的模块表），包内**零运行时依赖**。访客机制与槽位契约见 [MAINTAINING.md](./MAINTAINING.md)。
+没有构建步骤——`lib/index.js` 与 `lib/client.js` 就是手写的运行时代码（React 取自浏览器的模块表），包内**零运行时依赖**。访客机制、槽位契约与登录态保存见 [MAINTAINING.md](./MAINTAINING.md)。
 
 ## 来源与许可
 

package/lib/client.js

@@ -43,6 +43,11 @@ window.__ModuleLoader__.load({
 		const STORAGE_IDENTITY = "dsh-webchat"
 		/** Host route used by the window fallback. */
 		const OPEN_ROUTE = "/api/dsh-webchat/open"
+		/** Host routes that keep the login alive across restarts. */
+		const RESTORE_ROUTE = "/api/dsh-webchat/session/restore"
+		const SAVE_ROUTE = "/api/dsh-webchat/session/save"
+		/** How often the guest's own storage is snapshotted while it is open. */
+		const SAVE_INTERVAL_MS = 30000
 
 		const STYLE_ID = "dsh-webchat-style"
 		const OVERLAY_ATTR = "data-dsh-webchat-overlay"
@@ -202,6 +207,107 @@ window.__ModuleLoader__.load({
 			return box
 		}
 
+		/**
+		 * Read everything the guest page itself can reach: its storage and its
+		 * own cookie string. That string cannot carry HttpOnly cookies — only the
+		 * host half can, and only when it reaches Electron — but it is what keeps
+		 * a login alive when it cannot.
+		 * @param element - the live webview.
+		 * @returns the guest state as JSON text.
+		 */
+		function readGuestState(element) {
+			return element.executeJavaScript(
+				"JSON.stringify({ storage: Object.keys(localStorage).map(function (key) { return [key, localStorage.getItem(key)] }), cookie: document.cookie })",
+			)
+		}
+
+		/**
+		 * Write a guest state back into the page: storage keys, then cookies.
+		 * Cookies are re-scoped to the site root, which is where a login cookie
+		 * belongs; the original attributes are not recoverable from
+		 * `document.cookie`.
+		 * @param element - the live webview.
+		 * @param state - `{ storage, cookie }`.
+		 */
+		function writeGuestState(element, state) {
+			return element.executeJavaScript(
+				"(function () { var state = " + JSON.stringify(state) + ";"
+				+ " var storage = Array.isArray(state.storage) ? state.storage : [];"
+				+ " for (var i = 0; i < storage.length; i++) { try { localStorage.setItem(storage[i][0], storage[i][1]) } catch (error) {} }"
+				+ " if (typeof state.cookie === 'string' && state.cookie !== '') {"
+				+ " var parts = state.cookie.split('; ');"
+				+ " for (var j = 0; j < parts.length; j++) {"
+				+ " var pair = parts[j];"
+				+ " if (pair.indexOf('=') === -1) continue;"
+				+ " try { document.cookie = pair + '; path=/' } catch (error) {}"
+				+ " } }"
+				+ " return true })()",
+			)
+		}
+
+		/**
+		 * Ask the host to put the saved session back before the page is
+		 * navigated: cookies through the shell's session API where that is
+		 * reachable, and the guest's own storage and cookie string either way.
+		 * @param partition - the partition the shell issued for the lease.
+		 * @returns `{ storage, cookie }` to apply, or null when there is nothing.
+		 */
+		async function restoreGuestSession(partition) {
+			try {
+				const response = await fetch(RESTORE_ROUTE, {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify({ partition }),
+				})
+				const payload = await response.json()
+				if (payload === null || typeof payload !== "object") return null
+				if (payload.ok !== true) {
+					console.warn("[dsh-webchat] session cookies:", payload.error || "not restored")
+				}
+				const storage = Array.isArray(payload.storage) ? payload.storage : []
+				const cookie = typeof payload.cookie === "string" ? payload.cookie : ""
+				if (storage.length === 0 && cookie === "") return null
+				return { storage, cookie }
+			} catch (error) {
+				console.warn("[dsh-webchat] session restore failed:", error)
+				return null
+			}
+		}
+
+		/**
+		 * Ask the host to refresh the snapshot. `withState` ships what only the
+		 * guest can read; the unload beacon deliberately skips it (the host then
+		 * keeps the previous values).
+		 * @param withState - whether to include the guest's own state.
+		 * @param target - the guest record; defaults to the live one, which
+		 *   disposal clears before its last save.
+		 */
+		async function saveGuestSession(withState, target) {
+			const record = target === undefined ? guest : target
+			if (record === null || record === undefined) return
+			const body = { partition: record.partition }
+			if (withState) {
+				try {
+					const state = JSON.parse(await readGuestState(record.element))
+					if (state !== null && typeof state === "object") {
+						if (Array.isArray(state.storage)) body.storage = state.storage
+						if (typeof state.cookie === "string") body.cookie = state.cookie
+					}
+				} catch (error) {
+					// Not ready: the host still snapshots whatever it can reach.
+				}
+			}
+			try {
+				await fetch(SAVE_ROUTE, {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify(body),
+				})
+			} catch (error) {
+				// Best effort: a snapshot that fails costs a login, not the page.
+			}
+		}
+
 		/**
 		 * Reserve a guest and attach its webview, once per app run.
 		 * @returns a promise resolving once the attempt settled.
@@ -216,6 +322,9 @@ window.__ModuleLoader__.load({
 						|| typeof reservation.lease !== "string" || typeof reservation.partition !== "string") {
 						throw new Error("the desktop browser bridge returned no reservation")
 					}
+					// Cookies land on the partition before anything is requested; the
+					// guest's own storage and cookie string come back with them.
+					const restored = await restoreGuestSession(reservation.partition)
 					const element = document.createElement("webview")
 					element.setAttribute("name", reservation.lease)
 					element.setAttribute("partition", reservation.partition)
@@ -237,9 +346,50 @@ window.__ModuleLoader__.load({
 							failure = messageOf(error)
 						})
 					}, { once: true })
+					// Storage and cookies can only be written while the page is on
+					// its own origin, so both are restored after the first load and
+					// the page is then asked to load once more — this time already
+					// signed in. Until that settles, snapshots are skipped: the
+					// freshly loaded page still has empty storage, and saving that
+					// would erase the very snapshot being restored.
+					let storageState = restored === null ? "none" : "pending"
+					element.addEventListener("did-finish-load", function () {
+						if (storageState !== "pending") return
+						storageState = "restoring"
+						Promise.resolve(writeGuestState(element, restored))
+							.then(function () {
+								storageState = "done"
+								element.reload()
+							})
+							.catch(function (error) {
+								storageState = "done"
+								console.warn("[dsh-webchat] could not restore site storage:", error)
+							})
+					})
+					element.addEventListener("did-finish-load", function () {
+						if (storageState === "pending" || storageState === "restoring") return
+						void saveGuestSession(true)
+					})
+					const onUnload = function () {
+						// Cookies are the part that matters and the host reads them
+						// itself, so the beacon carries no payload.
+						try {
+							navigator.sendBeacon(SAVE_ROUTE, JSON.stringify({ partition: reservation.partition }))
+						} catch (error) {
+							// The page is going away; nothing left to do.
+						}
+					}
+					window.addEventListener("beforeunload", onUnload)
 					const container = overlayContainer()
 					container.appendChild(element)
-					guest = { lease: reservation.lease, element, container }
+					guest = {
+						lease: reservation.lease,
+						partition: reservation.partition,
+						element,
+						container,
+						onUnload,
+						timer: setInterval(function () { void saveGuestSession(true) }, SAVE_INTERVAL_MS),
+					}
 					failure = ""
 				} catch (error) {
 					failure = messageOf(error)
@@ -255,6 +405,10 @@ window.__ModuleLoader__.load({
 			if (guest === null) return
 			const releasing = guest
 			guest = null
+			if (releasing.timer !== undefined) clearInterval(releasing.timer)
+			if (releasing.onUnload !== undefined) window.removeEventListener("beforeunload", releasing.onUnload)
+			// Last chance to keep the login: the page is about to be torn down.
+			void saveGuestSession(true, releasing)
 			releasing.container.remove()
 			if (bridge !== undefined) {
 				try { void bridge.release(releasing.lease) } catch (error) { /* already gone */ }

package/lib/index.js

@@ -1,35 +1,35 @@
 /**
- * dsh-webchat — minimal launcher half.
+ * dsh-webchat — host half.
  *
- * The DeepSeek web app IS the client: chat.deepseek.com already ships the model
- * picker, deep think, smart search, history and attachments. This plugin does
- * not reimplement any of that any more — it opens that page in a window and
- * gets out of the way. Everything the previous release did around it (a custom
- * chat panel, transcript storage, /api/dsh-webchat engine routes, the
- * webchat_status/send/recover/import/transfer tools, transfer distillation)
- * has been removed.
+ * Two jobs:
  *
- * Why a window and not a pane: chat.deepseek.com sends
- * `Content-Security-Policy: frame-ancestors 'none'`, so it cannot be framed,
- * and the desktop build runs with `webviewTag: false`, so it cannot be a
- * `<webview>` either. A real window is the only faithful way to show the
- * official page.
+ * 1. **Session survival.** The browser half renders chat.deepseek.com inside
+ *    the DSH window through the shell's native browser guest, and the shell
+ *    gives every guest a process-lifetime partition — so the DeepSeek login is
+ *    gone after every restart. This half runs in the Electron main process, the
+ *    only place that can read a partition's cookies (HttpOnly ones included),
+ *    so it snapshots them to disk and puts them back on the next run. The
+ *    browser half captures the page's own storage and calls these routes.
  *
- * Three strategies are tried in order, so the button always does something:
- *   1. `app-window`       — a BrowserWindow created by this process (the DSH
- *                           desktop app is Electron). Focused instead of
- *                           duplicated when one is already open.
- *   2. `app-window-shell` — a chromeless Edge/Chrome window (`--app=`) with its
- *                           own user-data-dir, for hosts where (1) is denied.
- *   3. `system-browser`   — the OS default browser.
+ * 2. **A window fallback.** Where no guest bridge exists (a plain `dsh web`
+ *    profile) the page cannot be embedded at all, so the browser half asks this
+ *    half to open it in a window. Three strategies are tried in order:
+ *      - `app-window`       — a BrowserWindow created by this process (the DSH
+ *                             desktop app is Electron), focused instead of
+ *                             duplicated when one is already open;
+ *      - `app-window-shell` — a chromeless Edge/Chrome window (`--app=`) with
+ *                             its own user-data-dir;
+ *      - `system-browser`   — the OS default browser.
  *
- * The browser half (./client) renders the single button that calls this.
+ * Routes: `GET /state` (diagnostics), `POST /open` (the fallback),
+ * `POST /session/restore` and `POST /session/save` (the snapshot).
  */
 
 import { spawn } from 'node:child_process'
-import { existsSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
-import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
 
 /**
  * A CommonJS `require` anchored at this module. Electron hands `electron` to
@@ -47,10 +47,192 @@ export const inject = ['webServer']
 /** The page this plugin exists to open. */
 export const PAGE_URL = 'https://chat.deepseek.com/'
 
-/** Route family; the browser half spells the same two paths. */
+/** Route family; the browser half spells the same paths. */
 export const ROUTES = {
   state: '/api/dsh-webchat/state',
   open: '/api/dsh-webchat/open',
+  restore: '/api/dsh-webchat/session/restore',
+  save: '/api/dsh-webchat/session/save',
+}
+
+/**
+ * The shell hands browser guests a **process-lifetime** session partition
+ * (`dsh-sidebar-browser-<uuid>`, no `persist:` prefix, fresh name every run), so
+ * cookies and site storage die with the app — DSH's own side-card browser
+ * behaves the same way. The plugin cannot ask for another partition: the main
+ * process compares `params.partition` against the lease it issued.
+ *
+ * So this half keeps the guest's session alive across restarts by hand. It runs
+ * in the Electron main process, which is what makes it possible at all: only
+ * there can `session.cookies` be read, and that includes HttpOnly cookies, which
+ * a renderer can never see. Site storage is captured by the browser half.
+ *
+ * The snapshot holds live session credentials in plain text under the user's own
+ * profile directory (that directory is user-private by default). Deleting the
+ * file logs the plugin's guest out.
+ */
+export const SESSION_FILE = () => sessionFilePath === null
+  ? join(homedir(), '.dsh', 'dsh-webchat', 'session.json')
+  : sessionFilePath
+
+/** Overridable snapshot path, so tests never touch the real profile directory. */
+let sessionFilePath = null
+
+/** Point the snapshot somewhere else. Test seam; production leaves it unset. */
+export function setSessionFile(path) {
+  sessionFilePath = path
+}
+
+/** Overridable Electron lookup, so the routes' glue is testable outside Electron. */
+let electronLoader = null
+
+/** Replace the Electron lookup. Test seam; production leaves it unset. */
+export function setElectronLoader(loader) {
+  electronLoader = loader
+}
+
+/** A partition name the shell issues for a browser guest, and nothing else. */
+const GUEST_PARTITION = /^dsh-sidebar-browser-[0-9a-f-]{8,}$/
+
+/** Electron reachability, probed once and reported through the state route. */
+let electronStatus = 'unknown'
+
+/** Read a JSON request body; a malformed or oversized body reads as null. */
+function readJsonBody(req, limit = 2 * 1024 * 1024) {
+  return new Promise((resolve) => {
+    let size = 0
+    const chunks = []
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > limit) {
+        req.destroy()
+        resolve(null)
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'))
+      } catch (error) {
+        resolve(null)
+      }
+    })
+    req.on('error', () => resolve(null))
+  })
+}
+
+/**
+ * Read the saved snapshot.
+ * @param file - snapshot path.
+ * @returns the snapshot, or null when there is nothing usable on disk.
+ */
+export function readSnapshot(file) {
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'))
+    if (parsed === null || typeof parsed !== 'object') return null
+    return {
+      cookies: Array.isArray(parsed.cookies) ? parsed.cookies : [],
+      storage: Array.isArray(parsed.storage) ? parsed.storage : [],
+      // The page's own `document.cookie` string, kept by the browser half. It
+      // cannot carry HttpOnly cookies, but it is what survives when this process
+      // has no Electron session API at all.
+      cookie: typeof parsed.cookie === 'string' ? parsed.cookie : '',
+      savedAt: typeof parsed.savedAt === 'string' ? parsed.savedAt : '',
+    }
+  } catch (error) {
+    return null
+  }
+}
+
+/** Write the snapshot atomically, user-private, so a crash cannot truncate it. */
+export function writeSnapshot(file, snapshot) {
+  mkdirSync(dirname(file), { recursive: true })
+  const temp = `${file}.tmp`
+  writeFileSync(temp, `${JSON.stringify(snapshot, null, 2)}\n`, { mode: 0o600 })
+  renameSync(temp, file)
+}
+
+/**
+ * Copy saved cookies onto a partition's session.
+ * @param cookies - `session.cookies` of the live partition.
+ * @param snapshot - a snapshot from {@link readSnapshot}.
+ * @returns how many cookies the session accepted.
+ */
+export async function restoreCookies(cookies, snapshot) {
+  let restored = 0
+  for (const cookie of snapshot.cookies) {
+    if (cookie === null || typeof cookie !== 'object') continue
+    if (typeof cookie.name !== 'string' || typeof cookie.value !== 'string') continue
+    const domain = typeof cookie.domain === 'string' ? cookie.domain : ''
+    if (domain === '') continue
+    const path = typeof cookie.path === 'string' && cookie.path !== '' ? cookie.path : '/'
+    const details = {
+      url: `${cookie.secure === true ? 'https' : 'http'}://${domain.replace(/^\./, '')}${path}`,
+      name: cookie.name,
+      value: cookie.value,
+      domain,
+      path,
+      secure: cookie.secure === true,
+      httpOnly: cookie.httpOnly === true,
+    }
+    if (typeof cookie.expirationDate === 'number') details.expirationDate = cookie.expirationDate
+    if (typeof cookie.sameSite === 'string') details.sameSite = cookie.sameSite
+    try {
+      await cookies.set(details)
+      restored += 1
+    } catch (error) {
+      // A cookie the running Electron refuses (bad domain, expired, …) is not
+      // worth failing the whole restore for.
+    }
+  }
+  return restored
+}
+
+/**
+ * Serialize a partition's cookies, HttpOnly ones included.
+ * @param cookies - `session.cookies` of the live partition.
+ * @returns plain objects safe to write to disk.
+ */
+export async function captureCookies(cookies) {
+  const list = await cookies.get({})
+  return list.map((cookie) => ({
+    name: cookie.name,
+    value: cookie.value,
+    domain: cookie.domain,
+    path: cookie.path,
+    secure: cookie.secure === true,
+    httpOnly: cookie.httpOnly === true,
+    ...(typeof cookie.expirationDate === 'number' ? { expirationDate: cookie.expirationDate } : {}),
+    ...(typeof cookie.sameSite === 'string' ? { sameSite: cookie.sameSite } : {}),
+  }))
+}
+
+/**
+ * The live session of a guest partition, through the Electron main process.
+ * @param partition - the partition name the shell issued for the lease.
+ * @returns the Electron session.
+ * @throws when this process cannot reach Electron or refuses the partition.
+ */
+async function partitionSession(partition) {
+  if (!GUEST_PARTITION.test(partition)) throw new Error('dsh-webchat: not a browser-guest partition')
+  const electron = await electronApi()
+  if (electron.session === undefined) throw new Error('dsh-webchat: this process exposes no Electron session API')
+  return electron.session.fromPartition(partition)
+}
+
+/**
+ * Probe Electron once, for the state route's diagnostics.
+ * @returns a short status string.
+ */
+export async function electronProbe() {
+  try {
+    const electron = await electronApi()
+    electronStatus = electron.session === undefined ? 'no session API' : 'ready'
+  } catch (error) {
+    electronStatus = messageOf(error)
+  }
+  return electronStatus
 }
 
 /**
@@ -102,23 +284,37 @@ function messageOf(error) {
  * loader resolves bare specifiers itself and does not always hand `electron`
  * to Electron's own resolver, so a CommonJS require — which Electron serves
  * natively — is the fallback.
+ *
+ * Either `BrowserWindow` (the window strategy) or `session` (the guest session
+ * snapshot) makes the module usable, so the two callers check their own need.
  * @returns the Electron module.
- * @throws with every probe failure joined, when neither path yields a window API.
+ * @throws with every probe failure joined, when neither path yields Electron.
  */
 async function electronApi() {
-  const usable = (mod) => (mod !== null && typeof mod === 'object' && mod.BrowserWindow !== undefined ? mod : undefined)
+  if (electronLoader !== null) return electronLoader()
+  // Electron's ESM namespace can carry the real API under `default` when its
+  // named exports are not statically detectable, and this loader hands back
+  // exactly that shape, so both forms are accepted.
+  const usable = (mod) => {
+    if (mod === null || typeof mod !== 'object') return undefined
+    if (mod.BrowserWindow !== undefined || mod.session !== undefined) return mod
+    const inner = mod.default
+    if (inner !== null && typeof inner === 'object'
+      && (inner.BrowserWindow !== undefined || inner.session !== undefined)) return inner
+    return undefined
+  }
   const failures = []
   try {
     const fromImport = usable(await import('electron'))
     if (fromImport !== undefined) return fromImport
-    failures.push('esm import resolved but exposed no BrowserWindow')
+    failures.push('esm import resolved but exposed neither BrowserWindow nor session')
   } catch (error) {
     failures.push(`esm import failed: ${messageOf(error)}`)
   }
   try {
     const fromRequire = usable(requireHere('electron'))
     if (fromRequire !== undefined) return fromRequire
-    failures.push('cjs require resolved but exposed no BrowserWindow')
+    failures.push('cjs require resolved but exposed neither BrowserWindow nor session')
   } catch (error) {
     failures.push(`cjs require failed: ${messageOf(error)}`)
   }
@@ -163,7 +359,9 @@ function shellProfileDir() {
 
 /** Open — or focus — a window owned by this process. */
 async function openAppWindow() {
-  const { BrowserWindow } = await electronApi()
+  const electron = await electronApi()
+  const { BrowserWindow } = electron
+  if (BrowserWindow === undefined) throw new Error('this process exposes no Electron BrowserWindow')
   const slot = windowSlot()
   if (slot.current !== null && slot.current.isDestroyed() === false) {
     slot.current.focus()
@@ -263,12 +461,25 @@ export function apply(ctx) {
         return
       }
       const slot = windowSlot()
+      const file = SESSION_FILE()
+      const snapshot = readSnapshot(file)
       json(res, 200, {
         ok: true,
         url: PAGE_URL,
         appWindowOpen: slot.current !== null && slot.current.isDestroyed() === false,
         last: lastAttempt,
         attempts: lastAttempts,
+        // Counts only: this endpoint is unauthenticated, so the cookie values
+        // themselves never leave the snapshot file.
+        session: {
+          file,
+          electron: electronStatus,
+          saved: snapshot === null ? null : {
+            cookies: snapshot.cookies.length,
+            storage: snapshot.storage.length,
+            savedAt: snapshot.savedAt,
+          },
+        },
       })
     },
   }), 'dsh-webchat: state route')
@@ -286,4 +497,94 @@ export function apply(ctx) {
       json(res, result.ok ? 200 : 502, result)
     },
   }), 'dsh-webchat: open route')
+
+  // The guest's session lives in a process-lifetime partition, so the browser
+  // half asks this side to put the saved cookies back before it navigates…
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: ROUTES.restore,
+    handler: async (req, res) => {
+      if (req.method !== 'POST') {
+        res.writeHead(405, { allow: 'POST' })
+        res.end()
+        return
+      }
+      const body = await readJsonBody(req)
+      const partition = body !== null && typeof body.partition === 'string' ? body.partition : ''
+      // Validate before anything else: this half must never touch a session the
+      // shell did not hand out for a browser guest.
+      if (!GUEST_PARTITION.test(partition)) {
+        json(res, 400, { ok: false, error: 'dsh-webchat: not a browser-guest partition' })
+        return
+      }
+      const snapshot = readSnapshot(SESSION_FILE())
+      if (snapshot === null) {
+        json(res, 200, { ok: true, cookies: 0, storage: null, cookie: '', savedAt: '' })
+        return
+      }
+      let restored = 0
+      let error = ''
+      try {
+        const session = await partitionSession(partition)
+        restored = await restoreCookies(session.cookies, snapshot)
+      } catch (failure) {
+        // Without a session API the HttpOnly cookies cannot come back, but the
+        // guest still gets its storage and its own cookie string, so this is
+        // reported rather than fatal.
+        error = messageOf(failure)
+      }
+      json(res, 200, {
+        ok: error === '',
+        error,
+        cookies: restored,
+        storage: snapshot.storage,
+        cookie: snapshot.cookie,
+        savedAt: snapshot.savedAt,
+      })
+    },
+  }), 'dsh-webchat: session restore route')
+
+  // …and asks it to refresh that snapshot as the page is used.
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: ROUTES.save,
+    handler: async (req, res) => {
+      if (req.method !== 'POST') {
+        res.writeHead(405, { allow: 'POST' })
+        res.end()
+        return
+      }
+      const body = await readJsonBody(req)
+      const partition = body !== null && typeof body.partition === 'string' ? body.partition : ''
+      if (!GUEST_PARTITION.test(partition)) {
+        json(res, 400, { ok: false, error: 'dsh-webchat: not a browser-guest partition' })
+        return
+      }
+      const file = SESSION_FILE()
+      const previous = readSnapshot(file)
+      // A save without site storage (the unload beacon) must not erase what an
+      // earlier save captured.
+      const storage = body !== null && Array.isArray(body.storage)
+        ? body.storage
+        : (previous === null ? [] : previous.storage)
+      const cookie = body !== null && typeof body.cookie === 'string'
+        ? body.cookie
+        : (previous === null ? '' : previous.cookie)
+      // The snapshot is written even when this process cannot reach Electron:
+      // site storage and the page's own cookie string are carried by the guest
+      // and are still worth keeping.
+      let cookies = []
+      let error = ''
+      try {
+        const session = await partitionSession(partition)
+        cookies = await captureCookies(session.cookies)
+      } catch (failure) {
+        error = messageOf(failure)
+      }
+      writeSnapshot(file, { version: 1, savedAt: new Date().toISOString(), cookies, storage, cookie })
+      json(res, 200, { ok: true, cookies: cookies.length, storage: storage.length, cookie: cookie !== '', error })
+    },
+  }), 'dsh-webchat: session save route')
+
+  void electronProbe()
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaychang1989/dsh-webchat",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Opens the official DeepSeek web app (chat.deepseek.com) inside DeepSeek Harness: one sidebar entry renders the real page in the center column, through the same native browser guest the built-in side-card browser uses. No chat UI, no agent tools, no runtime dependencies.",
   "keywords": [
     "dsh",