dsh-inner-browser-use 0.38.0 → 0.40.0

package/README.md

@@ -12,7 +12,7 @@ live picture of that browser, and your own cursor keeps working on the picture.
 | --- | --- |
 | `browser_open` | Starts the browser (or reuses the running one) and opens an address. `headless: false` shows a real window on the desktop instead. |
 | `browser_view` | Returns the address, the title, every control as `1 … 120`, and the visible text. |
-| `browser_read` | Reads the page the way a person does: one Markdown block of headings, paragraphs, lists and links, no controls. Far fewer tokens than a snapshot on long pages, and the links stay usable. Give it a `query` and only the passages that answer it come back, ranked (BM25 over Readability-style blocks, link-heavy menus down-weighted). |
+| `browser_read` | Reads the page the way a person does: one Markdown block of headings, paragraphs, lists and links, no controls. Far fewer tokens than a snapshot on long pages, and the links stay usable. Give it a `query` and only the sentences that answer it come back: BM25 over Readability-style blocks, then per-sentence scoring with heading, position and link-density priors, idf-weighted coverage, MMR de-duplication and a character budget — 92% fewer tokens on a long page in the bench. |
 | `browser_find` | Finds words (or a regex) anywhere on the page: matching controls come back with a clickable number, matching text with its point, each saying whether it is on screen. |
 | `browser_extract` | Returns the items a CSS selector matches, one compact line each with its link, instead of the whole page. |
 | `browser_click` | Clicks a numbered control, or an `x`/`y` point. `double: true` double-clicks. A cookie banner or modal over the control is cleared first, then the click happens. |
@@ -21,7 +21,8 @@ live picture of that browser, and your own cursor keeps working on the picture.
 | `browser_scroll` | Scrolls the wheel at the centre of the page, or at `x`/`y`. `dy: 600` is about a screen down. |
 | `browser_shot` | Saves a full-size PNG into `~/.dsh-inner-browser-use/screenshots` and returns the path. |
 | `browser_media` | Lists the video and sound the page already fetched, with sizes, the one its own player shows first and marked `main`; `save: <row>`, `save: main` or part of the address keeps one. Ads and beacons stay out unless `all: true`; `watch: false` stops remembering the page. A stream is followed to its pieces and joined, so nothing has to be installed. |
-| `browser_state` | Reports whether the browser runs, which profile it uses, its address and title, and how many columns are showing it. |
+| `browser_login` | Keeps a sign-in by name: `save` stores this window's cookies and each site's local storage, `list` shows what is kept, `use` signs that account back in and reopens the page, `drop` forgets it. Names survive a restart and belong to the browser rather than to one chat, so two accounts on one site are two names. What sits on disk is encrypted, with the key in the system keychain. |
+| `browser_state` | Reports whether the browser runs, which profile it uses, its address and title, how many columns are showing it, how much memory it holds right now and when it would close on its own if left alone. |
 
 `browser_read` on the same page is the words only, in Markdown (measured: 4,520
 characters of an about page against 2,987 characters of snapshot — and the

package/README.zh.md

@@ -11,7 +11,7 @@ profile，不是产品自带的那个浏览页签：右栏放的是它的画面
 | --- | --- |
 | `browser_open` | 启动浏览器（已在跑就复用）并打开一个地址。传 `headless: false` 会改为在桌面上开真实窗口。 |
 | `browser_view` | 返回地址、标题、编号成 `1 … 120` 的控件，以及可见文字。 |
-| `browser_read` | 按人读文章的方式给 Markdown（标题、段落、列表、链接）。带 `query` 只回能回答的段落；问不到时自动改为整页，不再空手回来。页面和上次读的没变就只回一行，不重发正文（`force: true` 强制重发）。 |
+| `browser_read` | 按人读文章的方式给 Markdown（标题、段落、列表、链接）。带 `query` 只回能回答的那几句（段落排序后再按句子打分，标题、位置、链接密度做先验，重复句去掉，按字符预算装箱）；问不到时自动改为整页，不再空手回来。页面和上次读的没变就只回一行，不重发正文（`force: true` 强制重发）。 |
 | `browser_extract` | 按 CSS 选择器把列表项读成一行一条、带链接，比整页读省得多。 |
 | `browser_view` 的 `map` | 大页面先看地标：各类控件各多少个、去重后的控件和编号、正文多少字，但不带回正文。 |
 | `browser_click` | 点编号控件，或点 `x`/`y` 坐标。`double: true` 双击。控件被横幅或弹层挡着时，先关掉它再点。 |
@@ -20,7 +20,8 @@ profile，不是产品自带的那个浏览页签：右栏放的是它的画面
 | `browser_scroll` | 在页面中心滚轮，也可以指定 `x`/`y`。`dy: 600` 约一屏。 |
 | `browser_shot` | 存一张 PNG 到 `~/.dsh/inner-browser-use/screenshots`，返回路径；`region: [x, y, w, h]` 只截一块（游戏、图表、看局部）。 |
 | `browser_media` | 列出页面已经请求过的视频和声音（带大小），页面自己播放器里那个排第一、标 `main`；`save: <行号>`、`save: main` 或地址片段存下来。广告和统计默认不出现（`all: true` 才看），`watch: false` 关掉这个页面的记录。流会顺着播放列表把片段取回拼好，不用装任何东西。 |
-| `browser_state` | 报浏览器在不在跑、用的哪个 profile、地址、标题，以及有几个右栏在看它。 |
+| `browser_login` | 按名字留住登录：`save` 存下当前窗口的 cookie 和各站的 localStorage，`list` 看有哪些，`use` 切回那个账号并重开页面，`drop` 忘掉。名字跟着浏览器走、不跟着一个会话走，重启也在；同一站点两个账号就存两个名字。磁盘上那一份是加密的，钥匙在系统钥匙串里。 |
+| `browser_state` | 报浏览器在不在跑、用的哪个 profile、地址、标题、有几个右栏在看它，以及它此刻占多少内存、没人用的话还有多久关闭。 |
 
 点、输入、按键之后的那一行会多一句结果：`· navigated to …`（换页了）、`· content changed`（页内有变化）、`· no visible change`（点了没动）、Flash 页则是 `· screen updated` / `· no frame change`；`read: true` 时不再多说。
 

package/docs/ARCHITECTURE.md

@@ -165,10 +165,70 @@ picture comes back on the mutation that satisfies it. A page that changes 137 ms
 starts answers at 138 ms, not at the next 100 ms tick — the same reason `idle` (a mutation-free
 window) costs one round trip on an animation-heavy page instead of one per frame.
 
+## Reading for an answer
+
+`browser_read` with a `query` does not return the page; it returns the sentences that answer the
+question. The page-side block reader already returns paragraphs with their heading and link
+density, so the work stays in `read.js` and costs no extra round trip.
+
+Paragraphs are ranked first (BM25 over the question's terms, link-heavy menus down-weighted), then
+split into sentences. Each sentence is scored on its own with the same saturation and length
+normalisation, and that score is multiplied by three priors: the words of its heading, the rank of
+the paragraph it sits in, and inverse link density. Words the page says everywhere are dropped
+before scoring — a term in most sentences cannot point at anything — and a sentence that matches
+only part of the question is scaled by the share of the question's idf weight it actually covers,
+which is what stops a paragraph containing "to" from competing with one containing "refund".
+
+Selection is not "the top N scores": each pick subtracts its Jaccard overlap with what is already
+chosen (MMR), selection stops when the best remaining sentence is worth nothing, and picked
+sentences are packed to a character budget and restored to document order. Terms are folded
+(plurals, trailing `-ing`/`-ed`) so a question can use a different inflection than the page.
+
+`sentences: false` keeps the paragraph path for callers who want the whole section.
+
+## Sign-ins and reclaim
+
 Sign-in state lives in the profile, and session cookies — the kind a sign-in usually sets,
 which Chrome would otherwise drop on exit — are saved next to it and restored on the next
 launch, so a restart of the app does not sign the person out.
 
+Three layers, each adding one thing the previous cannot do:
+
+- **The profile** keeps everything Chrome writes: dated cookies, origin storage, service
+  workers. It survives a restart of the app and a restart of the machine.
+- **The session jar** (`session-cookies.json`) covers the part Chrome throws away on exit.
+  Every cookie that comes back from `page.cookies()` without an expiry is written when the
+  browser closes, and put back on the next launch. A cookie the browser already holds is
+  never overwritten from the jar — a rotation happened in the live browser, and the jar is
+  the older truth.
+- **`browser_login`** (`vault.js`) turns that state into named snapshots a chat can call
+  back: cookies plus per-origin `localStorage`, saved under a name, listed, restored, or
+  dropped. `list` is a directory read, so it costs nothing while the browser is down.
+  Restoring writes cookies first, then navigates to each stored origin to write its local
+  storage (the API is origin-bound), then reopens the page that was saved.
+
+Everything written at rest is sealed with AES-256-GCM (`{v, alg, iv, tag, data}`, all
+base64). The key comes from `DSH_INNER_BROWSER_VAULT_KEY` when a test sets one, otherwise
+from the macOS keychain, otherwise from `vault.key` in the state root — 0600, and a fallback
+rather than the intended home, because an unattended `security add-generic-password` can
+block on a prompt. A tampered blob, a wrong key and a truncated file all come back empty;
+nothing trusts what it cannot verify. A plaintext jar from a version before this one is
+still read and re-sealed on the next write, so an upgrade does not sign anyone out.
+
+The reclaim ladder is three separate timers, because they answer three different questions:
+
+| Question | Timer | What happens |
+| --- | --- | --- |
+| Did the person close the column? | `REST_MS` = 60 s | The browser is put away a minute after the last pane lets go. |
+| Has nobody touched it at all? | `IDLE_MS` = 15 min | The whole process is reclaimed, but never while a pane is still watching a frame. |
+| Is this one tab stale? | `TAB_IDLE_MS` = 10 min, `MAX_TABS` = 6 | The tab is closed, not the browser; a returning chat gets a fresh page instead of a dead one (`expired`). |
+
+`browser_state` reports both what the process costs right now (`ps` over its process tree,
+which includes renderers, not just the parent) and `closesIn`, so the model can decide
+between keeping the page and letting it go instead of guessing. A freeze
+(`Page.setWebLifecycleState`) is deliberately not wired in: closing a stale tab is already
+cheap, and a frozen page that misses a mutation would make the event-driven wait lie.
+
 A system-prompt section (`browser-in-this-chat`) tells the model to reach for these tools
 without asking first when someone wants something done on a site.
 

package/docs/ARTIFACTS.md

@@ -22,12 +22,14 @@
 ~/.dsh-inner-browser-use/
   artifacts/<项目>/<会话>/<种类>/   给人看的产出，只在这里（见上）
   chrome/                          浏览器自己的数据：登录态、Cookie、缓存
+  logins/                          按名字留住的登录，一个名字一个文件，加密
+  vault.key                        钥匙串拿不到钥匙时的替代文件，只有本人可读
   flash/                           Flash 播放器运行时，第一次用 flash:true 才装
   browser.log                     最近一次浏览器启动和页面记录
   asks.log                        人问过什么、答了什么
   tabs.json / mirror.json / flash.json / watcher.json   上次开着哪些页
 ```
 
-`chrome/` 是浏览器进程自己在读写，不要手动改；要清登录态，用 `browser_open` 的档位或插件自己的入口，别删目录里的某个文件。上面这些都在一个根目录下，卸载插件前想留产出就拷 `artifacts/`。
+`chrome/session-cookies.json` 是 Chrome 退出时会丢的会话 cookie，加密后存在 profile 旁边；`logins/` 与 `vault.key` 由 `browser_login` 和启动时自动保存的登录备份共用，不要手动改或删，要清就用 `browser_login({action:"drop"})`。`chrome/` 其余部分是浏览器进程自己在读写，不要手动改；要清登录态，用 `browser_open` 的档位或插件自己的入口，别删目录里的某个文件。上面这些都在一个根目录下，卸载插件前想留产出就拷 `artifacts/`。
 
 测试里用 `DSH_INNER_BROWSER_ARTIFACTS` 指向临时目录，不写真实 home。

package/docs/BENCH.md

@@ -1,3 +1,34 @@
+## 只读答案那几句（0.40.0）
+
+同一张本地故事页：24 段会议记录里夹着一段账单说明，问题是「退款多久到账」。一条路按段
+落读（`sentences: false`），另一条走默认的句子级证据。
+
+| 项 | 整页段落 | 句子证据 |
+| --- | --- | --- |
+| 回来的字符数 | 1172 | 90 |
+| 折合 token | 345 | 26 |
+| 答案还在 | 是 | 是（`30 days`） |
+| 命中的块 / 总块 | 8 / 49 | 1 / 49 |
+| 读这一趟 | — | 11 ms |
+
+省下 92%，`read-answer` 预算 250 ms。句子级这一步没有新增进程、没有模型、没有依赖：分句、
+打分、去重都在已有的阅读调用里完成。同一批里的 `read` / `read-repeat` / `read-changed` 行与
+0.39.0 持平（`dense` 6 ms / 337 token，`full` 6 ms / 624 token）。
+
+## 登录能留、能切、关得掉（0.39.0）
+
+本地页签在加载时写一个会话 cookie 和一个 `localStorage` 令牌，然后用工具层实际走一遍：保存 → 清空浏览器里的一切 → 切回。磁盘上那一份同时用字符串搜一遍。
+
+| 项 | 结果 |
+| --- | --- |
+| `browser_login {action:"save"}` | 2 ms，8 个 cookie |
+| `browser_login {action:"use"}`（清空后切回、重开页面） | 105 ms |
+| 切回后 cookie 与 `localStorage` | 都在（`signedIn: true`） |
+| 密文里能否搜到 cookie 值 / 令牌 | 搜不到（`sealed: true`） |
+| 预算 | `login-vault: 1600 ms`，19 项全过 |
+
+`browser_state` 另外报两行：当前进程树占多少内存（含渲染进程），以及没人用的话还有多久关闭——两者都来自 `ps` 一次采样和已有的空闲计时器，不额外起进程。关闭策略没变：右栏关掉约 1 分钟、没人碰约 15 分钟回收整个浏览器，页签 10 分钟不动、最多 6 个。
+
 ## 等到变化，而不是去问（0.38.0）
 
 `browser_wait` 以前在宿主侧每 100 毫秒读一次页面判断条件，命中与否都被凑到下一个整拍上。

package/index.js

@@ -941,6 +941,8 @@ export function apply(ctx) {
         '不要用它：读公开文章、单个链接正文、文档、搜索结果摘要、GitHub 仓库或 PR 页面——这些能用 `web_fetch` / envoy 读就不用浏览器；一打开就是一个后台 Chrome 进程加一个页签，会话多了很占内存。',
         '也不要用它做连通性、可达性、服务是否起来的检查：那是一个 HTTP 请求的事，`web_fetch` 或 `curl` 就够，开浏览器只会多一个进程和一栏画面。只有「这一步必须在真实浏览器里点/填/登录」才轮到它。',
         '人点名之后不问、不另起外部 Chrome；画面留在本会话右栏，做完保留，不主动关。',
+        '登录态属于浏览器，不属于某个会话：`browser_login` 的 `save` 把当前登录按名字留存（`list` 看、`use` 切账号、`drop` 忘掉），换会话、重启都还在；同一站点要多个账号就存成不同名字。留存的登录凭据在磁盘上是加密的，密钥在系统钥匙串里。人让你登录时先 `browser_login` 的 `list` 看一眼有没有可复用的，再决定要不要重新登。',
+        '浏览器不用时自己让位：右栏关掉约一分钟后、没人碰约一刻钟后回收整个进程，页签十分钟不动、最多六个；`browser_state` 会给出它现在占多少内存和还有多久关闭。人还在看的时候不关。',
         '先接着用已有的页：`browser_view`（拿编号控件与可见文字）→ `browser_click` / `browser_type` → 再 `browser_view` 直到出现要的结果；页面要等就重复读，不 sleep。`browser_open` 只用于没有页、要换新地址、或要明确刷新；同一个地址不要反复重开。',
         '页面很长、只想确认某句话/按钮在哪时用 `browser_find`，别整页读。要读长文（文章、文档、issue、论坛帖）用 `browser_read`：它回 Markdown，只花几十分之一的 token，链接可点；要动手点、填表才用 `browser_view` 拿编号。',
         '要保存页面样子用 `browser_shot`，它会给出 PNG 绝对路径；要交给人看的文件，把绝对路径写进回复。',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-inner-browser-use",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "An agent-owned Chromium sidecar mirrored into the DeepSeek Harness right column: the agent drives it, the person watches and can take the mouse, and logins survive restarts.",
   "type": "module",
   "main": "index.js",
@@ -18,6 +18,7 @@
     "read.js",
     "review.js",
     "media.js",
+    "vault.js",
     "client.js",
     "locale/*.json",
     "cordis.patch.yml",
@@ -49,7 +50,7 @@
     "dsh": ">=0.2.0"
   },
   "scripts": {
-    "test": "node --test test/artifacts.test.mjs test/client.test.mjs test/cookies.test.mjs test/diff.test.mjs test/fresh.test.mjs test/host.test.mjs test/input.test.mjs test/isolation.test.mjs test/keyboard.test.mjs test/leak.test.mjs test/login.test.mjs test/media.test.mjs test/no-duplicate.test.mjs test/package.test.mjs test/readfault.test.mjs test/refs.test.mjs test/review.test.mjs test/session.test.mjs test/settle.test.mjs test/sidecar.test.mjs test/swf.test.mjs test/tabs.test.mjs test/trouble.test.mjs",
+    "test": "node --test test/artifacts.test.mjs test/client.test.mjs test/cookies.test.mjs test/diff.test.mjs test/fresh.test.mjs test/host.test.mjs test/input.test.mjs test/isolation.test.mjs test/keyboard.test.mjs test/leak.test.mjs test/login.test.mjs test/media.test.mjs test/no-duplicate.test.mjs test/package.test.mjs test/readfault.test.mjs test/refs.test.mjs test/review.test.mjs test/session.test.mjs test/settle.test.mjs test/sidecar.test.mjs test/swf.test.mjs test/tabs.test.mjs test/trouble.test.mjs test/vault.test.mjs",
     "doctor": "node scripts/doctor.mjs",
     "breadth": "node scripts/breadth.mjs",
     "live": "node scripts/live.mjs",

package/read.js

@@ -1185,7 +1185,22 @@ const tokenPattern = /[a-z0-9]+|[\u3400-\u9fff]/g
  * @returns {string[]} lower-case terms.
  */
 export function terms(text) {
-  return String(text ?? '').toLowerCase().match(tokenPattern) ?? []
+  const raw = String(text ?? '').toLowerCase().match(tokenPattern) ?? []
+  return raw.map(fold)
+}
+
+/** "refunds" and "refund" are the same idea; a light fold lets a question that
+ * says one word find a page that says the other. Deliberately not a stemmer —
+ * no dictionary, no suffix table beyond plurals and a trailing -ing/-ed. */
+function fold(word) {
+  if (word.length <= 3 || /[0-9]/.test(word) || /[^a-z]/.test(word)) return word
+  if (word.endsWith('ies') && word.length > 4) return `${word.slice(0, -3)}y`
+  if (word.endsWith('sses')) return word.slice(0, -2)
+  if (word.endsWith('ing') && word.length > 5) return word.slice(0, -3)
+  if (word.endsWith('ed') && word.length > 4 && !word.endsWith('eed')) return word.slice(0, -2)
+  if (word.endsWith('es') && word.length > 4) return word.slice(0, -2)
+  if (word.endsWith('s') && !word.endsWith('ss') && !word.endsWith('us') && !word.endsWith('is')) return word.slice(0, -1)
+  return word
 }
 
 /** How often a term may occur before it stops adding meaning. */
@@ -1230,6 +1245,134 @@ export function rank(blocks, query) {
   return scored
 }
 
+/** A sentence ends at a full stop, a question mark, an exclamation, or their
+ * CJK equivalents; a very short fragment joins its neighbour rather than
+ * travelling alone. */
+const SENTENCE_BREAK = /(?<=[。！？；])|(?<=[.!?;])\s+/u
+
+/**
+ * @param {string} text - a paragraph.
+ * @returns {string[]} its sentences, trimmed.
+ */
+export function sentences(text) {
+  const raw = String(text ?? '').replace(/\s+/g, ' ').trim()
+  if (raw === '') return []
+  const out = []
+  for (const piece of raw.split(SENTENCE_BREAK)) {
+    const one = piece.trim()
+    if (one === '') continue
+    /* A full stop inside "e.g." leaves a fragment whose continuation starts
+       lowercase; that is the one case where the break was not real. */
+    const continues = /^[a-z(]/.test(one) || out[out.length - 1]?.length < 4
+    if (out.length > 0 && continues) out[out.length - 1] = `${out[out.length - 1]} ${one}`
+    else out.push(one)
+  }
+  return out
+}
+
+/**
+ * The sentences that answer a query, chosen the way a retriever picks
+ * evidence: BM25 over sentences, a prior for the paragraph and heading they
+ * sit in, and maximal-marginal-relevance so the second sentence adds
+ * something the first did not say. Purely local — no model, no network.
+ * @param {{h?: string, t?: string, d?: number}[]} blocks - paragraphs.
+ * @param {string} query - what the caller wants to know.
+ * @param {{maxChars?: number, limit?: number, blocks?: number, lambda?: number}} [options] - ceilings.
+ * @returns {{rows: {text: string, heading: string, at: number, step: number}[], total: number, matched: number}} picked sentences in page order.
+ */
+export function evidence(blocks, query, options = {}) {
+  const typed = terms(query)
+  if (typed.length === 0) return { rows: [], total: blocks.length, matched: 0 }
+  const near = rank(blocks, query).slice(0, Math.max(1, Math.min(60, Number(options.blocks ?? 40))))
+  const units = []
+  for (const row of near) {
+    const heading = String(row.block.h ?? '')
+    const body = String(row.block.t ?? '')
+    const parts = sentences(body)
+    for (let step = 0; step < parts.length; step += 1) {
+      const spoken = terms(parts[step])
+      if (spoken.length === 0) continue
+      units.push({ text: parts[step], terms: spoken, heading, at: blocks.indexOf(row.block), step, prior: row.score, block: row.block })
+    }
+  }
+  if (units.length === 0) return { rows: [], total: blocks.length, matched: 0 }
+  const total = Math.max(1, units.length)
+  const seen = new Map()
+  for (const unit of units) for (const term of new Set(unit.terms)) seen.set(term, (seen.get(term) ?? 0) + 1)
+  const average = units.reduce((sum, unit) => sum + unit.terms.length, 0) / total
+  /* A word the page says everywhere cannot point at anything: "to" is in every
+     paragraph of a long article. Keep the terms that actually narrow the page;
+     if the question is all common words, keep them all. */
+  const weight = (term) => {
+    const inHowMany = seen.get(term) ?? 0
+    return inHowMany === 0 ? 0 : Math.log(1 + (total - inHowMany + 0.5) / (inHowMany + 0.5))
+  }
+  const sharp = typed.filter((term) => weight(term) >= 0.5)
+  const asked = sharp.length > 0 ? sharp : typed
+  const askedWeight = asked.reduce((sum, term) => sum + weight(term), 0)
+  for (const unit of units) {
+    const counts = new Map()
+    for (const term of unit.terms) counts.set(term, (counts.get(term) ?? 0) + 1)
+    let score = 0
+    let covered = 0
+    for (const term of asked) {
+      const tf = counts.get(term) ?? 0
+      if (tf === 0) continue
+      covered += weight(term)
+      score += weight(term) * ((tf * (SATURATION + 1)) / (tf + SATURATION * (1 - 0.75 + (0.75 * unit.terms.length) / average)))
+    }
+    /* Matching one frequent word of a nine-word question is not evidence; the
+       share of the question's weight the sentence actually answers is. */
+    score *= covered / Math.max(1e-6, askedWeight)
+    /* The paragraph's own relevance and the words of the heading it sits under
+       both say "this is the right place", so they lift their sentences. */
+    const headingHit = asked.filter((term) => terms(unit.heading).includes(term)).length
+    /* A menu sentence can match the words without saying anything about them;
+       the paragraph's link density is what tells the two apart. */
+    const linkish = 1 - 0.8 * Number(unit.block?.d ?? 0)
+    unit.score = score * linkish * (1 + 0.25 * headingHit) * (1 + 0.5 * (unit.prior > 0 ? 1 : 0))
+  }
+  /* Below a fifth of the best sentence, a match is coincidence rather than
+     evidence; carrying it only costs tokens. */
+  const best = units.reduce((top, unit) => Math.max(top, unit.score), 0)
+  for (const unit of units) if (unit.score < best * 0.2) unit.score = 0
+  const lambda = Math.max(0, Math.min(0.9, Number(options.lambda ?? 0.35)))
+  const ceiling = Math.max(200, Math.min(24_000, Number(options.maxChars ?? 4000)))
+  const limit = Math.max(1, Math.min(60, Number(options.limit ?? 24)))
+  const chosen = []
+  const left = units.filter((unit) => unit.score > 0)
+  let used = 0
+  let lastHeading = ''
+  while (left.length > 0 && chosen.length < limit) {
+    let best = -1
+    let bestValue = -Infinity
+    for (let i = 0; i < left.length; i += 1) {
+      const candidate = left[i]
+      const spoken = new Set(candidate.terms)
+      let overlap = 0
+      for (const picked of chosen) {
+        const other = new Set(picked.terms)
+        let shared = 0
+        for (const term of spoken) if (other.has(term)) shared += 1
+        overlap = Math.max(overlap, shared / Math.max(1, spoken.size + other.size - shared))
+      }
+      const value = candidate.score * (1 - lambda) - lambda * overlap
+      if (value > bestValue) { bestValue = value; best = i }
+    }
+    /* Once the best sentence left is no better than nothing — or is simply a
+       repeat of one already picked — the answer is complete. */
+    if (best < 0 || bestValue <= 0) break
+    const pick = left.splice(best, 1)[0]
+    const heading = pick.heading !== lastHeading && pick.heading !== '' ? pick.heading.length + 8 : 0
+    if (used + pick.text.length + heading > ceiling && chosen.length > 0) break
+    lastHeading = pick.heading
+    used += pick.text.length + heading
+    chosen.push(pick)
+  }
+  chosen.sort((a, b) => a.at - b.at || a.step - b.step)
+  return { rows: chosen.map((one) => ({ text: one.text, heading: one.heading, at: one.at, step: one.step })), total: blocks.length, matched: chosen.length }
+}
+
 /**
  * Read only the passages of a page that answer a query, so a long page costs
  * what the answer costs instead of what the page costs.
@@ -1248,12 +1391,19 @@ export async function readRelevant(page, query, options = {}) {
     if (ranked.length === 0) {
       return { title: String(said?.title ?? page.title ?? ''), url: String(page.url ?? ''), text: '', chars: 0, matched: 0, total: all.length }
     }
-    const limit = Math.max(1, Math.min(20, Number(options.limit ?? 8)))
+    /* Passages cost whole paragraphs; sentences cost only the ones that say
+       something about the query, which on a long page is most of the saving. */
+    let pieces = ranked
+    if (options.sentences !== false) {
+      const picked = evidence(all, query, { maxChars: budget, limit: options.limit, blocks: options.blocks, lambda: options.lambda })
+      pieces = picked.rows.map((row) => ({ block: { h: row.heading, t: row.text }, score: 0 }))
+    }
+    const limit = Math.max(1, Math.min(60, Number(options.limit ?? (options.sentences === false ? 8 : 24))))
     const lines = []
     let used = 0
     let matched = 0
     let lastHeading = ''
-    for (const row of ranked.slice(0, limit)) {
+    for (const row of pieces.slice(0, limit)) {
       const body = String(row.block.t ?? '')
       if (used + body.length > budget) continue
       const heading = String(row.block.h ?? '')

package/sidecar.js

@@ -6,11 +6,12 @@
  * shows it as a screencast, so the tab is a viewer, not the browser.
  */
 import { execFileSync, spawn, spawnSync } from 'node:child_process'
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, appendFileSync } from 'node:fs'
+import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { readyFlash } from './runtime/flash-setup.mjs'
+import { readSealed, tightenDir, writeSealed } from './vault.js'
 import { isMedia, kindOf } from './media.js?m=1'
 
 /**
@@ -113,6 +114,44 @@ const TAB_IDLE_MS = 10 * 60_000
 /** @param {number} ms - how long to wait. @returns {Promise<void>} resolves after it. */
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 
+/** @param {number} root - a process id. @returns {number} bytes of RSS the process tree holds. */
+function treeBytes(root) {
+  if (!Number.isFinite(root) || root <= 0) return 0
+  try {
+    const rows = execFileSync('ps', ['-Ao', 'pid=,ppid=,rss='], { encoding: 'utf8', timeout: 3000 })
+      .trim()
+      .split('\n')
+      .map((line) => line.trim().split(/\s+/u))
+      .filter((cols) => cols.length >= 3)
+    /** @type {Map<number, number[]>} */
+    const byParent = new Map()
+    /** @type {Map<number, number>} */
+    const size = new Map()
+    for (const [pid, ppid, rss] of rows) {
+      const parent = Number(ppid)
+      const kids = byParent.get(parent) ?? []
+      kids.push(Number(pid))
+      byParent.set(parent, kids)
+      size.set(Number(pid), Number(rss) * 1024)
+    }
+    let total = size.get(root) ?? 0
+    const queue = [root]
+    const seen = new Set()
+    while (queue.length > 0) {
+      const pid = queue.shift()
+      if (seen.has(pid)) continue
+      seen.add(pid)
+      for (const kid of byParent.get(pid) ?? []) {
+        total += size.get(kid) ?? 0
+        queue.push(kid)
+      }
+    }
+    return total
+  } catch {
+    return 0
+  }
+}
+
 /** @param {string} path - candidate. @returns {string | undefined} the one that exists. */
 function firstBinary() {
   return CHROME_BINARIES.find((path) => existsSync(path))
@@ -348,9 +387,19 @@ export function snapshotLogin(dir) {
   const files = COOKIE_FILES.map((name) => ({ name, from: join(dir, name) })).filter((row) => existsSync(row.from))
   if (files.length === 0) return 0
   const to = loginBackupDir(dir)
-  mkdirSync(to, { recursive: true })
+  /* A copy of a cookie store is a copy of every sign-in in it: nobody else gets
+     to read the folder or the files, even on a shared machine. */
+  tightenDir(to)
   const stamp = String(Date.now())
-  for (const row of files) copyFileSync(row.from, join(to, `${stamp}-${row.name.replace(/\//g, '_')}`))
+  for (const row of files) {
+    const target = join(to, `${stamp}-${row.name.replace(/\//g, '_')}`)
+    copyFileSync(row.from, target)
+    try {
+      chmodSync(target, 0o600)
+    } catch {
+      /* best effort */
+    }
+  }
   const mine = readdirSync(to).filter((name) => name.startsWith(`${stamp}-`))
   const older = readdirSync(to).filter((name) => !mine.includes(name)).sort()
   const generations = 5
@@ -2996,6 +3045,7 @@ export class Sidecar {
    * @param {number} [ms] - how long a browser nobody watches may stay up.
    */
   touch(ms = IDLE_MS) {
+    this.idleAt = Date.now() + ms
     if (this.idle !== null) clearTimeout(this.idle)
     this.idle = setTimeout(() => {
       this.idle = null
@@ -3087,6 +3137,7 @@ export class Sidecar {
   }
 
   async shutdown() {
+    this.idleAt = 0
     /* A browser this process did not start belongs to somebody else — another
        app on the same profile, or a script that connected to it — and closing
        it would close the person's window. Let go of it instead: drop the socket
@@ -3158,7 +3209,7 @@ export class Sidecar {
         rmSync(file, { force: true })
         return
       }
-      writeFileSync(file, JSON.stringify(jar), { mode: 0o600 })
+      writeSealed(file, jar)
     } catch {
       /* a browser that is already gone has nothing to save */
     }
@@ -3166,12 +3217,9 @@ export class Sidecar {
 
   /** @returns {Promise<void>} puts back what saveSessionCookies kept. */
   async restoreSessionCookies() {
-    let jar = []
-    try {
-      jar = JSON.parse(String(readFileSync(sessionJar(profileDir(this.profile)), 'utf8')))
-    } catch {
-      return
-    }
+    /* Sealed by this version; plain JSON by one before it. Both are read, so an
+       update never signs anyone out. */
+    const jar = readSealed(sessionJar(profileDir(this.profile)))
     if (!Array.isArray(jar)) return
     /* A cookie the browser already holds is newer than the note: the site may
        have rotated its session id since the note was written, and putting the
@@ -3250,6 +3298,12 @@ export class Sidecar {
          screenshot is in this space, not in the window's. */
       viewport: this.page?.view ?? null,
       profiles,
+      /* What this browser costs right now: the whole process tree, renderers
+         included. Reported so a chat can decide whether to let it rest. */
+      memory: this.alive ? treeBytes(Number(this.child?.pid ?? 0)) : 0,
+      /* When it would close itself if nobody came back, and why: 0 means the
+         browser is either watched or not on a clock. */
+      closesIn: this.idle === null || this.stopping === true ? 0 : Math.max(0, Number(this.idleAt ?? 0) - Date.now()),
       error: this.alive ? '' : this.lastError,
     }
   }

package/tools.js

@@ -16,6 +16,7 @@ import { basename, join } from 'node:path'
 import { mkdir, readdir, stat, unlink, writeFile } from 'node:fs/promises'
 import { VIEW, DESKTOP_UA } from './sidecar.js?v=1'
 import { planOf, gather, sizeText, coreRows } from './media.js?m=2'
+import { dropLogin, listLogins, readLogin, saveLogin, vaultState } from './vault.js'
 import { readPage, renderPage, readArticle, readRelevant, findOnPage, locate, locateFirst, FRAME_BASE, covering, contextFor, identityOf, sameThing, differs, labelSpot, selectSpot, bounds, pictures, clickInDom, writeInDom, REF_GONE } from './read.js?v=1'
 import { brief as askBrief, recordRound, lastRoundNote, lastRound, markRound, MARK_STATUS } from './review.js?v=1'
 
@@ -965,6 +966,56 @@ async function evaluate(page, expression, route, raceMs = 2000) {
   return result?.value
 }
 
+/**
+ * The local storage a page is holding, per origin: some sites keep the sign-in
+ * itself there and cookies alone would come back signed out.
+ * @param {any} page - sidecar page.
+ * @returns {Promise<Array<{origin: string, items: Record<string, string>}>>} what it holds.
+ */
+async function storageOf(page) {
+  const raw = await evaluate(
+    page,
+    '(() => { try { const items = {}; for (let i = 0; i < localStorage.length; i += 1) { const key = localStorage.key(i); if (key !== null) items[key] = String(localStorage.getItem(key)).slice(0, 4000); } return JSON.stringify([{ origin: location.origin, items }]) } catch { return "[]" } })()',
+    null,
+    4000,
+  )
+  let rows = []
+  try {
+    rows = JSON.parse(String(raw ?? '[]'))
+  } catch {
+    return []
+  }
+  if (!Array.isArray(rows)) return []
+  return rows
+    .filter((row) => row !== null && typeof row === 'object' && typeof row.origin === 'string' && row.items !== null && typeof row.items === 'object')
+    .map((row) => ({ origin: String(row.origin), items: Object.fromEntries(Object.entries(row.items).slice(0, 200).map(([key, value]) => [key, String(value)])) }))
+}
+
+/**
+ * Puts one origin's local storage back. The page has to be on that origin to
+ * write to it, so this navigates there first — a sign-in that lives in local
+ * storage is worth the extra step.
+ * @param {any} page - sidecar page.
+ * @param {{origin: string, items: Record<string, string>}} row - what to put back.
+ * @returns {Promise<number>} how many entries went in.
+ */
+async function restoreStorage(page, row) {
+  if (String(row?.origin ?? '') === '' || page === null) return 0
+  try {
+    const here = String(page.url ?? '')
+    if (!here.startsWith(String(row.origin))) await page.navigate(String(row.origin))
+  } catch {
+    return 0
+  }
+  const written = await evaluate(
+    page,
+    `(() => { try { const items = ${JSON.stringify(row.items ?? {})}; for (const [key, value] of Object.entries(items)) localStorage.setItem(key, value); return Object.keys(items).length } catch { return 0 } })()`,
+    null,
+    4000,
+  )
+  return Number(written) || 0
+}
+
 /**
  * What the page looks like in one cheap string: address, title, how many
  * elements and how much text. Two of these equal says the click did nothing
@@ -3050,6 +3101,10 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
           `mirror owner ${owner === '' ? 'none' : owner}`, // ui-copy-ignore
           owner === '' ? 'no owner' : `owner ${owner}`,
           `refs followed ${String(follows.count)}`,
+          /* What it costs and when it would let go: the two facts that decide
+             whether to keep using it or let it rest. */
+          state.alive === true ? `memory ${Math.max(1, Math.round(Number(state.memory ?? 0) / 1048576))} MB` : 'memory 0 MB',
+          state.closesIn > 0 ? `closes in ${Math.max(1, Math.round(Number(state.closesIn) / 60_000))} min unless used` : 'no close scheduled',
           holdText(sidecar) === '' ? 'person free' : `person using it (${String(Math.ceil(Number(sidecar.holding()) / 1000))} s left)`,
         ]
         if (state.alive === true && viewerNote(state.viewers) !== '') rows.push(NO_VIEWER)
@@ -3057,6 +3112,86 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       },
     },
 
+    {
+      name: 'browser_login', // ui-copy-ignore
+      description: 'Sign-ins belong to the browser, not to a chat: every chat uses them and they survive a restart. "save" keeps the sign-in showing right now under a name, "list" shows what is kept, "use" signs the browser back in as that account and reopens the page, "drop" forgets it. What is written is sealed, and the key is the one in the system keystore. One site can hold several accounts: save them under different names and switch with "use".',
+      parameters: { // ui-copy-ignore
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['list', 'save', 'use', 'drop'], description: 'list, save, use or drop.' },
+          name: { type: 'string', description: 'Account name, for example "work" or "personal". Needed by save, use and drop.' },
+        },
+        required: ['action'], // ui-copy-ignore
+        additionalProperties: false,
+      },
+      output: TEXT_OUTPUT, // ui-copy-ignore
+      timeoutMs: 25_000,
+      isConcurrencySafe: () => false,
+      /** @param {any} args - action and name. @returns {Promise<{text: string}>} what happened. */
+      execute: async (args) => {
+        const action = String(args?.action ?? '')
+        if (action === 'list') {
+          const rows = listLogins()
+          const shape = vaultState()
+          if (rows.length === 0) {
+            return { text: 'Nothing saved yet. Sign in on the site, then browser_login {action:"save", name:"work"}.' }
+          }
+          const head = `${rows.length} kept sign-in${rows.length === 1 ? '' : 's'}, ${Math.max(1, Math.round(shape.bytes / 1024))} KB sealed${shape.keyInKeychain ? ', key in the system keystore' : ''}`
+          const lines = rows.map((row) => {
+            const sites = row.origins.length === 0 ? '' : `, ${row.origins.join(' ')}`
+            return `${row.name} — ${row.cookieCount} cookies${sites}, saved ${new Date(row.savedAt).toLocaleString()}`
+          })
+          return { text: [head, ...lines].join('\n') }
+        }
+        const name = String(args?.name ?? '').trim()
+        if (name === '') return { text: 'Name the account: browser_login {action:"save", name:"work"}.' }
+        if (action === 'drop') {
+          return { text: dropLogin(name) ? `Forgot "${name}".` : `Nothing saved as "${name}".` }
+        }
+        if (action === 'save') {
+          const page = await sidecar.ensure({ session: currentSession() })
+          const cookies = await page.cookies()
+          const storage = await storageOf(page)
+          const kept = saveLogin(name, { cookies, storage, url: String(page.url ?? '') })
+          const sites = kept.origins.length === 0 ? '' : ` and ${kept.origins.length} site${kept.origins.length === 1 ? '' : 's'} of local storage`
+          return { text: `Saved "${kept.name}": ${kept.cookieCount} cookies${sites}, sealed on disk.` }
+        }
+        if (action === 'use') {
+          const held = readLogin(name)
+          if (held === null) return { text: `Nothing saved as "${name}". browser_login {action:"list"} shows what is kept.` }
+          const page = await sidecar.ensure({ session: currentSession() })
+          let put = 0
+          for (const cookie of (Array.isArray(held.cookies) ? held.cookies : []).slice(0, 400)) {
+            const domain = String(cookie?.domain ?? '').replace(/^\./u, '')
+            if (domain === '' || cookie?.name === undefined) continue
+            try {
+              await page.setCookie({
+                name: String(cookie.name),
+                value: String(cookie.value ?? ''),
+                domain,
+                path: String(cookie.path ?? '/'),
+                secure: cookie.secure === true,
+                httpOnly: cookie.httpOnly === true,
+                sameSite: cookie.sameSite,
+                expires: cookie.session === true ? undefined : Number(cookie.expires) || undefined,
+              })
+              put += 1
+            } catch {
+              /* one cookie a site refuses is not a reason to stop */
+            }
+          }
+          let stored = 0
+          for (const row of (Array.isArray(held.storage) ? held.storage : []).slice(0, 4)) stored += await restoreStorage(page, row)
+          const back = String(held.url ?? '')
+          if (back !== '') await page.navigate(back)
+          else await page.reload()
+          const said = stored === 0 ? '' : `, ${stored} local storage entries`
+          return { text: `Signed in as "${name}": ${put} cookies${said}, page reopened.` }
+        }
+        return { text: 'Pass action "list", "save", "use" or "drop".' }
+      },
+    },
+
     {
       name: 'browser_resume', // ui-copy-ignore
       description: 'Take the page back from the person at the mirror: clears the hold so the next action is sent at once, instead of waiting the few seconds out.',

package/vault.js

@@ -0,0 +1,333 @@
+/**
+ * Sign-in material at rest.
+ *
+ * A cookie jar is a password: whoever reads the file is signed in as the person.
+ * Chrome keeps its own store encrypted, but the copy this plugin makes when a
+ * session cookie would otherwise be dropped is a plain file, and a plain file in
+ * a home directory is one backup or one shared folder away from being someone
+ * else's session. Everything this plugin writes about a sign-in is therefore
+ * sealed with AES-256-GCM, and the key lives in the system Keychain — not next
+ * to the ciphertext, not in the profile, not in an environment variable by
+ * default.
+ *
+ * What stays unsealed is a name and a timestamp, so the list of accounts can be
+ * shown without opening the vault.
+ */
+import { createCipheriv, createDecipheriv, randomBytes, timingSafeEqual } from 'node:crypto'
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+const KEYCHAIN_SERVICE = 'dsh-inner-browser-use-vault'
+const KEY_BYTES = 32
+const IV_BYTES = 12
+
+/** @returns {string} where the browser state, and so the vault, lives. */
+export function vaultRoot() {
+  return process.env.DSH_INNER_BROWSER_STATE_DIR || join(homedir(), '.dsh', 'inner-browser-use')
+}
+
+/**
+ * The key, in order of preference: the one this run was handed (tests, or a
+ * person who keeps it in their own secret store), the one in the Keychain, the
+ * one on disk with owner-only permissions. A missing key is created once and
+ * then never rotated silently, because rotating it would sign everyone out.
+ * @returns {Buffer} 32 bytes.
+ */
+export function vaultKey() {
+  const given = String(process.env.DSH_INNER_BROWSER_VAULT_KEY ?? '')
+  if (given !== '') {
+    const raw = Buffer.from(given, 'base64')
+    if (raw.length === KEY_BYTES) return raw
+  }
+  const fromKeychain = readKeychain()
+  if (fromKeychain !== null) return fromKeychain
+  const file = join(vaultRoot(), 'vault.key')
+  if (existsSync(file)) {
+    const raw = Buffer.from(String(readFileSync(file, 'utf8')).trim(), 'base64')
+    if (raw.length === KEY_BYTES) return raw
+  }
+  const made = randomBytes(KEY_BYTES)
+  const written = writeKeychain(made)
+  if (written === true) return made
+  mkdirSync(vaultRoot(), { recursive: true })
+  writeFileSync(file, `${made.toString('base64')}\n`, { mode: 0o600 })
+  chmodSync(file, 0o600)
+  return made
+}
+
+/** @returns {Buffer|null} the Keychain copy, if this platform has one. */
+function readKeychain() {
+  if (process.platform !== 'darwin') return null
+  try {
+    const out = execFileSync('security', ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', 'vault', '-w'], {
+      encoding: 'utf8',
+      timeout: 4000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    const raw = Buffer.from(out.trim(), 'base64')
+    return raw.length === KEY_BYTES ? raw : null
+  } catch {
+    return null
+  }
+}
+
+/** @param {Buffer} key - the material. @returns {boolean} whether the Keychain took it. */
+function writeKeychain(key) {
+  if (process.platform !== 'darwin') return false
+  try {
+    execFileSync('security', ['add-generic-password', '-U', '-s', KEYCHAIN_SERVICE, '-a', 'vault', '-w', key.toString('base64')], {
+      timeout: 4000,
+      stdio: ['ignore', 'ignore', 'ignore'],
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** @returns {'env'|'keychain'|'file'|'none'} which of the three the key in use came from. */
+function keySource() {
+  const given = String(process.env.DSH_INNER_BROWSER_VAULT_KEY ?? '')
+  if (given !== '' && Buffer.from(given, 'base64').length === KEY_BYTES) return 'env'
+  if (readKeychain() !== null) return 'keychain'
+  const file = join(vaultRoot(), 'vault.key')
+  if (existsSync(file)) {
+    const raw = Buffer.from(String(readFileSync(file, 'utf8')).trim(), 'base64')
+    if (raw.length === KEY_BYTES) return 'file'
+  }
+  return 'none'
+}
+
+/**
+ * @param {unknown} value - anything JSON can hold.
+ * @returns {{v: number, alg: string, iv: string, tag: string, data: string}} the sealed blob.
+ */
+export function seal(value) {
+  const key = vaultKey()
+  const iv = randomBytes(IV_BYTES)
+  const cipher = createCipheriv('aes-256-gcm', key, iv)
+  const data = Buffer.concat([cipher.update(Buffer.from(JSON.stringify(value), 'utf8')), cipher.final()])
+  return {
+    v: 1,
+    alg: 'aes-256-gcm',
+    iv: iv.toString('base64'),
+    tag: cipher.getAuthTag().toString('base64'),
+    data: data.toString('base64'),
+  }
+}
+
+/**
+ * Opens a sealed blob. A tampered blob, a different key, or a plain array all
+ * come back as `undefined` rather than as data that might be trusted.
+ * @param {unknown} blob - what `seal` returned, or its JSON text.
+ * @returns {any} the value, or undefined.
+ */
+export function unseal(blob) {
+  let held = blob
+  if (typeof held === 'string') {
+    try {
+      held = JSON.parse(held)
+    } catch {
+      return undefined
+    }
+  }
+  if (held === null || typeof held !== 'object') return undefined
+  const row = /** @type {any} */ (held)
+  if (row.v !== 1 || row.alg !== 'aes-256-gcm') return undefined
+  try {
+    const key = vaultKey()
+    const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(String(row.iv), 'base64'))
+    decipher.setAuthTag(Buffer.from(String(row.tag), 'base64'))
+    const text = Buffer.concat([decipher.update(Buffer.from(String(row.data), 'base64')), decipher.final()])
+    return JSON.parse(text.toString('utf8'))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Reads a file that is either sealed or, from an older version, plain JSON.
+ * @param {string} path - the file.
+ * @returns {any} its value, or undefined.
+ */
+export function readSealed(path) {
+  let text = ''
+  try {
+    text = String(readFileSync(path, 'utf8'))
+  } catch {
+    return undefined
+  }
+  const opened = unseal(text)
+  if (opened !== undefined) return opened
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Writes a sealed file and makes sure nobody but the owner can read it, even if
+ * it was created earlier with looser permissions.
+ * @param {string} path - where.
+ * @param {unknown} value - what.
+ * @returns {void}
+ */
+export function writeSealed(path, value) {
+  writeFileSync(path, `${JSON.stringify(seal(value))}\n`, { mode: 0o600 })
+  try {
+    chmodSync(path, 0o600)
+  } catch {
+    /* a file system without permissions is not a reason to fail the save */
+  }
+}
+
+/** @param {string} path - a directory. @returns {void} owner-only, best effort. */
+export function tightenDir(path) {
+  try {
+    mkdirSync(path, { recursive: true, mode: 0o700 })
+    chmodSync(path, 0o700)
+  } catch {
+    /* best effort */
+  }
+}
+
+/* ------------------------------------------------------------------ logins */
+
+/**
+ * A name becomes a file name. Anything that could climb out of the directory or
+ * collide on a case-insensitive file system is folded to a safe character.
+ * @param {string} name - what the person called the account.
+ * @returns {string} the file stem.
+ */
+export function loginSlug(name) {
+  const raw = String(name ?? '').trim()
+  if (raw === '') return ''
+  return raw
+    .replace(/[^\w. -]/gu, '_')
+    .replace(/\s+/gu, '-')
+    .replace(/^[.-]+/u, '')
+    .slice(0, 48)
+}
+
+/** @returns {string} where named accounts live. */
+export function loginDir() {
+  const dir = join(vaultRoot(), 'logins')
+  tightenDir(dir)
+  return dir
+}
+
+/**
+ * @param {string} name - account name.
+ * @returns {string} the file for it.
+ */
+function loginFile(name) {
+  const slug = loginSlug(name)
+  return slug === '' ? '' : join(loginDir(), `${slug}.json`)
+}
+
+/**
+ * Keeps one account: cookies plus the local storage of the sites it was saved
+ * on. Sealed as a whole, so even the list of sites is not readable off disk.
+ * @param {string} name - account name.
+ * @param {{cookies: object[], storage: Array<{origin: string, items: Record<string, string>}>, url?: string}} payload - what to keep.
+ * @returns {{name: string, savedAt: number, cookieCount: number, origins: string[]}} what was written.
+ */
+export function saveLogin(name, payload) {
+  const file = loginFile(name)
+  if (file === '') throw new Error('a login needs a name')
+  const cookies = Array.isArray(payload?.cookies) ? payload.cookies.slice(0, 400) : []
+  const storage = Array.isArray(payload?.storage) ? payload.storage.slice(0, 40) : []
+  const savedAt = Date.now()
+  writeSealed(file, {
+    name: String(name).trim().slice(0, 80),
+    savedAt,
+    url: String(payload?.url ?? ''),
+    cookies,
+    storage,
+  })
+  return {
+    name: String(name).trim().slice(0, 80),
+    savedAt,
+    cookieCount: cookies.length,
+    origins: storage.map((row) => String(row?.origin ?? '')).filter(Boolean),
+  }
+}
+
+/**
+ * @param {string} name - account name.
+ * @returns {any|null} the kept account, or null.
+ */
+export function readLogin(name) {
+  const file = loginFile(name)
+  if (file === '' || !existsSync(file)) return null
+  const held = readSealed(file)
+  return held === undefined ? null : held
+}
+
+/**
+ * Everything in the vault, newest first. Only the envelope is needed for the
+ * list, but the envelope is sealed too, so this opens each file.
+ * @returns {Array<{name: string, savedAt: number, cookieCount: number, origins: string[]}>} the accounts.
+ */
+export function listLogins() {
+  const dir = loginDir()
+  const rows = []
+  let names = []
+  try {
+    names = readdirSync(dir).filter((name) => name.endsWith('.json'))
+  } catch {
+    return rows
+  }
+  for (const name of names) {
+    const held = readSealed(join(dir, name))
+    if (held === null || typeof held !== 'object') continue
+    rows.push({
+      name: String(held.name ?? name.replace(/\.json$/u, '')),
+      savedAt: Number(held.savedAt ?? 0),
+      cookieCount: Array.isArray(held.cookies) ? held.cookies.length : 0,
+      origins: Array.isArray(held.storage) ? held.storage.map((row) => String(row?.origin ?? '')).filter(Boolean) : [],
+    })
+  }
+  return rows.sort((a, b) => b.savedAt - a.savedAt)
+}
+
+/**
+ * @param {string} name - account name.
+ * @returns {boolean} whether something was there to remove.
+ */
+export function dropLogin(name) {
+  const file = loginFile(name)
+  if (file === '' || !existsSync(file)) return false
+  rmSync(file, { force: true })
+  return true
+}
+
+/**
+ * How big the vault is, and whether the key is outside it: the two facts a
+ * person wants when deciding whether a sign-in is safe to leave here.
+ * @returns {{files: number, bytes: number, keyInKeychain: boolean, keySource: string}} the shape.
+ */
+export function vaultState() {
+  const dir = loginDir()
+  let files = 0
+  let bytes = 0
+  try {
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith('.json')) continue
+      files += 1
+      bytes += statSync(join(dir, name)).size
+    }
+  } catch {
+    /* an empty vault is a valid vault */
+  }
+  const source = keySource()
+  return { files, bytes, keyInKeychain: source === 'keychain', keySource: source }
+}
+
+/** @param {string} path - two files. @param {Buffer} a - one. @param {Buffer} b - the other. @returns {boolean} same bytes. */
+export function sameKey(a, b) {
+  return a.length === b.length && timingSafeEqual(a, b)
+}