@gotcos/glasses-server 6.99.16 → 6.99.20

package/server/lib/prep-store.ts

@@ -0,0 +1,226 @@
+/**
+ * Prep v1.1 (6.99.19): the durable Prep store at dataPath('prep').
+ *
+ *   drafts/<draftId>.json            one PrepDraft, written whole (fsync + rename, mode 0600)
+ *   files/<draftId>/<fileId>.bin     the original bytes, copied out of /api/media at add time (the media stage expires in 4 h)
+ *   files/<draftId>/<fileId>.txt     the extracted text a run and a bind read (ready files only)
+ *   runs/<draftId>/<clientRequestId>.txt   a run's exact prompt, saved before the job is submitted
+ *   binds/<draftId>/<sessionId>/<revision>.json   the exact Meeting Ask rows a bind attaches, saved before its intent
+ *
+ * Drafts are read back from disk on first use, so a restarted server (a fresh instance) serves the same drafts. Writes
+ * are synchronous inside one server process; prep-runtime.ts serializes each draft's read-modify-write. Nothing is
+ * auto-deleted in v1. A draft file that cannot be read is skipped and logged, never deleted.
+ */
+import { createHash } from 'node:crypto'
+import { lstatSync, mkdirSync, readFileSync, readdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
+import { ASK_SESSION } from './ask-session-id.js'
+import { PREP_DRAFT_ID, PREP_FILE_ID, PREP_PROVIDERS, PREP_UUID_V4, type PrepDraft, type PrepOccurrence } from '../../shared/prep.js'
+
+export class PrepError extends Error {
+  constructor(readonly code: string, readonly status = 400, readonly draft?: PrepDraft, readonly extra: Record<string, unknown> = {}) {
+    super(code)
+    this.name = 'PrepError'
+  }
+}
+
+/**
+ * v1.1 #16: "occ:v2:" + sha256("occ:v2:" + provider|account|calendarId|eventId or ""|externalId or ""|startsAt exact
+ * UTC ISO). Every part, no quantization, so distinct occurrences never coalesce. Finds a draft; never binds one.
+ */
+export function prepOccurrenceKey(o: Pick<PrepOccurrence, 'provider' | 'account' | 'calendarId' | 'eventId' | 'externalId' | 'startsAt'>): string {
+  const text = 'occ:v2:' + [o.provider, o.account ?? '', o.calendarId, o.eventId ?? '', o.externalId ?? '', new Date(Date.parse(o.startsAt)).toISOString()].join('|')
+  return 'occ:v2:' + createHash('sha256').update(text).digest('hex')
+}
+
+/**
+ * The provider identity, or null. All of provider, calendarId, eventId or externalId, and startsAt must be present
+ * (account is optional and part of the key); anything less is no identity at all, never a guess from title or time.
+ * A client-sent `key` is ignored and recomputed. A non-object is a 400.
+ */
+export function parsePrepOccurrence(raw: unknown): PrepOccurrence | null {
+  if (raw === null) return null
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new PrepError('invalid_occurrence')
+  const o = raw as Record<string, unknown>
+  const id = (v: unknown) => typeof v === 'string' && v.trim() && v.length <= 512 ? v : null
+  const iso = (v: unknown) => typeof v === 'string' && v.length <= 64 && Number.isFinite(Date.parse(v)) ? new Date(Date.parse(v)).toISOString() : null
+  const provider = PREP_PROVIDERS.includes(o.provider as never) ? o.provider as PrepOccurrence['provider'] : null
+  const account = id(o.account), calendarId = id(o.calendarId), eventId = id(o.eventId), externalId = id(o.externalId)
+  const startsAt = iso(o.startsAt)
+  if (!provider || !calendarId || (!eventId && !externalId) || !startsAt) return null
+  const base = { provider, account, calendarId, eventId, externalId, startsAt }
+  return { key: prepOccurrenceKey(base), ...base, endsAt: iso(o.endsAt) }
+}
+
+/** The loader skips a draft file larger than this; writes stop well short of it. */
+export const DRAFT_LOAD_BYTES = 5_000_000
+export const DRAFT_WRITE_BYTES = 4_000_000
+
+export class PrepStore {
+  readonly root: string
+  private cache: Map<string, PrepDraft> | null = null
+
+  constructor(root = dataPath('prep')) { this.root = resolve(root) }
+
+  private dir(...parts: string[]): string {
+    mkdirSync(this.root, { recursive: true, mode: 0o700 })
+    if (lstatSync(this.root).isSymbolicLink()) throw new PrepError('prep_store_unsafe', 503)
+    let p = this.root
+    for (const part of parts) {
+      p = join(p, part)
+      mkdirSync(p, { recursive: true, mode: 0o700 })
+      if (lstatSync(p).isSymbolicLink()) throw new PrepError('prep_store_unsafe', 503)
+    }
+    return p
+  }
+
+  private load(): Map<string, PrepDraft> {
+    if (this.cache) return this.cache
+    const drafts = new Map<string, PrepDraft>()
+    const dir = this.dir('drafts')
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith('.json')) continue
+      const id = name.slice(0, -5)
+      try {
+        const path = join(dir, name), st = lstatSync(path)
+        if (!PREP_DRAFT_ID.test(id) || !st.isFile() || st.size > DRAFT_LOAD_BYTES) throw new Error('unsafe')
+        const draft = JSON.parse(readFileSync(path, 'utf8')) as PrepDraft
+        if (draft?.id !== id || !Number.isSafeInteger(draft.revision) || !Array.isArray(draft.files)) throw new Error('shape')
+        draft.snapshots ??= []
+        draft.fileOperations ??= []
+        drafts.set(id, draft)
+      } catch {
+        // Kept on disk for a person to look at; it simply is not served.
+        console.warn(`[prep] skipped an unreadable draft file (${id.slice(0, 12)})`)
+      }
+    }
+    this.cache = drafts
+    return drafts
+  }
+
+  get(id: string): PrepDraft | undefined {
+    if (!PREP_DRAFT_ID.test(id)) return undefined
+    const d = this.load().get(id)
+    return d ? structuredClone(d) : undefined
+  }
+
+  list(): PrepDraft[] { return [...this.load().values()].map(d => structuredClone(d)) }
+
+  byClientDraftId(clientDraftId: string): PrepDraft | undefined {
+    for (const d of this.load().values()) if (d.clientDraftId === clientDraftId) return structuredClone(d)
+    return undefined
+  }
+
+  write(draft: PrepDraft): PrepDraft {
+    if (!PREP_DRAFT_ID.test(draft.id)) throw new PrepError('invalid_draft_id')
+    const encoded = JSON.stringify(draft)
+    // Never write a draft the loader would refuse: it would vanish on the next restart.
+    if (Buffer.byteLength(encoded, 'utf8') > DRAFT_WRITE_BYTES) throw new PrepError('prep_draft_too_large', 507)
+    try {
+      durableAtomicWriteFileSync(join(this.dir('drafts'), draft.id + '.json'), encoded, { mode: 0o600 })
+    } catch (e) {
+      if (e instanceof PrepError) throw e
+      throw new PrepError('prep_write_failed', 507)
+    }
+    this.load().set(draft.id, structuredClone(draft))
+    return structuredClone(draft)
+  }
+
+  private blobPath(draftId: string, fileId: string, ext: 'bin' | 'txt'): string {
+    if (!PREP_DRAFT_ID.test(draftId) || !PREP_FILE_ID.test(fileId)) throw new PrepError('invalid_file_id')
+    return join(this.dir('files', draftId), `${fileId}.${ext}`)
+  }
+
+  putOriginal(draftId: string, fileId: string, bytes: Buffer): void {
+    try { durableAtomicWriteFileSync(this.blobPath(draftId, fileId, 'bin'), bytes, { mode: 0o600 }) } catch (e) {
+      if (e instanceof PrepError) throw e
+      throw new PrepError('prep_write_failed', 507)
+    }
+  }
+
+  putText(draftId: string, fileId: string, text: string): void {
+    try { durableAtomicWriteFileSync(this.blobPath(draftId, fileId, 'txt'), text, { mode: 0o600 }) } catch (e) {
+      if (e instanceof PrepError) throw e
+      throw new PrepError('prep_write_failed', 507)
+    }
+  }
+
+  readOriginal(draftId: string, fileId: string): Buffer {
+    try { return readFileSync(this.blobPath(draftId, fileId, 'bin')) } catch (e) {
+      if (e instanceof PrepError) throw e
+      throw new PrepError('file_not_found', 404)
+    }
+  }
+
+  /** The stored text, or '' when the file has none (not ready, or never extracted). */
+  readText(draftId: string, fileId: string): string {
+    try { return readFileSync(this.blobPath(draftId, fileId, 'txt'), 'utf8') } catch (e) {
+      if (e instanceof PrepError) throw e
+      return ''
+    }
+  }
+
+  /** The exact prompt of a run, saved before its job is submitted so a retry after a crash resubmits the same bytes. */
+  putPrompt(draftId: string, clientRequestId: string, prompt: string): void {
+    try { durableAtomicWriteFileSync(this.promptPath(draftId, clientRequestId), prompt, { mode: 0o600 }) } catch (e) {
+      if (e instanceof PrepError) throw e
+      throw new PrepError('prep_write_failed', 507)
+    }
+  }
+
+  readPrompt(draftId: string, clientRequestId: string): string | null {
+    try { return readFileSync(this.promptPath(draftId, clientRequestId), 'utf8') } catch (e) {
+      if (e instanceof PrepError) throw e
+      return null
+    }
+  }
+
+  private promptPath(draftId: string, clientRequestId: string): string {
+    if (!PREP_DRAFT_ID.test(draftId) || !PREP_UUID_V4.test(clientRequestId)) throw new PrepError('invalid_client_request_id')
+    return join(this.dir('runs', draftId), `${clientRequestId}.txt`)
+  }
+
+  /**
+   * The exact Meeting Ask rows one bind attaches, saved before the binding intent, so a retry after a crash re-applies
+   * the frozen revision rather than whatever the draft holds by then.
+   */
+  putBindPayload(draftId: string, sessionId: string, revision: number, rows: unknown[]): void {
+    try { durableAtomicWriteFileSync(this.bindPath(draftId, sessionId, revision), JSON.stringify(rows), { mode: 0o600 }) } catch (e) {
+      if (e instanceof PrepError) throw e
+      throw new PrepError('prep_write_failed', 507)
+    }
+  }
+
+  readBindPayload(draftId: string, sessionId: string, revision: number): unknown[] | null {
+    try {
+      const rows = JSON.parse(readFileSync(this.bindPath(draftId, sessionId, revision), 'utf8'))
+      return Array.isArray(rows) ? rows : null
+    } catch (e) {
+      if (e instanceof PrepError) throw e
+      return null
+    }
+  }
+
+  /** Keyed by (draft, meeting, revision): a replay of one bind can never read another bind's rows. */
+  private bindPath(draftId: string, sessionId: string, revision: number): string {
+    if (!PREP_DRAFT_ID.test(draftId) || !ASK_SESSION.test(sessionId) || !Number.isSafeInteger(revision) || revision < 0) throw new PrepError('invalid_session_id')
+    return join(this.dir('binds', draftId, sessionId), `${revision}.json`)
+  }
+
+  /** Bytes on disk under the store root (drafts, originals, text). Walked on each add: at most 300 drafts x 10 files. */
+  usageBytes(): number {
+    let total = 0
+    const walk = (p: string) => {
+      for (const name of readdirSync(p)) {
+        const child = join(p, name), st = lstatSync(child)
+        if (st.isSymbolicLink()) continue
+        if (st.isDirectory()) walk(child)
+        else if (st.isFile()) total += st.size
+      }
+    }
+    walk(this.dir())
+    return total
+  }
+}

package/server/lib/stt-resolver.ts

@@ -17,6 +17,13 @@
 //      holds a profile vocabulary term the primary's side does not, the second
 //      opinion's words are taken.
 //
+// A third caller (6.99.18) is the saved iPhone transcript, where the second
+// side is the live Whisper words the phone already heard with the vocabulary
+// prompt. Those words have approximate clocks and a prompted Whisper can echo a
+// vocabulary term into a pause, so that caller sets anchoredVocabularyOnly: a
+// term is taken only where the primary heard other words in the same place,
+// and the taken words are clocked across the primary words they replace.
+//
 // Everything else stays as the primary heard it. No region whose two sides
 // differ in a negation, a number or a unit is ever changed, whatever its length
 // (the 2026-10-13 diagnostic saw "born lacking" become "born having" and
@@ -37,7 +44,7 @@ export interface Hypothesis {
 }
 
 export type DisagreementKind = 'substitution' | 'primary_only' | 'second_only'
-export type ResolutionReason = 'gap_fill' | 'vocabulary' | 'protected' | 'not_speech' | 'low_confidence' | 'too_wide' | null
+export type ResolutionReason = 'gap_fill' | 'vocabulary' | 'protected' | 'not_speech' | 'low_confidence' | 'too_wide' | 'unanchored' | null
 
 export interface Disagreement {
   kind: DisagreementKind
@@ -66,6 +73,10 @@ export interface ResolveOptions {
    *  10 s) made the resolver worse than plain text alignment, because Large-v3's
    *  remapped token clocks have a heavy tail (median skew 0.23 s, p90 1.0 s). */
   maxSkewSec?: number | null
+  /** The second side's clocks are approximate (live words). A vocabulary term is
+   *  taken only from a substitution, never an insertion the primary has nothing
+   *  for, and the taken words are clocked across the primary words they replace. */
+  anchoredVocabularyOnly?: boolean
 }
 
 export interface ResolveResult {
@@ -241,6 +252,15 @@ function gapVerdict(q: Token[], options: ResolveOptions): ResolutionReason {
   return 'gap_fill'
 }
 
+/** The second side's words spread evenly over the time the replaced primary words took. */
+function reclock(q: Token[], p: Token[]): Token[] {
+  const { start, end } = span(p)
+  if (start === null) return q.map(t => ({ ...t, start: null, end: null }))
+  const stop = Math.max(start, end ?? start)
+  const step = (stop - start) / q.length
+  return q.map((t, i) => ({ ...t, start: start + i * step, end: start + (i + 1) * step }))
+}
+
 export function resolveHypotheses(primary: Hypothesis, second: Hypothesis, options: ResolveOptions): ResolveResult {
   const P = tokens(primary), Q = tokens(second)
   const toWords = (ts: Token[]): HypWord[] => ts.map(t => ({
@@ -290,6 +310,7 @@ export function resolveHypotheses(primary: Hypothesis, second: Hypothesis, optio
       const wantVocab = newTerms.length > 0
       if (wantGap || wantVocab) {
         if (!sameProtected(p, q)) reason = 'protected'
+        else if (wantVocab && options.anchoredVocabularyOnly && !p.length) reason = 'unanchored'
         else if (wantVocab && (q.length > MAX_VOCAB_REGION_WORDS || p.length > q.length + MAX_VOCAB_REGION_SLACK)) {
           // A term inside a long disagreement is not a reason to swap the whole region.
           reason = wantGap ? gapVerdict(q, options) : 'too_wide'
@@ -308,7 +329,10 @@ export function resolveHypotheses(primary: Hypothesis, second: Hypothesis, optio
       taken: options.apply ? take : 'primary',
       reason,
     })
-    if (options.apply && take === 'second') { out.push(...q); wordsFromSecond += q.length }
+    if (options.apply && take === 'second') {
+      out.push(...(options.anchoredVocabularyOnly ? reclock(q, p) : q))
+      wordsFromSecond += q.length
+    }
     else out.push(...p)
   }
   return {

package/server/lib/transcript-cleanup.ts

@@ -28,6 +28,7 @@
 
 import { existsSync, mkdirSync, appendFileSync, readFileSync, renameSync, statSync } from 'node:fs'
 import { dirname } from 'node:path'
+import { isPrepCopyId } from '../../shared/prep.js'
 import { LensGistLimitError, runLensGistEngine } from './lens-gist-engines.js'
 import { resolveProviderBinary } from './provider-binary.js'
 import { getVocabulary, getWhisperCorrections } from './profile.js'
@@ -167,11 +168,19 @@ const notesSearchDefault: CleanupDeps['searchNotes'] = async (queries, sessionId
   })(queries, sessionId, signal)
 }
 
+/**
+ * The meeting files whose words may steer saved-transcript cleanup. Pasted text and read pages (paste_, web_) are
+ * article words, not the room's vocabulary, and so are Prep copies (prep_prep_..., 6.99.19): notes and documents
+ * written before the call. None of them may rewrite the saved transcript.
+ */
+export function cleanupVocabularyFiles(files: ReadonlyArray<{ id: string; name: string; status: string; text: string }>, isPastedFileId: (id: string) => boolean): CleanupFile[] {
+  return files.filter(f => !isPastedFileId(f.id) && !isPrepCopyId(f.id) && f.status === 'ready' && typeof f.text === 'string' && f.text.trim()).map(f => ({ name: f.name, text: f.text }))
+}
+
 const filesDefault: CleanupDeps['files'] = async sessionId => {
   try {
     const { MeetingAskStore, isPastedFileId } = await import('./meeting-ask-store.js')
-    // Pasted text and read pages (paste_, web_) are article words, not the room's vocabulary: they must not rewrite the saved transcript.
-    return new MeetingAskStore().files(sessionId).filter(f => !isPastedFileId(f.id) && f.status === 'ready' && typeof f.text === 'string' && f.text.trim()).map(f => ({ name: f.name, text: f.text }))
+    return cleanupVocabularyFiles(new MeetingAskStore().files(sessionId), isPastedFileId)
   } catch { return [] }
 }
 

package/server/lib/work-orchestrator/runtime.ts

@@ -48,14 +48,20 @@ export const INPUT_SCAN_WAIT_MS = 20_000
 
 /** What one plan input reads. The server passes the process-wide stores; a test passes its own. */
 export interface OrchestratorParts { tags: TagIndex; usage: UsageMonitor; snapshot: () => ControlSnapshot | null }
+export interface OrchestratorInputOptions {
+  /** Read the existing usage view only, without starting provider usage subprocesses. Default retains Work's refresh. */
+  usageMode?: 'cached'
+}
 
-export async function orchestratorInputFor(workID: string, meetingWorkIDs: string[], parts?: OrchestratorParts): Promise<OrchestratorInput> {
+export async function orchestratorInputFor(workID: string, meetingWorkIDs: string[], parts?: OrchestratorParts,
+  options: OrchestratorInputOptions = {}): Promise<OrchestratorInput> {
   const tags = parts?.tags ?? orchestratorTagIndex()
   const monitor = parts?.usage ?? orchestratorUsage()
   const scan = tags.refresh().catch(() => null)
   const scanned = await Promise.race([scan, new Promise<null>(r => setTimeout(() => r(null), INPUT_SCAN_WAIT_MS).unref?.())])
   // On demand: the plan this input feeds may fork or start a session, so a reading older than 2 minutes is re-read.
-  const usageViews = await monitor.forPlan()
+  // Ask's proposal-only adapter uses cache-only evidence; it does not own the usage probes' child lifetimes.
+  const usageViews = options.usageMode === 'cached' ? monitor.views() : await monitor.forPlan()
   const roots = agentSessionRoots()
   return buildOrchestratorInput(workID, meetingWorkIDs, {
     snapshot: parts ? parts.snapshot() : orchestratorSnapshots().get(),

package/server/routes/ask-work-plan.ts

@@ -0,0 +1,114 @@
+/** Mounted under authenticated /api. Plan-only: never records a round, sends a handoff or writes a task. */
+import { Router } from 'express'
+import { ASK_WORK_PLAN_PROTOCOL, ASK_WORK_PLAN_BODY_BYTES, ASK_WORK_PLAN_DEADLINE_MS, ASK_WORK_PLAN_RULES,
+  AskWorkPlanError, parseAskWorkPlanRequest, resolveAskWorkTask, askWorkMeetingIDs, prepareAskWorkPlan, askWorkProposalID } from '../lib/ask-work-plan.js'
+import { listBoard, type TaskBoardRow } from '../lib/task-store.js'
+import { createWorkBoardReader } from '../lib/work-board-reader.js'
+import { orchestratorInputFor, type OrchestratorParts } from '../lib/work-orchestrator/runtime.js'
+import { runMeetingAskModel, AskProcessError } from '../lib/meeting-ask-runner.js'
+import { maintenanceAdmissionsOpen, acquireMaintenanceWork } from '../lib/maintenance-lifecycle.js'
+import { parseWorkChatAnswer, WORK_CHAT_SYSTEM, WORK_CHAT_ORCHESTRATOR_RULES, WORK_CHAT_PLANNERS, WORK_CHAT_EFFORTS,
+  WORK_CHAT_DEFAULT_EFFORT, WORK_CHAT_ORCHESTRATOR_OUTPUT_TOKENS, WORK_CHAT_THINKING_TOKENS,
+  WORK_CHAT_DEADLINE_MS, WORK_CHAT_MAX_ASSIGNMENTS } from '../lib/work-chat.js'
+
+export interface AskWorkPlanDeps {
+  board: () => Promise<TaskBoardRow[]>
+  input: typeof orchestratorInputFor
+  run: typeof runMeetingAskModel
+  admissions: () => boolean
+  lease: () => { release(): void }
+  now: () => number
+}
+/** Ask never launches usage probes; stale or unknown cached headroom disables targets in prepareAskWorkPlan. */
+export function readAskWorkPlanInput(workID: string, meetingWorkIDs: string[], parts?: OrchestratorParts) {
+  return orchestratorInputFor(workID, meetingWorkIDs, parts, { usageMode: 'cached' })
+}
+const defaults: AskWorkPlanDeps = {
+  // A new reader guarantees the post-plan revision check starts a new bounded board read.
+  board: () => createWorkBoardReader(() => listBoard()).read(0), input: readAskWorkPlanInput, run: runMeetingAskModel,
+  admissions: maintenanceAdmissionsOpen, lease: () => acquireMaintenanceWork('work_chat'), now: Date.now,
+}
+
+export function createAskWorkPlanRouter(given: Partial<AskWorkPlanDeps> = {}) {
+  const deps = { ...defaults, ...given }, router = Router()
+  let running = false
+  router.use('/ask/work-plan', (_req, res, next) => { res.set('Cache-Control', 'private, no-store'); next() })
+  router.get('/ask/work-plan', (_req, res) => res.json({ protocolVersion: ASK_WORK_PLAN_PROTOCOL, planOnly: true,
+    requiresExistingWork: true, dispatch: false, controlSnapshot: 1, planner: 'sonnet', planners: WORK_CHAT_PLANNERS,
+    effort: WORK_CHAT_DEFAULT_EFFORT, efforts: WORK_CHAT_EFFORTS, maxAssignments: WORK_CHAT_MAX_ASSIGNMENTS,
+    maxQuestionChars: 2000, maxBodyBytes: ASK_WORK_PLAN_BODY_BYTES }))
+  router.post('/ask/work-plan', async (req, res) => {
+    const fail = (error: unknown) => {
+      const known = error instanceof AskWorkPlanError
+      if (!res.destroyed) res.status(known ? error.status : 503).json({ error: known ? error.code : 'ask_work_plan_unavailable',
+        message: known && error.code === 'question_contains_sensitive_text'
+          ? 'Remove credentials from the question and try again.'
+          : 'No assignment was dispatched. Refresh the task and retry the plan.' })
+    }
+    let request
+    try { request = parseAskWorkPlanRequest(req.body) } catch (error) { fail(error); return }
+    if (!deps.admissions()) { fail(new AskWorkPlanError('maintenance', 503)); return }
+    if (running) { fail(new AskWorkPlanError('ask_work_plan_busy', 409)); return }
+    running = true
+    const controller = new AbortController(), abort = () => controller.abort()
+    const timer = setTimeout(abort, ASK_WORK_PLAN_DEADLINE_MS)
+    res.on('close', abort)
+    let lease: ReturnType<AskWorkPlanDeps['lease']> | undefined
+    let release = true
+    try {
+      lease = deps.lease()
+      let rows: TaskBoardRow[]
+      try { rows = await deps.board() }
+      catch { throw new AskWorkPlanError('work_board_unavailable', 503) }
+      if (controller.signal.aborted) throw new AskWorkPlanError('ask_work_plan_canceled', 408)
+      const task = resolveAskWorkTask(request, rows)
+      let evidence
+      // The default reads cached usage only. Still await the bounded evidence dependency before releasing admission.
+      try { evidence = await deps.input(request.workID, askWorkMeetingIDs(task)) }
+      catch { throw new AskWorkPlanError('orchestrator_input_unavailable', 503) }
+      if (controller.signal.aborted) throw new AskWorkPlanError('ask_work_plan_canceled', 408)
+      const prepared = prepareAskWorkPlan(request, task, evidence, deps.now())
+      if (controller.signal.aborted) throw new AskWorkPlanError('ask_work_plan_canceled', 408)
+      if (!deps.admissions()) throw new AskWorkPlanError('maintenance', 503)
+      const { planner = 'sonnet', effort = WORK_CHAT_DEFAULT_EFFORT, ...prompt } = prepared.input
+      // The runner settles only after termination proof (or explicit unconfirmed exit). Racing its
+      // promise with abort would release the lease and admit another provider during the kill wait.
+      const output = await deps.run({ engine: 'claude', model: planner }, JSON.stringify(prompt),
+        WORK_CHAT_SYSTEM + '\n\n' + WORK_CHAT_ORCHESTRATOR_RULES + '\n\n' + ASK_WORK_PLAN_RULES,
+        controller.signal, undefined, { caller: 'ask_work_plan' }, { effort, maxOutputTokens: WORK_CHAT_ORCHESTRATOR_OUTPUT_TOKENS,
+          maxThinkingTokens: WORK_CHAT_THINKING_TOKENS[effort], deadlineMs: WORK_CHAT_DEADLINE_MS })
+      if (controller.signal.aborted) throw new AskWorkPlanError('ask_work_plan_canceled', 408)
+      let answer
+      try { answer = parseWorkChatAnswer(output.text, prepared.input) }
+      catch { throw new AskWorkPlanError('invalid_plan_answer', 503) }
+      // A model may take minutes; never return an apparently current proposal for a changed/finished task.
+      try { rows = await deps.board() }
+      catch { throw new AskWorkPlanError('work_board_unavailable', 503) }
+      if (controller.signal.aborted) throw new AskWorkPlanError('ask_work_plan_canceled', 408)
+      const currentTask = resolveAskWorkTask(request, rows)
+      try { evidence = await deps.input(request.workID, askWorkMeetingIDs(currentTask)) }
+      catch { throw new AskWorkPlanError('orchestrator_input_unavailable', 503) }
+      if (controller.signal.aborted) throw new AskWorkPlanError('ask_work_plan_canceled', 408)
+      const current = prepareAskWorkPlan(request, currentTask, evidence, deps.now())
+      // Revalidate every proposed target against current discovery, live state and plan headroom.
+      try { answer = parseWorkChatAnswer(output.text, current.input) }
+      catch { throw new AskWorkPlanError('plan_targets_changed', 409) }
+      if (!res.destroyed) res.json({ protocolVersion: ASK_WORK_PLAN_PROTOCOL, planOnly: true, workID: request.workID,
+        revision: request.revision, title: prepared.title, ...answer, evidence: prepared.evidence, revalidatedEvidence: current.evidence,
+        proposalID: askWorkProposalID(prepared.input, answer), question: prepared.input.question, createdAt: new Date(deps.now()).toISOString(),
+        model: output.model ?? `claude:${planner} (requested)`, effort })
+    } catch (error) {
+      if (error instanceof AskProcessError && error.terminationUnconfirmed) {
+        // Match Meeting Ask's orphan policy: no second process or maintenance drain until recovery.
+        release = false
+        console.warn('[ask-work-plan] provider termination unconfirmed; admission and maintenance lease retained')
+        fail(new AskWorkPlanError('provider_termination_unconfirmed', 503))
+      } else fail(error)
+    }
+    finally {
+      clearTimeout(timer); res.off('close', abort)
+      if (release) { lease?.release(); running = false }
+    }
+  })
+  return router
+}

package/server/routes/health.ts

@@ -1,4 +1,5 @@
 import { dropItCapability } from '../lib/drop-settings.js'
+import { PREP_CAPABILITY } from '../../shared/prep.js'
 import { phoneMicrophoneMeetingsCapability } from '../lib/phone-recording.js'
 import { macLiveVoicesSnapshot } from '../lib/mac-window-replay.js'
 import { DICTATION_CLEAN_MODELS } from '../lib/dictation-clean-models.js'
@@ -465,6 +466,9 @@ healthRouter.get('/health', async (_req, res) => {
       providerObserveFields({ state: cachedHookStatus().state, ready: hookHaltReady(cachedHookStatus()) }),
     ),
     server_instance_id: getServerInstanceId(),
+    // 6.99.20: the same id in camelCase, the name COS Control 0.5.376's Prep discovery reads from /api/health
+    // (it refused Prep with "did not answer Prep discovery" when only server_instance_id was here). Additive.
+    serverInstanceId: getServerInstanceId(),
     boot_id: serverMetrics.bootId,
     generation_id: getServerGenerationId(),
     mediaLimits,
@@ -538,6 +542,8 @@ healthRouter.get('/health', async (_req, res) => {
       titleSteer: TITLE_STEER_CAPABILITY,
       // Drop it P1: the pinned COS chat (routes/drops.ts). Codes only; `enabled` is false unless turned on. Absent on an older server.
       dropIt: dropItCapability(),
+      // 6.99.19 Prep: notes and files before a call, kept in the meeting by an explicit bind (routes/prep.ts). Absent on an older server.
+      prep: { ...PREP_CAPABILITY, serverInstanceId: getServerInstanceId() },
       // 6.77.0: codes only (this route is public): the protocol and whether the switch is on.
       transcriptCleanup: transcriptCleanupAdvertised(),
       richMedia: {
@@ -752,6 +758,8 @@ healthRouter.get('/models', async (req, res) => {
       titleSteer: TITLE_STEER_CAPABILITY,
       // Drop it P1: the pinned COS chat (routes/drops.ts). Codes only; `enabled` is false unless turned on. Absent on an older server.
       dropIt: dropItCapability(),
+      // 6.99.19 Prep: notes and files before a call, kept in the meeting by an explicit bind (routes/prep.ts). Absent on an older server.
+      prep: { ...PREP_CAPABILITY, serverInstanceId: getServerInstanceId() },
       richMedia: {
         video: richMedia.video,
         maxPromptVisuals: MAX_MODEL_IMAGE_INPUTS,

package/server/routes/prep.ts

@@ -0,0 +1,81 @@
+/**
+ * Prep v1.1 routes (6.99.19). Mounted under /api, so the X-Cos-Token check in index.ts runs first. Every answer is
+ * Cache-Control: no-store and carries the top-level `serverInstanceId` (errors included; the original-bytes route
+ * sends it as the X-COS-Server-Instance header). Errors are `{ error: '<code>' }` like Meeting Ask; a revision conflict
+ * also carries `draft`, run_in_progress carries `run`, and file_context_limit carries needBytes and haveBytes.
+ * Every mutation requires X-COS-Expected-Server-Instance (v1.1 #19), checked before the runtime is called. The
+ * behaviour lives in lib/prep-runtime.ts; shared/prep.ts lists the routes and DTOs.
+ */
+import { Router, type Request, type Response } from 'express'
+import { PrepError } from '../lib/prep-store.js'
+import { wellFormed, type PrepRuntime } from '../lib/prep-runtime.js'
+
+export const EXPECTED_SERVER_HEADER = 'x-cos-expected-server-instance'
+
+/** An ASCII fallback name plus the RFC 5987 UTF-8 name: no quotes, slashes or control characters reach the header. */
+export function attachmentDisposition(name: string): string {
+  // By code point, without lone surrogates: encodeURIComponent throws URIError on half an emoji.
+  const whole = Array.from(wellFormed(name)).slice(0, 240).join('')
+  const ascii = whole.replace(/[^A-Za-z0-9._ -]/g, '_').replace(/^[ .]+/, '').slice(0, 120) || 'file'
+  return `attachment; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(whole)}`
+}
+
+export function createPrepRouter(runtime: PrepRuntime): Router {
+  const router = Router()
+  router.use('/prep', (_q, res, next) => { res.set('Cache-Control', 'no-store'); next() })
+
+  const serverInstanceId = () => { try { return runtime.serverInstanceId() } catch { return null } }
+  const send = (res: Response, status: number, body: Record<string, unknown>) => res.status(status).json({ ...body, serverInstanceId: serverInstanceId() })
+  const failure = (res: Response, error: unknown) => {
+    if (error instanceof PrepError) {
+      send(res, error.status, { error: error.code, ...error.extra, ...(error.draft ? { draft: error.draft } : {}) })
+      return
+    }
+    console.warn('[prep] request failed:', error instanceof Error ? error.message : 'unknown')
+    send(res, 503, { error: 'prep_unavailable' })
+  }
+  /** A mutation: the expected server is checked before the runtime runs anything. */
+  const write = (status: number, fn: (req: Request) => Promise<Record<string, unknown>>) => async (req: Request, res: Response) => {
+    try {
+      runtime.authorize(req.get(EXPECTED_SERVER_HEADER))
+      send(res, status, await fn(req))
+    } catch (e) { failure(res, e) }
+  }
+  const read = (fn: (req: Request) => Promise<Record<string, unknown>> | Record<string, unknown>) => async (req: Request, res: Response) => {
+    try { send(res, 200, await fn(req)) } catch (e) { failure(res, e) }
+  }
+
+  router.post('/prep/drafts', async (req, res) => {
+    try {
+      runtime.authorize(req.get(EXPECTED_SERVER_HEADER))
+      const { draft, created } = await runtime.create(req.body)
+      send(res, created ? 201 : 200, { draft })
+    } catch (e) { failure(res, e) }
+  })
+  router.get('/prep/drafts', read(req => ({ drafts: runtime.list({ occurrence: req.query.occurrence, state: req.query.state, limit: req.query.limit }) })))
+  router.get('/prep/drafts/:id', read(async req => ({ draft: await runtime.get(String(req.params.id)) })))
+  router.delete('/prep/drafts/:id', write(200, async req => ({ draft: await runtime.archive(String(req.params.id)) })))
+  router.patch('/prep/drafts/:id', write(200, async req => ({ draft: await runtime.patch(String(req.params.id), req.body) })))
+  router.post('/prep/drafts/:id/files', write(200, async req => ({ draft: await runtime.addFiles(String(req.params.id), req.body) })))
+  router.delete('/prep/drafts/:id/files/:fileId', write(200, async req => ({ draft: await runtime.removeFile(String(req.params.id), String(req.params.fileId), req.query.revision, req.query.serverInstanceId) })))
+  router.get('/prep/drafts/:id/files/:fileId', (req, res) => {
+    try {
+      const file = runtime.readOriginal(String(req.params.id), String(req.params.fileId))
+      res.set({ 'Content-Type': file.mime, 'Content-Disposition': attachmentDisposition(file.name), 'X-Content-Type-Options': 'nosniff', 'X-COS-Server-Instance': serverInstanceId() ?? '' })
+      res.send(file.bytes)
+    } catch (e) { failure(res, e) }
+  })
+  router.get('/prep/drafts/:id/files/:fileId/text', read(req => ({ text: runtime.readText(String(req.params.id), String(req.params.fileId)) })))
+  router.post('/prep/drafts/:id/run', write(202, async req => ({ ...await runtime.run(String(req.params.id), req.body) })))
+  router.get('/prep/drafts/:id/runs/:clientRequestId', async (req, res) => {
+    try {
+      const { status, run, job } = await runtime.getRun(String(req.params.id), String(req.params.clientRequestId))
+      send(res, status, status === 202 ? { run } : { run, job })
+    } catch (e) { failure(res, e) }
+  })
+  router.post('/prep/drafts/:id/bind', write(200, async req => ({ ...await runtime.bind(String(req.params.id), req.body) })))
+  router.delete('/prep/drafts/:id/bind/:sessionId', write(200, async req => ({ draft: await runtime.unbind(String(req.params.id), String(req.params.sessionId), req.query.serverInstanceId) })))
+  router.get('/prep/by-session/:sessionId', read(req => ({ snapshots: runtime.bySession(String(req.params.sessionId)) })))
+  router.get('/prep/suggest', read(req => ({ drafts: runtime.suggest({ sessionId: req.query.sessionId, startedAt: req.query.startedAt }) })))
+  return router
+}

package/server/routes/welcome-context.ts

@@ -4,6 +4,8 @@
 
 import { Router } from 'express'
 import { callPython, pythonBridgeAvailable } from '../lib/python-bridge.js'
+import { parsePrepOccurrence } from '../lib/prep-store.js'
+import type { PrepOccurrence } from '../../shared/prep.js'
 
 export const welcomeContextRouter = Router()
 
@@ -14,7 +16,29 @@ const CALENDAR_TTL_MS = 2 * 60_000
 const COORD_MOVE_DEG = 0.05 // ~5km
 
 type WeatherPayload = { temp: string; desc: string; location: string }
-type NextEventPayload = { title: string; time: string; inMinutes?: number }
+/**
+ * 6.99.19: `occurrence` (shared/prep.ts PrepOccurrence) is present ONLY when the bridge answers the event with a
+ * provider, calendar id, event id or external id, and start. The bridge sends no event ids today, so it is absent.
+ * It lets a client find a Prep draft for this exact event; it never binds one, and nothing is inferred from the title.
+ */
+type NextEventPayload = { title: string; time: string; inMinutes?: number; occurrence?: PrepOccurrence }
+
+/** The bridge event's provider identity, or undefined. snake_case (calendar_context.py) or camelCase is accepted. */
+export function bridgeOccurrence(evt: Record<string, unknown> | null | undefined): PrepOccurrence | undefined {
+  if (!evt || typeof evt !== 'object') return undefined
+  const pick = (...keys: string[]) => keys.map(k => evt[k]).find(v => v !== undefined && v !== null)
+  try {
+    return parsePrepOccurrence({
+      provider: pick('provider'),
+      account: pick('account', 'account_id', 'accountId') ?? null,
+      calendarId: pick('calendar_id', 'calendarId'),
+      eventId: pick('event_id', 'eventId') ?? null,
+      externalId: pick('external_id', 'externalId') ?? null,
+      startsAt: pick('start_time', 'start', 'startsAt'),
+      endsAt: pick('end_time', 'end', 'endsAt') ?? null,
+    }) ?? undefined
+  } catch { return undefined }
+}
 
 let cachedWeather: WeatherPayload | null = null
 let weatherFetchedAt = 0
@@ -327,16 +351,20 @@ export async function fetchNextEvent(): Promise<{ event: NextEventPayload | null
       const minsUntil = Number.isFinite(eventTime)
         ? Math.max(0, Math.round((eventTime - now) / 60_000))
         : undefined
+      const occurrence = bridgeOccurrence(meaningful as Record<string, unknown>)
       cachedNextEvent = {
         title: meaningful.title || 'Meeting',
         time: meaningful.start_time || meaningful.start || '',
         ...(minsUntil != null ? { inMinutes: minsUntil } : {}),
+        ...(occurrence ? { occurrence } : {}),
       }
     } else if (cal?.next_event && !isGenericNoiseEvent(cal.next_event.title || '')) {
+      const occurrence = bridgeOccurrence(cal.next_event as Record<string, unknown>)
       cachedNextEvent = {
         title: cal.next_event.title || 'Meeting',
         time: cal.next_event.start_time || '',
         ...(cal.minutes_until_next != null ? { inMinutes: cal.minutes_until_next } : {}),
+        ...(occurrence ? { occurrence } : {}),
       }
     } else {
       cachedNextEvent = null