@gotcos/glasses-server 6.98.0 → 6.99.12

package/server/lib/codex-bridge.ts

@@ -722,8 +722,16 @@ export async function callCodexStreaming(
     callbacks.onChunk(text)
   }
 
+  let maintenanceClosed = false
   async function finalize(text: string) {
     if (finalized) return
+    // A next maintenance pass may start only after the entire provider tree
+    // has closed. Normal chat retains its existing result-event behavior.
+    if (options?.maintenancePass && !maintenanceClosed) {
+      if (terminationRequested) return
+      await terminateForTerminal('maintenance checkpoint', () => finalize(text))
+      return
+    }
     const responseAuthFailure = terminalProviderAuthFailure('codex', text)
     const authFailure = responseAuthFailure
       ?? (!text.trim() ? terminalTextError ?? terminalProviderAuthFailure('codex', stderr) : null)
@@ -861,6 +869,11 @@ export async function callCodexStreaming(
 
   async function finalizeError(msg: string, exitCode?: number | null, status: Exclude<CodexRunStatus, 'running'> = 'failed') {
     if (finalized) return
+    if (options?.maintenancePass && !maintenanceClosed) {
+      if (terminationRequested) return
+      await terminateForTerminal('maintenance error', () => finalizeError(msg, exitCode, status))
+      return
+    }
     finalized = true
     // Canary R14: a Codex child keeps retrying after the bridge ends the turn; its nonce dies now.
     keyTurn?.revoke('cancel')
@@ -876,7 +889,7 @@ export async function callCodexStreaming(
       exitCode,
     })
     try {
-      await callbacks.onError(safeCodexUserError(msg))
+      await callbacks.onError(options?.maintenancePass && msg === 'maintenance_pass_timeout' ? msg : safeCodexUserError(msg))
     } catch (error) {
       console.error('[codex-bridge] terminal error callback failed:', error)
     }
@@ -910,6 +923,7 @@ export async function callCodexStreaming(
       console.error(`[codex-bridge] provider did not close after SIGKILL (${reason}); retaining lifecycle ownership`)
       return
     }
+    maintenanceClosed = true
     await onClosed(result)
   }
 
@@ -949,6 +963,7 @@ export async function callCodexStreaming(
 
   const wallTimer = setTimeout(() => {
     void terminateForTerminal('wall timeout', result => {
+      if (options?.maintenancePass) return finalizeError('maintenance_pass_timeout', result.code)
       if (fullText) return finalize(fullText)
       return finalizeError(`Wall clock limit reached (${WALL_MAX_MS / 1000}s). Codex process killed.`, result.code)
     })
@@ -1046,7 +1061,11 @@ export async function callCodexStreaming(
       try { handleEvent(JSON.parse(buffer.trim())) } catch { /* ignore */ }
     }
     runUsage.settle()
-    if (finalized) return
+    if (finalized || terminationRequested) return
+    if (options?.maintenancePass) {
+      finalizeError('maintenance_pass_incomplete_exit', code)
+      return
+    }
     if (fullText) {
       void finalize(fullText)
       return

package/server/lib/display-bus.ts

@@ -11,6 +11,9 @@ export interface DisplayEvent {
   type: 'chunk' | 'done' | 'error' | 'tool_status' | 'start' | 'session_restore' | 'transcript_chunk' | 'prompt_transcript' | 'recording_start' | 'recording_stop' | 'coaching_nudge' | 'coaching_nudge_v2'
     // Control asked the glasses to stop a G2 meeting (routes/meeting.ts stop-request).
     | 'meeting_stop_requested' | 'mac_speaker_live_revision'
+    // Drop it P2: a reminder he set fired; the lens shows it (plan section 5). Not in the ticketless projections, so a
+    // stream without a ticket never receives it; shipped clients do not listen for it and ignore it.
+    | 'cos_ping'
   data: Record<string, unknown>
 }
 

package/server/lib/drop-destinations.ts

@@ -0,0 +1,134 @@
+/**
+ * Drop it destinations (plan section 3): the writes a filed drop makes, through the existing COS bridge.
+ *
+ * | Destination   | Write                                              | Undo                                         |
+ * | New card      | `task-capture-drop` (answers the id)               | `task-archive-drop` while untouched          |
+ * | Existing card | a link on the drop only (no tasks.md write)        | the link is removed                          |
+ * | Thread        | `thread-source --id <thread>`                      | `thread-unsource --id --source-id`           |
+ * | Memory        | `memory-capture` into To review (the bridge embeds | `memory-uncapture`: quarantine (reversible),  |
+ * |               | it through the embedding provider, as any memory) | refused once the memory was reviewed          |
+ * | Session, note, reminder: the drop store only.                                                               |
+ *
+ * A bridge that does not know a verb answers `cos_pipeline_not_configured` (or the portable runtime's
+ * `task_runtime_unavailable`), which becomes DropDestinationError('destination_unavailable'): the caller keeps a plain
+ * note and says why. Every destination is local; nothing here sends anything anywhere.
+ */
+import { callPython, contextSourceAvailable } from './python-bridge.js'
+import { archiveDropCard, captureDropCard, listBoard, taskDomains, TaskBridgeError, TaskRunError } from './task-store.js'
+import { domainLabel } from './domain-label.js'
+import { normalizeThreads, THREAD_ID_PATTERN } from './cos-context-browser.js'
+import { DROP_ROUTER_LIMITS, rankByOverlap, type RouteCandidates } from './drop-router.js'
+
+export class DropDestinationError extends Error {
+  constructor(readonly code: 'destination_unavailable' | 'destination_failed' | 'memory_too_short') { super(code) }
+}
+
+export interface DropWriters {
+  captureCard(domain: string, text: string, dropId: string): Promise<{ id: string; workIdentity: string; created: boolean }>
+  archiveCard(domain: string, id: string, dropId: string, text: string): Promise<'archived' | 'touched' | 'gone'>
+  /** `attempt` is the filing's number: each filing is a new capture, so a replay never answers a set-aside row. */
+  captureMemory(text: string, dropId: string, attempt: string): Promise<{ id: string; created: boolean }>
+  /** pruned | touched (reviewed since, or not this drop's) | gone. */
+  pruneMemory(id: string, dropId: string): Promise<'pruned' | 'touched' | 'gone'>
+  sourceThread(threadId: string, text: string, dropId: string): Promise<{ sourceId: string; created: boolean }>
+  unsourceThread(threadId: string, sourceId: string, dropId: string): Promise<'removed' | 'touched' | 'gone'>
+  /** What the router may choose from. Any part that cannot be read is simply left out. */
+  candidates(text: string, session?: { id: string; label: string }): Promise<RouteCandidates>
+  /** Card stages for History status, keyed by Work identity. */
+  cardStates(): Promise<Map<string, { workStage: string; checked: boolean }>>
+}
+
+const MISSING = new Set(['cos_pipeline_not_configured', 'task_runtime_unavailable', 'unknown_command'])
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,199}$/
+
+/** A bridge answer as an error code, or null. The COS bridge answers both `{error:{code}}` and `{error:"…"}`. */
+export function bridgeErrorCode(answer: unknown): string | null {
+  if (!answer || typeof answer !== 'object') return 'empty_answer'
+  const error = (answer as { error?: unknown }).error
+  if (error === undefined) return null
+  if (typeof error === 'string') return /unknown command/i.test(error) ? 'unknown_command' : 'bridge_error'
+  const code = (error as { code?: unknown })?.code
+  return typeof code === 'string' ? code : 'bridge_error'
+}
+function fail(code: string | null): never {
+  if (code === 'memory_rejected') throw new DropDestinationError('memory_too_short')
+  throw new DropDestinationError(code && MISSING.has(code) ? 'destination_unavailable' : 'destination_failed')
+}
+async function python(args: string[], input?: string): Promise<Record<string, unknown>> {
+  // The file tier (no venv) answers `{}` for every verb it does not know: that is a missing verb, not a failure.
+  if (contextSourceAvailable() !== 'bridge') fail('cos_pipeline_not_configured')
+  let answer: unknown
+  try { answer = await callPython(args, 20_000, input) } catch { fail('bridge_error') }
+  const code = bridgeErrorCode(answer)
+  if (code) fail(code)
+  return answer as Record<string, unknown>
+}
+const taskCode = (e: unknown): string | null => e instanceof TaskBridgeError || e instanceof TaskRunError ? e.code : null
+
+export const CANDIDATE_MS = 6_000
+/** The value, or null when it failed or took longer than `ms`. */
+export async function within<T>(ms: number, fn: () => Promise<T>): Promise<T | null> {
+  let timer: NodeJS.Timeout | undefined
+  try {
+    return await Promise.race([fn().catch(() => null), new Promise<null>(resolve => { timer = setTimeout(() => resolve(null), ms) })])
+  } finally { if (timer) clearTimeout(timer) }
+}
+
+export function createBridgeDropWriters(): DropWriters {
+  return {
+    async captureCard(domain, text, dropId) {
+      try { return await captureDropCard(domain, text, dropId) } catch (e) { fail(taskCode(e)) }
+    },
+    async archiveCard(domain, id, dropId, text) {
+      try { return await archiveDropCard(domain, id, dropId, text) } catch (e) { fail(taskCode(e)) }
+    },
+    async captureMemory(text, dropId, attempt) {
+      const out = await python(['memory-capture'], JSON.stringify({ text, dropId, attempt }))
+      if (out.ok !== true || typeof out.id !== 'string' || !ID.test(out.id)) fail('bridge_error')
+      return { id: out.id as string, created: out.created !== false }
+    },
+    async pruneMemory(id, dropId) {
+      const out = await python(['memory-uncapture', '--id', id], JSON.stringify({ dropId }))
+      if (out.ok === true && (out.result === 'pruned' || out.result === 'touched' || out.result === 'gone')) return out.result
+      fail('bridge_error')
+    },
+    async sourceThread(threadId, text, dropId) {
+      if (!THREAD_ID_PATTERN.test(threadId)) fail('invalid_thread')
+      const out = await python(['thread-source', '--id', threadId], JSON.stringify({ text, dropId }))
+      if (out.ok !== true || typeof out.sourceId !== 'string' || !ID.test(out.sourceId)) fail('bridge_error')
+      return { sourceId: out.sourceId as string, created: out.created !== false }
+    },
+    async unsourceThread(threadId, sourceId, dropId) {
+      const out = await python(['thread-unsource', '--id', threadId, '--source-id', sourceId], JSON.stringify({ dropId }))
+      if (out.ok === true && (out.result === 'removed' || out.result === 'touched' || out.result === 'gone')) return out.result
+      fail('bridge_error')
+    },
+    async candidates(text, session) {
+      // The board and the threads are read side by side, each bounded: POST /api/drops holds the API mutation lease,
+      // so its worst case (candidates 6 s, Jev 20 s, a card write with lock retries about 37 s) stays under Control's
+      // 90 s drain. A part that is slow or unreadable is simply not offered.
+      const out: RouteCandidates = { domains: [], cards: [], threads: [], ...(session ? { session } : {}) }
+      try { out.domains = taskDomains().map(name => ({ name, label: domainLabel(name) })) } catch { /* no domains: no new card */ }
+      const [cards, threads] = await Promise.all([
+        within(CANDIDATE_MS, async () => {
+          const open = (await listBoard()).filter(row => !row.checked)
+          return rankByOverlap(text, open, row => row.text, DROP_ROUTER_LIMITS.cardCandidates)
+            .map(row => ({ id: row.id, workIdentity: row.workIdentity ?? row.id, domain: row.domain, text: row.text }))
+        }),
+        within(CANDIDATE_MS, async () => {
+          if (!contextSourceAvailable()) return []
+          const list = normalizeThreads(await callPython(['threads', '--limit', '50'], CANDIDATE_MS), 50).threads.filter(t => !t.is_resolved)
+          return rankByOverlap(text, list, t => `${t.name} ${t.topics.join(' ')}`, DROP_ROUTER_LIMITS.threadCandidates).map(t => ({ id: t.id, name: t.name }))
+        }),
+      ])
+      out.cards = cards ?? []
+      out.threads = threads ?? []
+      return out
+    },
+    async cardStates() {
+      const map = new Map<string, { workStage: string; checked: boolean }>()
+      for (const row of await listBoard()) map.set(row.workIdentity ?? row.id, { workStage: row.workStage ?? 'planned', checked: row.checked })
+      return map
+    },
+  }
+}

package/server/lib/drop-history-search.ts

@@ -0,0 +1,97 @@
+/**
+ * Drop it P2 (plan PLAN_drop_it_2026-11-04 section 6): History search by meaning.
+ *
+ * The chat's History searches its drops by words at once, on the client. After a pause it asks this for the drop he
+ * MEANS: one Jev Choice over the drops' cleaned words and link labels, with `none` as an option, on the work-search
+ * pattern (lib/work-search.ts): the same option cleaning, the same ranking, a 10-minute cache and one request per query.
+ *
+ * Cost and privacy:
+ * - Charged to the drop router's own budget (COS_DROP_DAILY_TOKENS, its usage ledger and breaker), through the client
+ *   the caller passes in; P1 pins drops to Jev, so the decision provider setting does not apply here either.
+ * - Off with the router (COS_DROP_ROUTER=0).
+ * - A drop whose words trip the secret check (cleanDropForJev) is never offered: it stays a note, found by words only.
+ * - A Choice holds 254 options plus `none`. History can be longer, so the newest 254 are searched and the answer says
+ *   `partial` (word search still covers everything) instead of refusing.
+ * - Logs hold a count and an error code, never words.
+ */
+import { createHash } from 'node:crypto'
+import type { DecisionClient } from './decision-provider.js'
+import { DecisionProviderError } from './decision-provider.js'
+import { estimateJevTokens, JevError } from './jev.js'
+import { cleanDropForJev, dropRouterEnabled } from './drop-router.js'
+import type { DropRecord } from './drop-store.js'
+import { normalizeQuery, queryLength, rankHits, searchOptionText, unavailable, WORK_SEARCH_LIMITS, type WorkSearchHit, type WorkSearchReason } from './work-search.js'
+
+export const DROP_SEARCH_INSTRUCTIONS = 'The user typed `query` into the search box of the history of things they jotted down '
+  + '(ideas, tasks, notes, reminders). Which entry are they trying to find? Pick the one they mean even when it uses different '
+  + 'words, or none if no entry fits.'
+export const DROP_SEARCH_NONE = 'None of these entries is what the user is looking for.'
+
+export type DropSearchResult =
+  | { available: true; results: WorkSearchHit[]; none: number | null; cached: boolean; tokens: number; searched: number; partial: boolean }
+  | { available: false; reason: WorkSearchReason | 'query_invalid'; message: string }
+
+/** What Jev reads for one drop: its words and its link labels, cleaned as work search cleans a card. */
+export function dropOptionText(drop: Pick<DropRecord, 'text' | 'links'>): string {
+  const labels = drop.links.map(l => l.label).filter(Boolean).join('; ')
+  return searchOptionText(labels ? `${drop.text} (${labels})` : drop.text)
+}
+
+/** The drops a search covers, newest first: never one that tripped the secret check, never one with no words left. */
+export function searchableDrops(drops: readonly DropRecord[]): { rows: Array<{ id: string; text: string }>; total: number } {
+  const rows = [...drops]
+    .sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt))
+    .filter(d => d.route?.reason !== 'redacted' && !cleanDropForJev(d.text).tripped)
+    .map(d => ({ id: d.id, text: dropOptionText(d) }))
+    .filter(r => r.text.length > 0)
+  return { rows: rows.slice(0, WORK_SEARCH_LIMITS.maxCandidates), total: rows.length }
+}
+
+const PASSED_THROUGH = new Set<string>(['jev_not_configured', 'jev_key_rejected', 'jev_cap_reached', 'jev_breaker_open', 'jev_request_rejected'])
+
+export class DropHistorySearcher {
+  private cache = new Map<string, { at: number; results: WorkSearchHit[]; none: number | null; searched: number; partial: boolean }>()
+  private inflight = new Map<string, Promise<DropSearchResult>>()
+  constructor(private readonly client: DecisionClient, private readonly now: () => number = () => Date.now(), private readonly env: NodeJS.ProcessEnv = process.env) {}
+
+  /** Never throws for a Jev failure: it answers `available: false` with one line, and word search carries on. */
+  async search(query: unknown, drops: readonly DropRecord[]): Promise<DropSearchResult> {
+    if (typeof query !== 'string' || queryLength(query.trim()) < WORK_SEARCH_LIMITS.queryMin || queryLength(query) > WORK_SEARCH_LIMITS.queryMax) {
+      return { available: false, reason: 'query_invalid', message: `Type ${WORK_SEARCH_LIMITS.queryMin} to ${WORK_SEARCH_LIMITS.queryMax} characters to search by meaning.` }
+    }
+    if (!dropRouterEnabled(this.env)) return unavailable('search_off')
+    const { rows, total } = searchableDrops(drops)
+    const partial = total > rows.length
+    if (!rows.length) return { available: true, results: [], none: 1, cached: false, tokens: 0, searched: 0, partial: false }
+    const set = createHash('sha256').update(JSON.stringify(rows.map(r => [r.id, r.text]))).digest('hex')
+    const key = createHash('sha256').update(normalizeQuery(query) + '\0' + set).digest('hex')
+    const hit = this.cache.get(key)
+    if (hit && this.now() - hit.at < WORK_SEARCH_LIMITS.cacheMs) return { available: true, results: hit.results, none: hit.none, cached: true, tokens: 0, searched: hit.searched, partial: hit.partial }
+    if (hit) this.cache.delete(key)
+    const running = this.inflight.get(key)
+    if (running) return running
+    const work = this.ask(query, rows, key, partial)
+    this.inflight.set(key, work)
+    try { return await work } finally { this.inflight.delete(key) }
+  }
+
+  private async ask(query: string, rows: Array<{ id: string; text: string }>, key: string, partial: boolean): Promise<DropSearchResult> {
+    const state = { query: query.trim() }
+    const criteria: Record<string, string> = Object.fromEntries(rows.map((r, i) => [`t${i}`, r.text]))
+    criteria.none = DROP_SEARCH_NONE
+    const questions = { c: { type: 'choice', instructions: DROP_SEARCH_INSTRUCTIONS, criteria } }
+    try {
+      const reply = await this.client.ask(state, questions, estimateJevTokens({ state, questions }))
+      const { results, none } = rankHits(reply.answers.c?.probabilities, rows.map(r => r.id))
+      if (this.cache.size >= WORK_SEARCH_LIMITS.cacheEntries) this.cache.delete(this.cache.keys().next().value!)
+      this.cache.set(key, { at: this.now(), results, none, searched: rows.length, partial })
+      return { available: true, results, none, cached: false, tokens: reply.inputTokens, searched: rows.length, partial }
+    } catch (e) {
+      if (e instanceof DecisionProviderError) return unavailable(e.code)
+      if (!(e instanceof JevError)) throw e
+      if (PASSED_THROUGH.has(e.code)) return unavailable(e.code as WorkSearchReason)
+      console.warn('[drop-search] Jev failed:', e.code)
+      return unavailable('jev_unavailable')
+    }
+  }
+}

package/server/lib/drop-p2-boot.ts

@@ -0,0 +1,60 @@
+/**
+ * Drop it P2: when the pings, reminders and follow-ups run. Only while Drop it is on, and they must run without a
+ * request (a reminder fires on its own), so this checks the switch at boot and once a minute: on, it opens the drop
+ * service (the same stores the routes use) and starts the runtime; off, it stops the runtime and closes its state.
+ *
+ * Off (the default for every install) opens nothing and writes nothing, exactly as P1.
+ */
+import type { DropService } from './drop-service.js'
+import { PingStateStore } from './ping-engine.js'
+import type { DropP2Runtime } from './drop-p2-runtime.js'
+
+export const DROP_P2_CHECK_MS = 60_000
+
+export interface DropP2BootDeps {
+  enabled: () => boolean
+  /** The routes' lazy service: opening it here and in a request gives the same instance. */
+  service: () => DropService | null
+  pingRoot: string
+  make: (stores: ReturnType<DropService['p2Stores']>, pingState: PingStateStore) => DropP2Runtime
+  openPingState?: (root: string) => PingStateStore
+  checkMs?: number
+}
+
+export function createDropP2Boot(deps: DropP2BootDeps) {
+  let runtime: DropP2Runtime | null = null
+  let state: PingStateStore | null = null
+  let timer: ReturnType<typeof setInterval> | null = null
+
+  function down() {
+    runtime?.stop(); runtime = null
+    try { state?.close() } catch { /* already closed */ }
+    state = null
+  }
+  /** Bring the runtime in line with the switch. Never throws: a store that cannot open leaves the pings off. */
+  function check(): DropP2Runtime | null {
+    let on = false
+    try { on = deps.enabled() } catch { on = false }
+    if (!on) { if (runtime) { down(); console.log('[pings] stopped: Drop it is off') } return null }
+    if (runtime) return runtime
+    const service = deps.service()
+    if (!service) return null
+    try {
+      state = (deps.openPingState ?? (root => new PingStateStore(root)))(deps.pingRoot)
+      runtime = deps.make(service.p2Stores(), state)
+      runtime.start()
+      console.log('[pings] started')
+    } catch (e) {
+      console.error('[pings] could not start:', e instanceof Error ? e.message.slice(0, 80) : 'error')
+      down()
+    }
+    return runtime
+  }
+  return {
+    /** The running runtime, or null. The routes read it for banners. */
+    runtime: (): DropP2Runtime | null => runtime,
+    check,
+    start() { if (timer) return; check(); timer = setInterval(check, deps.checkMs ?? DROP_P2_CHECK_MS); timer.unref?.() },
+    stop() { if (timer) clearInterval(timer); timer = null; down() },
+  }
+}

package/server/lib/drop-p2-runtime.ts

@@ -0,0 +1,237 @@
+/**
+ * Drop it P2: the parts running together. One object the server starts beside the P1 drop service.
+ *
+ * - The ping engine polls its sources every minute (prep needs a minute's grain for its 15-minute window).
+ * - The reminder tick runs every 30 seconds.
+ * - The resolution poll reads the board, the Work journal and the thread cache every 2 minutes; the server's own card
+ *   writes and session turn ends call in at once (`onCardWrite`, `onSessionTurn`).
+ * - Banners go to an outbox Control reads (`banners(after)`), each once per boot cursor; a reminder banner also goes to
+ *   the lens as a `cos_ping` display event.
+ *
+ * Every reader is injected, so a test runs it on fixtures and a fake clock, and a reader that throws only quiets its
+ * source for that tick. Each loop is single flight: a slow board read never stacks a second one. Timers never hold the
+ * process open. Logs are counts only.
+ */
+import { existsSync, lstatSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { randomBytes } from 'node:crypto'
+import type { DropRecord, InboxFeedStore } from './drop-store.js'
+import { PingEngine, type PingBanner, type PingSnapshot, type PingStateStore } from './ping-engine.js'
+import { DEFAULT_BANNER_SOURCES, type PingSource } from './ping-budget.js'
+import { P2_FOLLOWUP_KINDS, timeMinutes, type P2Settings } from './drop-p2-settings.js'
+import type { IntakeRow, ThreadRow, SignalRow, PingCandidate } from './ping-sources.js'
+import { feedSink } from './ping-feed-sink.js'
+import { createReminderScheduler, pendingReminders, applyReminderAction, type ReminderAction, type ReminderStore } from './reminder-scheduler.js'
+import { cardWriteResolutions, pollResolutions, RESOLUTION_POLL_MS, sessionTurnResolutions, type CardSnapshot, type HandoffSnapshot, type SessionState, type ThreadSnapshot } from './drop-resolution.js'
+
+export const P2_TIMING = { pingTickMs: 60_000, reminderTickMs: 30_000, resolutionPollMs: RESOLUTION_POLL_MS, outbox: 50, kickDelayMs: 3_000 } as const
+/** The COS caches are a few hundred KB; anything far larger is not the cache this reads. */
+const CACHE_MAX_BYTES = 8 * 1024 * 1024
+
+export interface BoardRowLite { id: string; domain: string; workIdentity?: string; workStage?: string; checked?: boolean }
+export interface JournalReceiptLite { id: string; workID?: string | null; status: string; result?: string | null }
+
+export interface DropP2Deps {
+  drops: ReminderStore & { list(): DropRecord[] }
+  feed: Pick<InboxFeedStore, 'byKey' | 'insert'>
+  pingState: Pick<PingStateStore, 'read' | 'write'>
+  timezone: () => string
+  now?: () => number
+  /** The next calendar event; undefined when the calendar could not be read. */
+  nextEvent?: () => Promise<{ title?: unknown; time?: unknown } | null | undefined>
+  /** Open Work intake items; undefined when the store is not available. */
+  intakeOpen?: () => IntakeRow[] | undefined
+  /** operations/scripts, for the thread and signal caches (read only; no script is run). */
+  scriptsDir?: string | null
+  /** The board; throwing means it could not be read, and the poll infers nothing from it. */
+  board?: () => Promise<BoardRowLite[]>
+  /** Work journal receipts; undefined when the journal is not available. */
+  journal?: () => JournalReceiptLite[] | undefined
+  /** Publishes a lens event (display bus). */
+  emitLens?: (event: { type: 'cos_ping'; data: Record<string, unknown> }) => void
+  enabled?: () => readonly PingSource[]
+  bootId?: string
+  /** True while the server drains for an update or restart: every loop skips its turn (a reminder fires next tick, late). */
+  paused?: () => boolean
+  /** 6.99.11 settings (drop-p2-settings.ts). Absent: the defaults, exactly as before. */
+  settings?: () => P2Settings
+}
+
+/** Follow-ups allowed by the settings: the switch, then the kind (the link kind in the key `dropId:kind:id:state`). */
+export function followUpAllowed(c: PingCandidate, s: P2Settings | null): boolean {
+  if (!s) return true
+  if (!s.followUps.on) return false
+  const kind = c.key.split(':')[1] as (typeof P2_FOLLOWUP_KINDS)[number]
+  return (P2_FOLLOWUP_KINDS as readonly string[]).includes(kind) ? s.followUps.kinds[kind] : true
+}
+
+export interface OutboxBanner extends PingBanner { seq: number; at: string }
+
+/** The journal's validated raw receipts (work-activity readWorkJournal) as the few fields the poll reads. */
+export function journalReceiptsLite(records: ReadonlyArray<Record<string, unknown>>): JournalReceiptLite[] {
+  const out: JournalReceiptLite[] = []
+  for (const r of records) {
+    if (typeof r?.id !== 'string' || typeof r.status !== 'string') continue
+    out.push({ id: r.id, status: r.status, workID: typeof r.workID === 'string' ? r.workID : null, result: typeof r.result === 'string' ? r.result : null })
+  }
+  return out
+}
+
+/** Read one array out of a COS cache file, or undefined when the file is missing, unsafe, too large or unreadable. */
+export function readCacheArray(dir: string | null | undefined, file: string, key: string): unknown[] | undefined {
+  if (!dir) return undefined
+  const path = join(dir, file)
+  try {
+    if (!existsSync(path)) return undefined
+    const st = lstatSync(path)
+    if (!st.isFile() || st.isSymbolicLink() || st.size > CACHE_MAX_BYTES) return undefined
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>
+    const list = parsed?.[key]
+    return Array.isArray(list) ? list : undefined
+  } catch { return undefined }
+}
+
+export function createDropP2Runtime(deps: DropP2Deps) {
+  const now = deps.now ?? (() => Date.now())
+  const bootId = deps.bootId ?? randomBytes(8).toString('hex')
+  const outbox: OutboxBanner[] = []
+  let seq = 0
+
+  const settingsNow = (): P2Settings | null => { try { return deps.settings?.() ?? null } catch { return null } }
+  const followUps = (list: PingCandidate[]) => { const s = settingsNow(); return list.filter(c => followUpAllowed(c, s)) }
+  const banner = (b: PingBanner) => {
+    outbox.push({ ...b, seq: ++seq, at: new Date(now()).toISOString() })
+    if (outbox.length > P2_TIMING.outbox) outbox.shift()
+    if (b.exempt && b.sources.includes('reminder') && (settingsNow()?.reminders.lensPush ?? true)) {
+      try { deps.emitLens?.({ type: 'cos_ping', data: { title: b.title, line: b.line, feedIds: b.feedIds, ...(b.notifyId ? { notifyId: b.notifyId } : {}) } }) }
+      catch { /* the lens is a second screen: the chat and the Mac banner already have it */ }
+    }
+  }
+
+  const threadsNow = () => readCacheArray(deps.scriptsDir, '.threads_cache.json', 'threads') as ThreadRow[] | undefined
+  const signalsNow = () => readCacheArray(deps.scriptsDir, '.signals_cache.json', 'signals') as SignalRow[] | undefined
+
+  const engine = new PingEngine({
+    state: deps.pingState,
+    feed: feedSink(deps.feed, now),
+    banner,
+    now,
+    timezone: deps.timezone,
+    enabled: deps.enabled ?? (() => DEFAULT_BANNER_SOURCES),
+    ...(deps.settings ? { settings: deps.settings } : {}),
+    read: async (): Promise<PingSnapshot> => {
+      const snap: PingSnapshot = {}
+      try { const e = await deps.nextEvent?.(); if (e !== undefined) snap.nextEvent = e } catch { /* calendar unread */ }
+      try { const i = deps.intakeOpen?.(); if (i !== undefined) snap.intakeOpen = i } catch { /* intake unread */ }
+      const threads = threadsNow(), signals = signalsNow()
+      // Each cache on its own: a missing signals cache must not quiet stale threads. The engine counts the stale source
+      // as read (and so may expire a held item) only when both were read.
+      if (threads !== undefined) snap.threads = threads
+      if (signals !== undefined) snap.signals = signals
+      return snap
+    },
+  })
+
+  const isPaused = () => { try { return deps.paused?.() === true } catch { return true } }
+  const reminderStore = {
+    // While paused, the scheduler sees nothing due, so nothing is written during a drain.
+    select: (m: Parameters<typeof deps.drops.select>[0]) => isPaused() ? [] : deps.drops.select(m),
+    update: deps.drops.update.bind(deps.drops),
+  }
+  const reminders = createReminderScheduler({ store: reminderStore, deliver: c => engine.push(c), now, intervalMs: P2_TIMING.reminderTickMs,
+    snoozeMinutes: () => settingsNow()?.reminders.snoozeMinutes ?? 60 })
+
+  async function resolutionSnapshot() {
+    const snap: { cards?: Map<string, CardSnapshot>; handoffs?: Map<string, HandoffSnapshot[]>; threads?: Map<string, ThreadSnapshot> } = {}
+    try {
+      const rows = await deps.board?.()
+      if (rows) snap.cards = new Map(rows.map(r => [`${r.domain}:${r.workIdentity ?? r.id}`, { workStage: r.workStage, checked: r.checked }]))
+    } catch { /* board unread: nothing is inferred from it */ }
+    try {
+      const receipts = deps.journal?.()
+      if (receipts) {
+        snap.handoffs = new Map()
+        for (const r of receipts) {
+          const m = typeof r.workID === 'string' ? /^task:([^:]+):(.+)$/.exec(r.workID) : null
+          if (!m) continue
+          const key = `${m[1]}:${m[2]}`
+          snap.handoffs.set(key, [...(snap.handoffs.get(key) ?? []), { id: r.id, status: r.status, result: r.result ?? null }])
+        }
+      }
+    } catch { /* journal unread */ }
+    const threads = threadsNow()
+    if (threads) snap.threads = new Map(threads.filter(t => typeof t?.id === 'string').map(t => [t.id as string, { is_resolved: t.is_resolved === true, is_stale: t.is_stale === true }]))
+    return snap
+  }
+
+  let polling = false, ticking = false
+  async function pollOnce(): Promise<number> {
+    if (polling || isPaused()) return 0
+    polling = true
+    try {
+      const drops = deps.drops.list()
+      if (!drops.length) return 0
+      const found = followUps(pollResolutions(drops, await resolutionSnapshot(), now()))
+      return found.length ? engine.push(found).posted : 0
+    } catch { return 0 } finally { polling = false }
+  }
+  async function pingOnce() {
+    if (ticking || isPaused()) return
+    ticking = true
+    try { await engine.tick() } catch { /* never throws by contract; belt and braces */ } finally { ticking = false }
+  }
+
+  const timers: Array<ReturnType<typeof setInterval>> = []
+  let kickTimer: ReturnType<typeof setTimeout> | null = null
+  return {
+    bootId,
+    engine,
+    start() {
+      if (timers.length) return
+      reminders.start()
+      void pingOnce(); void pollOnce()
+      for (const [fn, ms] of [[pingOnce, P2_TIMING.pingTickMs], [pollOnce, P2_TIMING.resolutionPollMs]] as const) {
+        const t = setInterval(() => { void fn() }, ms); t.unref?.(); timers.push(t)
+      }
+    },
+    stop() { reminders.stop(); for (const t of timers.splice(0)) clearInterval(t); if (kickTimer) clearTimeout(kickTimer); kickTimer = null },
+    /**
+     * A card was written through this server (work-board, tasks): poll the board shortly, instead of within 2 minutes.
+     * Several writes in a row make one poll. The write invalidated the shared board reader, so the poll sees it.
+     */
+    kickPoll() {
+      if (kickTimer) return
+      kickTimer = setTimeout(() => { kickTimer = null; void pollOnce() }, P2_TIMING.kickDelayMs)
+      kickTimer.unref?.()
+    },
+    tickReminders: () => reminders.tick(),
+    pingOnce,
+    pollOnce,
+    /** The server's own card write (work-board, tasks routes): the same rule as the poll, at once. */
+    onCardWrite(domain: string, workIdentity: string, row: CardSnapshot | null) {
+      try { const c = followUps(cardWriteResolutions(deps.drops.list(), domain, workIdentity, row, now())); if (c.length) engine.push(c) } catch { /* the poll will see it */ }
+    },
+    onSessionTurn(sessionId: string, outcome: SessionState, endedAtMs?: number) {
+      // Every session's every Stop lands here: copy only the drops held for a session and already sent.
+      try {
+        const held = deps.drops.select(d => d.state !== 'undone' && d.dest === 'session' && !!d.hold?.sentAt)
+        if (!held.length) return
+        const c = followUps(sessionTurnResolutions(held, sessionId, outcome, now(), endedAtMs ?? now()))
+        if (c.length) engine.push(c)
+      } catch { /* nothing else watches a held session; it stays open in History */ }
+    },
+    pushAgent: (ev: Parameters<PingEngine['pushAgent']>[0]) => engine.pushAgent(ev),
+    push: (c: PingCandidate[]) => engine.push(c),
+    /** Banners since a cursor. A cursor from another boot starts over from what this boot holds. */
+    banners(after: { bootId?: string; seq?: number } = {}): { bootId: string; seq: number; banners: OutboxBanner[] } {
+      const from = after.bootId === bootId && Number.isSafeInteger(after.seq) ? after.seq! : 0
+      return { bootId, seq, banners: outbox.filter(b => b.seq > from) }
+    },
+    pendingReminders: () => pendingReminders(deps.drops),
+    reminderAction: (dropId: string, action: ReminderAction) => {
+      const s = settingsNow()
+      return applyReminderAction(deps.drops, dropId, action, now(), s ? { snoozeMs: s.reminders.snoozeMinutes * 60_000, dayMinutes: timeMinutes(s.reminders.defaultTime) } : undefined)
+    },
+  }
+}
+export type DropP2Runtime = ReturnType<typeof createDropP2Runtime>