@gotcos/glasses-server 6.78.2 → 6.79.1

package/server/lib/live-cue-verdicts.ts

@@ -0,0 +1,413 @@
+// Live cue verdicts (6.79.0): a durable log of every cue the v2 engine emitted, and Miles's rating of each one, so the bar,
+// spacing and repeat rules can be tuned on rated cues rather than on the trace alone.
+//
+// live-cues-log.jsonl: one row per emitted cue, appended before the cue is held or emitted (so a fast rating never 404s),
+// mode 0600. Unlike the trace it carries transcript text: `before`, the last 400 characters of what was said before the cue,
+// so a cue can be judged against it. `before` is blanked after 7 days and the row dropped after 30. The reader validates
+// every line and skips (and counts) anything else, so a torn line or a hand-seeded row with a typo never breaks history.
+// live-cues-verdicts.json: { v: 1, verdicts: { [cueId]: { verdict?, note?, vote?, at } } }, atomic write, last write wins.
+// An unreadable or corrupt verdicts file fails closed: it is left byte for byte and every write is refused, because a
+// read-modify-write from an empty map would erase the week's ratings.
+//
+// Concurrency: every read-modify-write here is synchronous fs from read to rename, so two requests on the event loop can
+// never interleave inside one. No maintenance lease: a history poll must never hold up an update drain.
+//
+// Standalone on purpose: verdicts and history work with v2 off, and a v2-off server must never build the engine (it
+// constructs the Jev and SubQ clients). The route passes in which meeting the running engine, if any, holds the cue for.
+
+import { appendFileSync, closeSync, constants, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, statSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { dataPath } from './data-dir.js'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { errMsg } from './utils.js'
+import { getMeetingStore } from './meeting-store.js'
+import { findCosOperationsMeetingBySessionId, findDirectLibraryMeetingBySessionId } from './cos-operations-meetings.js'
+import { CUE_FEEDBACK_REASON_MAX, type CueKind, type CueSourceRef, type LiveCuesV2MemorySource } from '../../shared/live-cues-v2.js'
+import type { WouldWithhold } from './live-cues-filter.js'
+
+// ── Wire types (server-local: shared/live-cues-v2.ts is hash-pinned with the companion copy) ──
+export const LIVE_CUE_VERDICTS_PROTOCOL = 1 as const
+/** `before`: the last characters (code points) said before the cue, whitespace-collapsed. */
+export const CUE_BEFORE_MAX = 400
+export const CUE_VERDICTS = ['useful', 'late', 'repeat', 'wrong', 'obvious'] as const
+export type CueVerdict = typeof CUE_VERDICTS[number]
+export type CueVote = 'up' | 'down'
+export type CueTitleSource = 'saved' | 'library' | 'capture'
+
+/** One line of live-cues-log.jsonl. `armedAt`, `prompt`, `memorySource` and `kept` are absent on rows seeded by hand. */
+export interface LiveCueLogRow {
+  v: 1
+  cueId: string
+  sessionId: string
+  /** The arm-time title as-is ("G2 Recording 2026-10-19 0741"); history resolves the saved title. */
+  meetingTitle: string
+  createdAt: number
+  armedAt?: number
+  kind: CueKind
+  headline: string
+  detail: string
+  gate: number
+  sources: CueSourceRef[]
+  model: string
+  /** Writer rules version (v2, v3; v4 and later read the same way, so rows from a newer writer are never skipped). */
+  prompt?: string
+  memorySource?: LiveCuesV2MemorySource
+  /** Notes the judge kept for the writer. */
+  kept?: number
+  /** Shadow owner/date template rules (never enforced): would this cue be withheld per meeting, or per topic. */
+  wouldWithhold?: WouldWithhold
+  before: string
+}
+/** A history row's rating. `verdict` null with a `vote` is a lens vote alone: unrated. */
+export interface CueRating { verdict: CueVerdict | null; note?: string; vote?: CueVote; at: number }
+export interface LiveCueHistoryRow extends LiveCueLogRow { title: string; titleSource: CueTitleSource; rating: CueRating | null }
+export interface LiveCuesHistoryResponse {
+  v: 1
+  cues: LiveCueHistoryRow[]
+  /** After the sessionId filter, before `unrated` and `limit`. */
+  counts: { total: number; rated: number; unrated: number; byVerdict: Record<CueVerdict, number> }
+  /** The newest `limit` rows were kept and older ones cut. */
+  truncated: boolean
+  /** Log lines that were not a valid cue row (torn, foreign, bad seed). */
+  skipped: number
+}
+export interface LiveCuesVerdictResponse { ok: true; cueId: string; verdict: CueVerdict | null; vote: CueVote | null }
+
+const DAY_MS = 24 * 60 * 60_000
+export const LIVE_CUE_VERDICT_LIMITS = {
+  retentionMs: 30 * DAY_MS,
+  /** `before` (transcript text) is blanked on rows older than this; the rest of the row stays for the retention window. */
+  beforeRetentionMs: 7 * DAY_MS,
+  pruneEveryMs: DAY_MS,
+  titleCacheMs: 60_000,
+  maxDays: 30,
+  defaultDays: 7,
+  defaultLimit: 200,
+  maxLimit: 1000,
+  maxSessionIds: 5,
+} as const
+
+/** The `before` excerpt: whitespace-collapsed, the last CUE_BEFORE_MAX code points (never half a surrogate pair). */
+export function cueBefore(said: string): string {
+  return Array.from(said.replace(/\s+/g, ' ').trim()).slice(-CUE_BEFORE_MAX).join('')
+}
+/** A note as stored: whitespace-collapsed, truncated at CUE_FEEDBACK_REASON_MAX like the lens reason. */
+export function cleanNote(note: string | undefined): string {
+  return (note ?? '').replace(/\s+/g, ' ').trim().slice(0, CUE_FEEDBACK_REASON_MAX)
+}
+export function isCueVerdict(value: unknown): value is CueVerdict {
+  return typeof value === 'string' && (CUE_VERDICTS as readonly string[]).includes(value)
+}
+
+const str = (v: unknown): v is string => typeof v === 'string'
+const num = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v)
+const optional = (v: unknown, ok: (x: unknown) => boolean) => v === undefined || ok(v)
+function isWouldWithhold(v: unknown): boolean {
+  const w = v as Partial<WouldWithhold> | null
+  return !!w && typeof w === 'object' && typeof w.perMeeting === 'boolean' && typeof w.perTopic === 'boolean' && optional(w.blockerCueId, str)
+}
+/** The full row schema. Hand-seeded rows must pass it too (`before: ""` and no optional fields are fine). */
+export function isLogRow(value: unknown): value is LiveCueLogRow {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
+  const r = value as Record<string, unknown>
+  return r.v === 1 && str(r.cueId) && r.cueId.length > 0 && str(r.sessionId) && r.sessionId.length > 0 && str(r.meetingTitle)
+    && num(r.createdAt) && (r.kind === 'reinforce' || r.kind === 'challenge')
+    && str(r.headline) && str(r.detail) && num(r.gate) && str(r.model) && str(r.before)
+    && Array.isArray(r.sources) && r.sources.every(s => !!s && typeof s === 'object' && str((s as CueSourceRef).id) && str((s as CueSourceRef).date) && str((s as CueSourceRef).title))
+    && optional(r.armedAt, num) && optional(r.prompt, p => typeof p === 'string' && /^v\d{1,2}$/.test(p))
+    && optional(r.memorySource, m => m === 'cue_memory' || m === 'notes' || m === 'none') && optional(r.kept, num)
+    && optional(r.wouldWithhold, isWouldWithhold)
+}
+
+export class LiveCueLog {
+  /** Parsed rows keyed by the file's identity, so a 15 s poll does not reparse megabytes on the event loop. */
+  private cache: { key: string; rows: LiveCueLogRow[]; skipped: number } | null = null
+  constructor(private readonly file: string) {}
+
+  /** Throws on failure: the engine records it on the evaluation's trace row. */
+  append(row: LiveCueLogRow): void {
+    mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 })
+    // A torn last line (a crash or failure mid-append) must not glue onto this row: start on a fresh line.
+    const lead = this.endsMidLine() ? '\n' : ''
+    appendFileSync(this.file, lead + JSON.stringify(row) + '\n', { mode: 0o600 })
+  }
+
+  /** Also the regular-file gate for append: a FIFO planted at this path would block the event loop forever on a
+   *  blocking open, so it is opened non-blocking and refused before appendFileSync ever opens it. */
+  private endsMidLine(): boolean {
+    const nonBlock = constants.O_NONBLOCK ?? 0, noFollow = constants.O_NOFOLLOW ?? 0
+    let fd: number
+    try { fd = openSync(this.file, constants.O_RDONLY | nonBlock | noFollow) } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return false
+      throw error
+    }
+    try {
+      const st = fstatSync(fd)
+      if (!st.isFile()) throw new Error('the cue log is not a regular file')
+      const size = st.size
+      if (size === 0) return false
+      const last = Buffer.alloc(1)
+      readSync(fd, last, 0, 1, size - 1)
+      return last[0] !== 0x0a
+    } finally { closeSync(fd) }
+  }
+
+  /** Every valid row in file order, and how many non-blank lines were skipped. Never throws. */
+  read(): { rows: LiveCueLogRow[]; skipped: number } {
+    let key = ''
+    try {
+      const st = statSync(this.file)
+      if (!st.isFile()) return { rows: [], skipped: 0 }        // never readFileSync a FIFO: it blocks the event loop
+      key = `${st.ino}:${st.size}:${st.mtimeMs}`
+    } catch { return { rows: [], skipped: 0 } }
+    if (this.cache?.key === key) return { rows: this.cache.rows, skipped: this.cache.skipped }
+    let text = ''
+    try { text = readFileSync(this.file, 'utf8') } catch { return { rows: [], skipped: 0 } }
+    const rows: LiveCueLogRow[] = []
+    let skipped = 0
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue
+      let value: unknown
+      try { value = JSON.parse(line) } catch { skipped += 1; continue }
+      if (isLogRow(value)) rows.push(value); else skipped += 1
+    }
+    this.cache = { key, rows, skipped }
+    return { rows, skipped }
+  }
+
+  /** The first logged row for this cue, under any meeting. */
+  find(cueId: string): LiveCueLogRow | null {
+    return this.read().rows.find(r => r.cueId === cueId) ?? null
+  }
+
+  /** Drops rows past retention and blanks `before` on rows past 7 days. Rewrites only when something changed; synchronous
+   *  read, filter and rename, so an append (also synchronous, same process) cannot land mid-rewrite. Null when there is
+   *  no log, otherwise the cueIds kept. */
+  prune(nowMs: number): { dropped: number; blanked: number; kept: Set<string> } | null {
+    if (!existsSync(this.file)) return null
+    const { rows } = this.read()
+    const cutoff = nowMs - LIVE_CUE_VERDICT_LIMITS.retentionMs
+    const textCutoff = nowMs - LIVE_CUE_VERDICT_LIMITS.beforeRetentionMs
+    let blanked = 0
+    const keep = rows.filter(r => r.createdAt >= cutoff).map(r => {
+      if (r.createdAt >= textCutoff || r.before === '') return r
+      blanked += 1
+      return { ...r, before: '' }
+    })
+    const dropped = rows.length - keep.length
+    if (dropped || blanked) durableAtomicWriteFileSync(this.file, keep.map(r => JSON.stringify(r) + '\n').join(''), { mode: 0o600 })
+    return { dropped, blanked, kept: new Set(keep.map(r => r.cueId)) }
+  }
+}
+
+export class VerdictsUnreadableError extends Error {
+  readonly code = 'verdicts_unreadable'
+  constructor(message: string) { super(message); this.name = 'VerdictsUnreadableError' }
+}
+
+interface StoredVerdict { verdict?: CueVerdict; note?: string; vote?: CueVote; at: number }
+interface VerdictFile { v: 1; verdicts: Record<string, StoredVerdict> }
+
+export class LiveCueVerdictStore {
+  constructor(private readonly file: string) {}
+
+  /** Missing is empty. Unreadable or not the expected shape throws, and the file is left exactly as it is. */
+  read(): Record<string, StoredVerdict> {
+    if (!existsSync(this.file)) return {}
+    let parsed: unknown
+    try {
+      // Never readFileSync a FIFO or a device: it blocks the event loop.
+      if (!statSync(this.file).isFile()) throw new Error('not a regular file')
+      parsed = JSON.parse(readFileSync(this.file, 'utf8'))
+    } catch (error) {
+      console.error(`[live-cue-verdicts] ${this.file} is unreadable; ratings are refused until it is fixed or moved: ${errMsg(error)}`)
+      throw new VerdictsUnreadableError(errMsg(error))
+    }
+    const verdicts = (parsed as Partial<VerdictFile> | null)?.verdicts
+    if (!verdicts || typeof verdicts !== 'object' || Array.isArray(verdicts)) {
+      console.error(`[live-cue-verdicts] ${this.file} is not a verdicts file; ratings are refused until it is fixed or moved`)
+      throw new VerdictsUnreadableError('not a verdicts file')
+    }
+    const out: Record<string, StoredVerdict> = {}
+    for (const [cueId, r] of Object.entries(verdicts)) {
+      if (!r || typeof r !== 'object' || typeof r.at !== 'number') continue
+      const rec: StoredVerdict = { at: r.at }
+      if (isCueVerdict(r.verdict)) rec.verdict = r.verdict
+      if (rec.verdict && typeof r.note === 'string' && r.note) rec.note = r.note
+      if (r.vote === 'up' || r.vote === 'down') rec.vote = r.vote
+      if (rec.verdict || rec.vote) out[cueId] = rec
+    }
+    return out
+  }
+
+  write(verdicts: Record<string, StoredVerdict>): void {
+    mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 })
+    durableAtomicWriteFileSync(this.file, JSON.stringify({ v: 1, verdicts } satisfies VerdictFile) + '\n', { mode: 0o600 })
+  }
+
+  /** Drops records whose cue left the log. */
+  prune(kept: Set<string>): number {
+    const all = this.read()
+    const gone = Object.keys(all).filter(id => !kept.has(id))
+    if (!gone.length) return 0
+    for (const id of gone) delete all[id]
+    this.write(all)
+    return gone.length
+  }
+}
+
+function ratingOf(rec: StoredVerdict | undefined): CueRating | null {
+  if (!rec) return null
+  return { verdict: rec.verdict ?? null, ...(rec.note ? { note: rec.note } : {}), ...(rec.vote ? { vote: rec.vote } : {}), at: rec.at }
+}
+
+/** The saved meeting's title for a capture: this server's own save first, then the COS meeting library (including a
+ *  merged scribe that declares the capture). Best effort; null when neither knows it. */
+export function resolveSavedTitle(sessionId: string): { title: string; source: 'saved' | 'library' } | null {
+  try { const m = getMeetingStore().findBySessionId(sessionId); if (m?.title) return { title: m.title, source: 'saved' } } catch { /* next */ }
+  try { const m = findCosOperationsMeetingBySessionId(sessionId); if (m?.title) return { title: m.title, source: 'library' } } catch { /* next */ }
+  try { const m = findDirectLibraryMeetingBySessionId(sessionId); if (m?.title) return { title: m.title, source: 'library' } } catch { /* none */ }
+  return null
+}
+
+export interface LiveCueVerdictsDeps {
+  log: LiveCueLog
+  store: LiveCueVerdictStore
+  now(): number
+  trace(row: Record<string, unknown>): void
+  resolveTitle(sessionId: string): { title: string; source: 'saved' | 'library' } | null
+}
+
+export type VerdictResult = { ok: true; response: LiveCuesVerdictResponse } | { ok: false; error: 'unknown_cue' | 'cue_session_mismatch' }
+
+export class LiveCueVerdicts {
+  private lastPruneAt = 0
+  private readonly titles = new Map<string, { at: number; value: { title: string; source: 'saved' | 'library' } | null }>()
+  constructor(readonly deps: LiveCueVerdictsDeps) {}
+
+  /** From the engine, before the cue is held or emitted. Throws on failure (the engine traces it and carries on). */
+  logCue(row: LiveCueLogRow): void {
+    this.deps.log.append(row)
+    this.maybePrune()
+  }
+
+  /** The meeting this cue belongs to: the running engine's (`liveOwner`), else the log's. Null when unknown. */
+  private owner(cueId: string, liveOwner: string | null): string | null {
+    return liveOwner ?? this.deps.log.find(cueId)?.sessionId ?? null
+  }
+
+  /** Throws VerdictsUnreadableError when the verdicts file cannot be read; nothing is written then. */
+  rate(input: { sessionId: string; cueId: string; verdict: CueVerdict | 'clear'; note?: string }, liveOwner: string | null): VerdictResult {
+    this.maybePrune()
+    const owner = this.owner(input.cueId, liveOwner)
+    if (!owner) return { ok: false, error: 'unknown_cue' }
+    if (owner !== input.sessionId) return { ok: false, error: 'cue_session_mismatch' }
+    const all = this.deps.store.read()
+    const prev = all[input.cueId]
+    const at = this.deps.now()
+    const note = cleanNote(input.note)
+    // clear drops the verdict and its note and keeps the lens vote; the record goes only when nothing is left.
+    const next: StoredVerdict = { at, ...(prev?.vote ? { vote: prev.vote } : {}) }
+    if (input.verdict !== 'clear') { next.verdict = input.verdict; if (note) next.note = note }
+    if (next.verdict || next.vote) all[input.cueId] = next; else delete all[input.cueId]
+    this.deps.store.write(all)
+    // The trace never carries the note or any transcript text.
+    this.trace({ kind: 'feedback', at: new Date(at).toISOString(), sessionId: input.sessionId, cueId: input.cueId, verdict: input.verdict, knownCue: true, ...(note && input.verdict !== 'clear' ? { noted: true } : {}) })
+    return { ok: true, response: { ok: true, cueId: input.cueId, verdict: next.verdict ?? null, vote: next.vote ?? null } }
+  }
+
+  /** The lens vote, beside any verdict and never over it, for a cue known under this meeting. Throws
+   *  VerdictsUnreadableError like rate(); the vote route's own answer is unchanged either way. */
+  vote(sessionId: string, cueId: string, vote: CueVote, liveOwner: string | null): void {
+    if (this.owner(cueId, liveOwner) !== sessionId) return
+    const all = this.deps.store.read()
+    all[cueId] = { ...all[cueId], vote, at: this.deps.now() }
+    this.deps.store.write(all)
+  }
+
+  /** Oldest first. With more rows than `limit`, the NEWEST `limit` are kept (truncated: true). Throws
+   *  VerdictsUnreadableError rather than report every cue as unrated. */
+  history(q: { days: number; sessionIds?: string[]; unrated: boolean; limit: number }): LiveCuesHistoryResponse {
+    this.maybePrune()
+    const cutoff = this.deps.now() - q.days * DAY_MS
+    const verdicts = this.deps.store.read()
+    const { rows: logged, skipped } = this.deps.log.read()
+    const sessions = q.sessionIds?.length ? new Set(q.sessionIds) : null
+    const seen = new Set<string>()
+    const rows = logged
+      .filter(r => r.createdAt >= cutoff && (!sessions || sessions.has(r.sessionId)))
+      .filter(r => { if (seen.has(r.cueId)) return false; seen.add(r.cueId); return true })
+      .sort((a, b) => a.createdAt - b.createdAt)
+    const byVerdict = Object.fromEntries(CUE_VERDICTS.map(v => [v, 0])) as Record<CueVerdict, number>
+    let rated = 0
+    for (const r of rows) { const v = verdicts[r.cueId]?.verdict; if (v) { byVerdict[v] += 1; rated += 1 } }
+    const wanted = rows.filter(r => !q.unrated || !verdicts[r.cueId]?.verdict)
+    const page = wanted.slice(-q.limit)
+    return {
+      v: 1,
+      cues: page.map((r): LiveCueHistoryRow => {
+        const saved = this.title(r.sessionId)
+        return { ...r, title: saved?.title ?? r.meetingTitle, titleSource: saved?.source ?? 'capture', rating: ratingOf(verdicts[r.cueId]) }
+      }),
+      counts: { total: rows.length, rated, unrated: rows.length - rated, byVerdict },
+      truncated: wanted.length > q.limit,
+      skipped,
+    }
+  }
+
+  /** Every logged cue for one meeting, whatever its age (for the per-meeting count once the engine's counter expired). */
+  loggedCues(sessionId: string): number {
+    return new Set(this.deps.log.read().rows.filter(r => r.sessionId === sessionId).map(r => r.cueId)).size
+  }
+
+  private title(sessionId: string): { title: string; source: 'saved' | 'library' } | null {
+    const nowMs = this.deps.now()
+    const hit = this.titles.get(sessionId)
+    if (hit && nowMs - hit.at < LIVE_CUE_VERDICT_LIMITS.titleCacheMs) return hit.value
+    let value: { title: string; source: 'saved' | 'library' } | null = null
+    try { value = this.deps.resolveTitle(sessionId) } catch { value = null }
+    this.titles.set(sessionId, { at: nowMs, value })
+    return value
+  }
+
+  /** Rows past retention, `before` past 7 days, and the verdicts of cues that left the log. Never throws. */
+  prune(): void {
+    this.lastPruneAt = this.deps.now()
+    try {
+      const log = this.deps.log.prune(this.deps.now())
+      // No log at all is not "every cue left": leave the verdicts alone.
+      const gone = log ? this.deps.store.prune(log.kept) : 0
+      if (log?.dropped || log?.blanked || gone) {
+        console.log(`[live-cue-verdicts] pruned ${log?.dropped ?? 0} cue(s) past 30 days, blanked ${log?.blanked ?? 0} excerpt(s) past 7 days, dropped ${gone} verdict(s)`)
+      }
+    } catch (error) {
+      console.warn(`[live-cue-verdicts] prune failed: ${errMsg(error)}`)
+    }
+  }
+
+  /** First use in this process (there is no boot hook and nothing runs at import), then at most once a day. */
+  maybePrune(): void {
+    if (this.deps.now() - this.lastPruneAt < LIVE_CUE_VERDICT_LIMITS.pruneEveryMs) return
+    this.prune()
+  }
+
+  private trace(row: Record<string, unknown>): void {
+    try { this.deps.trace(row) } catch { /* trace is best effort */ }
+  }
+}
+
+let singleton: LiveCueVerdicts | null = null
+export function liveCueVerdicts(): LiveCueVerdicts {
+  if (!singleton) {
+    const traceFile = dataPath('live-cues-trace.jsonl')
+    singleton = new LiveCueVerdicts({
+      log: new LiveCueLog(dataPath('live-cues-log.jsonl')),
+      store: new LiveCueVerdictStore(dataPath('live-cues-verdicts.json')),
+      now: () => Date.now(),
+      // The same trace file and feedback row shape as the engine's lens votes (live-cues-v2.ts realDeps).
+      trace(row) { mkdirSync(dirname(traceFile), { recursive: true, mode: 0o700 }); appendFileSync(traceFile, JSON.stringify(row) + '\n', { mode: 0o600 }) },
+      resolveTitle: resolveSavedTitle,
+    })
+  }
+  return singleton
+}

package/server/lib/live-cues-filter.ts

@@ -0,0 +1,72 @@
+// Live cues v2 post-writer filter (6.79.0): zero model calls. A TypeScript port of the offline reference
+// (cue_verdicts_mvp/v4_replay/filter_cues.py, RESULTS_filter.md); it must agree with it on every vector.
+//
+// tokens(cue): lowercase, scan [a-z0-9]+(?:[.,][0-9]+)*, drop commas inside a match ("3,000" -> "3000"), keep a token
+// with a digit and length >= 2, or an all-letter token of length >= 3 that is not a stopword. The SET of those.
+// overlap(A, B) = |A ∩ B| / min(|A|, |B|), 0 when either is empty.
+// isTemplate(cue): TEMPLATE_RE anywhere in the raw text (an owner or date ask).
+//
+// The repeat rule (enforced only when COS_LIVE_CUES_V2_REPEAT_OVERLAP is set) withholds a cue whose overlap with an
+// earlier SHOWN cue is >= the threshold. The template rules are shadow only: logged as `wouldWithhold`, never enforced.
+
+/** The last two lines are cue scaffolding, so two different owner/date asks do not look like repeats. */
+export const CUE_FILTER_STOPWORDS: ReadonlySet<string> = new Set(`
+all and any are ask but can did don for get got had has her him his how its let may new not now off one our out own per put say see set she the too two use was way who why yet you
+about above after again against also already another anyone around back because been before being below between both cannot
+could didn does doesn doing done down during each else even ever every everyone from further going gonna have haven having
+here into itself just know like made make many more most much must need needs next only onto other ours over really said says
+same should since some someone something still such than that their theirs them then there these they thing things think this
+those through under until upon very wasn well were what when where whether which while will with within without would wouldn
+yeah your yours okay
+settle decide decides decided name named names room nobody none owner owners owns ownership date dates deadline stated
+moving moves ends call meeting asks check
+`.split(/\s+/).filter(Boolean))
+
+const TOKEN_RE = /[a-z0-9]+(?:[.,][0-9]+)*/g
+export const CUE_TEMPLATE_RE = /\b(owner|owners|owns|ownership|deadline|due date|by when|by what date|a date|no date|set a date|settle a date|who (owns|will|should|builds|takes|drives|runs|tracks|chases|approves|signs off|finalizes|tests|gathers|asks|computes|is computing|does))\b/i
+/** The shadow per-topic rule's threshold (RESULTS_filter.md: 0.25 against earlier shown template cues). */
+export const CUE_TOPIC_OVERLAP = 0.25
+
+export function cueTokens(cue: string): Set<string> {
+  const out = new Set<string>()
+  for (const m of (cue || '').toLowerCase().match(TOKEN_RE) ?? []) {
+    const t = m.replace(/,/g, '')
+    if (/[0-9]/.test(t)) { if (t.length >= 2) out.add(t) }
+    else if (t.length >= 3 && !CUE_FILTER_STOPWORDS.has(t)) out.add(t)
+  }
+  return out
+}
+
+export function cueOverlap(a: Set<string>, b: Set<string>): number {
+  if (!a.size || !b.size) return 0
+  let shared = 0
+  for (const t of a) if (b.has(t)) shared += 1
+  return shared / Math.min(a.size, b.size)
+}
+
+export function isTemplateCue(cue: string): boolean { return CUE_TEMPLATE_RE.test(cue || '') }
+
+export interface ShownCue { cueId: string; detail: string }
+
+/** Rule R: the first earlier shown cue this one repeats at >= threshold, or null. */
+export function repeatOf(detail: string, shown: readonly ShownCue[], threshold: number): { blocker: string; overlap: number } | null {
+  const mine = cueTokens(detail)
+  for (const s of shown) {
+    const o = cueOverlap(mine, cueTokens(s.detail))
+    if (o >= threshold) return { blocker: s.cueId, overlap: Math.round(o * 1000) / 1000 }
+  }
+  return null
+}
+
+export interface WouldWithhold { perMeeting: boolean; perTopic: boolean; blockerCueId?: string }
+
+/** Rule T in shadow, both forms: per meeting (any earlier shown template cue) and per topic (one with overlap >= 0.25).
+ *  The blocker is the per-topic one when that form fires, else the per-meeting one. */
+export function wouldWithhold(detail: string, shown: readonly ShownCue[]): WouldWithhold {
+  if (!isTemplateCue(detail)) return { perMeeting: false, perTopic: false }
+  const mine = cueTokens(detail)
+  const templates = shown.filter(s => isTemplateCue(s.detail))
+  const topic = templates.find(s => cueOverlap(mine, cueTokens(s.detail)) >= CUE_TOPIC_OVERLAP)
+  const blocker = topic ?? templates[0]
+  return { perMeeting: templates.length > 0, perTopic: !!topic, ...(blocker ? { blockerCueId: blocker.cueId } : {}) }
+}

package/server/lib/live-cues-v2.ts

@@ -36,6 +36,9 @@ import { COS_SCRIPTS_DIR, PYTHON_BIN, contextSourceAvailable } from './python-br
 import { dataPath } from './data-dir.js'
 import { durableAtomicWriteFileSync } from './atomic-fs.js'
 import { terminateProviderProcess } from './provider-process-lifecycle.js'
+import { cueBefore, liveCueVerdicts, type LiveCueLogRow } from './live-cue-verdicts.js'
+import { repeatOf, wouldWithhold } from './live-cues-filter.js'
+import { errMsg } from './utils.js'
 import { CUE_GATE_QUESTIONS, CUE_JUDGE_INSTRUCTIONS, CUE_JUDGE_NONE, CUE_WRITER_SYSTEM_V2, CUE_WRITER_SYSTEM_V3 } from './live-cues-v2-prompts.js'
 import {
   CUE_DETAIL_MAX, CUE_FEEDBACK_REASON_MAX, CUE_HEADLINE_MAX, LIVE_CUES_V2_PROTOCOL, isLiveCueV2,
@@ -88,6 +91,39 @@ export function liveCuesV2Gate(env: NodeJS.ProcessEnv = process.env): number {
   const raw = Number(env.COS_LIVE_CUES_V2_GATE)
   return Number.isFinite(raw) && raw >= 0.3 && raw <= 0.99 ? raw : LIVE_CUES_V2_LIMITS.defaultGate
 }
+/** 6.79.0 tuning knobs for Friday's rated-cue review. Unset (or empty, which a managed env may pass for an unset optional
+ *  variable) is the calibrated default with no log. Anything else outside the accepted form falls back to the default with
+ *  one log line per distinct value per process: the knobs are read on every transcript feed. */
+const knobWarned = new Set<string>()
+function knobFallback<T>(name: string, raw: string, fallback: T, accepted: string): T {
+  if (!knobWarned.has(`${name}=${raw}`)) {
+    knobWarned.add(`${name}=${raw}`)
+    console.warn(`[live-cues-v2] ${name}=${JSON.stringify(raw)} is not ${accepted}; using the default`)
+  }
+  return fallback
+}
+export function liveCuesV2CooldownMs(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = env.COS_LIVE_CUES_V2_COOLDOWN_S
+  if (raw === undefined || raw.trim() === '') return LIVE_CUES_V2_LIMITS.cooldownAfterCueMs
+  const seconds = /^\d{1,3}$/.test(raw.trim()) ? Number(raw.trim()) : Number.NaN     // whole seconds only
+  return seconds >= 20 && seconds <= 900 ? seconds * 1000
+    : knobFallback('COS_LIVE_CUES_V2_COOLDOWN_S', raw, LIVE_CUES_V2_LIMITS.cooldownAfterCueMs, 'whole seconds from 20 to 900')
+}
+export function liveCuesV2JudgeKeep(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = env.COS_LIVE_CUES_V2_JUDGE_KEEP
+  if (raw === undefined || raw.trim() === '') return LIVE_CUES_V2_LIMITS.judgeKeep
+  const keep = Number(raw)
+  return keep >= 0.5 && keep <= 0.95 ? keep : knobFallback('COS_LIVE_CUES_V2_JUDGE_KEEP', raw, LIVE_CUES_V2_LIMITS.judgeKeep, 'a number from 0.5 to 0.95')
+}
+/** COS_LIVE_CUES_V2_REPEAT_OVERLAP: the repeat rule's threshold, 0.3 to 0.9, or null (off, today's behaviour) when unset
+ *  or empty. Any other value leaves the rule off, with one log line per value. RESULTS_filter.md: 0.5 withheld no useful
+ *  cue on any receipt; 0.4 withheld three. */
+export function liveCuesV2RepeatOverlap(env: NodeJS.ProcessEnv = process.env): number | null {
+  const raw = env.COS_LIVE_CUES_V2_REPEAT_OVERLAP
+  if (raw === undefined || raw.trim() === '') return null
+  const t = Number(raw)
+  return t >= 0.3 && t <= 0.9 ? t : knobFallback<number | null>('COS_LIVE_CUES_V2_REPEAT_OVERLAP', raw, null, 'a number from 0.3 to 0.9 (the repeat rule stays off)')
+}
 export function liveCuesV2Model(env: NodeJS.ProcessEnv = process.env): string {
   const raw = (env.COS_LIVE_CUES_V2_MODEL ?? '').trim().toLowerCase()
   if (raw === 'haiku') return 'claude-haiku-5-5'
@@ -273,6 +309,11 @@ export class LiveCuesV2Store {
     const m = this.read().meetings[sessionId]
     return { cues: m?.cues ?? 0, writerCalls: m?.writerCalls ?? 0 }
   }
+  /** The durable per-meeting counters, or null once they expired (24 h) or never existed. */
+  meetingCounters(sessionId: string): { cues: number; writerCalls: number } | null {
+    const m = this.read().meetings[sessionId]
+    return m ? { cues: m.cues, writerCalls: m.writerCalls } : null
+  }
   weeklyUsed(): number { return this.read().writerCalls }
   end(sessionId: string): void { const s = this.read(); s.ended[sessionId] = this.now().getTime(); delete s.paused[sessionId]; this.write(s) }
   isEnded(sessionId: string): boolean { return sessionId in this.read().ended }
@@ -322,6 +363,9 @@ export interface LiveCuesV2Deps {
   now(): Date
   store: LiveCuesV2Store
   trace(row: Record<string, unknown>): void
+  /** 6.79.0: the durable cue log (live-cues-log.jsonl) that verdicts are recorded against. May throw; never the trace,
+   *  which must stay free of transcript text. */
+  cueLog?(row: LiveCueLogRow): void
   env: NodeJS.ProcessEnv
 }
 
@@ -408,6 +452,7 @@ function realDeps(): LiveCuesV2Deps {
     trace(row) {
       try { mkdirSync(dirname(traceFile), { recursive: true, mode: 0o700 }); appendFileSync(traceFile, JSON.stringify(row) + '\n', { mode: 0o600 }) } catch { /* trace is best effort */ }
     },
+    cueLog: row => liveCueVerdicts().logCue(row),
     env: process.env,
   }
 }
@@ -582,6 +627,12 @@ export class LiveCuesV2Engine {
     return s.stopReason
   }
 
+  /** The cue, if this process emitted it and still holds it, under whichever meeting. */
+  findCue(cueId: string): LiveCueV2 | null {
+    for (const s of this.sessions.values()) { const cue = s.cues.find(c => c.cueId === cueId); if (cue) return cue }
+    return null
+  }
+
   recordFeedback(input: { sessionId: string; cueId: string; vote: 'up' | 'down'; reason?: string }): { ok: true; knownCue: boolean } {
     const knownCue = !!this.sessions.get(input.sessionId)?.cues.some(c => c.cueId === input.cueId)
     const reason = (input.reason ?? '').replace(/\s+/g, ' ').trim().slice(0, CUE_FEEDBACK_REASON_MAX)
@@ -614,7 +665,7 @@ export class LiveCuesV2Engine {
     if (s.breaker) return this.traceSkip(s, 'breaker_open', nowMs)
     if (this.deps.store.isPaused(sessionId)) return this.traceSkip(s, 'paused', nowMs)
     if (s.wordsSinceEval < L.minNewWords) return
-    if (nowMs - s.lastEvalAt < L.minIntervalMs || nowMs - s.lastCueAt < L.cooldownAfterCueMs) return
+    if (nowMs - s.lastEvalAt < L.minIntervalMs || nowMs - s.lastCueAt < liveCuesV2CooldownMs(this.deps.env)) return
     const counters = this.deps.store.counters(sessionId)
     if (counters.cues >= L.maxCuesPerMeeting || counters.writerCalls >= L.maxWriterCallsPerMeeting) return this.traceSkip(s, 'meeting_cap', nowMs)
     if (this.deps.store.weeklyUsed() >= liveCuesV2WeeklyCap(this.deps.env)) return this.traceSkip(s, 'budget_exhausted', nowMs)  // before the gate
@@ -637,6 +688,8 @@ export class LiveCuesV2Engine {
     s.lastEvalAt = started
     s.wordsSinceEval = 0
     const window = cleanWindow(s.chunks.join('\n')).slice(-L.windowChars)
+    // 6.79.0: what was said up to this evaluation, speaker labels kept, for the cue log's `before` (never a model input).
+    const said = s.chunks.join('\n').replace(/^\[\d+\]\s*/gm, '')
     const trace: Record<string, unknown> = { kind: 'evaluation', at: new Date(started).toISOString(), sessionId: s.sessionId, n: s.evaluations }
     let lease: MaintenanceWorkLease | null = null
     let wallHit = false
@@ -673,7 +726,7 @@ export class LiveCuesV2Engine {
         const t2 = Date.now()
         const judged = await this.deps.judge(s.title, window, mem.notes, abort.signal, provider)
         Object.assign(trace, { judgeMs: Date.now() - t2, judgeTokens: judged.tokens })
-        kept = mem.notes.filter(m => (judged.probs[m.id] ?? 0) >= L.judgeKeep).slice(0, L.judgeMaxNotes).map((m, i) => ({ ...m, id: `M${i + 1}` }))
+        kept = mem.notes.filter(m => (judged.probs[m.id] ?? 0) >= liveCuesV2JudgeKeep(this.deps.env)).slice(0, L.judgeMaxNotes).map((m, i) => ({ ...m, id: `M${i + 1}` }))
       }
       trace.kept = kept.length
       if (abort.signal.aborted) { trace.outcome = 'cancelled'; return }
@@ -702,6 +755,21 @@ export class LiveCuesV2Engine {
       const cue: LiveCueV2 = { protocol: 2, cueId: randomUUID(), sessionId: s.sessionId, headline: cueHeadline(parsed.detail), detail: parsed.detail,
         kind: parsed.kind, sources, gate: round(pCue), createdAt: this.deps.now().getTime(), model: out.model ?? model }
       if (!isLiveCueV2(cue)) { trace.outcome = 'withheld_invalid'; return }       // never emit what the companion would drop
+      // 6.79.0 repeat rule, off unless COS_LIVE_CUES_V2_REPEAT_OVERLAP is set: a cue that repeats an earlier SHOWN cue of
+      // this meeting is not logged, emitted or counted (the writer call already counted). Ids and the overlap only.
+      const repeatT = liveCuesV2RepeatOverlap(this.deps.env)
+      const repeat = repeatT === null ? null : repeatOf(cue.detail, s.cues, repeatT)
+      if (repeat) { Object.assign(trace, { outcome: 'withheld_repeat', repeatOf: repeat.blocker, repeatOverlap: repeat.overlap }); return }
+      // 6.79.0: logged before it is held or emitted, so a rating that arrives at once finds it. Its own try/catch: a log
+      // failure is traced on this evaluation and is never a writer failure or a step toward the breaker.
+      try {
+        this.deps.cueLog?.({ v: 1, cueId: cue.cueId, sessionId: s.sessionId, meetingTitle: s.title, createdAt: cue.createdAt, armedAt: s.armedAt, kind: cue.kind,
+          headline: cue.headline, detail: cue.detail, gate: cue.gate, sources: cue.sources, model: cue.model, prompt: version,
+          memorySource: mem.notes.length ? source : 'none', kept: kept.length, wouldWithhold: wouldWithhold(cue.detail, s.cues), before: cueBefore(said) })
+      } catch (error) {
+        trace.cueLogError = (error as NodeJS.ErrnoException)?.code ?? 'append_failed'
+        console.warn(`[live-cues-v2] cue log append failed: ${errMsg(error)}`)
+      }
       s.cues.push(cue)
       s.lastCueAt = cue.createdAt
       this.deps.store.recordCue(s.sessionId)
@@ -798,4 +866,8 @@ export function setLiveCuesV2Enabled(enabled: boolean, env: NodeJS.ProcessEnv =
 export function liveCuesV2Advertised(env: NodeJS.ProcessEnv = process.env): LiveCuesV2Capability | undefined {
   return liveCuesV2Enabled(env) ? liveCuesV2Capability() : undefined
 }
+/** 6.79.0: a meeting's durable cue and writer-call counters for the history route, read without building the engine. */
+export function liveCuesV2MeetingCounters(sessionId: string): { cues: number; writerCalls: number } | null {
+  return new LiveCuesV2Store(dataPath('live-cues-v2-state.json'), () => new Date()).meetingCounters(sessionId)
+}
 export function shutdownLiveCuesV2(): void { engine?.shutdown(); unsubscribe?.(); unsubscribe = null; engine = null }