@gotcos/glasses-server 6.63.1 → 6.65.0

package/server/lib/task-dates.ts

@@ -0,0 +1,369 @@
+/**
+ * When a Work task was created and when its line last changed (6.65.0, Control 0.5.259 "Newest created" and
+ * "Recent activity" orders). Read-only: nothing is ever written into tasks.md (canary C6).
+ *
+ * No task carries a creation time (0 of 293 on 2026-10-06), so the date is inferred, in this order:
+ *   1. createdOn from the source label: the first YYYY-MM-DD in it (241 of 293 live tasks carry one, usually the
+ *      meeting date). `createdFrom: 'source'`.
+ *   2. Else the day the task's text first appeared in the git history of its tasks.md
+ *      (`git log --reverse -S<text> -- tasks.md`, author date). `createdFrom: 'git'`. Each lookup is one git process,
+ *      so they are cached on disk by (file, text hash). A lookup that times out or fails is never cached as "not in
+ *      history"; it rests (TASK_DATE_LIMITS.lookupBackoffMs) and is tried again.
+ *   3. Else null.
+ * lineChangedAt is `git blame` of the line (author time), for committed lines only: an uncommitted line is null, never
+ * "now". tasks.md is auto-committed by the COS sync, so this is a coarse floor. Blame runs once per (HEAD, file mtime).
+ *
+ * Every dated read keeps ALL of its git work (rev-parse, blame, first-seen lookups) inside one deadline,
+ * TASK_DATE_LIMITS.deadlineMs (1.5 s, derived from the phone's 4 s request timeout below). Past it the read answers with
+ * what it has, and git work already started keeps running to fill the caches for a later read.
+ *
+ * Git runs only when a `.git` exists at or above the tasks.md folder. A public install keeps its tasks under
+ * ~/.cos-glasses/data, normally outside any repository, so no git process starts and the git-derived fields are null.
+ * If the home folder itself is a git repository, git does run: rev-parse on each dated read and blame once per HEAD or
+ * file change. Blame finds tasks.md untracked, so the git-derived fields stay null and no first-seen lookup runs.
+ */
+import { createHash } from 'node:crypto'
+import { execFile } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, statSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { dataPath } from './data-dir.js'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+
+export interface TaskDateFields {
+  /** 'YYYY-MM-DD' or null. */
+  createdOn: string | null
+  createdFrom: 'source' | 'git' | null
+  /** ISO time of the commit that last changed the task's line, or null (uncommitted, or no git). */
+  lineChangedAt: string | null
+}
+export const NO_TASK_DATES: Readonly<TaskDateFields> = Object.freeze({ createdOn: null, createdFrom: null, lineChangedAt: null })
+
+/**
+ * The phone and the glasses give up on a request after 4 s. A dated board read keeps all of its git work (rev-parse,
+ * blame, first-seen lookups) inside half of that, less an allowance for the board read itself (the task bridge answers
+ * in about 0.1 s) and the answer: 4,000 / 2 - 500 = 1,500 ms.
+ */
+const CLIENT_TIMEOUT_MS = 4_000
+const BOARD_READ_ALLOWANCE_MS = 500
+
+export const TASK_DATE_LIMITS = {
+  /** All git work for one request, overall. What does not finish keeps running and answers on a later call. */
+  deadlineMs: CLIENT_TIMEOUT_MS / 2 - BOARD_READ_ALLOWANCE_MS,
+  /** resolveTaskDatesWithin's grace past the deadline before it answers null dates for every row. */
+  answerSlackMs: 100,
+  /** One git process. It may outlive the request (it fills the caches); it is killed after this. */
+  gitTimeoutMs: 8_000,
+  /** A first-seen lookup that failed is not retried for this long; it is never cached as "not in history". */
+  lookupBackoffMs: 10 * 60_000,
+  /** A file whose rev-parse or blame timed out gets no git work for this long. */
+  fileBackoffMs: 60_000,
+  concurrency: 2,
+  cacheEntries: 5_000,
+  blameFiles: 32,
+  needleMin: 8,
+  needleMax: 200,
+  /** The leading characters of a task's text that must appear on its blamed line. */
+  guardChars: 40,
+} as const
+export const TASK_DATES_CACHE_FILE = dataPath('task-created-dates.json')
+
+/** What a bridge row offers (task-store.ts BridgeTaskRow). */
+export interface DateSourceRow { id: string; domain: string; line_number: number; source: string | null; description: string }
+export type DateGitRunner = (args: readonly string[], cwd: string, timeoutMs: number) => Promise<string>
+
+/** Homebrew's git first: `/usr/bin/git` without the developer tools opens an install dialog. */
+const GIT_BIN = ['/opt/homebrew/bin/git', '/usr/local/bin/git', '/usr/bin/git'].find(path => existsSync(path)) ?? '/usr/bin/git'
+export const realDateGitRunner: DateGitRunner = (args, cwd, timeoutMs) => new Promise((resolve, reject) => {
+  execFile(GIT_BIN, [...args], { cwd, timeout: timeoutMs, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
+    env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0' } }, (error, stdout) => error ? reject(error) : resolve(String(stdout)))
+})
+
+export function taskDateKey(domain: string, id: string): string { return `${domain}\0${id}` }
+
+function isCalendarDay(day: string): boolean {
+  const at = new Date(`${day}T00:00:00Z`)
+  return !Number.isNaN(at.getTime()) && at.toISOString().slice(0, 10) === day
+}
+
+/** The first real YYYY-MM-DD in a source label. Link targets are not label text (a Work details token is base64). */
+export function sourceDate(source: string | null | undefined): string | null {
+  if (!source) return null
+  const label = source.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+  for (const match of label.matchAll(/20\d\d-\d\d-\d\d/g)) if (isCalendarDay(match[0])) return match[0]
+  return null
+}
+
+export interface BlameLine { content: string; at: string | null }
+/** `git blame --line-porcelain` output to line number -> content and author time (null for an uncommitted line). */
+export function parseBlamePorcelain(output: string): Map<number, BlameLine> {
+  const lines = new Map<number, BlameLine>()
+  let current: { sha: string; line: number; time: number | null } | null = null
+  for (const raw of output.split('\n')) {
+    if (raw.startsWith('\t')) {
+      if (current) {
+        const committed = !/^0+$/.test(current.sha) && current.time !== null && Number.isFinite(current.time)
+        lines.set(current.line, { content: raw.slice(1), at: committed ? new Date(current.time! * 1000).toISOString() : null })
+      }
+      current = null
+      continue
+    }
+    const head = /^([0-9a-f]{40}|[0-9a-f]{64}) \d+ (\d+)(?: \d+)?$/.exec(raw)
+    if (head) { current = { sha: head[1], line: Number(head[2]), time: null }; continue }
+    if (current && raw.startsWith('author-time ')) current.time = Number(raw.slice('author-time '.length))
+  }
+  return lines
+}
+
+/** The line still holds the task (the file can change between the board read and the blame). */
+export function lineHolds(content: string, description: string): boolean {
+  const probe = description.trim().slice(0, TASK_DATE_LIMITS.guardChars)
+  return probe.length > 0 && content.includes(probe)
+}
+
+/** The text to find in history: the task's own words (not its checkbox, source or markers, which change later). */
+export function pickaxeNeedle(description: string, content?: string): string | null {
+  const text = description.trim()
+  if (text.length < TASK_DATE_LIMITS.needleMin || text.includes('\0')) return null
+  const full = text.slice(0, TASK_DATE_LIMITS.needleMax)
+  if (!content || content.includes(full)) return full
+  const head = text.slice(0, TASK_DATE_LIMITS.guardChars)
+  return content.includes(head) ? head : full
+}
+
+/** The nearest folder at or above `dir` holding `.git` (a folder, or a pointer file), or null. */
+export function findGitWorkTree(dir: string): string | null {
+  let at = dir
+  for (let depth = 0; depth < 64; depth++) {
+    if (existsSync(join(at, '.git'))) return at
+    const up = dirname(at)
+    if (up === at) return null
+    at = up
+  }
+  return null
+}
+
+interface FileState { file: string; dir: string; head: string; lines: Map<number, BlameLine> }
+/** `d`: the day, or null when history has no such text yet; then `h` is the HEAD it was looked up at. */
+interface CreatedEntry { d: string | null; h?: string }
+interface PickaxeJob { key: string; needle: string; state: FileState }
+
+/** execFile kills a git that outlives its timeout: a timeout says nothing about the history or the file. */
+export function isGitTimeout(error: unknown): boolean {
+  const e = error as { killed?: unknown; signal?: unknown; code?: unknown } | null
+  return !!e && (e.killed === true || (typeof e.signal === 'string' && e.signal.length > 0) || e.code === 'ETIMEDOUT')
+}
+
+export interface TaskDateResolverOptions {
+  git?: DateGitRunner
+  cacheFile?: string
+  /** The overall deadline for one resolve (TASK_DATE_LIMITS.deadlineMs). */
+  deadlineMs?: number
+  now?: () => number
+  findRepo?: (dir: string) => string | null
+}
+
+export class TaskDateResolver {
+  private readonly git: DateGitRunner
+  private readonly cacheFile: string
+  private readonly deadlineMs: number
+  private readonly now: () => number
+  private readonly findRepo: (dir: string) => string | null
+  private blame = new Map<string, { key: string; lines: Promise<Map<number, BlameLine> | null> }>()
+  private created: Map<string, CreatedEntry> | null = null
+  private pending = new Map<string, Promise<void>>()
+  /** A first-seen lookup that failed (a timeout, a git error): not "absent", and not retried until this time. */
+  private lookupBackoff = new Map<string, number>()
+  /** A file whose rev-parse or blame timed out: no git for it until this time. */
+  private fileBackoff = new Map<string, number>()
+  private dirty = false
+  private flushTimer: ReturnType<typeof setTimeout> | null = null
+
+  constructor(options: TaskDateResolverOptions = {}) {
+    this.git = options.git ?? realDateGitRunner
+    this.cacheFile = options.cacheFile ?? TASK_DATES_CACHE_FILE
+    this.deadlineMs = options.deadlineMs ?? TASK_DATE_LIMITS.deadlineMs
+    this.now = options.now ?? Date.now
+    this.findRepo = options.findRepo ?? findGitWorkTree
+  }
+
+  /**
+   * Date fields for every row, keyed by taskDateKey(domain, id). Never throws; an unknown is null. Everything git does
+   * for this call (rev-parse, blame, first-seen lookups) shares ONE deadline: past it the call answers with what it
+   * has, source dates included, and git work already started keeps running to fill the caches for a later call.
+   */
+  async resolve(rows: readonly DateSourceRow[], root: string): Promise<Map<string, TaskDateFields>> {
+    const deadline = this.now() + this.deadlineMs
+    const out = new Map<string, TaskDateFields>()
+    const states = new Map<string, FileState | null>()
+    const reads = [...new Set(rows.map(row => row.domain))].map(domain =>
+      this.fileState(join(root, domain, 'tasks.md')).catch(() => null).then(state => { states.set(domain, state) }))
+    await this.until(Promise.all(reads), deadline)
+    const jobs = new Map<string, PickaxeJob>()
+    const waiting: Array<{ fields: TaskDateFields; key: string }> = []
+    for (const row of rows) {
+      const fields: TaskDateFields = { ...NO_TASK_DATES }
+      out.set(taskDateKey(row.domain, row.id), fields)
+      const fromSource = sourceDate(row.source)
+      if (fromSource) { fields.createdOn = fromSource; fields.createdFrom = 'source' }
+      const state = states.get(row.domain)
+      if (!state) continue
+      const line = state.lines.get(row.line_number)
+      if (line && lineHolds(line.content, row.description)) fields.lineChangedAt = line.at
+      if (fromSource) continue
+      const needle = pickaxeNeedle(row.description, line?.content)
+      if (!needle) continue
+      const key = createHash('sha256').update(state.file + '\0' + needle).digest('hex').slice(0, 32)
+      const known = this.lookup(key, state.head)
+      if (known === undefined) { jobs.set(key, { key, needle, state }); waiting.push({ fields, key }) }
+      else if (known) { fields.createdOn = known; fields.createdFrom = 'git' }
+    }
+    if (jobs.size) {
+      await this.runWithin([...jobs.values()], deadline)
+      for (const { fields, key } of waiting) {
+        const day = this.created?.get(key)?.d
+        if (day) { fields.createdOn = day; fields.createdFrom = 'git' }
+      }
+    }
+    return out
+  }
+
+  /** Write the first-seen cache now (it is otherwise written shortly after a lookup lands). */
+  flush(): void {
+    if (this.flushTimer) { clearTimeout(this.flushTimer); this.flushTimer = null }
+    if (!this.dirty || !this.created) return
+    this.dirty = false
+    try {
+      mkdirSync(dirname(this.cacheFile), { recursive: true, mode: 0o700 })
+      durableAtomicWriteFileSync(this.cacheFile, JSON.stringify({ version: 1, created: Object.fromEntries(this.created) }) + '\n', { mode: 0o600 })
+    } catch (e) { console.warn('[task-dates] cache not saved:', e instanceof Error ? e.message : e) }
+  }
+
+  /** Lookups still running in the background (tests). */
+  async settled(): Promise<void> {
+    while (this.pending.size) await Promise.allSettled([...this.pending.values()])
+    await Promise.allSettled([...this.blame.values()].map(entry => entry.lines))
+  }
+
+  /** Wait for `work` or the deadline, whichever comes first. */
+  private async until(work: Promise<unknown>, deadline: number): Promise<void> {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const late = new Promise<void>(resolve => { timer = setTimeout(resolve, Math.max(0, deadline - this.now())) })
+    try { await Promise.race([work, late]) } finally { clearTimeout(timer) }
+  }
+
+  private async fileState(file: string): Promise<FileState | null> {
+    const dir = dirname(file)
+    if (!this.findRepo(dir)) return null
+    if ((this.fileBackoff.get(file) ?? 0) > this.now()) return null
+    let stat: ReturnType<typeof statSync>
+    try { stat = statSync(file) } catch { return null }
+    if (!stat.isFile()) return null
+    let head: string
+    try { head = (await this.git(['rev-parse', '--verify', '-q', 'HEAD'], dir, TASK_DATE_LIMITS.gitTimeoutMs)).trim() } catch (e) {
+      if (isGitTimeout(e)) this.fileBackoff.set(file, this.now() + TASK_DATE_LIMITS.fileBackoffMs)
+      return null
+    }
+    if (!/^[0-9a-f]{40,64}$/.test(head)) return null
+    const key = `${head}|${stat.mtimeMs}|${stat.size}`
+    let entry = this.blame.get(file)
+    if (!entry || entry.key !== key) {
+      // An untracked file fails blame: nothing about it comes from git, until HEAD or the file changes. A blame that
+      // timed out says nothing about the file, so it is forgotten (and the file rests) rather than kept as "untracked".
+      const blamed = { key, lines: this.git(['blame', '--line-porcelain', '--', basename(file)], dir, TASK_DATE_LIMITS.gitTimeoutMs)
+        .then(parseBlamePorcelain, (e: unknown) => {
+          if (isGitTimeout(e)) {
+            this.fileBackoff.set(file, this.now() + TASK_DATE_LIMITS.fileBackoffMs)
+            if (this.blame.get(file) === blamed) this.blame.delete(file)
+          }
+          return null
+        }) }
+      entry = blamed
+      this.blame.delete(file)
+      this.blame.set(file, entry)
+      while (this.blame.size > TASK_DATE_LIMITS.blameFiles) this.blame.delete(this.blame.keys().next().value!)
+    }
+    const lines = await entry.lines
+    return lines ? { file, dir, head, lines } : null
+  }
+
+  /** The cached day, null when history had no such text at this HEAD, or undefined when it must be looked up. */
+  private lookup(key: string, head: string): string | null | undefined {
+    const entry = this.cache().get(key)
+    if (entry?.d) return entry.d
+    if (entry && entry.h === head) return null
+    // A lookup that failed recently is neither known nor retried yet: the field stays null for now.
+    if ((this.lookupBackoff.get(key) ?? 0) > this.now()) return null
+    return undefined
+  }
+
+  /** Start lookups until the deadline, then answer with what landed. Lookups already started keep running. */
+  private async runWithin(jobs: PickaxeJob[], deadline: number): Promise<void> {
+    let next = 0
+    const worker = async () => {
+      while (next < jobs.length && this.now() < deadline) await this.pickaxe(jobs[next++])
+    }
+    await this.until(Promise.all(Array.from({ length: Math.min(TASK_DATE_LIMITS.concurrency, jobs.length) }, worker)), deadline)
+  }
+
+  private pickaxe(job: PickaxeJob): Promise<void> {
+    const running = this.pending.get(job.key)
+    if (running) return running
+    const work = this.git(['log', '--reverse', '--format=%ad', '--date=short', `-S${job.needle}`, '--', basename(job.state.file)],
+      job.state.dir, TASK_DATE_LIMITS.gitTimeoutMs)
+      .then(out => {
+        const day = out.split('\n').map(line => line.trim()).find(line => /^\d{4}-\d{2}-\d{2}$/.test(line)) ?? null
+        this.lookupBackoff.delete(job.key)
+        this.remember(job.key, day ? { d: day } : { d: null, h: job.state.head })
+      }, () => {
+        // A timeout or a git error is not "not in history": nothing is cached, and the lookup rests before a retry.
+        this.lookupBackoff.set(job.key, this.now() + TASK_DATE_LIMITS.lookupBackoffMs)
+      })
+      .finally(() => this.pending.delete(job.key))
+    this.pending.set(job.key, work)
+    return work
+  }
+
+  private cache(): Map<string, CreatedEntry> {
+    if (this.created) return this.created
+    this.created = new Map()
+    try {
+      const parsed = JSON.parse(readFileSync(this.cacheFile, 'utf8')) as { version?: unknown; created?: Record<string, unknown> }
+      if (parsed?.version === 1 && parsed.created && typeof parsed.created === 'object') {
+        for (const [key, raw] of Object.entries(parsed.created)) {
+          const entry = raw as Partial<CreatedEntry>
+          if (typeof entry?.d === 'string' && isCalendarDay(entry.d)) this.created.set(key, { d: entry.d })
+          else if (entry?.d === null && typeof entry.h === 'string') this.created.set(key, { d: null, h: entry.h })
+        }
+      }
+    } catch { /* missing or unreadable: start empty */ }
+    return this.created
+  }
+
+  private remember(key: string, entry: CreatedEntry): void {
+    const cache = this.cache()
+    cache.delete(key)
+    cache.set(key, entry)
+    while (cache.size > TASK_DATE_LIMITS.cacheEntries) cache.delete(cache.keys().next().value!)
+    this.dirty = true
+    if (!this.flushTimer) {
+      this.flushTimer = setTimeout(() => this.flush(), 250)
+      this.flushTimer.unref?.()
+    }
+  }
+}
+
+/**
+ * The resolver, bounded from outside as well: if it has not answered by the deadline (plus a moment for the answer
+ * itself), every row gets null dates. A dated board read is never held past the deadline by git.
+ */
+export async function resolveTaskDatesWithin(resolver: Pick<TaskDateResolver, 'resolve'>, rows: readonly DateSourceRow[], root: string,
+                                             deadlineMs: number = TASK_DATE_LIMITS.deadlineMs): Promise<Map<string, TaskDateFields>> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const late = new Promise<Map<string, TaskDateFields>>(resolve => {
+    timer = setTimeout(() => resolve(new Map()), deadlineMs + TASK_DATE_LIMITS.answerSlackMs)
+  })
+  try { return await Promise.race([resolver.resolve(rows, root), late]) } finally { clearTimeout(timer) }
+}
+
+let shared: TaskDateResolver | null = null
+export function sharedTaskDateResolver(): TaskDateResolver { return shared ??= new TaskDateResolver() }

package/server/lib/task-store.ts

@@ -10,6 +10,8 @@ import {
 } from './morning-brief-config.js'
 import { localClock, shiftDay, taskInstant } from './morning-brief-schedule.js'
 import { callTaskBridge, taskBridgeAvailable, taskOperationsRoot, taskBridgeUnavailableMessage } from './task-bridge.js'
+import { NO_TASK_DATES, TASK_DATE_LIMITS, resolveTaskDatesWithin, sharedTaskDateResolver, taskDateKey, type TaskDateFields,
+  type TaskDateResolver } from './task-dates.js'
 import { taskDomainNames, isSafeDomainName } from './domains.js'
 import { isClientJobId } from './query-job-types.js'
 import { DEFAULT_MODEL, isClaudeModel } from '../../shared/model-preference.js'
@@ -469,7 +471,7 @@ export function projectRow(
   }
 }
 
-export async function listBoard(columnFilter?: string, nowMs = Date.now()): Promise<TaskBoardRow[]> {
+async function boardPairs(columnFilter: string | undefined, nowMs: number): Promise<Array<{ source: BridgeTaskRow; row: TaskBoardRow }>> {
   if (!taskBridgeAvailable()) {
     throw new TaskRunError(503, 'cos_pipeline_not_configured', taskBridgeUnavailableMessage())
   }
@@ -479,8 +481,33 @@ export async function listBoard(columnFilter?: string, nowMs = Date.now()): Prom
     Promise.resolve(loadTaskLedger(taskStorePaths())),
   ])
   return rows
-    .map(row => projectRow(row, ledger, clock.day, nowMs, config.timezone, config.taskCatchUpMinutes))
-    .filter((row): row is TaskBoardRow => !!row && (!columnFilter || row.column === columnFilter))
+    .map(source => ({ source, row: projectRow(source, ledger, clock.day, nowMs, config.timezone, config.taskCatchUpMinutes) }))
+    .filter((pair): pair is { source: BridgeTaskRow; row: TaskBoardRow } => !!pair.row && (!columnFilter || pair.row.column === columnFilter))
+}
+
+export async function listBoard(columnFilter?: string, nowMs = Date.now()): Promise<TaskBoardRow[]> {
+  return (await boardPairs(columnFilter, nowMs)).map(pair => pair.row)
+}
+
+/**
+ * GET /api/tasks and GET /api/work-board rows (6.65.0): the board plus `createdOn`, `createdFrom` and `lineChangedAt`
+ * (lib/task-dates.ts). Every caller of those two routes pays for the dated read, the glasses' and the phone's /api/tasks
+ * reads included: its git work is bounded by TASK_DATE_LIMITS.deadlineMs (1.5 s, under the phone's 4 s timeout), past
+ * which the dates come back null. The shared Work board reader (the glasses' activity, open-work and request glances)
+ * and Jev advice use listBoard, which does no git work.
+ * Additive: every existing field is unchanged, and older Controls ignore the new ones. The dates come from the source
+ * label and from git, read-only, for both the configured COS bridge and the packaged task runtime; a date that cannot
+ * be known is null, and a failure to date never fails the board.
+ */
+export async function listBoardWithDates(columnFilter?: string, nowMs = Date.now(),
+                                         resolver: Pick<TaskDateResolver, 'resolve'> = sharedTaskDateResolver(),
+                                         deadlineMs: number = TASK_DATE_LIMITS.deadlineMs): Promise<Array<TaskBoardRow & TaskDateFields>> {
+  const pairs = await boardPairs(columnFilter, nowMs)
+  let dates = new Map<string, TaskDateFields>()
+  try { dates = await resolveTaskDatesWithin(resolver, pairs.map(pair => pair.source), taskOperationsRoot(), deadlineMs) } catch (e) {
+    console.warn('[tasks] dates unavailable:', e instanceof Error ? e.message : e)
+  }
+  return pairs.map(({ row }) => ({ ...row, ...(dates.get(taskDateKey(row.domain, row.id)) ?? NO_TASK_DATES) }))
 }
 
 export function workBadgeCount(rows: readonly TaskBoardRow[]): number {

package/server/lib/work-search.ts

@@ -0,0 +1,226 @@
+/**
+ * Work search by meaning (6.65.0, Control 0.5.259).
+ *
+ * Control searches the board's cards by words on its own, instantly. After a pause it asks this for the card the user
+ * MEANS: one Jev Choice over the board's task texts, with `none` as an option. Measured 2026-10-06 on 105 real Quilt
+ * tasks and 10 queries: the right card first 10 of 10 times in 0.2 s (keyword search alone found 7 of 10).
+ *
+ * The candidates are the board's own rows (the same listBoard read /api/tasks serves), never client text: the client
+ * names a scope, a domain, or exact ids. A Choice holds at most 254 options plus `none`, so a larger set is refused as
+ * `too_many_candidates` rather than truncated (a truncated search would silently miss cards).
+ *
+ * Cost controls of its own, separate from Work intake and session advice (COS_JEV_DAILY_TOKENS): a daily input-token
+ * cap (COS_JEV_SEARCH_DAILY_TOKENS, default 1,000,000, about 200 searches at the ~5k input tokens measured per search:
+ * 64.5k over 13 live calls), its own usage ledger, its own breaker (3 failures, then 1 hour), and a switch
+ * (COS_JEV_SEARCH=0 turns it off). Key resolution and the request timeout are jev.ts's. A search that cannot run
+ * answers HTTP 200 with `available: false` and a reason, so Control keeps its word search and says one line about why.
+ */
+import { createHash } from 'node:crypto'
+import { dataPath } from './data-dir.js'
+import { estimateJevTokens, JevClient, JevError } from './jev.js'
+import { boundForRedaction, redactSecretText } from './activity-preview.js'
+import { redactSecrets } from './lens-gist-engines.js'
+
+export const WORK_SEARCH_LIMITS = {
+  queryMin: 2, queryMax: 200,
+  /** A Jev Choice holds 255 options; one is `none`. */
+  maxCandidates: 254,
+  optionChars: 300,
+  /** How much of a task's text the redaction reads: four times what Jev gets, so no pattern ever scans a long input. */
+  optionScanChars: 1_200,
+  minP: 0.02, maxResults: 20,
+  cacheMs: 10 * 60_000, cacheEntries: 200,
+  defaultDailyTokens: 1_000_000,
+} as const
+export const WORK_SEARCH_USAGE_FILE = dataPath('jev-search-usage.json')
+export const WORK_SEARCH_SCOPES = ['all', 'attention', 'progress', 'completed'] as const
+export type WorkSearchScope = typeof WORK_SEARCH_SCOPES[number]
+
+export const WORK_SEARCH_INSTRUCTIONS = 'The user typed `query` into the search box of their task board. Which task are they trying '
+  + 'to find? Pick the task they mean even when it uses different words, or none if no task fits.'
+export const WORK_SEARCH_NONE = 'None of these tasks is what the user is looking for.'
+
+export type WorkSearchReason = 'jev_not_configured' | 'jev_key_rejected' | 'jev_cap_reached' | 'jev_breaker_open' | 'jev_request_rejected'
+  | 'jev_unavailable' | 'search_off' | 'too_many_candidates'
+export const WORK_SEARCH_MESSAGES: Record<WorkSearchReason, string> = {
+  jev_not_configured: 'Meaning search needs a TypeSafe key. Add one in Settings.',
+  jev_key_rejected: 'TypeSafe did not accept the saved key. Check it in Settings. Word search still works.',
+  jev_cap_reached: 'Meaning search has used today’s budget. It resets at midnight UTC. Word search still works.',
+  jev_breaker_open: 'Meaning search is paused for an hour after repeated failures. Word search still works.',
+  jev_request_rejected: 'Jev refused this search request. Word search still works.',
+  jev_unavailable: 'Meaning search got no answer from Jev. Word search still works.',
+  search_off: 'Meaning search is turned off on this server.',
+  too_many_candidates: `Meaning search covers up to ${WORK_SEARCH_LIMITS.maxCandidates} cards. Pick a domain to search this view.`,
+}
+
+export interface WorkSearchHit { id: string; p: number }
+export type WorkSearchResult =
+  | { available: true; results: WorkSearchHit[]; none: number | null; cached: boolean; tokens: number }
+  | { available: false; reason: WorkSearchReason; message: string }
+
+export function unavailable(reason: WorkSearchReason): Extract<WorkSearchResult, { available: false }> {
+  return { available: false, reason, message: WORK_SEARCH_MESSAGES[reason] }
+}
+
+/** The daily input-token cap for search alone. The ledger day is UTC, so the budget resets at midnight UTC. */
+export function workSearchDailyCap(): number {
+  const raw = Number(process.env.COS_JEV_SEARCH_DAILY_TOKENS)
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : WORK_SEARCH_LIMITS.defaultDailyTokens
+}
+
+/**
+ * On unless COS_JEV_SEARCH says off (0, false, no, off). The value comes from the server's environment, which is fixed
+ * when the server starts (the LaunchAgent plist, or ~/.cos-glasses/.env read at boot), so changing it takes a restart.
+ * The cap, COS_JEV_SEARCH_DAILY_TOKENS, is the same.
+ */
+export function workSearchEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return !['0', 'false', 'no', 'off'].includes((env.COS_JEV_SEARCH ?? '').trim().toLowerCase())
+}
+
+/** Search's own Jev client: its own ledger file, cap and breaker. jev.ts supplies the key and the timeout. */
+export function createWorkSearchJevClient(fetchImpl: typeof fetch = fetch, now: () => Date = () => new Date(),
+                                          usageFile = WORK_SEARCH_USAGE_FILE): JevClient {
+  return new JevClient(fetchImpl, now, usageFile, workSearchDailyCap)
+}
+
+let sharedSearchClient: JevClient | null = null
+/** One search client per process: it owns search's breaker. Saving a new key resets it (routes/jev.ts). */
+export function sharedWorkSearchJevClient(): JevClient { return sharedSearchClient ??= createWorkSearchJevClient() }
+
+const WORK_DETAILS_RE = /\[Work details\]\([^)]*\)/gi
+const MARKDOWN_LINK_RE = /\[([^\]]*)\]\([^)\s]*\)/g
+// Bounded scheme, as in activity-preview.ts: an unbounded one is retried from every position of a long run.
+const SCHEME_URL_RE = /\b(?:[a-z][a-z0-9+.-]{0,31}:\/\/|www\.)\S+/gi
+const EMAIL_RE = /[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9.-]{1,253}\.[A-Za-z]{2,24}\b/g
+// A host with a path (docs.google.com/document/d/…). A bare domain stays: it is usually a brand name people search for.
+const PATH_URL_RE = /\b(?:[a-z0-9-]{1,63}\.){1,8}[a-z]{2,24}\/\S*/gi
+const LONG_RUN_RE = /[A-Za-z0-9_-]{24,}/g
+
+/**
+ * What Jev reads for one card (6.65.0 QA, S-W6): the task text with `[Work details](…)` links dropped, other markdown
+ * links reduced to their label, credentials masked by the server's secret redaction (redactSecretText, then
+ * redactSecrets), and URLs, email addresses and opaque ids (24 or more letters, digits, `-` or `_` with both a letter and
+ * a digit, the shape of a key or a document id) removed. They add nothing to finding a card, and TypeSafe is a third
+ * party. One line, at most 300 characters.
+ */
+export function searchOptionText(text: string): string {
+  let out = boundForRedaction(text, WORK_SEARCH_LIMITS.optionScanChars).head.replace(WORK_DETAILS_RE, ' ')
+  out = redactSecrets(redactSecretText(out))
+  out = out.replace(MARKDOWN_LINK_RE, '$1').replace(SCHEME_URL_RE, ' ').replace(EMAIL_RE, ' ').replace(PATH_URL_RE, ' ')
+  out = out.replace(LONG_RUN_RE, run => /\d/.test(run) && /[A-Za-z]/.test(run) ? ' ' : run)
+  return out.replace(/\s+/g, ' ').trim().slice(0, WORK_SEARCH_LIMITS.optionChars).trim()
+}
+
+/**
+ * API POSTs that only read (6.65.0 QA). index.ts lets them past the global mutation lease. POST /work/search reads the
+ * board and asks Jev one question; it writes nothing but its own token ledger (one atomic write). Under the lease, a
+ * drain for an update or restart would wait up to 20 s (the Jev timeout) for a search, and a drain would answer every
+ * search 503. Outside it, a restart mid-search loses at most that search's token count.
+ */
+export function isReadOnlyApiPost(method: string, path: string): boolean {
+  return method === 'POST' && path === '/work/search'
+}
+
+/** A query's length as people count it: code points, not UTF-16 units, so 150 emoji are 150 (Control counts characters). */
+export function queryLength(query: string): number { return [...query].length }
+
+export interface SearchableRow { id: string; domain: string; text: string; checked: boolean; workIdentity?: string }
+export interface CandidateRequest { domain?: string; scope?: WorkSearchScope; ids?: string[] }
+
+/**
+ * The cards a search covers, in board order. Exact ids win: Control sends them for views only it can compute (Needs
+ * attention, In progress). Otherwise a domain board covers that domain's cards; All work covers open cards; Completed
+ * covers completed ones. Needs attention and In progress without ids cover open cards. Rows without searchable text
+ * are left out. Returns null when there are more than 254.
+ */
+export function selectCandidates<Row extends SearchableRow>(rows: readonly Row[], request: CandidateRequest): Row[] | null {
+  const inDomain = (row: Row) => !request.domain || row.domain === request.domain
+  let picked: Row[]
+  if (request.ids) {
+    const wanted = new Set(request.ids)
+    picked = rows.filter(row => wanted.has(row.id) || (!!row.workIdentity && wanted.has(row.workIdentity)))
+  } else if (request.scope === 'completed') {
+    picked = rows.filter(row => row.checked && inDomain(row))
+  } else if (request.scope === 'attention' || request.scope === 'progress') {
+    picked = rows.filter(row => !row.checked && inDomain(row))
+  } else if (request.domain) {
+    picked = rows.filter(row => row.domain === request.domain)
+  } else {
+    picked = rows.filter(row => !row.checked)
+  }
+  picked = picked.filter(row => searchOptionText(row.text).length > 0)
+  return picked.length > WORK_SEARCH_LIMITS.maxCandidates ? null : picked
+}
+
+/** Jev's probabilities as hits: offered cards only, p at least 0.02, most likely first, at most 20. */
+export function rankHits(probabilities: Record<string, unknown> | undefined, ids: readonly string[]): { results: WorkSearchHit[]; none: number | null } {
+  if (!probabilities || typeof probabilities !== 'object') throw new JevError('jev_bad_answer', 'Jev returned no probabilities')
+  const results: WorkSearchHit[] = []
+  let none: number | null = null
+  for (const [key, raw] of Object.entries(probabilities)) {
+    const p = typeof raw === 'number' && Number.isFinite(raw) ? raw : Number.NaN
+    if (Number.isNaN(p) || p < 0 || p > 1) throw new JevError('jev_bad_answer', 'Jev answered with a probability outside 0 to 1')
+    if (key === 'none') { none = round(p); continue }
+    const index = /^t(0|[1-9]\d*)$/.test(key) ? Number(key.slice(1)) : -1
+    if (index < 0 || index >= ids.length) throw new JevError('jev_bad_answer', 'Jev chose a card that was not offered')
+    if (p >= WORK_SEARCH_LIMITS.minP) results.push({ id: ids[index], p: round(p) })
+  }
+  results.sort((a, b) => b.p - a.p)
+  return { results: results.slice(0, WORK_SEARCH_LIMITS.maxResults), none }
+}
+const round = (n: number) => Math.round(n * 10_000) / 10_000
+
+/** Case, spacing and Unicode form do not change what was asked. */
+export function normalizeQuery(query: string): string {
+  return query.normalize('NFKC').replace(/\s+/g, ' ').trim().toLowerCase()
+}
+
+const PASSED_THROUGH = new Set<string>(['jev_not_configured', 'jev_key_rejected', 'jev_cap_reached', 'jev_breaker_open', 'jev_request_rejected'])
+
+export class WorkSearcher {
+  private cache = new Map<string, { at: number; results: WorkSearchHit[]; none: number | null }>()
+  private inflight = new Map<string, Promise<WorkSearchResult>>()
+  constructor(private readonly jev: JevClient, private readonly now: () => number = () => Date.now()) {}
+
+  /** One Jev Choice over `candidates` (already selected, at most 254). Never throws for a Jev failure. */
+  async search(query: string, candidates: readonly SearchableRow[]): Promise<WorkSearchResult> {
+    if (candidates.length > WORK_SEARCH_LIMITS.maxCandidates) return unavailable('too_many_candidates')
+    if (!candidates.length) return { available: true, results: [], none: 1, cached: false, tokens: 0 }
+    const texts = candidates.map(row => searchOptionText(row.text))
+    const set = createHash('sha256').update(JSON.stringify(candidates.map((row, i) => [row.id, texts[i]]))).digest('hex')
+    const key = createHash('sha256').update(normalizeQuery(query) + '\0' + set).digest('hex')
+    const hit = this.cache.get(key)
+    if (hit && this.now() - hit.at < WORK_SEARCH_LIMITS.cacheMs) {
+      return { available: true, results: hit.results, none: hit.none, cached: true, tokens: 0 }
+    }
+    if (hit) this.cache.delete(key)
+    // Typing can send the same search twice before the first answers; the second waits for the first.
+    const running = this.inflight.get(key)
+    if (running) return running
+    const work = this.ask(query, candidates.map(row => row.id), texts, key)
+    this.inflight.set(key, work)
+    try { return await work } finally { this.inflight.delete(key) }
+  }
+
+  private async ask(query: string, ids: string[], texts: string[], key: string): Promise<WorkSearchResult> {
+    const state = { query: query.trim() }
+    const criteria: Record<string, string> = Object.fromEntries(texts.map((text, i) => [`t${i}`, text]))
+    criteria.none = WORK_SEARCH_NONE
+    const questions = { c: { type: 'choice', instructions: WORK_SEARCH_INSTRUCTIONS, criteria } }
+    try {
+      const reply = await this.jev.ask(state, questions, estimateJevTokens({ state, questions }))
+      const { results, none } = rankHits(reply.answers.c?.probabilities, ids)
+      if (this.cache.size >= WORK_SEARCH_LIMITS.cacheEntries) this.cache.delete(this.cache.keys().next().value!)
+      this.cache.set(key, { at: this.now(), results, none })
+      return { available: true, results, none, cached: false, tokens: reply.inputTokens }
+    } catch (e) {
+      if (!(e instanceof JevError)) throw e
+      // Each says what happened. A 400, 413 or 422 is jev_request_rejected: the request itself was refused, which does
+      // not count toward the breaker (jev.ts), because the same cards would be refused again and an outage pause would
+      // only hide search for every other board. Unreachable, 5xx and a malformed answer are jev_unavailable.
+      if (PASSED_THROUGH.has(e.code)) return unavailable(e.code as WorkSearchReason)
+      console.warn('[work-search] Jev failed:', e.code)
+      return unavailable('jev_unavailable')
+    }
+  }
+}