@gotcos/glasses-server 6.98.1 → 6.99.12

package/server/lib/ping-engine.ts

@@ -0,0 +1,245 @@
+/**
+ * Drop it P2 (plan PLAN_drop_it_2026-11-04 section 5): the ping engine.
+ *
+ * Reads existing signals only (ping-sources.ts). Runs no script, calls no model (canary 9 pins the import graph).
+ * Every item lands silently in the pinned COS chat; ping-budget.ts decides which also banner.
+ *
+ * One delivery path for every source, polled or pushed:
+ * 1. Drop what was already posted (its key is in the feed), consumed by a digest, already held, or expired.
+ * 2. Quiet hours (Control's rule): work pings are held, not created. Reminders he set and resolutions of his own
+ *    drops post at once (a resolution silently; the budget never banners it in quiet hours).
+ * 3. From 8:00 on a weekday, what was held posts as ONE "While you were off" item. A held item whose source no
+ *    longer reports it (the thread moved, the meeting started) is dropped as expired.
+ * 4. The budget picks the banners. The ledger is written BEFORE any banner is shown, so a crash between the two
+ *    can lose a banner but never repeat one.
+ *
+ * Nothing here logs words: only counts.
+ */
+import { existsSync, lstatSync, mkdirSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { acquireServerInstanceLock, type ServerInstanceLock } from './server-instance-lock.js'
+import { localClock } from './morning-brief-schedule.js'
+import { DEFAULT_BANNER_SOURCES, DEFAULT_BUDGET, isQuietHours, PING_SOURCES, planBanners, trimLedger, bannerTitle, type BannerRecord, type BudgetOptions, type PingSource } from './ping-budget.js'
+import { bannerSourcesFrom, budgetFrom, matchesSteer, steerWords, timeMinutes, type P2Settings } from './drop-p2-settings.js'
+import {
+  agentCandidate, checkinCandidates, digestCandidate, followupCandidates, prepCandidates, signalCandidates, staleCandidates,
+  type IntakeRow, type PingCandidate, type SignalRow, type ThreadRow,
+} from './ping-sources.js'
+
+/** Sources posted at once even in quiet hours (plan section 5). */
+const ANY_HOUR: ReadonlySet<PingSource> = new Set<PingSource>(['reminder', 'resolution'])
+/** Sources the engine polls; a held one of these that the next read no longer reports has expired. */
+const POLLED: ReadonlySet<PingSource> = new Set<PingSource>(['prep', 'followups', 'stale', 'checkin'])
+export const PING_STATE_LIMITS = { held: 200, consumed: 5_000, consumedDays: 30, fileBytes: 4_000_000 } as const
+
+export interface PingSnapshot {
+  nextEvent?: { title?: unknown; time?: unknown } | null
+  intakeOpen?: readonly IntakeRow[] | null
+  threads?: readonly ThreadRow[] | null
+  signals?: readonly SignalRow[] | null
+}
+
+export interface PingState {
+  ledger: BannerRecord[]
+  held: PingCandidate[]
+  /** Keys a digest carried, so they never post again on their own. */
+  consumed: Array<{ key: string; at: number }>
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
+
+function parseState(raw: unknown): PingState {
+  const state: PingState = { ledger: [], held: [], consumed: [] }
+  if (!isRecord(raw)) return state
+  if (Array.isArray(raw.ledger)) for (const b of raw.ledger) {
+    if (!isRecord(b) || typeof b.at !== 'number' || !Array.isArray(b.sources) || !Array.isArray(b.ids)) continue
+    const sources = b.sources.filter((s): s is PingSource => (PING_SOURCES as readonly string[]).includes(s as string))
+    if (sources.length) state.ledger.push({ at: b.at, sources, ids: b.ids.filter((i): i is string => typeof i === 'string').slice(0, 50) })
+  }
+  if (Array.isArray(raw.held)) for (const h of raw.held.slice(0, PING_STATE_LIMITS.held)) {
+    if (isRecord(h) && typeof h.key === 'string' && typeof h.line === 'string' && (PING_SOURCES as readonly string[]).includes(h.source as string)) state.held.push(h as unknown as PingCandidate)
+  }
+  if (Array.isArray(raw.consumed)) for (const c of raw.consumed) {
+    if (isRecord(c) && typeof c.key === 'string' && typeof c.at === 'number') state.consumed.push({ key: c.key, at: c.at })
+  }
+  return state
+}
+
+/** `data/pings/state.json`: the banner ledger, held items and consumed keys. One writer, 0700 folder, 0600 file. */
+export class PingStateStore {
+  private state: PingState
+  private readonly path: string
+  private readonly lock: ServerInstanceLock
+  private closed = false
+  constructor(root: string) {
+    const dir = resolve(root)
+    mkdirSync(dir, { recursive: true, mode: 0o700 })
+    const st = lstatSync(dir)
+    if (!st.isDirectory() || st.isSymbolicLink() || st.uid !== process.getuid?.() || (st.mode & 0o077)) throw new Error('ping_store_unsafe')
+    this.path = join(dir, 'state.json')
+    this.lock = acquireServerInstanceLock({ lockDir: join(dir, 'writer.lock') })
+    let raw: unknown = null
+    try {
+      if (existsSync(this.path)) {
+        const f = lstatSync(this.path)
+        if (f.isFile() && !f.isSymbolicLink() && f.size <= PING_STATE_LIMITS.fileBytes && !(f.mode & 0o077)) raw = JSON.parse(readFileSync(this.path, 'utf8'))
+      }
+    } catch { raw = null }  // a damaged state file costs at most a repeated digest key check: the feed keys still hold
+    this.state = parseState(isRecord(raw) && raw.version === 1 ? raw : null)
+  }
+  read(): PingState { return structuredClone(this.state) }
+  write(next: PingState, nowMs: number): void {
+    if (this.closed) throw new Error('ping_store_closed')
+    const cutoff = nowMs - PING_STATE_LIMITS.consumedDays * 86_400_000
+    const state: PingState = {
+      ledger: trimLedger(next.ledger, nowMs),
+      held: next.held.slice(-PING_STATE_LIMITS.held),
+      consumed: next.consumed.filter(c => c.at >= cutoff).slice(-PING_STATE_LIMITS.consumed),
+    }
+    durableAtomicWriteFileSync(this.path, JSON.stringify({ version: 1, ...state }) + '\n')
+    this.state = state
+  }
+  close(): void { if (this.closed) return; this.closed = true; this.lock.release() }
+}
+
+/** Where items land: the pinned chat's feed. `post` is idempotent on the key and returns the feed item id. */
+export interface PingFeedSink {
+  hasKey(key: string): boolean
+  post(candidate: PingCandidate): string
+}
+export interface PingBanner { feedIds: string[]; title: string; line: string; sources: PingSource[]; exempt: boolean; notifyId?: string }
+
+export interface PingEngineDeps {
+  state: Pick<PingStateStore, 'read' | 'write'>
+  feed: PingFeedSink
+  /** Reads the polled sources. Each field it cannot read is left out, and that source stays quiet this tick. */
+  read: () => Promise<PingSnapshot>
+  /** Shows a banner (macOS notification; a reminder also pushes to the lens). Called only after the ledger write. */
+  banner: (b: PingBanner) => void
+  now?: () => number
+  timezone: () => string
+  enabled?: () => readonly PingSource[]
+  /** 6.99.11 settings. When given, they decide the budget, quiet hours, sources, check-in, steer and banners. */
+  settings?: () => P2Settings
+}
+
+export interface PingTickResult { posted: number; held: number; released: number; expired: number; banners: number }
+
+export class PingEngine {
+  private readonly now: () => number
+  constructor(private readonly deps: PingEngineDeps) { this.now = deps.now ?? (() => Date.now()) }
+
+  /** Poll the sources and deliver. Never throws: a source that fails is skipped. */
+  async tick(): Promise<PingTickResult> {
+    const nowMs = this.now(), tz = this.deps.timezone()
+    let snap: PingSnapshot = {}
+    try { snap = await this.deps.read() } catch { snap = {} }
+    const polled: PingCandidate[] = []
+    const safely = (fn: () => PingCandidate[]) => { try { polled.push(...fn()) } catch { /* one bad source never stops the others */ } }
+    const set = this.settingsNow()
+    const src = set?.pings.sources
+    const pingsOn = set ? set.pings.on : true
+    if (pingsOn && (src?.prep ?? true)) safely(() => prepCandidates(snap.nextEvent, nowMs, tz))
+    if (pingsOn && (src?.followups ?? true)) safely(() => followupCandidates(snap.intakeOpen, nowMs))
+    if (pingsOn && (src?.stale ?? true)) safely(() => staleCandidates(snap.threads, nowMs, tz))
+    if (pingsOn && (src?.signals ?? true)) safely(() => signalCandidates(snap.signals, nowMs))
+    if (set ? set.checkin.on : true) safely(() => checkinCandidates(nowMs, tz, set ? { weekday: set.checkin.weekday, minutes: timeMinutes(set.checkin.time) } : undefined))
+    // Sources this snapshot could read: a held item from a source we could not read this tick is kept, not expired.
+    const read = new Set<PingSource>(['checkin'])
+    if (snap.nextEvent !== undefined) read.add('prep')
+    if (snap.intakeOpen !== undefined) read.add('followups')
+    if (snap.threads !== undefined && snap.signals !== undefined) read.add('stale')
+    return this.deliver(polled, nowMs, tz, { keys: new Set(polled.map(c => c.key)), sources: read })
+  }
+
+  /** Deliver pushed candidates now: a reminder that fired, a resolution, an agent that finished. */
+  push(candidates: PingCandidate[]): PingTickResult {
+    const nowMs = this.now()
+    return this.deliver(candidates, nowMs, this.deps.timezone(), null)
+  }
+
+  /** A pushed agent event, through the template. Off with the pings switch or the agent source switch. */
+  pushAgent(ev: Parameters<typeof agentCandidate>[0]): PingTickResult {
+    const set = this.settingsNow()
+    if (set && (!set.pings.on || !set.pings.sources.agent)) return { posted: 0, held: 0, released: 0, expired: 0, banners: 0 }
+    const c = agentCandidate(ev)
+    return c ? this.push([c]) : { posted: 0, held: 0, released: 0, expired: 0, banners: 0 }
+  }
+
+  private settingsNow(): P2Settings | null {
+    try { return this.deps.settings?.() ?? null } catch { return null }
+  }
+
+  private deliver(incoming: PingCandidate[], nowMs: number, tz: string, current: { keys: Set<string>; sources: Set<PingSource> } | null): PingTickResult {
+    const result: PingTickResult = { posted: 0, held: 0, released: 0, expired: 0, banners: 0 }
+    const set = this.settingsNow()
+    const budget: BudgetOptions = set ? budgetFrom(set) : DEFAULT_BUDGET
+    const leaveAlone = set ? steerWords(set.steer.leaveAlone) : [], about = set ? steerWords(set.steer.about) : []
+    const words = (c: PingCandidate) => `${c.title ?? ''} ${c.line}`
+    // "Leave alone" mutes a ping by its words. Never a reminder he set, never a follow-up to his own drop.
+    if (leaveAlone.length) incoming = incoming.filter(c => c.source === 'reminder' || c.source === 'resolution' || !matchesSteer(words(c), leaveAlone))
+    const state = this.deps.state.read()
+    const consumed = new Set(state.consumed.map(c => c.key))
+    const heldKeys = new Set(state.held.map(h => h.key))
+    const quiet = isQuietHours(nowMs, tz, budget)
+    const posted: Array<{ candidate: PingCandidate; feedId: string }> = []
+    let changed = false
+
+    const seen = new Set<string>()
+    for (const c of incoming) {
+      if (seen.has(c.key)) continue
+      seen.add(c.key)
+      if (this.deps.feed.hasKey(c.key) || consumed.has(c.key) || heldKeys.has(c.key)) continue
+      if (c.expiresAt !== undefined && c.expiresAt <= nowMs) { result.expired++; continue }
+      if (quiet && !ANY_HOUR.has(c.source)) {
+        state.held.push(c); heldKeys.add(c.key); result.held++; changed = true
+        continue
+      }
+      posted.push({ candidate: c, feedId: this.deps.feed.post(c) }); result.posted++
+    }
+
+    // Release what quiet hours held, as one item, from 8:00 on a weekday.
+    if (!quiet && state.held.length && localClock(nowMs, tz).minutes >= budget.firstBannerMinutes) {
+      const live = state.held.filter(h => {
+        if (h.expiresAt !== undefined && h.expiresAt <= nowMs) return false
+        if (current && POLLED.has(h.source) && current.sources.has(h.source) && !current.keys.has(h.key)) return false
+        return !this.deps.feed.hasKey(h.key)
+      })
+      result.expired += state.held.length - live.length
+      const digest = digestCandidate(live, nowMs, tz)
+      if (digest && !this.deps.feed.hasKey(digest.key)) {
+        posted.push({ candidate: digest, feedId: this.deps.feed.post(digest) }); result.posted++
+      }
+      result.released = live.length
+      for (const h of state.held) state.consumed.push({ key: h.key, at: nowMs })
+      state.held = []; changed = true
+    }
+
+    if (posted.length) {
+      const enabled = set ? bannerSourcesFrom(set) : this.deps.enabled?.() ?? DEFAULT_BANNER_SOURCES
+      // "Ping me about": a ping whose words match may banner although its kind is silent. The caps still hold.
+      const promoted = new Set(about.length ? posted.filter(p => matchesSteer(words(p.candidate), about)).map(p => p.feedId) : [])
+      const plan = planBanners(posted.map(p => ({ id: p.feedId, source: p.candidate.source, createdAt: p.candidate.createdAt })), state.ledger, nowMs, tz, enabled, budget, promoted)
+      const banners: PingBanner[] = plan.banners.map(b => {
+        const items = b.ids.map(id => posted.find(p => p.feedId === id)!.candidate)
+        return {
+          feedIds: b.ids, sources: b.sources, exempt: b.exempt, title: bannerTitle(items.length, items[0].title ?? 'COS'),
+          line: items.length === 1 ? items[0].line : items.map(i => i.title ?? i.line).join(', '),
+          ...(items.length === 1 && items[0].notifyId ? { notifyId: items[0].notifyId } : {}),
+        }
+      })
+      for (const b of plan.banners) state.ledger.push({ at: nowMs, sources: b.sources, ids: b.ids })
+      if (plan.banners.length) changed = true
+      if (changed) { this.deps.state.write(state, nowMs); changed = false }
+      for (const b of banners) {
+        try { this.deps.banner(b); result.banners++ } catch { /* a notifier failure never fails delivery: the item is in the chat */ }
+      }
+    }
+    if (changed) this.deps.state.write(state, nowMs)
+    if (result.posted || result.held || result.released || result.banners) {
+      console.log(`[pings] posted=${result.posted} held=${result.held} released=${result.released} expired=${result.expired} banners=${result.banners}`)
+    }
+    return result
+  }
+}

package/server/lib/ping-feed-sink.ts

@@ -0,0 +1,33 @@
+/**
+ * Drop it P2: where pings land. A PingCandidate becomes one item in the pinned COS chat (InboxFeedStore), under its
+ * exactly-once key. The feed store checks the key and writes in one synchronous step, so a key can be inserted once.
+ *
+ * - A resolution is a `followup`, threaded under its drop. Every other source is a `ping`, its own thread.
+ * - Born unread, from `cos`. Nothing here leaves the Mac; the feed is the chat.
+ */
+import { randomBytes } from 'node:crypto'
+import type { FeedItem, InboxFeedStore, DropLink } from './drop-store.js'
+import type { PingFeedSink } from './ping-engine.js'
+import type { PingCandidate } from './ping-sources.js'
+import { clip } from './ping-sources.js'
+
+const feedId = () => `fi_${randomBytes(16).toString('hex')}`
+
+export function toFeedItem(c: PingCandidate, nowMs: number): FeedItem {
+  const id = feedId()
+  return {
+    id, kind: c.source === 'resolution' ? 'followup' : 'ping', threadId: c.threadId ?? id,
+    createdAt: new Date(nowMs).toISOString(), readAt: null, source: 'cos',
+    ...(c.title ? { title: clip(c.title, 200) } : {}),
+    line: c.line.slice(0, 2_000), links: c.links.slice(0, 12) as DropLink[], actions: c.actions.slice(0, 6), state: 'live', key: c.key,
+    // Counts toward "waiting on you" (drop-service isWaiting) until dismissed, answered or done.
+    ...(c.needsReply === true ? { needsReply: true } : {}),
+  }
+}
+
+export function feedSink(feed: Pick<InboxFeedStore, 'byKey' | 'insert'>, now: () => number = () => Date.now()): PingFeedSink {
+  return {
+    hasKey: key => feed.byKey(key) !== undefined,
+    post: c => feed.insert([toFeedItem(c, now())])[0].id,
+  }
+}

package/server/lib/ping-sources.ts

@@ -0,0 +1,192 @@
+/**
+ * Drop it P2 (plan PLAN_drop_it_2026-11-04 section 5): what COS may ping about, read from signals that already exist.
+ *
+ * Every function here is pure: a snapshot in, candidates out. They run no script and call no model; the words come
+ * from fixed templates filled with the source's own titles and counts (canary 9). Each candidate carries the
+ * exactly-once key the plan names, so a source read twice, or again after a restart, yields the same key.
+ *
+ * | Source     | Read                                   | Key                                    |
+ * | prep       | the next calendar event                | prep:<event hash>:<local day>          |
+ * | followups  | open Work intake items, by meeting     | followups:<meeting record id hash>     |
+ * | stale      | a thread whose is_stale is true        | stale:<thread id>:<ISO week>           |
+ * | signal     | a red Signal row                       | signal:<Signal.id>                     |
+ * | checkin    | the clock, Monday from 9:00            | checkin:<ISO week>                     |
+ * | agent      | a linked session's turn ended (pushed) | agent:<session id>:<turn end>          |
+ *
+ * Reminders and resolutions come from the drop store (reminder-scheduler.ts, drop-resolution.ts), not from here.
+ */
+import { createHash } from 'node:crypto'
+import { localClock } from './morning-brief-schedule.js'
+import { clockLabel } from './drop-when.js'
+import { PING_RANK, type PingSource } from './ping-budget.js'
+
+export interface PingLink { kind: 'card' | 'session' | 'handoff' | 'thread' | 'memory' | 'meeting' | 'file' | 'reminder' | 'ask'; id: string; label: string; domain?: string }
+export interface PingCandidate {
+  source: PingSource
+  /** Exactly-once key (plan section 4). */
+  key: string
+  title?: string
+  line: string
+  links: PingLink[]
+  actions: Array<{ id: string; label: string }>
+  /** Epoch ms the source saw it. */
+  createdAt: number
+  /** Epoch ms after which it is no longer worth posting (prep: the meeting start). */
+  expiresAt?: number
+  /** Counts toward "waiting on you" until answered, done or dismissed (plan section 12). */
+  needsReply?: boolean
+  /**
+   * The notification identifier the banner uses. A reminder uses `reminder-<drop id>`, the same id Control gives its
+   * local backup notification, so a server fire replaces Control's instead of doubling it (plan section 7).
+   */
+  notifyId?: string
+  /** The drop a follow-up answers (it threads under that drop in the chat); a ping without one is its own thread. */
+  threadId?: string
+}
+
+export const PING_TEXT = { title: 120, line: 400, digestLines: 5 } as const
+/** Prep pings go out 15 minutes before a meeting (plan section 5). */
+export const PREP_LEAD_MS = 15 * 60_000
+/** A thread is pinged about as stale at most once a week (the key carries the ISO week). */
+export const CHECKIN = { weekday: 1, minutes: 9 * 60, line: "What's one thing this week you don't want to forget? I'll remind you." } as const
+
+const hash = (s: string) => createHash('sha256').update(s).digest('hex').slice(0, 16)
+const CONTROL = /[\x00-\x1f\x7f]+/g
+/** One line of a source's own words, cleaned and capped: never a model's. */
+export function clip(text: unknown, max: number): string {
+  if (typeof text !== 'string') return ''
+  const t = text.replace(CONTROL, ' ').replace(/\s+/g, ' ').trim()
+  return t.length <= max ? t : t.slice(0, max - 1).trimEnd() + '…'
+}
+const ID_SAFE = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,199}$/
+
+/** ISO 8601 week key, "2026-W45", for the local day. */
+export function isoWeek(nowMs: number, timezone: string): string {
+  const [y, m, d] = localClock(nowMs, timezone).day.split('-').map(Number)
+  const date = new Date(Date.UTC(y, m - 1, d))
+  const dow = date.getUTCDay() || 7
+  date.setUTCDate(date.getUTCDate() + 4 - dow)
+  const yearStart = Date.UTC(date.getUTCFullYear(), 0, 1)
+  const week = Math.ceil(((date.getTime() - yearStart) / 86_400_000 + 1) / 7)
+  return `${date.getUTCFullYear()}-W${String(week).padStart(2, '0')}`
+}
+
+/** Prep: the next meeting, inside 15 minutes of its start. Expires at the start. */
+export function prepCandidates(next: { title?: unknown; time?: unknown } | null | undefined, nowMs: number, timezone: string): PingCandidate[] {
+  if (!next) return []
+  const start = typeof next.time === 'string' ? Date.parse(next.time) : NaN
+  const title = clip(next.title, PING_TEXT.title)
+  if (!Number.isFinite(start) || !title) return []
+  if (start <= nowMs || start - nowMs > PREP_LEAD_MS) return []
+  const day = localClock(start, timezone).day
+  return [{
+    source: 'prep', key: `prep:${hash(`${title}\n${next.time}`)}:${day}`,
+    title, line: `${title} at ${clockLabel(localClock(start, timezone).minutes)}. Prep me?`,
+    links: [], actions: [{ id: 'prep', label: 'Prep me' }, { id: 'dismiss', label: 'Not now' }],
+    createdAt: nowMs, expiresAt: start,
+  }]
+}
+
+export interface IntakeRow { id: string; status: string; meeting: { recordId: string; title: string; domain: string } }
+/** Follow-ups ready: open intake items grouped by meeting, one ping per meeting. */
+export function followupCandidates(open: readonly IntakeRow[] | null | undefined, nowMs: number): PingCandidate[] {
+  if (!open?.length) return []
+  const byMeeting = new Map<string, IntakeRow[]>()
+  for (const row of open) {
+    if (!row?.meeting?.recordId) continue
+    byMeeting.set(row.meeting.recordId, [...(byMeeting.get(row.meeting.recordId) ?? []), row])
+  }
+  return [...byMeeting.entries()].map(([recordId, rows]) => {
+    const title = clip(rows[0].meeting.title, PING_TEXT.title) || 'a meeting'
+    const n = rows.length
+    return {
+      source: 'followups' as const, key: `followups:${hash(recordId)}`,
+      title, line: `${n} follow-up${n === 1 ? '' : 's'} from ${title}.`,
+      links: [{ kind: 'meeting' as const, id: `m_${hash(recordId)}`, label: title, domain: rows[0].meeting.domain }],
+      actions: [{ id: 'review', label: 'Review' }, { id: 'dismiss', label: 'Dismiss' }],
+      createdAt: nowMs, needsReply: true,
+    }
+  })
+}
+
+export interface ThreadRow { id?: unknown; name?: unknown; is_stale?: unknown; is_resolved?: unknown; last_seen?: unknown }
+/** Stale: a thread the tracker marks stale and not resolved. At most weekly per thread (the key has the week). */
+export function staleCandidates(threads: readonly ThreadRow[] | null | undefined, nowMs: number, timezone: string): PingCandidate[] {
+  if (!threads?.length) return []
+  const week = isoWeek(nowMs, timezone)
+  const out: PingCandidate[] = []
+  for (const t of threads) {
+    if (t?.is_stale !== true || t.is_resolved === true || typeof t.id !== 'string' || !ID_SAFE.test(t.id)) continue
+    const name = clip(t.name, PING_TEXT.title)
+    if (!name) continue
+    const last = typeof t.last_seen === 'string' ? Date.parse(t.last_seen) : NaN
+    const days = Number.isFinite(last) ? Math.max(1, Math.floor((nowMs - last) / 86_400_000)) : null
+    out.push({
+      source: 'stale', key: `stale:${t.id}:${week}`, title: name,
+      line: days ? `${name} quiet for ${days} days.` : `${name} has gone quiet.`,
+      links: [{ kind: 'thread', id: t.id, label: name }], actions: [{ id: 'open', label: 'Open' }],
+      createdAt: nowMs,
+    })
+  }
+  return out
+}
+
+export interface SignalRow { id?: unknown; severity?: unknown; title?: unknown; context?: unknown }
+/** Red signals, by their own title and the cache's existing context.explanation. One ping per Signal.id. */
+export function signalCandidates(signals: readonly SignalRow[] | null | undefined, nowMs: number): PingCandidate[] {
+  if (!signals?.length) return []
+  const out: PingCandidate[] = []
+  for (const s of signals) {
+    if (s?.severity !== 'red' || typeof s.id !== 'string' || !ID_SAFE.test(s.id)) continue
+    const title = clip(s.title, PING_TEXT.title)
+    if (!title) continue
+    const ctx = s.context && typeof s.context === 'object' ? (s.context as { explanation?: unknown }).explanation : undefined
+    const why = clip(ctx, PING_TEXT.line - title.length - 2)
+    out.push({
+      source: 'stale', key: `signal:${s.id}`, title,
+      line: why ? `${title}. ${why}` : `${title}.`, links: [], actions: [{ id: 'dismiss', label: 'Dismiss' }],
+      createdAt: nowMs,
+    })
+  }
+  return out
+}
+
+/** The weekly check-in, Monday from 9:00 local, once per ISO week. His reply becomes a reminder. */
+export function checkinCandidates(nowMs: number, timezone: string, when: { weekday: number; minutes: number } = CHECKIN): PingCandidate[] {
+  const c = localClock(nowMs, timezone)
+  if (c.weekday !== when.weekday || c.minutes < when.minutes) return []
+  return [{
+    source: 'checkin', key: `checkin:${isoWeek(nowMs, timezone)}`, line: CHECKIN.line,
+    links: [], actions: [{ id: 'reply', label: 'Reply' }, { id: 'dismiss', label: 'Skip this week' }],
+    createdAt: nowMs, needsReply: true,
+  }]
+}
+
+const PROVIDER_NAME: Record<string, string> = { claude: 'Claude', codex: 'Codex', cursor: 'Cursor', grok: 'Grok' }
+/** Agent finished: a session linked to a drop or a Work handoff ended its turn. Pushed by the caller, never polled. */
+export function agentCandidate(ev: { provider?: unknown; sessionId?: unknown; turnEndedAt?: unknown; label?: unknown; failed?: unknown }): PingCandidate | null {
+  if (typeof ev.sessionId !== 'string' || !ID_SAFE.test(ev.sessionId) || typeof ev.turnEndedAt !== 'number' || !Number.isFinite(ev.turnEndedAt)) return null
+  const who = PROVIDER_NAME[typeof ev.provider === 'string' ? ev.provider : ''] ?? 'Your agent'
+  const label = clip(ev.label, PING_TEXT.title) || 'its task'
+  return {
+    source: 'agent', key: `agent:${ev.sessionId}:${Math.floor(ev.turnEndedAt)}`, title: label,
+    line: ev.failed === true ? `${who} stopped on ${label}. It needs a look.` : `${who} finished ${label}.`,
+    links: [{ kind: 'session', id: ev.sessionId, label }], actions: [{ id: 'open_result', label: 'Open result' }],
+    createdAt: ev.turnEndedAt, needsReply: ev.failed === true,
+  }
+}
+
+/** The one "While you were off" item that carries what quiet hours held (plan section 5). */
+export function digestCandidate(held: readonly PingCandidate[], nowMs: number, timezone: string): PingCandidate | null {
+  if (!held.length) return null
+  const lines = held.slice(0, PING_TEXT.digestLines).map(h => `- ${h.line}`)
+  if (held.length > PING_TEXT.digestLines) lines.push(`- and ${held.length - PING_TEXT.digestLines} more`)
+  const best = [...held].sort((a, b) => PING_RANK[a.source] - PING_RANK[b.source])[0]
+  const links = held.flatMap(h => h.links).slice(0, 12)
+  return {
+    source: best.source, key: `offhours:${localClock(nowMs, timezone).day}`,
+    title: held.length === 1 ? 'While you were off' : `While you were off: ${held.length} updates`,
+    line: lines.join('\n'), links, actions: [{ id: 'open', label: 'Open' }],
+    createdAt: nowMs, needsReply: held.some(h => h.needsReply),
+  }
+}

package/server/lib/query-job-coordinator.ts

@@ -1,3 +1,4 @@
+import { CONSOLIDATION_JOB_MS } from './meeting-consolidation-run.js'
 import { getOrCreateSession } from './conversation.js'
 import {
   QueryJobNotFoundError,
@@ -723,8 +724,10 @@ export class QueryJobCoordinator {
   private armProviderDeadline(active: ActiveRun): void {
     if (active.providerTimeoutTimer || active.terminalPersisted || active.persistenceFailed) return
     // On the monotonic steer clock (P7 S7): decideSteer compares it with the bridge's wall clock.
-    active.deadlineAt = steerClock() + this.providerTimeoutMs
-    active.providerTimeoutTimer = setTimeout(() => active.resolveProviderTimeout(), this.providerTimeoutMs)
+    const timeoutMs = active.request.maintenanceWorkflow === 'meeting-consolidation-v1'
+      ? CONSOLIDATION_JOB_MS : this.providerTimeoutMs
+    active.deadlineAt = steerClock() + timeoutMs
+    active.providerTimeoutTimer = setTimeout(() => active.resolveProviderTimeout(), timeoutMs)
     active.providerTimeoutTimer.unref?.()
   }
 

package/server/lib/query-job-runtime.ts

@@ -1,3 +1,6 @@
+import { resolveProviderWorkDir } from './launch-dir.js'
+import { COS_SCRIPTS_DIR } from './python-bridge.js'
+import { consolidationModelRunner } from './meeting-consolidation-run.js'
 import { routineAuditCaller } from './routines-config.js'
 import { jobAuditCaller } from './job-audit-caller.js'
 import { carriesBoundTo } from './agent-session-binding-store.js'
@@ -8,7 +11,9 @@ import { emitDisplay } from './display-bus.js'
 import { resolveQueryAttachments } from './query-attachments.js'
 import { getMediaStore } from './media-store.js'
 import { dataPath } from './data-dir.js'
-import { currentMessageEra, LEGACY_MESSAGE_ERA } from './message-era.js'
+import { currentMessageEra, exchangeBelongsToEra, LEGACY_MESSAGE_ERA } from './message-era.js'
+import { isWebAsk, prepareWebAsk } from './web-ask-admission.js'
+import { maxGlobalMsgNumInDir } from '../routes/message-ref.js'
 import { durableQueryJobsEnabled, messagesSteerEnabled, messagesTrailEnabled } from './query-job-feature.js'
 import { claudeSupportsSteer } from './claude-cli-support.js'
 import { steerProviderFor } from './claude-steer.js'
@@ -25,6 +30,9 @@ import {
 import { mergeMediaAttachmentRefs } from '../../shared/media-attachment.js'
 import { attachmentHistoryPrefix, defaultAttachmentRequest } from '../../shared/media-attachment.js'
 import {
+  createSession,
+  getActiveSessions,
+  getSessionRaw,
   findExchangesByJobIdentity,
   flushConversationToDisk,
   getSessionBinding,
@@ -44,7 +52,7 @@ import {
 } from './query-job-types.js'
 import { acquireMaintenanceWork } from './maintenance-lifecycle.js'
 import type { JobTrailDraft } from './job-trail.js'
-import { registerMessageReservationSource } from './message-reservations.js'
+import { maxReservedGlobalMsgNum, registerMessageReservationSource } from './message-reservations.js'
 import { bootResumeGate } from './boot-resume.js'
 import { keyAnswerCompletionFields, keyAnswerDoneFields } from './key-answer-fields.js'
 
@@ -69,9 +77,36 @@ export class QueryJobAdmissionPreparationError extends Error {
  * the strict QueryJobRequest parser before persistence. Once a reset era
  * exists, reject pre-era clients before they stamp five-digit numbers into
  * the fresh namespace. */
+/** 6.99.10: the next-number ceiling for a web Ask, the same arithmetic /api/message-counter serves. */
+function webAskCurrentMax(): number {
+  const era = currentMessageEra()
+  let liveMax = 0
+  for (const session of getActiveSessions()) {
+    for (const exchange of (session as { exchanges?: Array<{ globalMsgNum?: unknown; messageEra?: unknown }> }).exchanges ?? []) {
+      if (!exchangeBelongsToEra(exchange, era)) continue
+      if (typeof exchange?.globalMsgNum === 'number' && exchange.globalMsgNum > liveMax) liveMax = exchange.globalMsgNum
+    }
+  }
+  return Math.max(liveMax, maxGlobalMsgNumInDir(dataPath('archive'), era), maxReservedGlobalMsgNum(era))
+}
+
 export async function preparePublicDurableQueryAdmission(raw: unknown): Promise<unknown> {
   if (!raw || typeof raw !== 'object') return raw
-  const input = raw as Record<string, unknown>
+  let input = raw as Record<string, unknown>
+  // 6.99.10: Ask from COS Control Web (`source: 'web'`): the server picks the conversation and mints the message
+  // number (lib/web-ask-admission.ts). Every other caller is untouched.
+  if (isWebAsk(input) && !carriesBoundTo(input)) {
+    input = await prepareWebAsk(input, {
+      currentMax: webAskCurrentMax,
+      activeEra: currentMessageEra,
+      sessionExists: id => !!getSessionRaw(id),
+      createSession,
+      priorJob: async (clientJobId, generation) => {
+        const job = await queryJobCoordinator.getByClientGeneration(clientJobId, generation)
+        return job ? { sessionId: job.sessionId, globalMsgNum: job.globalMsgNum, messageEra: job.messageEra } : undefined
+      },
+    })
+  }
 
   // Plan 4.2: an attached turn must NEVER silently degrade into an ordinary COS
   // turn. The binding lives in the route path rather than the body, so a
@@ -255,7 +290,13 @@ const runner: QueryJobRunner = async ({ jobId, turnId, request, signal, callback
     ? { ...keyProfileLinkageProvider(keyTurn), resolvedModel: keyTurn.binding }
     : { provider: providerFor(model), resolvedModel: model }
 
-  await callModelStreaming(
+  const runModel = request.maintenanceWorkflow === 'meeting-consolidation-v1'
+    ? consolidationModelRunner(callModelStreaming, {
+        root: dataPath('meeting-consolidation'),
+        workspace: resolveProviderWorkDir({ scriptsDir: COS_SCRIPTS_DIR }),
+        runId: `${request.clientJobId}-g${request.generation}`,
+      }) : callModelStreaming
+  await runModel(
     request.query,
     request.sessionId,
     {

package/server/lib/query-job-types.ts

@@ -134,6 +134,8 @@ export interface QueryJobRequest {
    * it names the session, it does not change what is asked.
    */
   sessionName?: string
+  /** Explicit user-started, checkpointed maintenance. Changes execution semantics. */
+  maintenanceWorkflow?: 'meeting-consolidation-v1'
   /**
    * Key lanes (QA U9 / C10): run THIS turn on the key profile it names without binding the
    * session to it (the plan-limit "run this one on your key" offer). Kept only with a
@@ -599,6 +601,12 @@ export function parseQueryJobRequest(raw: unknown, options: ParseQueryJobRequest
   const handoffCode = optionalString(input.handoffCode, 'handoff_code', 128)
   const clientQueueItemId = optionalString(input.clientQueueItemId, 'client_queue_item_id', 120)
   const sessionName = sanitizeSessionName(input.sessionName)
+  const maintenanceWorkflow = input.maintenanceWorkflow
+  if (maintenanceWorkflow != null && (maintenanceWorkflow !== 'meeting-consolidation-v1'
+    || !['opus', 'codex-frontier'].includes(model ?? '') || input.dispatch != null || input.steerable === true
+    || (Array.isArray(input.attachmentIds) && input.attachmentIds.length > 0))) {
+    throw new QueryJobValidationError('invalid_maintenance_workflow')
+  }
   const globalMsgNum = input.globalMsgNum == null ? undefined : Number(input.globalMsgNum)
   if (globalMsgNum != null && (!Number.isSafeInteger(globalMsgNum) || globalMsgNum < 1)) {
     throw new QueryJobValidationError('invalid_global_msg_num')
@@ -670,6 +678,7 @@ export function parseQueryJobRequest(raw: unknown, options: ParseQueryJobRequest
     ...(input.handoffLatest === true ? { handoffLatest: true } : {}),
     ...(clientQueueItemId ? { clientQueueItemId } : {}),
     ...(sessionName ? { sessionName } : {}),
+    ...(maintenanceWorkflow === 'meeting-consolidation-v1' ? { maintenanceWorkflow } as const : {}),
     ...(input.keyTurnOnly === true && isProfilePreference(model) ? { keyTurnOnly: true as const } : {}),
     ...(input.steerable === true ? { steerable: true as const } : {}),
     attachmentIds,
@@ -735,7 +744,7 @@ export const FINGERPRINT_KEYS = [
   'clientJobId', 'generation', 'query', 'sessionId', 'model', 'effort',
   'cursorExecutionMode', 'messageEra', 'globalMsgNum', 'reference', 'handoffCode',
   'handoffLatest', 'clientQueueItemId', 'attachmentIds', 'attachmentRefs',
-  'activityToolMode', 'keyTurnOnly',
+  'activityToolMode', 'keyTurnOnly', 'maintenanceWorkflow',
 ] as const satisfies readonly (keyof QueryJobRequest)[]
 
 /** The request keys deliberately OUTSIDE the identity. Every key of