@gotcos/glasses-server 6.99.29 → 7.0.7

package/server/lib/session-links.ts

@@ -0,0 +1,280 @@
+/**
+ * Link cards (preview engine phase 1, PLAN_preview_engine_2026-11-08 4f). A Markdown link in a reply to a local file
+ * becomes a card where it sits. 40% of sessions link a local file; 3,389 links in 14 days, none of which worked.
+ *
+ * This module is pure apart from filesystem reads in `resolveLinkTarget`:
+ *   - `linkTokens`: the same bounded scanner as the inline-image tokens, for `[label](target)`. Code fences, inline
+ *     code, indented blocks and comments stay inert. Web URLs and #anchors are not local and stay as written.
+ *   - `splitLineAnchor`: `file.ts:42`, `:42:7`, `:42-50` and `#L42` become `line`, never part of the name.
+ *   - `resolveLinkTarget`: the row's cwd first, then the workspace root (21% of relative links need the root), then
+ *     authorized only inside the workspace or a Settings extra folder, and never a denied secret name.
+ *   - `previewKind`: what the viewer does with a name.
+ *
+ * Paths never leave the server: a card carries a base name, the link's words and an opaque id.
+ */
+import { realpathSync, statSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { isDeniedSecretPath } from './secret-path-guard.js'
+
+export const LINK_CARDS_PER_TURN = 20
+export const SESSION_OUTPUT_LINK_ID = /^al_[a-f0-9]{64}$/
+/** The marker a card leaves in the projected text: `[label](cos-file:N)`, N the index into the turn's outputLinks. */
+export const LINK_MARKER = /\[([^\]\n]*)\]\(cos-file:(\d{1,2})\)/g
+
+export type PreviewKind = 'image' | 'pdf' | 'html' | 'markdown' | 'text' | 'code' | 'table' | 'document' | 'slides' | 'sheet'
+  | 'audio' | 'video' | 'archive' | 'folder' | 'file'
+/** `secret_file`: the 7.0.4 shared deny list (secret-path-guard.ts) refused the name, as written or canonically. */
+export type LinkReason = 'outside_workspace' | 'missing' | 'unavailable' | 'secret_file'
+
+/** A link card. Only a base name, the link's words and an opaque id travel; never a Mac path. */
+export interface SessionOutputLink {
+  id: string
+  label: string
+  name: string
+  kind: PreviewKind
+  type: string
+  size?: number
+  line?: number
+  state: 'available' | 'unavailable'
+  reason?: LinkReason
+  /** The words the card shows instead (SECRET_FILE_NOTICE), set only with `secret_file`. */
+  notice?: string
+}
+
+export interface LinkToken { label: string; target: string; start: number; end: number }
+
+const KINDS: Array<[RegExp, PreviewKind, string]> = [
+  [/\.(png|jpe?g|webp|hei[cf]|avif)$/i, 'image', 'Image'],
+  [/\.gif$/i, 'image', 'GIF image'],
+  [/\.pdf$/i, 'pdf', 'PDF'],
+  [/\.html?$/i, 'html', 'HTML page'],
+  [/\.(md|markdown|mdx)$/i, 'markdown', 'Markdown'],
+  [/\.csv$/i, 'table', 'CSV'],
+  [/\.tsv$/i, 'table', 'TSV'],
+  [/\.(txt|log|text)$/i, 'text', 'Text'],
+  [/\.json$/i, 'code', 'JSON'],
+  [/\.jsonl$/i, 'code', 'JSON lines'],
+  [/\.ya?ml$/i, 'code', 'YAML'],
+  [/\.toml$/i, 'code', 'TOML'],
+  [/\.xml$/i, 'code', 'XML'],
+  // An SVG can carry script, so it is shown as its source, never as a picture.
+  [/\.svg$/i, 'code', 'SVG source'],
+  [/\.(ts|tsx|mts|cts)$/i, 'code', 'TypeScript'],
+  [/\.(js|jsx|mjs|cjs)$/i, 'code', 'JavaScript'],
+  [/\.py$/i, 'code', 'Python'],
+  [/\.swift$/i, 'code', 'Swift'],
+  [/\.(sh|zsh|bash)$/i, 'code', 'Shell script'],
+  [/\.(css|scss)$/i, 'code', 'CSS'],
+  [/\.(rb|go|rs|java|kt|c|h|cc|cpp|hpp|m|mm|sql|lua|php)$/i, 'code', 'Source code'],
+  [/\.(plist|ini|conf|cfg|properties)$/i, 'code', 'Settings file'],
+  [/\.docx?$/i, 'document', 'Word document'],
+  [/\.(pages|rtf)$/i, 'document', 'Document'],
+  [/\.xlsx?$/i, 'sheet', 'Excel workbook'],
+  [/\.numbers$/i, 'sheet', 'Spreadsheet'],
+  [/\.pptx?$/i, 'slides', 'PowerPoint deck'],
+  [/\.key$/i, 'slides', 'Keynote deck'],
+  [/\.(wav|mp3|m4a|aac|flac|aiff?)$/i, 'audio', 'Audio'],
+  [/\.(mp4|mov|webm|m4v)$/i, 'video', 'Video'],
+  [/\.(zip|tar|gz|tgz|bz2|xz|7z)$/i, 'archive', 'Archive'],
+  [/\.ehpk$/i, 'archive', 'EHPK package'],
+]
+export function previewKind(name: string): { kind: PreviewKind; type: string } {
+  for (const [re, kind, type] of KINDS) if (re.test(name)) return { kind, type }
+  const ext = /\.([a-z0-9]{1,8})$/i.exec(name)
+  return { kind: 'file', type: ext ? ext[1].toUpperCase() + ' file' : 'File' }
+}
+
+/** The base name a person sees: no directories, no control characters, at most 120 characters. */
+export function baseName(source: string): string {
+  const base = source.split(/[\\/]/).filter(Boolean).pop() || ''
+  const clean = base.replace(/[\u0000-\u001f\u007f]/g, '').trim()
+  return (clean || 'File').slice(0, 120)
+}
+
+/**
+ * A link's words, made safe to show: a label that is itself an absolute or home path becomes its base name, so
+ * `[/Users/x/plan.md](/Users/x/plan.md)` never puts the path in front of anyone. Anything else is kept (120 chars).
+ */
+export function linkLabel(label: string, name: string): string {
+  const clean = label.replace(/[\u0000-\u001f\u007f]/g, ' ').trim()
+  if (!clean) return name
+  if (/^(?:file:\/\/|~\/|\/)/.test(clean) || /(?:^|[\s(`'"])(?:\/Users\/|\/private\/|\/Volumes\/|\/var\/folders\/)/.test(clean)) return baseName(clean.replace(/^file:\/\//, ''))
+  return clean.slice(0, 120)
+}
+
+/**
+ * The words a link card shows in the reply. A label that is the file's own name keeps the line the link points at,
+ * so `[app.ts](/Users/x/app.ts#L42)` reads `app.ts:42`, as the 7.0.4 redactor wrote it. Prose labels stay as written.
+ */
+export function linkCardWords(label: string, name: string, target: string): string {
+  const words = linkLabel(label, name)
+  const { path, line } = splitLineAnchor(target)
+  if (!line) return words
+  const own = baseName(path.replace(/^file:\/\//i, ''))
+  return words === own || words === name ? words + ':' + line : words
+}
+
+export const LINK_SCAN_CHARS = 128 * 1024
+
+/**
+ * `[label](target)` tokens in reply text, never `![..](..)` (images have their own scanner). Bounded like the image
+ * scanner: inert inside fences, inline code, indented blocks and comments; the label has no brackets or newline; the
+ * target is angle-wrapped (spaces allowed) or balanced parentheses on one line. A trailing ` "title"` is dropped.
+ */
+export function linkTokens(raw: string, scanChars = LINK_SCAN_CHARS): LinkToken[] {
+  const text = raw.slice(0, scanChars)
+  const out: LinkToken[] = []
+  let fence = '', inline = 0
+  for (let i = 0; i < text.length; i++) {
+    if (i === 0 || text[i - 1] === '\n') {
+      if (!fence && /^(?: {4}| {0,3}\t)/.test(text.slice(i, i + 4))) { i = text.indexOf('\n', i); if (i < 0) break; continue }
+      const m = /^( {0,3})(`{3,}|~{3,})/.exec(text.slice(i, i + 80))
+      if (m) { if (!fence) fence = m[2]; else if (m[2][0] === fence[0] && m[2].length >= fence.length) fence = ''; i = text.indexOf('\n', i); if (i < 0) break; continue }
+    }
+    if (fence) continue
+    if (text[i] === '\\') { i++; continue }
+    if (text[i] === '`') { let n = 1; while (text[i + n] === '`') n++; if (!inline) inline = n; else if (inline === n) inline = 0; i += n - 1; continue }
+    if (inline) continue
+    if (text.startsWith('<!--', i)) { const end = text.indexOf('-->', i + 4); if (end < 0) break; i = end + 2; continue }
+    if (text[i] !== '[' || text[i - 1] === '!') continue
+    const close = text.indexOf(']', i + 1)
+    if (close < 0 || close - i > 250 || text[close + 1] !== '(') continue
+    const label = text.slice(i + 1, close)
+    if (label.includes('[') || label.includes('\n')) continue
+    let j = close + 2, target = '', valid = false
+    if (text[j] === '<') {
+      const end = text.indexOf('>', j + 1)
+      if (end >= 0 && text[end + 1] === ')' && !text.slice(j + 1, end).includes('\n')) { target = text.slice(j + 1, end); j = end + 2; valid = true }
+    } else {
+      const start = j; let depth = 1
+      while (j < text.length && j - start <= 4096) {
+        if (text[j] === '\n') break
+        if (text[j] === '(') depth++
+        if (text[j] === ')' && --depth === 0) { target = text.slice(start, j); j++; valid = true; break }
+        j++
+      }
+    }
+    if (!valid || !target || target.length > 4096 || /[\u0000-\u001f\u007f]/.test(target)) continue
+    const titled = /^(\S+)\s+"[^"]*"$/.exec(target)
+    if (titled) target = titled[1]
+    out.push({ label, target, start: i, end: j }); i = j - 1
+  }
+  return out
+}
+
+/** A target that names a local file: a path, `~/...` or `file://`. Web URLs, mail, anchors and network paths are not. */
+export function isLocalTarget(target: string): boolean {
+  if (!target || target.startsWith('#') || target.startsWith('//') || target.includes('\\')) return false
+  if (/^file:\/\//i.test(target)) return true
+  // `server.ts:42` is a path with a line, not a scheme.
+  return !/^[a-z][a-z0-9+.-]*:/i.test(splitLineAnchor(target).path)
+}
+
+/** `x.ts:42`, `x.ts:42:7`, `x.ts:42-50`, `x.ts#L42`, `x.ts#L42-L50` → the path and line 42. */
+export function splitLineAnchor(target: string): { path: string; line?: number } {
+  let m = /^(.*?)#L(\d{1,7})(?:C\d+)?(?:-L?\d{1,7})?$/.exec(target)
+  if (m && m[1]) return { path: m[1], line: Number(m[2]) || undefined }
+  m = /^(.*?):(\d{1,7})(?::\d{1,5}|-\d{1,7})?$/.exec(target)
+  if (m && m[1] && !/:$/.test(m[1])) return { path: m[1], line: Number(m[2]) || undefined }
+  const hash = target.indexOf('#')
+  return { path: hash > 0 ? target.slice(0, hash) : target }
+}
+
+export interface LinkRoots {
+  /** The session's canonical workspace, or null (broad or unknown). */
+  workspace: string | null
+  /** Canonical Settings extra folders. */
+  extra: readonly string[]
+  home: string
+}
+export type Resolved =
+  | { state: 'available'; path: string; root: string; name: string; isDir: boolean; size?: number }
+  | { state: 'unavailable'; reason: LinkReason; name: string }
+
+export function insideRoot(root: string, path: string): boolean {
+  const rel = relative(root, path)
+  return rel !== '' && rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel)
+}
+/** The allowed root holding a canonical path, or null. */
+export function authorizedRoot(path: string, roots: LinkRoots): string | null {
+  if (roots.workspace && insideRoot(roots.workspace, path)) return roots.workspace
+  for (const r of roots.extra) if (insideRoot(r, path)) return r
+  return null
+}
+
+function expandTarget(target: string, home: string): string | null {
+  if (/^file:\/\//i.test(target)) { try { return fileURLToPath(target) } catch { return null } }
+  if (target === '~') return home
+  if (target.startsWith('~/')) return join(home, target.slice(2))
+  return target
+}
+
+/**
+ * Where a link points, and whether COS may show it. Bases: the row's cwd, then the workspace root. A relative link
+ * that exists under neither is missing (when it would sit inside an allowed root) or outside. The canonical file
+ * decides containment, so a link out of the root is outside. A denied secret name is refused before any read, by its
+ * written name and by its canonical name.
+ */
+export function resolveLinkTarget(rawTarget: string, bases: readonly (string | null | undefined)[], roots: LinkRoots): Resolved {
+  const { path: written } = splitLineAnchor(rawTarget)
+  const variants = [written]
+  if (/%[0-9a-f]{2}/i.test(written)) { try { const d = decodeURIComponent(written); if (d !== written) variants.push(d) } catch { /* keep as written */ } }
+  // A percent-encoded name reads as its words ("Q3 plan.md", not "Q3%20plan.md").
+  const name = baseName(variants[variants.length - 1])
+  const lexicals: string[] = []
+  for (const v of variants) {
+    const expanded = expandTarget(v, roots.home)
+    if (!expanded) continue
+    if (isAbsolute(expanded)) lexicals.push(resolve(expanded))
+    else for (const b of bases) if (b && isAbsolute(b)) lexicals.push(resolve(b, expanded))
+  }
+  if (!lexicals.length) return { state: 'unavailable', reason: 'outside_workspace', name }
+  if (lexicals.some(p => isDeniedSecretPath(p))) return { state: 'unavailable', reason: 'secret_file', name }
+  for (const lexical of lexicals) {
+    let canonical: string
+    try { canonical = realpathSync(lexical) } catch { continue }
+    const root = authorizedRoot(canonical, roots)
+    if (!root) return { state: 'unavailable', reason: 'outside_workspace', name }
+    if (isDeniedSecretPath(canonical)) return { state: 'unavailable', reason: 'secret_file', name }
+    try {
+      const st = statSync(canonical)
+      if (st.isDirectory()) return { state: 'available', path: canonical, root, name, isDir: true }
+      if (!st.isFile()) return { state: 'unavailable', reason: 'missing', name }
+      // 7.0.4 QA's sent-file rule: a file with another hard link may be a secret under this name. Pictures are exempt
+      // (they are normalised to a JPEG, never served as they are).
+      if (st.nlink > 1 && !/\.(png|jpe?g|webp|hei[cf]|avif)$/i.test(canonical)) return { state: 'unavailable', reason: 'secret_file', name }
+      return { state: 'available', path: canonical, root, name, isDir: false, size: st.size }
+    } catch { return { state: 'unavailable', reason: 'missing', name } }
+  }
+  // Nothing there. Say missing only for a path that would be inside an allowed root (by its real parent folder).
+  const wouldBeInside = lexicals.some(p => {
+    if (authorizedRoot(p, roots)) return true
+    try { return authorizedRoot(join(realpathSync(resolve(p, '..')), baseName(p)), roots) !== null } catch { return false }
+  })
+  return { state: 'unavailable', reason: wouldBeInside ? 'missing' : 'outside_workspace', name }
+}
+
+/** Text with every card marker turned back into its words. Used when previews are off. Pure. */
+export function withoutLinkMarkers(text: string): string {
+  return text.replace(LINK_MARKER, '$1')
+}
+
+/** The sentence a reply ends with when it links more files than LINK_CARDS_PER_TURN (added after its last word). */
+export function linkOverflowSentence(extra: number): string {
+  return extra + (extra === 1 ? ' more linked file is not shown as a card.' : ' more linked files are not shown as cards.')
+}
+const LINK_OVERFLOW = /\n\n\d{1,6} more linked files? (?:is|are) not shown as (?:a )?cards?\./g
+/** The reply cap can cut the sentence: `\n\n23 more linked fi…`, at the end or just before the scan-limit line. */
+const LINK_OVERFLOW_CUT = /\n\n(\d{1,6})([^\n…]*)…(?=\n\[Reply shortened at the image preview scan limit\.\]$|$)/
+
+/**
+ * QA 7.0.5 (agent 4 C-N1): previews off sends no count, so the overflow sentence goes as well as the markers. A cut
+ * sentence goes only when what is left is exactly the start of that sentence, so a reply's own words stay. Pure.
+ */
+export function withoutLinkCards(text: string): string {
+  const out = withoutLinkMarkers(text).replace(LINK_OVERFLOW, '')
+  const cut = LINK_OVERFLOW_CUT.exec(out)
+  if (!cut || !linkOverflowSentence(Number(cut[1])).startsWith(cut[1] + cut[2])) return out
+  return out.slice(0, cut.index) + out.slice(cut.index + cut[0].length)
+}

package/server/lib/thread-turn-queue.ts

@@ -154,6 +154,16 @@ export function sessionSteerEnabled(env: NodeJS.ProcessEnv = process.env): boole
   return triStateFlag(env, 'COS_SESSION_STEER', false)
 }
 
+/**
+ * `COS_STEER_MIDTURN` (steer mid-turn, Miles 2026-11-07): a turn parked at a busy Claude desk
+ * session goes INTO the running turn through its peer inbox at the drain, and lands at its next
+ * tool step, instead of waiting for the turn to end. Default ON; `0` is the 6.99.33 behaviour.
+ * Independent of `COS_SESSION_STEER`, which only answers a client that asks for `mode: "steer"`.
+ */
+export function steerMidturnEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return triStateFlag(env, 'COS_STEER_MIDTURN', true)
+}
+
 /**
  * Reasons whose outcome COS cannot establish. Such a row is never resent and is kept for
  * UNKNOWN_DELIVERY_RETENTION_MS rather than 30 minutes, because the phone has to be able to

package/server/lib/today-brief.ts

@@ -4,7 +4,7 @@
  * Today's top text was counts ("Three agents are working, with 30 more sessions open"). This writes two or three plain
  * sentences about what the sessions are building toward, what is moving, what waits on Miles and what comes next, from
  * what an open Today already read: session titles, states and how long, each session's last line, what needs him, and
- * the Work cards in progress. Haiku writes it through the isolated text runner (claude-text-runner.ts: no tools, MCP,
+ * the Work cards in progress. Sonnet (7.0.1; Haiku before) writes it through the isolated text runner (claude-text-runner.ts: no tools, MCP,
  * hooks or session, `--model` always passed, so it can never become Opus).
  *
  * HOW IT STOPS (every model caller answers this; .claude/rules/gotchas.md "Every new claude -p caller"):
@@ -12,8 +12,10 @@
  *   set, the Settings toggle "Write the Today summary with a model" decides (today-brief-settings.json in the data
  *   folder). Neither set: OFF. The server has no clean private-build signal, so OFF is the default for everyone.
  * - CAPS: a generation only when an open Today asks (POST /api/today/brief), only when the trimmed inputs' fingerprint
- *   changed since the last summary, at most one start every 10 minutes, at most 60 starts a local day. A start is
- *   counted BEFORE the call, so a call that ran was spent whatever became of it.
+ *   changed since the last summary, at most one start every 10 minutes (7.0.5: a reconnect may skip that once per 10 minutes), at most "Summaries per day" starts a local day (7.0.5: a setting, 1 to 100, default 100; was 60). A start is
+ *   counted BEFORE the call, so a call that ran was spent whatever became of it. 7.0.1 FORCED REFRESH (the Today
+ *   refresh button, `force: true`): skips the 10-minute interval and the "inputs changed" check, at most one forced
+ *   start every 30 s, and still inside the same daily cap, the breaker, the switch, recording and drain.
  * - BREAKER: 3 failures in a row (a CLI error, a timeout, an empty or guarded answer) stop it for 1 hour; the next
  *   start after that hour is one trial, and a failed trial reopens it for another hour.
  * - NOT WHILE: a meeting is recording or the server is draining (6.99.26 QA). Those, the switch, the breaker, the cap
@@ -37,11 +39,36 @@ import { localDay } from './local-day.js'
 import { durableAtomicWriteFileSync } from './atomic-fs.js'
 import { securePrivateDirectory } from './secure-user-config.js'
 
-export const TODAY_BRIEF_MODEL = 'haiku'
+/**
+ * 7.0.1 (Miles 11/07, "It might be better to use sonnet for that summary generation"): Sonnet, was Haiku. The isolated
+ * runner passes it as `--model sonnet`, the CLI's alias for the current Sonnet (measured 11/07: it resolved to
+ * claude-sonnet-5-5 through runClaudeText).
+ *
+ * COST, measured 11/07 with a full-size prompt (40 sessions, about 3.6k input tokens, about 100 output) through the
+ * runner's own argv with JSON output: Sonnet $0.0156 to $0.0180 a call, Haiku $0.0008. About twenty times more a call.
+ * 7.0.5: the cap is "Summaries per day", default 100 (forced refreshes included), so the worst day is about $1.80 where Haiku's was about
+ * $0.05; the 10-minute interval and "only when the inputs changed" keep a normal day far below the cap. On a Claude
+ * subscription the CLI draws plan usage rather than billing; the figures are the CLI's own API-price estimate.
+ */
+export const TODAY_BRIEF_MODEL = 'sonnet'
 export const TODAY_BRIEF_EFFORT = 'low'
 export const TODAY_BRIEF_TIMEOUT_MS = 30_000
 export const TODAY_BRIEF_MIN_INTERVAL_MS = 10 * 60 * 1000
-export const TODAY_BRIEF_DAILY_CAP = 60
+/**
+ * 7.0.5 (Miles 11/08): "Summaries per day" is a setting, default 100, 1 to 100, saved with the switch in
+ * today-brief-settings.json and enforced here. Was a fixed 60. A saved value outside the range is clamped.
+ */
+export const TODAY_BRIEF_DAILY_CAP = 100
+export const TODAY_BRIEF_DAILY_CAP_MIN = 1
+export const TODAY_BRIEF_DAILY_CAP_MAX = 100
+/**
+ * 7.0.5: a client whose read failed and then recovered may say `reason: "reconnect"`: that one start skips the 10-minute
+ * interval (never the "inputs unchanged" check, the breaker, the switch or the daily cap). At most one such skip per
+ * this, so a client cannot use it to skip the interval again and again.
+ */
+export const TODAY_BRIEF_RECONNECT_MIN_MS = 10 * 60 * 1000
+/** 7.0.1: a forced refresh (the Today refresh button) at most once per this, on top of the daily cap. */
+export const TODAY_BRIEF_FORCE_MIN_MS = 30_000
 export const TODAY_BRIEF_BREAKER_FAILURES = 3
 export const TODAY_BRIEF_BREAKER_MS = 60 * 60 * 1000
 /** The fenced data block's bound. Four characters a token: about 3,000 tokens, with the system prompt about 3,300. */
@@ -54,7 +81,7 @@ export const TODAY_BRIEF_SETTINGS_FILE = 'today-brief-settings.json'
 
 export type TodayBriefState = 'fresh' | 'stale' | 'off' | 'failed'
 /** Why there is no fresh summary: the switch, a cap, the breaker, a failed call, or nothing to write about. */
-export type TodayBriefReason = 'switch_off' | 'interval' | 'daily_cap' | 'paused' | 'failed' | 'empty_inputs' | 'not_asked' | 'recording' | 'maintenance'
+export type TodayBriefReason = 'switch_off' | 'interval' | 'daily_cap' | 'paused' | 'failed' | 'empty_inputs' | 'not_asked' | 'recording' | 'maintenance' | 'refresh_throttled'
 export type TodayBriefSwitchSource = 'env' | 'settings' | 'default'
 
 export interface TodayBriefView {
@@ -70,6 +97,8 @@ export interface TodayBriefView {
   /** The switch as resolved now, and what set it. */
   enabled: boolean
   source: TodayBriefSwitchSource
+  /** 7.0.1: with reason `refresh_throttled`, how long until a forced refresh may start. */
+  retryAfterMs?: number
 }
 
 // ── inputs ─────────────────────────────────────────────────────────────────
@@ -484,6 +513,10 @@ interface BriefFile {
   count: number
   /** When the last generation started (the interval). */
   lastStartAt: number
+  /** 7.0.1: when the last FORCED generation started (TODAY_BRIEF_FORCE_MIN_MS). */
+  lastForceAt: number
+  /** 7.0.5: when the last start that used the reconnect skip began (TODAY_BRIEF_RECONNECT_MIN_MS). */
+  lastReconnectAt: number
   /** Failures in a row, and when the breaker opened. */
   failures: number
   openedAt: number
@@ -496,7 +529,7 @@ interface BriefFile {
   lastFailCode: string
   cache: BriefCache | null
 }
-const emptyFile = (day: string): BriefFile => ({ schema: 1, day, count: 0, lastStartAt: 0, failures: 0, openedAt: 0, lastAskFingerprint: '', lastOpener: '', lastFailAt: 0, lastFailCode: '', cache: null })
+const emptyFile = (day: string): BriefFile => ({ schema: 1, day, count: 0, lastStartAt: 0, lastForceAt: 0, lastReconnectAt: 0, failures: 0, openedAt: 0, lastAskFingerprint: '', lastOpener: '', lastFailAt: 0, lastFailCode: '', cache: null })
 const num = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : 0)
 
 function readJson(file: string): unknown {
@@ -521,6 +554,8 @@ function parseFile(raw: unknown, day: string): BriefFile {
     day: typeof raw.day === 'string' ? raw.day : day,
     count: Math.floor(num(raw.count)),
     lastStartAt: num(raw.lastStartAt),
+    lastForceAt: num(raw.lastForceAt),
+    lastReconnectAt: num(raw.lastReconnectAt),
     failures: Math.floor(num(raw.failures)),
     openedAt: num(raw.openedAt),
     lastAskFingerprint: typeof raw.lastAskFingerprint === 'string' ? raw.lastAskFingerprint : '',
@@ -554,28 +589,44 @@ export interface TodayBriefDeps {
 }
 
 /** The Settings status line's facts: paused until, today's cap reached, or the last call failed. */
-export type TodayBriefStatus = { kind: 'paused'; until: string } | { kind: 'daily_cap'; count: number } | { kind: 'failed'; at: string; code: string } | null
-export interface TodayBriefSettings { enabled: boolean; source: TodayBriefSwitchSource; saved: boolean | null; status?: TodayBriefStatus }
+export type TodayBriefStatus = { kind: 'paused'; until: string } | { kind: 'daily_cap'; count: number; cap: number } | { kind: 'failed'; at: string; code: string } | null
+export interface TodayBriefSettings { enabled: boolean; source: TodayBriefSwitchSource; saved: boolean | null; status?: TodayBriefStatus
+  /** 7.0.5: "Summaries per day" (TODAY_BRIEF_DAILY_CAP_MIN to _MAX). */
+  dailyCap: number }
+/** 7.0.5: GET|PUT /api/today/brief/settings/cap. */
+export interface TodayBriefCapView { dailyCap: number; min: number; max: number; default: number; usedToday: number }
+
+/** A whole number of summaries a day, 1 to 100. Anything that is not a finite number is the default. */
+export function clampTodayBriefDailyCap(value: unknown): number {
+  const n = typeof value === 'number' ? value : NaN
+  if (!Number.isFinite(n)) return TODAY_BRIEF_DAILY_CAP
+  return Math.min(TODAY_BRIEF_DAILY_CAP_MAX, Math.max(TODAY_BRIEF_DAILY_CAP_MIN, Math.round(n)))
+}
 
 export interface TodayBrief {
   /** The cached summary, no generation (GET). */
   peek(): TodayBriefView
-  /** Why nothing could be generated now, checked BEFORE the server's board and sub-agent reads; null when it may. */
-  gate(): TodayBriefReason | null
+  /** Why nothing could be generated now, checked BEFORE the server's board and sub-agent reads; null when it may.
+   *  7.0.1 `force` (the refresh button): the 10-minute interval does not apply; one forced start per 30 s does. */
+  gate(opts?: { force?: boolean; reconnect?: boolean }): TodayBriefReason | null
   /** A gated ask: the page's rows only, no reads and no call. Fresh while the page's rows match the cached summary's. */
   askGated(pageInputs: TodayBriefInputs, reason: TodayBriefReason): TodayBriefView
   /** An open Today's ask with what it read (POST). Generates only when every gate allows; never throws for a gate.
    *  `pageFingerprint` is the page's rows alone, kept with a new summary for later gated asks. */
-  ask(inputs: TodayBriefInputs, pageFingerprint?: string): Promise<TodayBriefView>
+  ask(inputs: TodayBriefInputs, pageFingerprint?: string, opts?: { force?: boolean; reconnect?: boolean }): Promise<TodayBriefView>
   settings(): TodayBriefSettings
   setEnabled(enabled: boolean): TodayBriefSettings
+  /** 7.0.5: "Summaries per day". */
+  cap(): TodayBriefCapView
+  setDailyCap(value: number): TodayBriefCapView
 }
 
 export function createTodayBrief(deps: TodayBriefDeps): TodayBrief {
   const now = deps.now ?? Date.now
   const env = deps.env ?? (() => process.env)
   const minInterval = deps.minIntervalMs ?? TODAY_BRIEF_MIN_INTERVAL_MS
-  const dailyCap = deps.dailyCap ?? TODAY_BRIEF_DAILY_CAP
+  /** A test's fixed cap, else the saved setting (read live), else 100. */
+  const dailyCap = (): number => deps.dailyCap ?? savedCap() ?? TODAY_BRIEF_DAILY_CAP
   let state: BriefFile | null = null
   let inflight: Promise<void> | null = null
 
@@ -598,6 +649,17 @@ export function createTodayBrief(deps: TodayBriefDeps): TodayBrief {
     const raw = readJson(deps.settingsFile)
     return record(raw) && raw.schema === 1 && typeof raw.enabled === 'boolean' ? raw.enabled : null
   }
+  const savedCap = (): number | null => {
+    const raw = readJson(deps.settingsFile)
+    return record(raw) && raw.schema === 1 && typeof raw.dailyCap === 'number' && Number.isFinite(raw.dailyCap) ? clampTodayBriefDailyCap(raw.dailyCap) : null
+  }
+  /** The settings file keeps both fields: writing one never drops the other. */
+  const writeSettings = (patch: { enabled?: boolean; dailyCap?: number }) => {
+    const enabled = patch.enabled ?? savedSetting()
+    const cap = patch.dailyCap ?? savedCap()
+    securePrivateDirectory(dirname(deps.settingsFile))
+    durableAtomicWriteFileSync(deps.settingsFile, JSON.stringify({ schema: 1, ...(enabled !== null ? { enabled } : {}), ...(cap !== null ? { dailyCap: cap } : {}) }) + '\n', { mode: 0o600 })
+  }
   const resolveSwitch = (): { enabled: boolean; source: TodayBriefSwitchSource; saved: boolean | null } => {
     const saved = savedSetting()
     const raw = (env().COS_TODAY_BRIEF_LLM ?? '').trim()
@@ -611,7 +673,16 @@ export function createTodayBrief(deps: TodayBriefDeps): TodayBrief {
   const within = (since: number, ms: number) => since >= 0 && since < ms
   const breakerOpen = (f: BriefFile) => f.failures >= TODAY_BRIEF_BREAKER_FAILURES && within(now() - f.openedAt, TODAY_BRIEF_BREAKER_MS)
 
+  const forceWait = (f: BriefFile): number => {
+    const since = now() - f.lastForceAt
+    return f.lastForceAt && within(since, TODAY_BRIEF_FORCE_MIN_MS) ? TODAY_BRIEF_FORCE_MIN_MS - since : 0
+  }
   const view = (fingerprint: string, reason?: TodayBriefReason): TodayBriefView => {
+    const base = viewOf(fingerprint, reason)
+    if (reason !== 'refresh_throttled' || !base.enabled) return base
+    return { ...base, reason, retryAfterMs: Math.max(1, Math.ceil(forceWait(load()))) }
+  }
+  const viewOf = (fingerprint: string, reason?: TodayBriefReason): TodayBriefView => {
     const sw = resolveSwitch()
     if (!sw.enabled) return { text: '', at: null, basis: '', model: TODAY_BRIEF_MODEL, state: 'off', reason: 'switch_off', enabled: false, source: sw.source }
     const f = load(), cache = todaysCache(f)
@@ -624,11 +695,14 @@ export function createTodayBrief(deps: TodayBriefDeps): TodayBrief {
     }
   }
 
-  const generate = (inputs: TodayBriefInputs, fingerprint: string, pageFingerprint: string, lease: { release(): void } | null): Promise<void> => {
+  const generate = (inputs: TodayBriefInputs, fingerprint: string, pageFingerprint: string, lease: { release(): void } | null, force = false, reconnectSkip = false): Promise<void> => {
     const f = load()
-    // Counted before the call: a call that started was spent.
+    // Counted before the call: a call that started was spent. A forced start counts against the same daily cap.
     f.count += 1
     f.lastStartAt = now()
+    if (force) f.lastForceAt = now()
+    // 7.0.5: only a start that actually skipped the interval spends the reconnect allowance.
+    if (reconnectSkip) f.lastReconnectAt = now()
     save()
     const prompt = buildTodayBriefPrompt(inputs, now())
     const started = now()
@@ -664,26 +738,35 @@ export function createTodayBrief(deps: TodayBriefDeps): TodayBrief {
       .finally(() => { try { lease?.release() } catch { /* released by its owner */ } })
   }
   /** The brief's own gates plus the server's (recording, drain). */
-  const gate = (f: BriefFile): TodayBriefReason | null => {
+  /** 7.0.5: a reconnect may skip the interval once per TODAY_BRIEF_RECONNECT_MIN_MS. */
+  const reconnectAllowed = (f: BriefFile) => !(f.lastReconnectAt && within(now() - f.lastReconnectAt, TODAY_BRIEF_RECONNECT_MIN_MS))
+  /** Whether this start would skip the interval because of a reconnect (the interval would hold it, the allowance is there). */
+  const reconnectSkips = (f: BriefFile, force: boolean, reconnect: boolean) =>
+    reconnect && !force && !!f.lastStartAt && within(now() - f.lastStartAt, minInterval) && reconnectAllowed(f)
+  const gate = (f: BriefFile, force = false, reconnect = false): TodayBriefReason | null => {
     if (!resolveSwitch().enabled) return 'switch_off'
     if (inflight) return null   // an ask waits on the call already running rather than answering stale
     const blocked = deps.blocked?.() ?? null
     if (blocked) return blocked
     if (breakerOpen(f)) return 'paused'
-    if (f.count >= dailyCap) return 'daily_cap'
-    if (f.lastStartAt && within(now() - f.lastStartAt, minInterval)) return 'interval'
+    if (f.count >= dailyCap()) return 'daily_cap'
+    // 7.0.1: the refresh button skips the 10-minute interval, never the cap, the breaker or the switch, and has its own
+    // floor so a held-down button cannot spend the day's cap in a minute.
+    if (force) return forceWait(f) > 0 ? 'refresh_throttled' : null
+    if (f.lastStartAt && within(now() - f.lastStartAt, minInterval) && !reconnectSkips(f, force, reconnect)) return 'interval'
     return null
   }
   const settingsView = (): TodayBriefSettings => {
     const sw = resolveSwitch()
-    if (!sw.enabled) return sw
+    if (!sw.enabled) return { ...sw, dailyCap: dailyCap() }
     const f = load()
     const status: TodayBriefStatus = breakerOpen(f) ? { kind: 'paused', until: new Date(f.openedAt + TODAY_BRIEF_BREAKER_MS).toISOString() }
-      : f.count >= dailyCap ? { kind: 'daily_cap', count: f.count }
+      : f.count >= dailyCap() ? { kind: 'daily_cap', count: f.count, cap: dailyCap() }
         : f.failures > 0 && f.lastFailAt ? { kind: 'failed', at: new Date(f.lastFailAt).toISOString(), code: f.lastFailCode || 'failed' }
           : null
-    return { ...sw, status }
+    return { ...sw, status, dailyCap: dailyCap() }
   }
+  const capView = (): TodayBriefCapView => ({ dailyCap: dailyCap(), min: TODAY_BRIEF_DAILY_CAP_MIN, max: TODAY_BRIEF_DAILY_CAP_MAX, default: TODAY_BRIEF_DAILY_CAP, usedToday: load().count })
   const remember = (f: BriefFile, fingerprint: string, opener: string) => {
     if (f.lastAskFingerprint !== fingerprint || f.lastOpener !== opener) { f.lastAskFingerprint = fingerprint; f.lastOpener = opener; save() }
   }
@@ -693,29 +776,33 @@ export function createTodayBrief(deps: TodayBriefDeps): TodayBrief {
       if (!resolveSwitch().enabled) return view('')
       return view(load().lastAskFingerprint)
     },
-    gate() { return gate(load()) },
+    gate(opts) { return gate(load(), opts?.force === true, opts?.reconnect === true) },
     askGated(pageInputs, reason) {
       if (!resolveSwitch().enabled) return view('')
       const fingerprint = todayBriefFingerprint(pageInputs)
       remember(load(), fingerprint, todayBriefOpener(pageInputs))
       return view(fingerprint, reason)
     },
-    async ask(inputs, pageFingerprint = '') {
+    async ask(inputs, pageFingerprint = '', opts) {
       if (!resolveSwitch().enabled) return view('')
+      const force = opts?.force === true
+      const reconnect = opts?.reconnect === true
       const fingerprint = todayBriefFingerprint(inputs)
       const f = load()
       remember(f, fingerprint, todayBriefOpener(inputs))
       const cache = todaysCache(f)
-      if (cache && cache.fingerprint === fingerprint) return view(fingerprint)
+      // A forced refresh writes again even when nothing changed: the person asked for a fresh summary.
+      if (!force && cache && cache.fingerprint === fingerprint) return view(fingerprint)
       // Concurrent asks share one generation, whichever inputs started it.
       if (inflight) { await inflight; return view(fingerprint, todaysCache(load())?.fingerprint === fingerprint ? undefined : 'interval') }
       if (!hasBriefInputs(inputs)) return view(fingerprint, 'empty_inputs')
-      const closed = gate(f)
+      const closed = gate(f, force, reconnect)
       if (closed) return view(fingerprint, closed)
+      const reconnectSkip = reconnectSkips(f, force, reconnect)
       // The call holds the server's lease; a drain that began after the gate refuses here, before anything is spent.
       let lease: { release(): void } | null = null
       try { lease = deps.lease ? deps.lease() : null } catch { return view(fingerprint, 'maintenance') }
-      const run = generate(inputs, fingerprint, pageFingerprint, lease)
+      const run = generate(inputs, fingerprint, pageFingerprint, lease, force, reconnectSkip)
       inflight = run
       try { await run } finally { if (inflight === run) inflight = null }
       const after = todaysCache(load())
@@ -723,9 +810,13 @@ export function createTodayBrief(deps: TodayBriefDeps): TodayBrief {
     },
     settings: settingsView,
     setEnabled(enabled) {
-      securePrivateDirectory(dirname(deps.settingsFile))
-      durableAtomicWriteFileSync(deps.settingsFile, JSON.stringify({ schema: 1, enabled }) + '\n', { mode: 0o600 })
+      writeSettings({ enabled })
       return settingsView()
     },
+    cap: capView,
+    setDailyCap(value) {
+      writeSettings({ dailyCap: clampTodayBriefDailyCap(value) })
+      return capView()
+    },
   }
 }

package/server/lib/web-memories-bridge.ts

@@ -1,6 +1,6 @@
 import { getOwnerName } from './profile.js'
 import { COS_SCRIPTS_DIR } from './python-bridge.js'
-import { getNeedsYouReader, needsYouCount, type NeedsYouBlock } from './learning-needs-you.js'
+import { getNeedsYouReader, memoryReview, needsYouCount, type NeedsYouBlock } from './learning-needs-you.js'
 
 export const READ_ONLY_MEMORY_WEB_OPS = new Set([
   'status', 'learning.list', 'learning.review', 'learning.event', 'learning.status',
@@ -101,6 +101,8 @@ export async function dispatchMemoriesWebOp(
         // when it cannot be read. Never `learning.to_review`: that is an object of counts, and
         // the page rendered it as "To review (NaN)".
         learningToReview: needsYouCount(needsYou),
+        // Every item that needs review past the shown cap, by the same predicate: the "of N" in Today's "Next 7 of N".
+        learningToReviewTotal: needsYou ? memoryReview.total(needsYou) : null,
         learningTotal: learning.total ?? 0,
         learningRewardEnabled: needsYou ? needsYou.reward_enabled === true : learning.reward_enabled === true,
         ...(needsYou ? { needs_you: needsYou } : {}),