@gotcos/glasses-server 6.94.2 → 6.94.3

package/server/lib/session-find-redact.ts

@@ -0,0 +1,254 @@
+/**
+ * What may leave this Mac about a session, and in what shape (the "find" route, Control 0.5.363).
+ *
+ * Every string a decision model sees, and every string the route hands back as `judged_text`, goes through
+ * `redactForModel`: READ a bounded window, REDACT it, then CUT. The order is the point. The list titles a session by
+ * cutting its first line at 80 characters BEFORE any redaction, so a key that straddles the cut leaves its first half
+ * unmasked (validated 2026-11-01: `OPENAI_API_KEY=abc123` cut after `abc` is no longer a recognizable pair). Here the
+ * pair is masked whole while the window still holds all of it, and only then does the cut fall.
+ *
+ * Steps, in order:
+ *   1. Read: lone surrogates, control and bidi characters out, NFKC (a full-width `ｊｏｈｎ＠ｅｘ…` becomes a plain address
+ *      the next steps can see), one line, the first SCAN code points.
+ *   1b. Leading attachments out of the prompt and the title (`@"path"`, `[Image: source: path]`, a bare path), so the 150 characters
+ *      start at the words typed.
+ *   2. This module's own rules for what mask does not know: home-folder paths, not every file path (/Users/<name>/…, /home, ~/, file://, C:\Users, /Volumes, /mnt/c)
+ *      as `[path]`, links to an IP address or localhost with a port or path as `[link]` (bare domains stay), phone numbers, card numbers, US social security numbers, short
+ *      `pk_` and `rk_` keys, base64 that carries `+` or `/` (first, because mask's long-run rule stops at a `/` and would leave
+ *      the tail of a run), and a credential word in a few other languages.
+ *   3. SetupAssistant.mask, ported: key shapes, then `key: value` and `"key": "value"` pairs whose key names a credential,
+ *      then long opaque runs. Control masks the same way before it draws a hit, so both sides agree on what a key is.
+ *   4. work-search's `searchOptionText`: the server's secret redaction, markdown links to their label, URLs, email
+ *      addresses and opaque ids out. Its own slice at 300 UTF-16 units never comes into play for the 150 code points a
+ *      session gets; a 200 code point query made of astral characters may be cut earlier, which is safe and well formed.
+ *   5. Cut by code points (an emoji is one, so a surrogate pair is never split). If the cut falls inside an unbroken
+ *      ASCII token, that token is dropped: the half of a key that survives a cut is the half nobody masked.
+ *
+ * This is not anonymization. Names, street addresses and ordinary prose go through, and the consent line says so.
+ */
+import { searchOptionText, WORK_SEARCH_LIMITS } from './work-search.js'
+
+export const FIND_TITLE_CHARS = 90
+export const FIND_PROMPT_CHARS = 150
+export const FIND_QUERY_CHARS = 200
+/** The collector keeps 2,000 characters of a typed prompt (FIND_PROMPT_KEEP_CHARS); a prompt that long was cut there. A test holds the two together. */
+export const UPSTREAM_PROMPT_CUT = 2_000
+/** Code points read before redacting: seven times the longest cut, so a pair or a block that starts inside a cut is whole. */
+export const FIND_SCAN_CHARS = 1_000
+/** Input bound before anything is normalized, so a pathological caller cannot make NFKC or the scan expensive. */
+const INPUT_UNITS = 8_000
+export const HIDDEN = '[hidden]'
+
+const keyShapes: RegExp[] = [
+  /(?<![A-Za-z0-9])(?:sk|sess)-[A-Za-z0-9_\-]{16,}/g,
+  /(?<![A-Za-z0-9])(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{8,}/g,
+  /(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{16,}|(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{16,}/g,
+  /(?<![A-Za-z0-9])glpat-[A-Za-z0-9_\-]{16,}/g,
+  /(?<![A-Za-z0-9])xox[abprs]-[A-Za-z0-9\-]{10,}/g,
+  /hooks\.slack\.com\/services\/[A-Za-z0-9/_\-]+/g,
+  /(?<![A-Za-z0-9])(?:AKIA|ASIA)[0-9A-Z]{12,}/g,
+  /(?<![A-Za-z0-9])eyJ[A-Za-z0-9_\-]{6,}\.[A-Za-z0-9_\-]{6,}\.[A-Za-z0-9_\-]{6,}/g,
+  /(?<![A-Za-z0-9])bearer\s+[A-Za-z0-9._~+/\-]{16,}=*/gi,
+  /authorization["']?\s*[:=]\s*["']?basic\s+[A-Za-z0-9+/]{8,}={0,2}/gi,
+  /(?<![A-Za-z0-9])basic\s+[A-Za-z0-9+/]{16,}={1,2}/gi,
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[^-]*(?:-----END [A-Z ]*PRIVATE KEY-----)?/g,
+  /[A-Za-z][A-Za-z0-9+.\-]*:\/\/[^/\s:@'"]+:[^/\s@'"]+@/g,
+  /(?<![A-Za-z0-9])--(?:password|passwd|token|secret|api[_-]?key)(?:=|\s+)\S{4,}/gi,
+]
+const pairKeyShape = /(?<![A-Za-z0-9])(["']?)([A-Za-z_][A-Za-z0-9_.\-]*)\1[ \t]*[:=][ \t]*/g
+const pairValueShape = /^(?:"[^"\\]{4,}"|'[^'\\]{4,}'|[^\s"',;]{6,})/
+const longRunShape = /(?<![A-Za-z0-9_\-])[A-Za-z0-9_\-]{32,}(?![A-Za-z0-9_\-])/g
+
+/** A key that names a credential: it holds PASSWORD or PASSWD, or ends in a credential word. A copy of SetupAssistant.credentialKey. */
+export function credentialKey(key: string): boolean {
+  let snake = ''
+  let previous = ''
+  for (const ch of key) {
+    if (/[A-Z]/.test(ch) && previous && (/[a-z]/.test(previous) || /[0-9]/.test(previous))) snake += '_'
+    snake += ch
+    previous = ch
+  }
+  const upper = snake.toUpperCase().replace(/-/g, '_').replace(/\./g, '_')
+  if (upper.includes('PASSWORD') || upper.includes('PASSWD')) return true
+  const words = ['PASS', 'SECRET', 'TOKEN', 'APIKEY', 'API_KEY', 'PRIVATE_KEY', 'ACCESS_KEY', 'ACCESS_KEY_ID', 'SECRET_KEY', 'AUTH_KEY', 'CREDENTIALS']
+  return words.some(word => upper === word || upper.endsWith('_' + word))
+}
+
+/** A name, not a key: a UUID, a name that carries one, or a plan or file name of words joined by underscores or hyphens. */
+function readsAsName(run: string): boolean {
+  const rest = run.replace(/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g, '')
+  const segments = rest.split(/[_-]/).filter(Boolean)
+  if (rest.length < run.length && segments.every(s => /^\p{L}+$/u.test(s))) return true
+  const humps = (word: string) => { let count = 0, previous = ''; for (const ch of word) { if (/[A-Z]/.test(ch) && previous && /[a-z]/.test(previous)) count++; previous = ch } return count }
+  return segments.filter(s => s.length >= 4 && /^\p{L}+$/u.test(s) && humps(s) <= 1).length >= 2
+}
+
+/** Port of SetupAssistant.mask (Control, Sources/SetupAssistant.swift). Tests pin it to the same fake secrets. */
+export function maskKeyShapes(text: string): string {
+  let out = text
+  for (const re of keyShapes) out = out.replace(new RegExp(re.source, re.flags), HIDDEN)
+  // Credential pairs: found on the string as it stands, then the ranges are hidden together (as the Swift does).
+  const hide: Array<[number, number]> = []
+  let resume = 0
+  for (const match of out.matchAll(new RegExp(pairKeyShape.source, 'g'))) {
+    const start = match.index!, end = start + match[0].length
+    if (start < resume) continue
+    const key = match[2]!
+    if (!credentialKey(key)) continue
+    const value = pairValueShape.exec(out.slice(end))
+    if (!value) continue
+    // A bare "pass" is a word as often as a password ("First pass: reviewed"): it hides only a value with a digit in it.
+    if (key.toLowerCase() === 'pass' && !/[0-9]/.test(value[0])) continue
+    hide.push([start, end + value[0].length])
+    resume = end + value[0].length
+  }
+  let result = '', cursor = 0
+  for (const [from, to] of hide) { result += out.slice(cursor, from) + HIDDEN; cursor = to }
+  out = result + out.slice(cursor)
+  return out.replace(new RegExp(longRunShape.source, 'g'), run => (/\p{L}/u.test(run) && /[0-9]/.test(run) && !readsAsName(run)) ? HIDDEN : run)
+}
+
+// What mask does not know. Each is broad on purpose: a number or a code wrongly hidden costs a little search signal, and one
+// left in goes to a third party.
+const PHONE_NANP = /(?<![\d])(?:\+?1[\s.\-]?)?\(?\d{3}\)?[\s.\-]?\d{3}[\s.\-]?\d{4}(?!\d)/g
+const PHONE_INTERNATIONAL = /(?<![\d\w])\+\d{1,3}[\s.\-]?\(?\d{1,4}\)?(?:[\s.\-]?\d{2,4}){2,4}(?!\d)/g
+const CARD_NUMBER = /(?<!\d)(?:\d[ \-]?){12,18}\d(?!\d)/g
+const SSN = /(?<!\d)\d{3}[\- ]\d{2}[\- ]\d{4}(?!\d)/g
+const SSN_LABELLED = /\b(?:ssn|social security(?: number)?)\D{0,16}\d{9}(?!\d)/gi
+const SHORT_STRIPE_KEY = /(?<![A-Za-z0-9])(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9_]+/g
+const BASE64_RUN = /(?<![A-Za-z0-9+/_\-])[A-Za-z0-9+/]{24,}={0,2}(?![A-Za-z0-9+/])/g
+// A credential word in other languages, with its value: "contraseña: Clave9876", "Passwort = Geheim1234".
+const FOREIGN_CREDENTIAL = /(?<![\p{L}\p{N}])(?:contrase[ñn]a|mot de passe|passwort|kennwort|senha|palavra-passe|wachtwoord|lösenord|hasło|пароль|密码|パスワード|비밀번호)[ \t]*[:=：][ \t]*\S{4,}/giu
+
+// A pair whose key ends in KEY, which mask's credentialKey list (API_KEY, ACCESS_KEY, SECRET_KEY...) does not: STRIPE_KEY=, OPENAI_KEY=,
+// AccountKey=, license-key:, and the spoken forms "api key:" and "secret key=". A bare "key: value" is a YAML word as often as a
+// secret, so it hides only a value of 8 or more characters that has a digit in it. "monkey=" and "hotkey" end in the letters but not
+// at a word boundary, so they are left alone.
+// PARITY: these rules, the unicode address rule and the invisible-character strip are THIS module's. Control's SetupAssistant.mask does
+// not have them, which is safe (Control masks only what it draws; this decides what leaves the Mac). Do not add them to the Swift
+// pin (`SWIFT_MASK` below tests maskKeyShapes alone).
+const KEY_VALUE = String.raw`(?:"[^"\\]{4,}"|'[^'\\]{4,}'|[^\s"',;]{6,})`
+const KEY_PAIR = new RegExp(String.raw`(?<![A-Za-z0-9])(?:[A-Za-z0-9_.\-]*[_.\-](?:key|KEY|Key)|[A-Za-z0-9_.\-]*(?<=[a-z0-9])Key)["']?[ \t]*[:=][ \t]*${KEY_VALUE}`, 'g')
+const SPOKEN_KEY_PAIR = new RegExp(String.raw`(?<![A-Za-z0-9])(?:api|secret|access|private|auth|account|license|licence|encryption|signing)[ ]key["']?[ \t]*[:=][ \t]*${KEY_VALUE}`, 'gi')
+const BARE_KEY_PAIR = /(?<![A-Za-z0-9_.\-])(?:key|KEY|Key)[ \t]*[:=][ \t]*(?=[^\s"',;]*\d)[^\s"',;]{8,}/g
+// An address with letters outside ASCII (josé@example.com); the server's own rule is ASCII only.
+const UNICODE_EMAIL = /[\p{L}\p{N}._%+\-]{1,64}@[\p{L}\p{N}.\-]{1,253}\.\p{L}{2,24}/gu
+
+// A path into someone's home folder carries the account name and the layout of the machine, and the consent line does not promise
+// either, so it goes out before anything else is read. Only a REAL path shape counts, so a word is not eaten: a root, an account name
+// and at least one more segment (`/home/dashboard` and `/Users/list` are words), or `~/` with a segment that holds a slash or an
+// extension (`~/month` is a word), or `~name/…`, or file://. Case does not matter (/users/, c:\users\), nor the form it arrives in:
+// /Volumes/<x>/Users, /System/Volumes/Data/Users, /mnt/c/Users, C:\\Users\\ (escaped backslashes), `My\ Clients/Acme\ Corp` (escaped
+// spaces) and an apostrophe in the name (/Users/o'brien/x). A path that opens inside a quote runs to the closing quote, spaces and dots
+// and all; any other runs to the next unescaped space.
+const HOME_PREFIX = String.raw`(?:(?:\/System\/Volumes\/Data|\/Volumes\/[^\/\n]+|\/mnt\/[a-z])?\/(?:users|home)\/[^\s\/\\"\x60]+\/|[a-z]:\\{1,2}users\\{1,2}[^\s\\"\x60]+\\{1,2}|~[\w.\-]*\/(?=(?:\\ |[^\s])*[\/.]))`
+const HOME_SHAPE_QUOTED = /^(?:file:\/\/|(?:\/System\/Volumes\/Data|\/Volumes\/[^\/\n]+|\/mnt\/[a-z])?\/(?:users|home)\/[^\/\\\n]+[\/\\][^\n]|[a-z]:\\{1,2}users\\{1,2}[^\\\n]+\\{1,2}[^\n]|~[\w.\-]*\/[^\n]*[\/.])/i
+const QUOTED_HOME_PATH = /(["'\x60])((?:(?!\1)[^\n])+)\1/g
+const BARE_HOME_PATH = new RegExp(String.raw`(?<![\w.\-\/\\~])(?:file:\/\/(?:\\ |\S)*|${HOME_PREFIX}(?:\\ |\S)+)`, 'gi')
+export const PATH_PLACEHOLDER = '[path]'
+const maskQuotedHomePaths = (text: string) => text.replace(QUOTED_HOME_PATH, (whole, _quote: string, inner: string) => HOME_SHAPE_QUOTED.test(inner.trim()) ? PATH_PLACEHOLDER : whole)
+
+// A link to a machine: an IP address or `localhost` WITH a port or a path (`192.168.1.20:8080/admin?x=1`, `localhost:3141/api/keys`).
+// Scheme URLs go later, in searchOptionText. Left alone on purpose: a bare domain (`quilt.com`, a brand people search for), a bare
+// address or `localhost` with nothing after it, a version like `1.2.3.4`, and `word.ext:number` (`meeting.ts:2452` is code, not a link).
+const OCTET = String.raw`(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)`
+const HOST_LINK = new RegExp(String.raw`(?<![\w.@\-])(?:(?:${OCTET}\.){3}${OCTET}|localhost)(?::\d{2,5}(?:\/[^\s]*)?|\/[^\s]*)`, 'gi')
+const LINK_PLACEHOLDER = '[link]'
+const maskHostLinks = (text: string) => text.replace(HOST_LINK, LINK_PLACEHOLDER)
+
+/**
+ * What an agent app puts in front of the words: `@"/path/with spaces.png"`, `@'path'`, `@/path/file`, `@~/file`, `[Image: source: path]`,
+ * `[Image #1]`, `[Pasted text #1 +20 lines]`, and a bare path. Measured on the owner's newest 508 first prompts: 33 start with `@"`,
+ * 19 with `[Image`, 3 with a bare path; 25 carry more than one in a row. They are not what the person was asking, they eat the 150
+ * characters that make the match, and a path in them names the account. They are dropped from the front, repeatedly, until the words
+ * begin. Only known forms: `@"Jane Doe" can you` (no slash, no file extension), an `@name` mention and `[File upload bug]` are words
+ * and stay. `cut` says the text was already cut upstream (an 80 or 120 character title, a 2,000 character prompt): an attachment that
+ * opens and never closes then runs to the end of what is left, so nothing of it is kept.
+ */
+const FILE_EXT = String.raw`(?:png|jpe?g|gif|heic|webp|pdf|txt|md|tsx?|jsx?|json|py|swift|csv|xlsx?|docx?|pptx?|html?|css|log|zip|mov|mp4|wav|mp3|sh|ya?ml|toml)`
+const LEADING_ATTACHMENT = new RegExp(String.raw`^\s*(?:@"(?=[^"]*(?:\/|\.${FILE_EXT}"))[^"]*"|@'(?=[^']*(?:\/|\.${FILE_EXT}'))[^']*'|@(?:~|\.{0,2})?\/(?:\\ |\S)*|@[^\s\/]*\.${FILE_EXT}\b|\[(?:Image(?: #\d+|:[^\]]*)|Pasted text[^\]]*|Pasted image[^\]]*)\]|(?:\/users|\/home)\/[^\s\/]+\/(?:\\ |\S)+|~\/(?=\S*[\/.])(?:\\ |\S)+|file:\/\/\S+)\s*`, 'i')
+const UNCLOSED_ATTACHMENT = /^\s*(?:@"|@'|\[(?:Image|Pasted))/i
+export function stripLeadingAttachments(text: string, cut = false): string {
+  let out = text
+  for (let i = 0; i < 20; i++) {
+    const next = out.replace(LEADING_ATTACHMENT, '')
+    if (next === out) break
+    out = next
+  }
+  return cut && UNCLOSED_ATTACHMENT.test(out) ? '' : out
+}
+
+export function maskMore(text: string): string {
+  // An address goes out as a space, as searchOptionText does, so a query that is only an address is left empty.
+  let out = maskHostLinks(maskQuotedHomePaths(text).replace(BARE_HOME_PATH, PATH_PLACEHOLDER)).replace(UNICODE_EMAIL, ' ')
+  for (const re of [KEY_PAIR, SPOKEN_KEY_PAIR, BARE_KEY_PAIR, FOREIGN_CREDENTIAL, SHORT_STRIPE_KEY, SSN_LABELLED, SSN, CARD_NUMBER, PHONE_INTERNATIONAL, PHONE_NANP]) out = out.replace(re, HIDDEN)
+  // Base64 that carries + or /, and the padded or long kind: mixed case with a digit, so a path or a word is left alone.
+  return out.replace(BASE64_RUN, run => (/[A-Z]/.test(run) && /[a-z]/.test(run) && /\d/.test(run) && (/[+/=]/.test(run) || run.length >= 40)) ? HIDDEN : run)
+}
+
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g
+/** Lone surrogates, control and bidi characters out, NFKC, one line. */
+function readableLine(raw: string): string {
+  const wellFormed = raw.slice(0, INPUT_UNITS).replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, '')
+  return wellFormed.normalize('NFKC')
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f\u00ad\u061c\u180e\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/g, '')
+    .replace(/\s+/g, ' ').trim()
+}
+
+const TOKEN_CHAR = /[A-Za-z0-9_\-+/=.:@%]/
+
+/**
+ * At most `max` code points. When the cut falls inside an unbroken ASCII token (the last kept character and the next one
+ * both belong to it), the kept part of that token is dropped too: half a key is the half nobody masked. Text in a script that
+ * does not use spaces has no such token and is cut where it falls. `cutEarlier` says an earlier step already cut the text.
+ */
+export function cutAtCodePoints(text: string, max: number, cutEarlier = false): string {
+  const points = Array.from(text)
+  if (points.length <= max && !cutEarlier) return text
+  const kept = points.slice(0, max)
+  const next = points[max]
+  const inside = cutEarlier ? true : next !== undefined && TOKEN_CHAR.test(next) && kept.length > 0 && TOKEN_CHAR.test(kept[kept.length - 1]!)
+  if (inside) while (kept.length > 0 && TOKEN_CHAR.test(kept[kept.length - 1]!)) kept.pop()
+  return kept.join('').trim()
+}
+
+/**
+ * Read, redact, then cut. Returns one clean line of at most `max` code points, possibly empty. `cutUpstream` says the text was already
+ * cut by whoever made it (the list cuts a first line at 80 and a title at 120, before any redaction), so its last token may be half a key.
+ */
+export function redactForModel(raw: string, max: number, cutUpstream = false): string {
+  if (typeof raw !== 'string' || !raw) return ''
+  const scan = cutAtCodePoints(readableLine(raw), FIND_SCAN_CHARS)
+  // work-search's own slice at 300 UTF-16 units can leave half of a surrogate pair; it goes before the cut by code points.
+  const redacted = searchOptionText(maskKeyShapes(maskMore(scan))).replace(LONE_SURROGATE, '')
+  // searchOptionText slices at its own 300 UTF-16 units; if it reached them it may have cut inside a token.
+  return cutAtCodePoints(redacted, max, cutUpstream || redacted.length >= WORK_SEARCH_LIMITS.optionChars)
+}
+
+/** The search words as they leave: redacted like everything else, at most 200 code points. */
+export function redactQuery(query: string): string { return redactForModel(query, FIND_QUERY_CHARS) }
+
+export interface CandidateTexts {
+  /** What the model reads for this session: the title and the first prompt, or the prompt alone when it begins with the title. */
+  option: string
+  /** The first-prompt part, redacted and cut. This is `judged_text` on the wire. */
+  prompt: string
+}
+
+const norm = (text: string) => text.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim()
+
+/**
+ * One session as the model sees it (the canary's shape B: 19 of 20 in the top three against 15 for the title alone):
+ * `title: first prompt`. The list titles a session by the first line of its first prompt, and then the title is the start
+ * of the prompt, so the prompt alone says it and a second copy of the words would only cost tokens.
+ */
+export function candidateTexts(title: string, typed: string): CandidateTexts {
+  const titleCut = title.length === 80 || title.length === 120
+  const t = redactForModel(stripLeadingAttachments(title, titleCut), FIND_TITLE_CHARS, titleCut)
+  const promptCut = typed.length >= UPSTREAM_PROMPT_CUT
+  const prompt = redactForModel(stripLeadingAttachments(typed, promptCut), FIND_PROMPT_CHARS)
+  if (!prompt) return { option: t, prompt: '' }
+  const titleWords = norm(t)
+  if (!titleWords || (titleWords.length >= 12 && norm(prompt).startsWith(titleWords.slice(0, 30)))) return { option: prompt, prompt }
+  return { option: `${t}: ${prompt}`, prompt }
+}

package/server/lib/session-find.ts

@@ -0,0 +1,345 @@
+/**
+ * Find a session by meaning (Control 0.5.363): `POST /api/agent-sessions/find`.
+ *
+ * Control's command panel sends what the person typed. This reads the Mac's own session store (never client text), shows a
+ * decision model each session's title and the first 150 characters of its first prompt, and answers the few sessions that
+ * model thinks were meant, with how sure it is. What it does and why it is shaped this way:
+ *   - session-find-collect.ts: the pool (newest 254, or 508 when the first 254 do not settle it), its filters and its memo.
+ *   - session-find-redact.ts: read, redact, then cut every string that leaves the Mac, and every string handed back.
+ *   - session-find-ask.ts: the Choice, the merge, the yes/no view, the floors and bands.
+ *
+ * WHAT LEAVES THE MAC. Per search: the redacted words typed, plus a redacted title and first-prompt excerpt of up to 508
+ * recent sessions, to the person's selected decision provider (Settings > Decision models, the `search` setting, no fallback
+ * to the other provider). Nothing leaves before the person has consented for THAT provider: the body names the provider they
+ * consented to, and a mismatch with the provider selected now is refused before any session is read.
+ *
+ * COST CONTROLS, separate from Work search, Work intake and session advice (so one runaway cannot spend another's budget):
+ * its own Jev ledger and SubQ ledger (session-find-jev-usage.json, session-find-subq-usage.json), a daily input-token cap
+ * of 3,000,000 for each (COS_SESSION_FIND_DAILY_TOKENS), each provider's own breaker (3 failures, then an hour), and a switch
+ * (COS_SESSION_FIND=0 turns it off; the value is read at boot like COS_JEV_SEARCH). The ledger day is UTC.
+ *
+ * It is also gated on the Sessions feature (COS_CLAUDE_SESSIONS_ENABLED=1), which is off by default on the published package:
+ * a person who never turned sessions on never sees a session leave their Mac.
+ */
+import { dataPath } from './data-dir.js'
+import { JevClient, JevError } from './jev.js'
+import {
+  DecisionProviderError, SubqDecisionClient, createDecisionClient, selectedDecisionProvider, type DecisionClient, type DecisionProvider,
+} from './decision-provider.js'
+import { resolveJevKey } from './jev.js'
+import { resolveSubqKey } from './subq-key.js'
+import { isAbortError, sharedSessionFindCollector, type FindCandidate, type SessionFindCollector } from './session-find-collect.js'
+import { FIND_CHOICE_OPTIONS, SessionFindAsker, type AskCandidate, type FindStrength } from './session-find-ask.js'
+import { candidateTexts, redactQuery } from './session-find-redact.js'
+import { agentSessionRoots, type AgentSessionRoots } from './agent-session-store.js'
+import { listKeyedSessionsStrict } from './keyed-sessions.js'
+
+export const SESSION_FIND_LIMITS = {
+  /** After redaction, in code points. Control sends three or more words; a shorter redacted query is not worth a model call. */
+  queryMin: 3,
+  /** Bytes of JSON-string a query may arrive as, before anything reads it. The 200 code point cap is applied to the redacted words. */
+  queryRawMax: 2_000,
+  defaultDailyTokens: 3_000_000,
+} as const
+export const SESSION_FIND_JEV_USAGE_FILE = dataPath('session-find-jev-usage.json')
+export const SESSION_FIND_SUBQ_USAGE_FILE = dataPath('session-find-subq-usage.json')
+
+export type SessionFindReason =
+  | 'consent_required' | 'provider_changed' | 'decision_not_configured' | 'jev_not_configured' | 'sessions_off' | 'find_off'
+  | 'cap_reached' | 'breaker_open' | 'query_too_short' | 'failed'
+export const SESSION_FIND_MESSAGES: Record<SessionFindReason, string> = {
+  consent_required: 'Meaning search needs your okay before it sends anything. Turn it on in Settings.',
+  provider_changed: 'The decision model changed since you agreed. Agree again for the new one in Settings.',
+  decision_not_configured: 'Meaning search needs an API key for the selected decision model. Add one in Settings.',
+  jev_not_configured: 'Meaning search needs a TypeSafe key. Add one in Settings.',
+  sessions_off: 'Sessions are turned off on this server, so there is nothing to search.',
+  find_off: 'Meaning search is turned off on this server.',
+  cap_reached: 'Meaning search has used today’s budget. It resets at midnight UTC.',
+  breaker_open: 'Meaning search is paused for an hour after repeated failures.',
+  query_too_short: 'Type a few more words to search by meaning.',
+  failed: 'Meaning search could not answer this time.',
+}
+
+/** The daily input-token cap for session find alone, per provider ledger. The ledger day is UTC. */
+export function sessionFindDailyCap(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = Number(env.COS_SESSION_FIND_DAILY_TOKENS)
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : SESSION_FIND_LIMITS.defaultDailyTokens
+}
+
+/** On unless COS_SESSION_FIND says off (0, false, no, off). Fixed when the server starts, like COS_JEV_SEARCH. */
+export function sessionFindEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return !['0', 'false', 'no', 'off'].includes((env.COS_SESSION_FIND ?? '').trim().toLowerCase())
+}
+
+/**
+ * Whether this server can find sessions by meaning at all: the Sessions feature is on and the switch is not off. This is what
+ * `capabilities.sessionFind` on GET /api/decision-provider reports, so Control never offers a consent it cannot honour.
+ * The Sessions test is claudeSessionsEnabled() in routes/claude-sessions.ts (a test holds the two together; that module is
+ * not imported here because it pulls in the whole registry).
+ */
+export function sessionFindAvailable(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.COS_CLAUDE_SESSIONS_ENABLED === '1' && sessionFindEnabled(env)
+}
+
+/**
+ * API POSTs that only read, for the mutation lease (index.ts). Finding a session reads the session store and asks a model;
+ * it writes only its own token ledger. Under the lease a drain for an update would wait for a search that can take a few
+ * seconds, and the helper's own deadline is shorter than the lease's. Its own predicate, not isReadOnlyApiPost's list: that
+ * list differs between the public and the private line, and a pinned test holds its single call site.
+ */
+export function isSessionFindPost(method: string, path: string): boolean {
+  return method === 'POST' && path === '/agent-sessions/find'
+}
+
+/** Session find's own Jev client: its own ledger, cap and breaker. jev.ts supplies the key and the timeout. */
+export function createSessionFindJevClient(fetchImpl: typeof fetch = fetch, now: () => Date = () => new Date(),
+                                           usageFile = SESSION_FIND_JEV_USAGE_FILE, cap: () => number = () => sessionFindDailyCap()): JevClient {
+  return new JevClient(fetchImpl, now, usageFile, cap)
+}
+let sharedJev: JevClient | null = null
+/** One per process: it owns this feature's Jev breaker. Saving a new Jev key resets it (routes/jev.ts). */
+export function sharedSessionFindJevClient(): JevClient { return sharedJev ??= createSessionFindJevClient() }
+
+/** The selected provider's client for this feature: Jev on its own client, SubQ on its own ledger and cap. */
+export function createSessionFindDecisionClient(jev: Pick<JevClient, 'ask'> = sharedSessionFindJevClient(), env: NodeJS.ProcessEnv = process.env,
+                                                subqUsageFile = SESSION_FIND_SUBQ_USAGE_FILE, cap: () => number = () => sessionFindDailyCap(env)): DecisionClient {
+  return createDecisionClient('search', jev, env, { usageFile: subqUsageFile, cap })
+}
+let sharedDecision: DecisionClient | null = null
+export function sharedSessionFindDecisionClient(): DecisionClient { return sharedDecision ??= createSessionFindDecisionClient() }
+
+export interface SessionFindRequest {
+  query: string
+  /** The provider the person agreed to send to, or null for "not agreed". */
+  consentedProvider: DecisionProvider | null
+  stage: 'first' | 'full'
+}
+
+export interface SessionFindRow {
+  session_id: string
+  provider: 'claude' | 'codex' | 'cursor'
+  slug: string
+  custom_title: string
+  display_label: string
+  first_prompt: string
+  discussion_summary: string
+  project: string
+  created: string
+  modified: string
+  duration_minutes: number
+  message_count: number
+  domain: string
+  device_id: string
+  machine_spawned: boolean
+  alive: boolean
+  state: 'recent'
+  pinned: boolean
+  last_activity_at: string
+  judged_text: string
+  probability: number
+  strength: FindStrength
+  compressed: boolean
+}
+
+export interface SessionFindAnswer {
+  available: boolean
+  reason: SessionFindReason | null
+  message: string
+  provider: DecisionProvider | null
+  /** True when the provider is documented to keep what it is sent (SubQ). False says nothing about TypeSafe, whose retention is not documented. */
+  storesData: boolean
+  rows: SessionFindRow[]
+  /** Sessions a model was asked about. */
+  asked: number
+  /** The oldest time among them (their last record), or null. */
+  reachedBack: string | null
+  /** Compressed Codex files this server could not read, so they were not asked about. */
+  skipped: number
+  /** No model was called for this answer. */
+  cached: boolean
+  /** On `cap_reached`: when that provider's ledger next resets. On `breaker_open`: when the breaker reopens. ISO 8601 UTC; absent when not known. */
+  resetsAt?: string
+}
+
+export function unavailableAnswer(reason: SessionFindReason, provider: DecisionProvider | null = null, resetsAt?: string): SessionFindAnswer {
+  return { available: false, reason, message: SESSION_FIND_MESSAGES[reason], provider, storesData: provider === 'subq', rows: [], asked: 0, reachedBack: null, skipped: 0, cached: false, ...(resetsAt ? { resetsAt } : {}) }
+}
+
+/**
+ * When a cap or a pause ends, read from the clients' own bookkeeping and never guessed. Both ledgers (JevClient `today()`, SubqDecisionClient
+ * `day()`) key a day by `now.toISOString().slice(0, 10)`, so a cap clears at the next UTC midnight of the client's clock. A breaker opens until
+ * the client's `breakerOpenUntil` (Jev reports it as an ISO string, SubQ as epoch milliseconds). Unknown stays undefined.
+ */
+export function resetsAtFor(reason: SessionFindReason, client: DecisionClient, provider: DecisionProvider, jev: JevClient | null, nowMs: number): string | undefined {
+  if (reason === 'cap_reached') {
+    const day = new Date(nowMs)
+    return new Date(Date.UTC(day.getUTCFullYear(), day.getUTCMonth(), day.getUTCDate() + 1)).toISOString()
+  }
+  if (reason !== 'breaker_open') return undefined
+  let until: number | null = null
+  if (provider === 'subq') { if (client instanceof SubqDecisionClient) until = client.status().breakerOpenUntil }
+  else if (jev) { const iso = jev.status().breakerOpenUntil; until = iso ? Date.parse(iso) : null }
+  return until !== null && Number.isFinite(until) && until > nowMs ? new Date(until).toISOString() : undefined
+}
+
+/** Every failure a model or its ledger can raise, as one of the contract's reasons. Anything not named is `failed`. */
+export function reasonFor(error: unknown): SessionFindReason {
+  if (error instanceof DecisionProviderError) {
+    if (error.code === 'decision_cap_reached') return 'cap_reached'
+    if (error.code === 'decision_breaker_open') return 'breaker_open'
+    if (error.code === 'decision_not_configured') return 'decision_not_configured'
+    return 'failed'
+  }
+  if (error instanceof JevError) {
+    if (error.code === 'jev_cap_reached') return 'cap_reached'
+    if (error.code === 'jev_breaker_open') return 'breaker_open'
+    if (error.code === 'jev_not_configured') return 'jev_not_configured'
+    return 'failed'
+  }
+  return 'failed'
+}
+
+export interface SessionFindDependencies {
+  collector: Pick<SessionFindCollector, 'collect'>
+  asker: Pick<SessionFindAsker, 'ask'>
+  decision: DecisionClient
+  roots: () => AgentSessionRoots
+  keyedIds: () => ReadonlySet<string>
+  available: () => { find: boolean; sessions: boolean }
+  /** The provider the person has selected for the `search` setting. Throws DecisionProviderError when the setting is invalid. */
+  selected: () => DecisionProvider
+  configured: (provider: DecisionProvider) => boolean
+  /** Cap or breaker already reached for this provider, known without sending anything. */
+  capacity: (client: DecisionClient, provider: DecisionProvider, jev: JevClient | null) => 'cap_reached' | 'breaker_open' | null
+  jev: JevClient | null
+  chunkSize?: number
+  now?: () => number
+}
+
+/**
+ * Cap and breaker, read from the two clients' own status. SubQ's status reads an unreadable ledger as the cap reached. Jev's reads
+ * a missing or unreadable ledger as 0 used (jev.ts usedToday), so this check cannot catch one; the client's own write would.
+ */
+export function clientCapacity(client: DecisionClient, provider: DecisionProvider, jev: JevClient | null): 'cap_reached' | 'breaker_open' | null {
+  if (provider === 'subq') {
+    if (!(client instanceof SubqDecisionClient)) return null
+    const status = client.status()
+    if (status.breakerOpenUntil) return 'breaker_open'
+    return status.usedToday >= status.dailyCap ? 'cap_reached' : null
+  }
+  if (!jev) return null
+  const status = jev.status()
+  if (status.breakerOpenUntil) return 'breaker_open'
+  return status.usedToday >= status.dailyCap ? 'cap_reached' : null
+}
+
+export function defaultSessionFindDependencies(): SessionFindDependencies {
+  return {
+    collector: sharedSessionFindCollector(),
+    asker: new SessionFindAsker(),
+    decision: sharedSessionFindDecisionClient(),
+    roots: () => agentSessionRoots(),
+    // Strict: a damaged keyed-sessions file must fail the search (reported as `failed`), not read as no keyed sessions.
+    keyedIds: () => new Set(listKeyedSessionsStrict().map(record => record.id.toLowerCase())),
+    available: () => ({ find: sessionFindEnabled(), sessions: process.env.COS_CLAUDE_SESSIONS_ENABLED === '1' }),
+    selected: () => selectedDecisionProvider('search'),
+    configured: provider => provider === 'subq' ? !!resolveSubqKey() : !!resolveJevKey(),
+    capacity: clientCapacity,
+    jev: sharedSessionFindJevClient(),
+  }
+}
+
+const iso = (ms: number) => new Date(ms).toISOString()
+
+export class SessionFinder {
+  constructor(private readonly deps: SessionFindDependencies = defaultSessionFindDependencies()) {}
+
+  /**
+   * Never throws for a model or ledger failure: those are answers with a reason. A thrown AbortError means the caller went
+   * away; the route does not answer it.
+   */
+  async find(request: SessionFindRequest, signal: AbortSignal): Promise<SessionFindAnswer> {
+    const { deps } = this
+    const live = deps.available()
+    if (!live.find) return unavailableAnswer('find_off')
+    if (!live.sessions) return unavailableAnswer('sessions_off')
+
+    // Everything below that can refuse does so before a single session is read or a single byte is sent.
+    let provider: DecisionProvider
+    try { provider = deps.selected() } catch { return unavailableAnswer('failed') }
+    if (!request.consentedProvider) return unavailableAnswer('consent_required', provider)
+    if (request.consentedProvider !== provider) return unavailableAnswer('provider_changed', provider)
+    const query = redactQuery(request.query)
+    if (Array.from(query).length < SESSION_FIND_LIMITS.queryMin) return unavailableAnswer('query_too_short', provider)
+    if (!deps.configured(provider)) return unavailableAnswer(provider === 'jev' ? 'jev_not_configured' : 'decision_not_configured', provider)
+    let client: DecisionClient
+    try { client = deps.decision.snapshot?.() ?? deps.decision } catch (error) { return unavailableAnswer(reasonFor(error), provider) }
+    // The snapshot is the provider this whole search uses. A settings change between the two reads above and this one is refused.
+    if ((client.provider ?? 'jev') !== provider) return unavailableAnswer('provider_changed', provider)
+    const full = deps.capacity(client, provider, deps.jev)
+    if (full) return unavailableAnswer(full, provider, resetsAtFor(full, client, provider, deps.jev, (deps.now ?? Date.now)()))
+
+    try {
+      const roots = deps.roots()
+      // Inside the try: an unreadable keyed-sessions file is a failed search, never an empty set (keyed text must not leave).
+      const keyedIds = deps.keyedIds()
+      const chunk = Math.min(deps.chunkSize ?? FIND_CHOICE_OPTIONS, FIND_CHOICE_OPTIONS)
+      const firstPool = await deps.collector.collect({ roots, limit: chunk, keyedIds, signal })
+      const byKey = new Map<string, FindCandidate & { judged: string }>()
+      const toAsk = (pool: readonly FindCandidate[]): AskCandidate[] => {
+        const out: AskCandidate[] = []
+        for (const candidate of pool) {
+          if (byKey.has(candidate.key)) continue
+          const { option, prompt } = candidateTexts(candidate.title, candidate.typed)
+          // A session whose words all redact away has nothing a model could judge it by.
+          if (!option) continue
+          byKey.set(candidate.key, { ...candidate, judged: prompt })
+          out.push({ key: candidate.key, option, clockMs: candidate.clockMs })
+        }
+        return out
+      }
+      const first = toAsk(firstPool.candidates)
+      let skipped = firstPool.skippedNoDecoder + firstPool.skippedUnreadable
+      const outcome = await deps.asker.ask({
+        client, query, stage: request.stage, first, chunkSize: chunk,
+        shouldStop: () => signal.aborted,
+        second: async () => {
+          const wider = await deps.collector.collect({ roots, limit: chunk * 2, keyedIds, signal })
+          skipped = Math.max(skipped, wider.skippedNoDecoder + wider.skippedUnreadable)
+          return toAsk(wider.candidates)
+        },
+      })
+      if (outcome.stopped) throw abortLike()
+      const rows: SessionFindRow[] = []
+      for (const row of outcome.rows) {
+        const candidate = byKey.get(row.key)
+        if (!candidate) continue
+        rows.push(toRow(candidate, row.probability, row.strength))
+      }
+      return {
+        available: true, reason: null, message: '', provider, storesData: provider === 'subq', rows,
+        asked: outcome.asked.length, reachedBack: outcome.asked.length ? iso(Math.min(...outcome.asked.map(c => c.clockMs))) : null,
+        skipped, cached: outcome.cached,
+      }
+    } catch (error) {
+      if (isAbortError(error)) throw error
+      const reason = reasonFor(error)
+      return unavailableAnswer(reason, provider, resetsAtFor(reason, client, provider, deps.jev, (deps.now ?? Date.now)()))
+    }
+  }
+}
+
+function abortLike(): Error { const e = new Error('cancelled'); e.name = 'AbortError'; return e }
+
+/** The list's session fields (routes/agent-sessions.ts toEntry), without live state, plus what this search adds. */
+function toRow(candidate: FindCandidate & { judged: string }, probability: number, strength: FindStrength): SessionFindRow {
+  const title = candidate.title
+  return {
+    session_id: candidate.session_id, provider: candidate.provider, slug: candidate.session_id,
+    custom_title: title, display_label: title, first_prompt: candidate.listFirstLine || title, discussion_summary: '',
+    project: candidate.project, created: candidate.created, modified: iso(candidate.mtimeMs),
+    duration_minutes: 0, message_count: 0, domain: '', device_id: candidate.provider, machine_spawned: false,
+    alive: false, state: 'recent', pinned: false,
+    last_activity_at: iso(candidate.clockMs), judged_text: candidate.judged, probability, strength, compressed: candidate.compressed,
+  }
+}

package/server/lib/speaker-calibration-log.ts

@@ -12,6 +12,7 @@
 
 import { existsSync, readFileSync } from 'node:fs'
 import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { sameSpeakerName } from './speaker-name-nfc.js'
 
 export interface CalibrationPurgeResult {
   /** Rows whose `speaker` matched and were dropped. */
@@ -51,7 +52,7 @@ export function filterCalibrationRows(
       kept.push(line)
       continue
     }
-    if (speaker === speakerName) {
+    if (sameSpeakerName(speaker, speakerName)) {
       result.removed++
       continue
     }
@@ -90,7 +91,7 @@ export function relabelCalibrationRows(
     // merge must never lose history. (Contrast filterCalibrationRows, where
     // removed + retained = total.)
     retained++
-    if (row.speaker === fromName) {
+    if (sameSpeakerName(row.speaker, fromName)) {
       row.speaker = toName
       relabeled++
       out.push(JSON.stringify(row))