@gotcos/glasses-server 6.27.2 → 6.27.3

package/.env.example

@@ -23,6 +23,13 @@ BIND_HOST=0.0.0.0
 # ~/.cos-glasses/data/media alongside the standalone conversation/archive data.
 # COS_MEDIA_ROOT=/path/on-a-local-volume/media
 
+# Private canary for server 6.27.3 + companion 6.8.343. When enabled, every
+# MP4/MOV uses a durable, resumable 256 KiB upload draft instead of one long
+# WebView request. Accepted chunks and finalize receipts survive server
+# restarts. Leave off for the released transport; COS Control 0.5.20 manages
+# this setting and prevents unsafe binary rollback while V2 state exists.
+# COS_VIDEO_UPLOAD_V2=0
+
 # Optional logical server identity location. Most installs should keep the
 # default (~/.cos-glasses/server-instance-id) so reconnects can verify the same
 # server after Wi-Fi/Tailscale changes and process restarts.

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## 6.27.3
+
+### Durable, resumable video transport (private canary)
+
+- Replaces fragile single-request phone video uploads with a generation-pinned,
+  resumable 256 KiB protocol whose accepted chunks survive server restarts.
+- Adds idempotent init/finalize receipts, explicit acknowledgement and cancel,
+  bounded draft retention, and maintenance status so updates cannot erase a
+  video draft that is still being transferred or whose receipt is not stored.
+- Keeps the published media record byte-compatible with 6.27.2: the original
+  MP4/MOV remains required and the existing validated ffprobe/ffmpeg path stays
+  the fallback. Phone frame extraction is separately gated until its physical
+  iPhone decoder/canvas acceptance test executes.
+- New V2 admission is disabled by default (`COS_VIDEO_UPLOAD_V2=0`). Existing
+  V2 drafts remain observable, cancellable, and finalizable after the flag is
+  turned off so rollback never strands accepted bytes.
+
 ## 6.27.2
 
 ### One finalizer for phone and Mac dictation

package/README.md

@@ -176,8 +176,12 @@ in the managed CLI working directory),
 `COS_WEATHER_DEFAULT_LAT` / `COS_WEATHER_DEFAULT_LON` /
 `COS_WEATHER_DEFAULT_CITY` (optional home fallback when phone GPS is denied),
 `COS_SCRIPTS_DIR` (full pipeline), `COS_DURABLE_QUERY_JOBS=0` (optional
-machine-wide rollback for build 204+ server-owned query recovery), and `COS_MEDIA_ROOT` (optional image-store
-location; default `~/.cos-glasses/data/media`). Your name + transcription vocabulary live in
+machine-wide rollback for build 204+ server-owned query recovery),
+`COS_MEDIA_ROOT` (optional image/video store location; default
+`~/.cos-glasses/data/media`), and `COS_VIDEO_UPLOAD_V2=1` (private 6.27.3+
+resumable-video canary, managed by COS Control 0.5.20). The V2 canary retains
+accepted 256 KiB chunks and finalize receipts across restarts; keep it off when
+using an older companion. Your name + transcription vocabulary live in
 `~/.cos-glasses/.cos-profile.json` (see `.cos-profile.example.json`).
 Factory example values are ignored; add the real names, companies, acronyms,
 and specialist terms you say often. Guided Setup writes a safe empty profile

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.27.2",
+  "version": "6.27.3",
   "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, or Cursor Agent CLI",
   "type": "module",
   "bin": {

package/server/index.ts

@@ -162,6 +162,20 @@ app.use('/api', requireApiToken(API_TOKEN))
 // through their true terminal boundary.
 app.use('/api', (req, res, next) => {
   if (req.method === 'GET' || req.method === 'HEAD' || req.method === 'OPTIONS') return next()
+  // V2 video chunks are bounded to 256 KiB and commit through the upload
+  // registry's own generation lock. Holding the global mutation lease while
+  // the phone transfers the body recreated the exact 90-second drain failure
+  // this protocol exists to remove. Admission is checked by the route before
+  // bytes are committed; in-flight bounded bodies finish or are discarded.
+  const videoUploadBody = req.method === 'PUT'
+    && /^\/media\/video-upload\/vu_[0-9a-f]{24}\/(?:original|frame)\/\d+$/.test(req.path)
+  // Finalize may run ffmpeg for a long clip. Its durable registry state is the
+  // restart/rollback gate, so holding the global request lease as well would
+  // recreate Control's 90-second drain timeout. The route performs its own
+  // fail-closed admission immediately before claiming `finalizing`.
+  const videoUploadFinalize = req.method === 'POST'
+    && /^\/media\/video-upload\/vu_[0-9a-f]{24}\/finalize$/.test(req.path)
+  if (videoUploadBody || videoUploadFinalize) return next()
   const lifecycleOwned = (req.path === '/query-jobs' && req.method === 'POST')
     || req.path === '/query'
     || req.path === '/diagnostics/provider-proof'
@@ -190,6 +204,14 @@ app.use('/api', (req, res, next) => {
       nonce: typeof req.headers['x-cos-maintenance-nonce'] === 'string'
         ? req.headers['x-cos-maintenance-nonce'] : undefined,
     })
+  // Cleanup and receipt acknowledgement only reduce rollback blockers. They
+  // remain available during a drain so Control is never forced to wait for a
+  // four-hour upload TTL after the phone already cancelled or persisted the
+  // terminal receipt.
+  const videoUploadCleanup = /^\/media\/video-upload\/vu_[0-9a-f]{24}$/.test(req.path)
+    && req.method === 'DELETE'
+    || /^\/media\/video-upload\/vu_[0-9a-f]{24}\/ack$/.test(req.path)
+      && req.method === 'POST'
 
   try {
     // KNOWN HAZARD, deliberately not fixed here (2026-08-11). This lease is held for
@@ -207,7 +229,7 @@ app.use('/api', (req, res, next) => {
     // of the network transfer, which means changing a fail-closed middleware that
     // guards every mutation. That needs its own pass and its own tests.
     const lease = acquireMaintenanceWork('api_mutation', {
-      allowDuringDrain: controllerProof,
+      allowDuringDrain: controllerProof || videoUploadCleanup,
     })
     let released = false
     const release = () => {

package/server/lib/media-store.ts

@@ -31,7 +31,7 @@ import {
   writeFileSync,
 } from 'node:fs'
 import { join, resolve, sep } from 'node:path'
-import { atomicWriteFileSync, loadJsonOrQuarantine } from './atomic-fs.js'
+import { atomicWriteFileSync, durableAtomicWriteFileSync, loadJsonOrQuarantine } from './atomic-fs.js'
 import { dataPath } from './data-dir.js'
 import {
   isValidMediaId,
@@ -183,6 +183,10 @@ export interface MediaRecord {
   updatedAtMs: number
   reservedAtMs?: number
   associatedAtMs?: number
+  /** Durable provenance for resumable video uploads. It is never exposed in
+   * the public attachment ref; it lets a lost finalize response or server
+   * restart rediscover the one record that upload already published. */
+  videoUploadId?: string
 }
 
 interface MediaIndexFile {
@@ -236,6 +240,10 @@ export interface IngestRichMediaFileInput {
    *  existing ceiling; chunked finalize passes 'chunked' so a multi-hundred-MB video
    *  is judged against the chunked cap instead of being refused AFTER transfer. */
   transfer?: MediaTransferMode
+  /** Preallocated by the durable video-upload manifest before publication. */
+  mediaId?: string
+  /** Private idempotency link used only by video-upload receipt recovery. */
+  videoUploadId?: string
 }
 
 /** Handle for a streaming upload's staging file. `dispose()` is idempotent and
@@ -313,6 +321,9 @@ function sanitizeRecord(raw: unknown): MediaRecord | null {
     updatedAtMs: typeof r.updatedAtMs === 'number' ? r.updatedAtMs : Date.now(),
     ...(typeof r.reservedAtMs === 'number' ? { reservedAtMs: r.reservedAtMs } : {}),
     ...(typeof r.associatedAtMs === 'number' ? { associatedAtMs: r.associatedAtMs } : {}),
+    ...(typeof r.videoUploadId === 'string' && /^vu_[0-9a-f]{24}$/.test(r.videoUploadId)
+      ? { videoUploadId: r.videoUploadId }
+      : {}),
   }
 }
 
@@ -468,15 +479,35 @@ export class MediaStore {
       rmSync(join(this.root, 'tmp'), { recursive: true, force: true })
       mkdirSync(join(this.root, 'tmp'), { recursive: true, mode: 0o700 })
     } catch { /* best effort */ }
+    let dirty = false
     if (this.allowOrphanCleanup) {
       try {
         for (const entry of readdirSync(join(this.root, 'assets'))) {
           try {
             if (!this.records.has(entry)) {
-              // Unpublished orphan — the upload died between rename and index
-              // publish. Remove; the client never received this id.
-              rmSync(join(this.root, 'assets', entry), { recursive: true, force: true })
-              console.warn(`[media-store] removed unpublished orphan asset ${entry}`)
+              const intentPath = join(this.root, 'assets', entry, 'publication-intent.json')
+              let recovered = false
+              if (existsSync(intentPath)) {
+                try {
+                  const candidate = sanitizeRecord(JSON.parse(readFileSync(intentPath, 'utf8')))
+                  if (candidate && candidate.ref.id === entry && candidate.videoUploadId
+                      && existsSync(this.absPath(candidate.storagePath))) {
+                    this.records.set(entry, candidate)
+                    dirty = true
+                    recovered = true
+                    console.warn(`[media-store] recovered resumable video publication ${entry}`)
+                  }
+                } catch {
+                  // An unreadable/inconsistent intent grants no publication.
+                  // The client can safely repeat finalize from its durable draft.
+                }
+              }
+              if (!recovered) {
+                // Unpublished orphan — the upload died between rename and index
+                // publish and supplied no valid durable publication intent.
+                rmSync(join(this.root, 'assets', entry), { recursive: true, force: true })
+                console.warn(`[media-store] removed unpublished orphan asset ${entry}`)
+              }
             }
           } catch { /* skip this asset */ }
         }
@@ -484,7 +515,6 @@ export class MediaStore {
     } else {
       console.warn('[media-store] preserving unindexed asset dirs for recovery this boot')
     }
-    let dirty = false
     for (const rec of this.records.values()) {
       try {
         if (!rec.contentRemoved && rec.lifecycle !== 'deleted' && rec.lifecycle !== 'expired' &&
@@ -497,7 +527,13 @@ export class MediaStore {
       } catch { /* skip */ }
     }
     if (dirty) {
-      try { this.saveIndex() } catch (err) { console.error('[media-store] reconcile save failed:', err) }
+      try {
+        this.saveIndex()
+        for (const rec of this.records.values()) {
+          if (!rec.videoUploadId) continue
+          try { rmSync(join(this.root, 'assets', rec.ref.id, 'publication-intent.json'), { force: true }) } catch { /* next boot */ }
+        }
+      } catch (err) { console.error('[media-store] reconcile save failed:', err) }
     }
   }
 
@@ -563,10 +599,23 @@ export class MediaStore {
   }
 
   private async publishPreparedRichMedia(
-    input: { label?: string; capturedAt?: string; sessionId?: string },
+    input: {
+      label?: string
+      capturedAt?: string
+      sessionId?: string
+      mediaId?: string
+      videoUploadId?: string
+    },
     prepared: PreparedRichMediaFile,
   ): Promise<MediaAttachmentRef> {
-    const id = `m_${randomBytes(12).toString('hex')}`
+    const id = input.mediaId && isValidMediaId(input.mediaId)
+      ? input.mediaId
+      : `m_${randomBytes(12).toString('hex')}`
+    const existing = this.getRecord(id)
+    if (existing) {
+      if (input.videoUploadId && existing.videoUploadId === input.videoUploadId) return existing.ref
+      throw new MediaStoreError('media_conflict', `attachment ${id} already exists`)
+    }
     const now = Date.now()
     const nowIso = new Date(now).toISOString()
     const extension = prepared.category === 'video'
@@ -631,13 +680,24 @@ export class MediaStore {
       sha256,
       lifecycle: 'staged',
       ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+      ...(input.videoUploadId ? { videoUploadId: input.videoUploadId } : {}),
       createdAtMs: now,
       updatedAtMs: now,
     }
+    // A crash can land after assets/<id> is renamed but before index.json is
+    // committed. Keep a private complete record beside the asset so boot
+    // reconciliation can finish that exact publication rather than deleting a
+    // valid video as an orphan. The public ref never exposes this file.
+    durableAtomicWriteFileSync(
+      join(this.root, 'assets', id, 'publication-intent.json'),
+      JSON.stringify(record),
+      { mode: 0o600 },
+    )
     await this.withLock(() => {
       this.records.set(id, record)
       this.saveIndex()
     })
+    try { rmSync(join(this.root, 'assets', id, 'publication-intent.json'), { force: true }) } catch { /* boot can clean it */ }
     // AFTER publication and outside the lock: x265 encodes at roughly real
     // time, so awaiting it here would hold the upload response open for the
     // length of the video.
@@ -814,6 +874,16 @@ export class MediaStore {
     return this.getRecord(id)?.ref ?? null
   }
 
+  /** Private receipt-recovery lookup. Upload ids are not capabilities and are
+   * never returned by ordinary media metadata routes. */
+  findByVideoUploadId(uploadId: string): MediaRecord | null {
+    if (!/^vu_[0-9a-f]{24}$/.test(uploadId)) return null
+    for (const record of this.records.values()) {
+      if (record.videoUploadId === uploadId) return record
+    }
+    return null
+  }
+
   /** Recover the public refs associated with one exact conversation turn.
    *
    * The media index is already the durable lifecycle authority for uploaded
@@ -1159,6 +1229,27 @@ export class MediaStore {
     })
   }
 
+  /** Resumable-upload cancel may release a just-published result, but it must
+   * never delete a reservation that a queued Ask already owns. */
+  deleteExactlyStaged(id: string): Promise<'deleted' | 'retained' | 'missing'> {
+    return this.withLock(() => {
+      const rec = this.records.get(id)
+      if (!rec || rec.lifecycle === 'deleted') return 'missing'
+      if (rec.lifecycle !== 'staged') return 'retained'
+      this.removeAssetFiles(rec)
+      rec.lifecycle = 'deleted'
+      rec.contentRemoved = true
+      rec.updatedAtMs = Date.now()
+      this.saveIndex()
+      return 'deleted'
+    })
+  }
+
+  /** Durable upload manifests live beside, not inside, the legacy tmp tree. */
+  rootDirectory(): string {
+    return this.root
+  }
+
   private removeAssetFiles(rec: MediaRecord): void {
     try {
       rmSync(join(this.root, 'assets', rec.ref.id), { recursive: true, force: true })

package/server/lib/query-attachments.ts

@@ -50,7 +50,7 @@ export interface ResolvedQueryAttachments {
  * an optional aid over canonical text — so this ceiling cannot be treated as a
  * budget to trim silently. It has to fit a whole video.
  */
-const MAX_MODEL_IMAGE_INPUTS = VIDEO_SUMMARY_FRAMES_MAX
+export const MAX_MODEL_IMAGE_INPUTS = VIDEO_SUMMARY_FRAMES_MAX
 const MAX_ATTACHMENT_PROMPT_CHARS = 60_000
 
 export class QueryAttachmentError extends Error {

package/server/lib/video-upload-v2.ts

@@ -0,0 +1,726 @@
+// Durable resumable video upload protocol.
+//
+// Unlike the legacy generic upload registry, this state lives outside media/tmp,
+// survives a server restart, binds init to an idempotency key + server identity,
+// and retains a terminal publication receipt until the phone acknowledges it.
+
+import { createHash, randomBytes } from 'node:crypto'
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  statfsSync,
+  writeFileSync,
+  writeSync,
+} from 'node:fs'
+import { join } from 'node:path'
+import type { MediaAttachmentRef } from '../../shared/media-attachment.js'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { getMediaStore } from './media-store.js'
+import { MAX_CHUNKED_MEDIA_BYTES, MAX_VIDEO_DURATION_MS } from './rich-media-safety.js'
+
+export const VIDEO_UPLOAD_V2_PROTOCOL = 1
+export const VIDEO_UPLOAD_V2_CHUNK_BYTES = 256 * 1024
+export const VIDEO_UPLOAD_V2_MAX_FRAME_BYTES = 256 * 1024
+export const VIDEO_UPLOAD_V2_MAX_FRAME_PACK_BYTES = 2 * 1024 * 1024
+export const VIDEO_UPLOAD_PHONE_FRAMES_MIN = 8
+export const VIDEO_UPLOAD_PHONE_FRAMES_MAX = 12
+export const VIDEO_UPLOAD_SERVER_FRAMES_MIN = 8
+export const VIDEO_UPLOAD_SERVER_FRAMES_MAX = 16
+export const VIDEO_UPLOAD_V2_TTL_MS = 4 * 60 * 60_000
+export const VIDEO_UPLOAD_V2_RECEIPT_TTL_MS = 24 * 60 * 60_000
+export const VIDEO_UPLOAD_V2_MAX_CONCURRENT = 8
+export const VIDEO_UPLOAD_V2_TOTAL_RESERVED_BYTES = 4 * 1024 * 1024 * 1024
+export const VIDEO_UPLOAD_V2_FREE_DISK_RESERVE_BYTES = 512 * 1024 * 1024
+export const VIDEO_UPLOAD_V2_ACCEPTED_MIMES = ['video/mp4', 'video/quicktime'] as const
+
+const UPLOAD_ID_RE = /^vu_[0-9a-f]{24}$/
+const CLIENT_REQUEST_RE = /^[A-Za-z0-9._:-]{16,160}$/
+const MEDIA_ID_RE = /^m_[0-9a-f]{24}$/
+
+export function videoUploadV2Enabled(): boolean {
+  return process.env.COS_VIDEO_UPLOAD_V2 === '1'
+}
+
+export function phoneVideoFramesEnabled(): boolean {
+  return videoUploadV2Enabled() && process.env.COS_VIDEO_PHONE_FRAMES === '1'
+}
+
+export function isValidVideoUploadId(value: unknown): value is string {
+  return typeof value === 'string' && UPLOAD_ID_RE.test(value)
+}
+
+export type VideoUploadState = 'receiving' | 'finalizing' | 'published' | 'cancelled' | 'failed'
+
+interface AcceptedPart {
+  bytes: number
+  sha256: string
+}
+
+export interface VideoUploadManifest {
+  v: 1
+  uploadId: string
+  clientRequestId: string
+  serverInstanceId: string
+  state: VideoUploadState
+  generation: number
+  totalBytes: number
+  chunkBytes: number
+  chunkCount: number
+  mime: typeof VIDEO_UPLOAD_V2_ACCEPTED_MIMES[number]
+  label?: string
+  capturedAt?: string
+  sessionId?: string
+  original: Record<string, AcceptedPart>
+  frames: Record<string, AcceptedPart>
+  mediaId?: string
+  receipt?: MediaAttachmentRef
+  acknowledged?: boolean
+  failure?: string
+  createdAtMs: number
+  updatedAtMs: number
+  expiresAtMs: number
+}
+
+export interface VideoUploadInitInput {
+  clientRequestId: unknown
+  serverInstanceId: unknown
+  totalBytes: unknown
+  mime: unknown
+  label?: unknown
+  capturedAt?: unknown
+  sessionId?: unknown
+}
+
+export type VideoUploadErrorCode =
+  | 'video_upload_disabled'
+  | 'video_upload_not_found'
+  | 'video_upload_conflict'
+  | 'video_upload_busy'
+  | 'video_upload_incomplete'
+  | 'video_upload_invalid'
+  | 'video_upload_quota'
+  | 'video_upload_cancelled'
+  | 'video_upload_failed'
+  | 'server_identity_mismatch'
+
+export class VideoUploadError extends Error {
+  constructor(
+    readonly code: VideoUploadErrorCode,
+    message: string,
+    readonly detail: Readonly<Record<string, unknown>> = {},
+  ) {
+    super(message)
+    this.name = 'VideoUploadError'
+  }
+}
+
+export interface VideoUploadProgress {
+  protocol: 1
+  uploadId: string
+  serverInstanceId: string
+  state: VideoUploadState
+  totalBytes: number
+  chunkBytes: number
+  chunkCount: number
+  receivedOriginalChunks: number[]
+  missingOriginalChunks: number[]
+  receivedFrames: number[]
+  expiresAt: string
+  acknowledged: boolean
+  attachment?: MediaAttachmentRef
+  failure?: string
+}
+
+export interface VideoUploadStatus {
+  protocol: 1
+  enabled: boolean
+  receiving: number
+  finalizing: number
+  unacknowledgedPublished: number
+  failed: number
+  blocksRestart: boolean
+  blocksRollback: boolean
+}
+
+export interface VideoUploadRegistryOptions {
+  root?: string
+  now?: () => number
+  maxConcurrent?: number
+  maxReservedBytes?: number
+  freeDiskReserveBytes?: number
+}
+
+function boundedString(value: unknown, max: number): string | undefined {
+  return typeof value === 'string' && value.trim()
+    ? value.trim().replace(/[\u0000-\u001f\u007f]/g, '').slice(0, max)
+    : undefined
+}
+
+function sha256(bytes: Buffer): string {
+  return createHash('sha256').update(bytes).digest('hex')
+}
+
+function positiveSafeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0
+}
+
+function parseIndex(value: unknown): number | null {
+  const raw = typeof value === 'string' && /^\d{1,9}$/.test(value) ? Number(value) : value
+  return typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 0 ? raw : null
+}
+
+function sameInit(manifest: VideoUploadManifest, input: Required<Pick<VideoUploadManifest,
+  'serverInstanceId' | 'totalBytes' | 'mime'>> & Pick<VideoUploadManifest, 'label' | 'capturedAt' | 'sessionId'>): boolean {
+  return manifest.serverInstanceId === input.serverInstanceId
+    && manifest.totalBytes === input.totalBytes
+    && manifest.mime === input.mime
+    && (manifest.label ?? '') === (input.label ?? '')
+    && (manifest.capturedAt ?? '') === (input.capturedAt ?? '')
+    && (manifest.sessionId ?? '') === (input.sessionId ?? '')
+}
+
+function parseManifest(raw: unknown): VideoUploadManifest | null {
+  if (!raw || typeof raw !== 'object') return null
+  const r = raw as Record<string, unknown>
+  if (r.v !== 1 || !isValidVideoUploadId(r.uploadId)
+    || typeof r.clientRequestId !== 'string' || !CLIENT_REQUEST_RE.test(r.clientRequestId)
+    || typeof r.serverInstanceId !== 'string' || r.serverInstanceId.length < 8
+    || !positiveSafeInteger(r.totalBytes) || r.totalBytes > MAX_CHUNKED_MEDIA_BYTES
+    || !positiveSafeInteger(r.chunkBytes) || !positiveSafeInteger(r.chunkCount)
+    || !VIDEO_UPLOAD_V2_ACCEPTED_MIMES.includes(r.mime as typeof VIDEO_UPLOAD_V2_ACCEPTED_MIMES[number])) return null
+  const state = r.state
+  if (state !== 'receiving' && state !== 'finalizing' && state !== 'published'
+    && state !== 'cancelled' && state !== 'failed') return null
+  const parts = (value: unknown): Record<string, AcceptedPart> => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
+    return Object.fromEntries(Object.entries(value as Record<string, unknown>).flatMap(([key, item]) => {
+      if (!/^\d{1,9}$/.test(key) || !item || typeof item !== 'object') return []
+      const p = item as Record<string, unknown>
+      if (!positiveSafeInteger(p.bytes) || typeof p.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(p.sha256)) return []
+      return [[key, { bytes: p.bytes, sha256: p.sha256 }]]
+    }))
+  }
+  return {
+    v: 1,
+    uploadId: r.uploadId,
+    clientRequestId: r.clientRequestId,
+    serverInstanceId: r.serverInstanceId,
+    state,
+    generation: typeof r.generation === 'number' && Number.isSafeInteger(r.generation) ? r.generation : 0,
+    totalBytes: r.totalBytes,
+    chunkBytes: r.chunkBytes,
+    chunkCount: r.chunkCount,
+    mime: r.mime as VideoUploadManifest['mime'],
+    ...(boundedString(r.label, 120) ? { label: boundedString(r.label, 120) } : {}),
+    ...(boundedString(r.capturedAt, 40) ? { capturedAt: boundedString(r.capturedAt, 40) } : {}),
+    ...(boundedString(r.sessionId, 64) ? { sessionId: boundedString(r.sessionId, 64) } : {}),
+    original: parts(r.original),
+    frames: parts(r.frames),
+    ...(typeof r.mediaId === 'string' && MEDIA_ID_RE.test(r.mediaId) ? { mediaId: r.mediaId } : {}),
+    ...(r.receipt && typeof r.receipt === 'object' ? { receipt: r.receipt as MediaAttachmentRef } : {}),
+    acknowledged: r.acknowledged === true,
+    ...(boundedString(r.failure, 160) ? { failure: boundedString(r.failure, 160) } : {}),
+    createdAtMs: typeof r.createdAtMs === 'number' ? r.createdAtMs : Date.now(),
+    updatedAtMs: typeof r.updatedAtMs === 'number' ? r.updatedAtMs : Date.now(),
+    expiresAtMs: typeof r.expiresAtMs === 'number' ? r.expiresAtMs : Date.now(),
+  }
+}
+
+export class VideoUploadRegistry {
+  private readonly root: string
+  private readonly now: () => number
+  private readonly maxConcurrent: number
+  private readonly maxReservedBytes: number
+  private readonly freeDiskReserveBytes: number
+  private readonly manifests = new Map<string, VideoUploadManifest>()
+  private readonly byClientRequest = new Map<string, string>()
+  private readonly locks = new Map<string, Promise<unknown>>()
+  private readonly finalizers = new Map<string, Promise<VideoUploadProgress>>()
+  private readonly activeWriters = new Map<string, number>()
+
+  constructor(options: VideoUploadRegistryOptions = {}) {
+    this.root = options.root ?? join(getMediaStore().rootDirectory(), 'video-upload-v1')
+    this.now = options.now ?? Date.now
+    this.maxConcurrent = options.maxConcurrent ?? VIDEO_UPLOAD_V2_MAX_CONCURRENT
+    this.maxReservedBytes = options.maxReservedBytes ?? VIDEO_UPLOAD_V2_TOTAL_RESERVED_BYTES
+    this.freeDiskReserveBytes = options.freeDiskReserveBytes ?? VIDEO_UPLOAD_V2_FREE_DISK_RESERVE_BYTES
+    mkdirSync(this.root, { recursive: true, mode: 0o700 })
+    this.load()
+    this.reconcilePublished()
+    this.sweepExpired()
+  }
+
+  init(input: VideoUploadInitInput): VideoUploadProgress {
+    if (!videoUploadV2Enabled()) throw new VideoUploadError('video_upload_disabled', 'resumable video upload is disabled')
+    const clientRequestId = boundedString(input.clientRequestId, 160)
+    const serverInstanceId = boundedString(input.serverInstanceId, 160)
+    if (!clientRequestId || !CLIENT_REQUEST_RE.test(clientRequestId) || !serverInstanceId) {
+      throw new VideoUploadError('video_upload_invalid', 'valid clientRequestId and serverInstanceId are required')
+    }
+    if (!positiveSafeInteger(input.totalBytes) || input.totalBytes > MAX_CHUNKED_MEDIA_BYTES) {
+      throw new VideoUploadError('video_upload_invalid', 'video size is invalid', { maxBytes: MAX_CHUNKED_MEDIA_BYTES })
+    }
+    if (!VIDEO_UPLOAD_V2_ACCEPTED_MIMES.includes(input.mime as VideoUploadManifest['mime'])) {
+      throw new VideoUploadError('video_upload_invalid', 'only MP4 and MOV videos are accepted')
+    }
+    const normalized = {
+      serverInstanceId,
+      totalBytes: input.totalBytes,
+      mime: input.mime as VideoUploadManifest['mime'],
+      label: boundedString(input.label, 120),
+      capturedAt: boundedString(input.capturedAt, 40),
+      sessionId: boundedString(input.sessionId, 64),
+    }
+    const existingId = this.byClientRequest.get(clientRequestId)
+    if (existingId) {
+      const existing = this.manifests.get(existingId)
+      if (existing && sameInit(existing, normalized)) return this.progress(existing)
+      throw new VideoUploadError('video_upload_conflict', 'clientRequestId was already used for different video metadata')
+    }
+    this.sweepExpired()
+    const active = [...this.manifests.values()].filter(item => item.state === 'receiving' || item.state === 'finalizing')
+    if (active.length >= this.maxConcurrent) throw new VideoUploadError('video_upload_quota', 'too many video uploads are active')
+    const reserved = active.reduce((sum, item) => sum + item.totalBytes, 0)
+    if (reserved + normalized.totalBytes > this.maxReservedBytes) {
+      throw new VideoUploadError('video_upload_quota', 'video upload disk quota is full')
+    }
+    try {
+      const fs = statfsSync(this.root)
+      const free = Number(fs.bavail) * Number(fs.bsize)
+      if (free - normalized.totalBytes < this.freeDiskReserveBytes) {
+        throw new VideoUploadError('video_upload_quota', 'not enough free disk for video upload')
+      }
+    } catch (error) {
+      if (error instanceof VideoUploadError) throw error
+      throw new VideoUploadError('video_upload_quota', 'free disk could not be verified')
+    }
+    const now = this.now()
+    const uploadId = `vu_${randomBytes(12).toString('hex')}`
+    const chunkCount = Math.ceil(normalized.totalBytes / VIDEO_UPLOAD_V2_CHUNK_BYTES)
+    const manifest: VideoUploadManifest = {
+      v: 1,
+      uploadId,
+      clientRequestId,
+      serverInstanceId,
+      state: 'receiving',
+      generation: 1,
+      totalBytes: normalized.totalBytes,
+      chunkBytes: VIDEO_UPLOAD_V2_CHUNK_BYTES,
+      chunkCount,
+      mime: normalized.mime,
+      ...(normalized.label ? { label: normalized.label } : {}),
+      ...(normalized.capturedAt ? { capturedAt: normalized.capturedAt } : {}),
+      ...(normalized.sessionId ? { sessionId: normalized.sessionId } : {}),
+      original: {},
+      frames: {},
+      createdAtMs: now,
+      updatedAtMs: now,
+      expiresAtMs: now + VIDEO_UPLOAD_V2_TTL_MS,
+    }
+    mkdirSync(this.dir(uploadId), { recursive: false, mode: 0o700 })
+    mkdirSync(this.originalDir(uploadId), { mode: 0o700 })
+    mkdirSync(this.frameDir(uploadId), { mode: 0o700 })
+    this.save(manifest)
+    this.manifests.set(uploadId, manifest)
+    this.byClientRequest.set(clientRequestId, uploadId)
+    return this.progress(manifest)
+  }
+
+  get(uploadId: string, serverInstanceId?: string): VideoUploadProgress {
+    const manifest = this.require(uploadId, serverInstanceId)
+    return this.progress(manifest)
+  }
+
+  async putOriginal(uploadId: string, indexValue: unknown, bytes: Buffer, serverInstanceId?: string): Promise<VideoUploadProgress> {
+    return this.putPart(uploadId, 'original', indexValue, bytes, serverInstanceId)
+  }
+
+  async putFrame(uploadId: string, indexValue: unknown, bytes: Buffer, serverInstanceId?: string): Promise<VideoUploadProgress> {
+    if (!phoneVideoFramesEnabled()) throw new VideoUploadError('video_upload_disabled', 'phone frame acceleration is disabled')
+    return this.putPart(uploadId, 'frames', indexValue, bytes, serverInstanceId)
+  }
+
+  async finalize(uploadId: string, serverInstanceId?: string): Promise<VideoUploadProgress> {
+    const existing = this.finalizers.get(uploadId)
+    if (existing) return existing
+    const task = this.finalizeOnce(uploadId, serverInstanceId)
+    this.finalizers.set(uploadId, task)
+    try { return await task } finally {
+      if (this.finalizers.get(uploadId) === task) this.finalizers.delete(uploadId)
+    }
+  }
+
+  async acknowledge(uploadId: string, serverInstanceId?: string): Promise<VideoUploadProgress> {
+    return this.withLock(uploadId, async () => {
+      const manifest = this.require(uploadId, serverInstanceId)
+      if (manifest.state !== 'published' || !manifest.receipt) {
+        throw new VideoUploadError('video_upload_incomplete', 'upload has no terminal receipt')
+      }
+      manifest.acknowledged = true
+      manifest.updatedAtMs = this.now()
+      manifest.expiresAtMs = manifest.updatedAtMs + VIDEO_UPLOAD_V2_RECEIPT_TTL_MS
+      this.save(manifest)
+      this.removeBodies(manifest)
+      return this.progress(manifest)
+    })
+  }
+
+  async cancel(uploadId: string, serverInstanceId?: string): Promise<VideoUploadProgress | null> {
+    return this.withLock(uploadId, async () => {
+      const manifest = this.manifests.get(uploadId)
+      if (!manifest) return null
+      this.assertIdentity(manifest, serverInstanceId)
+      if (manifest.state === 'published' && manifest.receipt) {
+        await getMediaStore().deleteExactlyStaged(manifest.receipt.id)
+      }
+      manifest.state = 'cancelled'
+      manifest.generation++
+      manifest.updatedAtMs = this.now()
+      manifest.expiresAtMs = manifest.updatedAtMs + VIDEO_UPLOAD_V2_RECEIPT_TTL_MS
+      this.save(manifest)
+      this.removeBodies(manifest)
+      return this.progress(manifest)
+    })
+  }
+
+  status(): VideoUploadStatus {
+    this.sweepExpired()
+    let receiving = 0; let finalizing = 0; let unacknowledgedPublished = 0; let failed = 0
+    for (const item of this.manifests.values()) {
+      if (item.state === 'receiving') receiving++
+      else if (item.state === 'finalizing') finalizing++
+      else if (item.state === 'published' && !item.acknowledged) unacknowledgedPublished++
+      else if (item.state === 'failed') failed++
+    }
+    return {
+      protocol: 1,
+      enabled: videoUploadV2Enabled(),
+      receiving,
+      finalizing,
+      unacknowledgedPublished,
+      failed,
+      blocksRestart: receiving + finalizing > 0,
+      blocksRollback: receiving + finalizing + unacknowledgedPublished > 0,
+    }
+  }
+
+  sweepExpired(at = this.now()): number {
+    let swept = 0
+    for (const manifest of [...this.manifests.values()]) {
+      if (manifest.expiresAtMs > at || this.activeWriters.get(manifest.uploadId)) continue
+      // A published asset belongs to MediaStore, not the upload registry. The
+      // receipt is retained for 24 hours so a phone that lost the finalize
+      // response can recover it, but a phone/WebView that never sends ACK must
+      // not block server rollback forever. Expiring this manifest deliberately
+      // leaves the staged/reserved/associated media record untouched; MediaStore
+      // owns its normal lifecycle and GC from this point forward.
+      if (manifest.state === 'receiving' || manifest.state === 'failed' || manifest.state === 'cancelled'
+        || manifest.state === 'published') {
+        this.manifests.delete(manifest.uploadId)
+        this.byClientRequest.delete(manifest.clientRequestId)
+        rmSync(this.dir(manifest.uploadId), { recursive: true, force: true })
+        swept++
+      }
+    }
+    return swept
+  }
+
+  private async putPart(
+    uploadId: string,
+    kind: 'original' | 'frames',
+    indexValue: unknown,
+    bytes: Buffer,
+    serverInstanceId?: string,
+  ): Promise<VideoUploadProgress> {
+    const index = parseIndex(indexValue)
+    if (index === null || bytes.length === 0) throw new VideoUploadError('video_upload_invalid', 'valid non-empty part required')
+    const max = kind === 'original' ? VIDEO_UPLOAD_V2_CHUNK_BYTES : VIDEO_UPLOAD_V2_MAX_FRAME_BYTES
+    if (bytes.length > max) throw new VideoUploadError('video_upload_invalid', 'part exceeds its byte ceiling', { maxBytes: max })
+    this.activeWriters.set(uploadId, (this.activeWriters.get(uploadId) ?? 0) + 1)
+    try {
+      return await this.withLock(uploadId, () => {
+        const manifest = this.require(uploadId, serverInstanceId)
+        if (manifest.state !== 'receiving') throw new VideoUploadError('video_upload_busy', `upload is ${manifest.state}`)
+        if (kind === 'original' && index >= manifest.chunkCount) throw new VideoUploadError('video_upload_invalid', 'chunk index exceeds declared upload')
+        if (kind === 'frames' && index >= VIDEO_UPLOAD_PHONE_FRAMES_MAX) throw new VideoUploadError('video_upload_invalid', 'frame index exceeds pack limit')
+        const collection = manifest[kind]
+        const key = String(index)
+        const digest = sha256(bytes)
+        const accepted = collection[key]
+        if (accepted) {
+          if (accepted.bytes === bytes.length && accepted.sha256 === digest) return this.progress(manifest)
+          throw new VideoUploadError('video_upload_conflict', 'part index already contains different bytes')
+        }
+        if (kind === 'frames') {
+          const packBytes = Object.values(manifest.frames).reduce((sum, part) => sum + part.bytes, 0)
+          if (packBytes + bytes.length > VIDEO_UPLOAD_V2_MAX_FRAME_PACK_BYTES) {
+            throw new VideoUploadError('video_upload_invalid', 'frame pack exceeds byte ceiling')
+          }
+        }
+        const path = this.partPath(manifest, kind, index)
+        const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600)
+        try {
+          const written = writeSync(fd, bytes)
+          if (written !== bytes.length) throw new Error(`short write: ${written}/${bytes.length}`)
+          fsyncSync(fd)
+        } finally { closeSync(fd) }
+        collection[key] = { bytes: bytes.length, sha256: digest }
+        manifest.updatedAtMs = this.now()
+        this.save(manifest)
+        return this.progress(manifest)
+      })
+    } finally {
+      const count = (this.activeWriters.get(uploadId) ?? 1) - 1
+      if (count <= 0) this.activeWriters.delete(uploadId)
+      else this.activeWriters.set(uploadId, count)
+    }
+  }
+
+  private async finalizeOnce(uploadId: string, serverInstanceId?: string): Promise<VideoUploadProgress> {
+    const manifest = await this.withLock(uploadId, () => {
+      const current = this.require(uploadId, serverInstanceId)
+      if (current.state === 'published' && current.receipt) return current
+      if (current.state === 'cancelled') throw new VideoUploadError('video_upload_cancelled', 'upload was cancelled')
+      if (this.activeWriters.get(uploadId)) throw new VideoUploadError('video_upload_busy', 'upload still has an active writer')
+      const missing = this.missingChunks(current)
+      if (missing.length > 0) throw new VideoUploadError('video_upload_incomplete', 'video upload is incomplete', { missingOriginalChunks: missing })
+      if (!current.mediaId) current.mediaId = `m_${randomBytes(12).toString('hex')}`
+      current.state = 'finalizing'
+      current.generation++
+      current.updatedAtMs = this.now()
+      this.save(current)
+      return current
+    })
+    if (manifest.state === 'published' && manifest.receipt) return this.progress(manifest)
+
+    const recovered = getMediaStore().findByVideoUploadId(uploadId)
+    if (recovered) return this.commitReceipt(uploadId, recovered.ref)
+
+    const assembledPath = join(this.dir(uploadId), 'original-assembled.bin')
+    try {
+      this.assembleOriginal(manifest, assembledPath)
+      const ref = await getMediaStore().ingestRichMediaFromFile({
+        sourcePath: assembledPath,
+        byteLength: manifest.totalBytes,
+        label: manifest.label,
+        declaredMime: manifest.mime,
+        capturedAt: manifest.capturedAt,
+        sessionId: manifest.sessionId,
+        transfer: 'chunked',
+        mediaId: manifest.mediaId,
+        videoUploadId: manifest.uploadId,
+      })
+      const current = this.manifests.get(uploadId)
+      if (current?.state === 'cancelled') {
+        await getMediaStore().deleteExactlyStaged(ref.id)
+        throw new VideoUploadError('video_upload_cancelled', 'upload was cancelled during finalization')
+      }
+      return this.commitReceipt(uploadId, ref)
+    } catch (error) {
+      if (error instanceof VideoUploadError && error.code === 'video_upload_cancelled') throw error
+      await this.withLock(uploadId, () => {
+        const current = this.manifests.get(uploadId)
+        if (current && current.state !== 'published' && current.state !== 'cancelled') {
+          current.state = 'failed'
+          current.failure = error instanceof Error ? error.message.slice(0, 160) : 'video finalization failed'
+          current.updatedAtMs = this.now()
+          this.save(current)
+        }
+      })
+      throw error
+    } finally {
+      try { rmSync(assembledPath, { force: true }) } catch { /* ingest may have moved it */ }
+    }
+  }
+
+  private async commitReceipt(uploadId: string, ref: MediaAttachmentRef): Promise<VideoUploadProgress> {
+    return this.withLock(uploadId, () => {
+      const current = this.require(uploadId)
+      if (current.state === 'cancelled') throw new VideoUploadError('video_upload_cancelled', 'upload was cancelled')
+      current.state = 'published'
+      current.receipt = ref
+      current.acknowledged = false
+      current.updatedAtMs = this.now()
+      current.expiresAtMs = current.updatedAtMs + VIDEO_UPLOAD_V2_RECEIPT_TTL_MS
+      this.save(current)
+      return this.progress(current)
+    })
+  }
+
+  private assembleOriginal(manifest: VideoUploadManifest, target: string): void {
+    rmSync(target, { force: true })
+    const fd = openSync(target, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600)
+    let total = 0
+    try {
+      for (let index = 0; index < manifest.chunkCount; index++) {
+        const bytes = readFileSync(this.partPath(manifest, 'original', index))
+        const part = manifest.original[String(index)]
+        if (!part || bytes.length !== part.bytes || sha256(bytes) !== part.sha256) {
+          throw new VideoUploadError('video_upload_failed', `chunk ${index} failed integrity verification`)
+        }
+        const written = writeSync(fd, bytes)
+        if (written !== bytes.length) throw new Error(`short assembly write: ${written}/${bytes.length}`)
+        total += written
+      }
+      if (total !== manifest.totalBytes) throw new VideoUploadError('video_upload_failed', 'assembled video size mismatch')
+      fsyncSync(fd)
+    } finally { closeSync(fd) }
+  }
+
+  private load(): void {
+    for (const entry of readdirSync(this.root, { withFileTypes: true })) {
+      if (!entry.isDirectory() || !isValidVideoUploadId(entry.name)) continue
+      try {
+        const manifest = parseManifest(JSON.parse(readFileSync(join(this.root, entry.name, 'manifest.json'), 'utf8')))
+        if (!manifest) continue
+        this.manifests.set(manifest.uploadId, manifest)
+        this.byClientRequest.set(manifest.clientRequestId, manifest.uploadId)
+      } catch { /* preserve unreadable draft on disk; do not invent state */ }
+    }
+  }
+
+  private reconcilePublished(): void {
+    for (const manifest of this.manifests.values()) {
+      if (manifest.state !== 'finalizing' && manifest.state !== 'failed'
+          && !(manifest.state === 'published' && !manifest.receipt)) continue
+      const record = getMediaStore().findByVideoUploadId(manifest.uploadId)
+      if (record) {
+        manifest.state = 'published'
+        manifest.receipt = record.ref
+        manifest.acknowledged = false
+        manifest.updatedAtMs = this.now()
+        manifest.expiresAtMs = manifest.updatedAtMs + VIDEO_UPLOAD_V2_RECEIPT_TTL_MS
+        this.save(manifest)
+      } else if (manifest.state === 'finalizing') {
+        // Finalize was claimed but media publication never completed. The
+        // complete draft is durable, so reopen it for an idempotent retry.
+        manifest.state = 'receiving'
+        manifest.failure = undefined
+        manifest.generation++
+        manifest.updatedAtMs = this.now()
+        this.save(manifest)
+      }
+    }
+  }
+
+  private require(uploadId: string, serverInstanceId?: string): VideoUploadManifest {
+    if (!isValidVideoUploadId(uploadId)) throw new VideoUploadError('video_upload_not_found', 'unknown video upload')
+    const manifest = this.manifests.get(uploadId)
+    if (!manifest) throw new VideoUploadError('video_upload_not_found', 'unknown or expired video upload')
+    this.assertIdentity(manifest, serverInstanceId)
+    return manifest
+  }
+
+  private assertIdentity(manifest: VideoUploadManifest, serverInstanceId?: string): void {
+    if (serverInstanceId && serverInstanceId !== manifest.serverInstanceId) {
+      throw new VideoUploadError('server_identity_mismatch', 'video upload belongs to a different COS server')
+    }
+  }
+
+  private progress(manifest: VideoUploadManifest): VideoUploadProgress {
+    const receivedOriginalChunks = Object.keys(manifest.original).map(Number).sort((a, b) => a - b)
+    const receivedFrames = Object.keys(manifest.frames).map(Number).sort((a, b) => a - b)
+    return {
+      protocol: 1,
+      uploadId: manifest.uploadId,
+      serverInstanceId: manifest.serverInstanceId,
+      state: manifest.state,
+      totalBytes: manifest.totalBytes,
+      chunkBytes: manifest.chunkBytes,
+      chunkCount: manifest.chunkCount,
+      receivedOriginalChunks,
+      missingOriginalChunks: this.missingChunks(manifest),
+      receivedFrames,
+      expiresAt: new Date(manifest.expiresAtMs).toISOString(),
+      acknowledged: manifest.acknowledged === true,
+      ...(manifest.receipt ? { attachment: manifest.receipt } : {}),
+      ...(manifest.failure ? { failure: manifest.failure } : {}),
+    }
+  }
+
+  private missingChunks(manifest: VideoUploadManifest): number[] {
+    const missing: number[] = []
+    for (let index = 0; index < manifest.chunkCount; index++) {
+      if (!manifest.original[String(index)]) missing.push(index)
+    }
+    return missing
+  }
+
+  private save(manifest: VideoUploadManifest): void {
+    durableAtomicWriteFileSync(join(this.dir(manifest.uploadId), 'manifest.json'), JSON.stringify(manifest), { mode: 0o600 })
+  }
+
+  private removeBodies(manifest: VideoUploadManifest): void {
+    rmSync(this.originalDir(manifest.uploadId), { recursive: true, force: true })
+    rmSync(this.frameDir(manifest.uploadId), { recursive: true, force: true })
+  }
+
+  private dir(uploadId: string): string { return join(this.root, uploadId) }
+  private originalDir(uploadId: string): string { return join(this.dir(uploadId), 'original') }
+  private frameDir(uploadId: string): string { return join(this.dir(uploadId), 'frames') }
+  private partPath(manifest: VideoUploadManifest, kind: 'original' | 'frames', index: number): string {
+    return join(kind === 'original' ? this.originalDir(manifest.uploadId) : this.frameDir(manifest.uploadId), `${index}.bin`)
+  }
+
+  private withLock<T>(uploadId: string, work: () => T | Promise<T>): Promise<T> {
+    const prior = this.locks.get(uploadId) ?? Promise.resolve()
+    const run = prior.then(work, work)
+    this.locks.set(uploadId, run.then(() => undefined, () => undefined))
+    return run
+  }
+}
+
+let defaultRegistry: VideoUploadRegistry | null = null
+
+export function getVideoUploadRegistry(): VideoUploadRegistry {
+  if (!defaultRegistry) defaultRegistry = new VideoUploadRegistry()
+  return defaultRegistry
+}
+
+export function _setVideoUploadRegistryForTests(registry: VideoUploadRegistry | null): VideoUploadRegistry | null {
+  const previous = defaultRegistry
+  defaultRegistry = registry
+  return previous
+}
+
+export function videoUploadV2Capability(videoProcessingReady: boolean) {
+  let registryReady = false
+  let reason = 'disabled'
+  if (videoUploadV2Enabled()) {
+    try {
+      getVideoUploadRegistry()
+      registryReady = true
+      reason = videoProcessingReady ? 'ready' : 'video_processing_unavailable'
+    } catch {
+      reason = 'storage_unavailable'
+    }
+  }
+  return {
+    available: registryReady && videoProcessingReady,
+    protocol: VIDEO_UPLOAD_V2_PROTOCOL,
+    chunkBytes: VIDEO_UPLOAD_V2_CHUNK_BYTES,
+    maxOriginalBytes: MAX_CHUNKED_MEDIA_BYTES,
+    maxDurationMs: MAX_VIDEO_DURATION_MS,
+    acceptedMimes: [...VIDEO_UPLOAD_V2_ACCEPTED_MIMES],
+    // The route and manifest format are present so the phone implementation can
+    // be canaried without another wire change. Do not advertise frame packs as
+    // usable until the server consumes them and physical WKWebView proof passes.
+    phoneFramesAvailable: false,
+    phoneFramesMin: VIDEO_UPLOAD_PHONE_FRAMES_MIN,
+    phoneFramesMax: VIDEO_UPLOAD_PHONE_FRAMES_MAX,
+    serverFramesMin: VIDEO_UPLOAD_SERVER_FRAMES_MIN,
+    serverFramesMax: VIDEO_UPLOAD_SERVER_FRAMES_MAX,
+    maxFrameBytes: VIDEO_UPLOAD_V2_MAX_FRAME_BYTES,
+    maxPackBytes: VIDEO_UPLOAD_V2_MAX_FRAME_PACK_BYTES,
+    maxSourcePixels: 33_177_600,
+    reason,
+  }
+}

package/server/routes/health.ts

@@ -59,6 +59,8 @@ import { getEarlyMeetingSyncSnapshot } from '../lib/g2-ops-handoff.js'
 import { getProgressiveHqSnapshot } from '../lib/meeting-batch-transcribe.js'
 import { getMeetingFinalizationSnapshot } from '../lib/meeting-finalization-jobs.js'
 import { resolveMeetingLibrary } from '../lib/cos-operations-meetings.js'
+import { videoUploadV2Capability } from '../lib/video-upload-v2.js'
+import { MAX_MODEL_IMAGE_INPUTS } from '../lib/query-attachments.js'
 
 export const healthRouter = Router()
 
@@ -172,6 +174,7 @@ healthRouter.get('/health', async (_req, res) => {
   // capabilities.liveCues so the two surfaces can never disagree.
   const liveCues = liveCuesCapability()
   const richMedia = await getRichMediaProcessingCapabilities()
+  const videoUploadV2 = videoUploadV2Capability(richMedia.video)
   // Upload limits are published so the client never carries its own byte caps:
   // cos-glasses-app and cos-glasses-server are separate repos that have already
   // diverged, so a constant in both is guaranteed to drift. Absent means an
@@ -326,6 +329,11 @@ healthRouter.get('/health', async (_req, res) => {
         maxVideoBytesPerAttachment: MAX_VIDEO_MEDIA_BYTES,
         maxVideoMinutes: 20,
         maxStillFrames: 8,
+        videoUploadV2: {
+          available: videoUploadV2.available,
+          protocol: videoUploadV2.protocol,
+          reason: videoUploadV2.reason,
+        },
       },
       meetingLifecycle: {
         earlySyncClaim: getEarlyMeetingSyncSnapshot(),
@@ -359,6 +367,8 @@ healthRouter.get('/models', async (req, res) => {
   const transcriptionLive = getWhisperPreviewCapability()
   const transcriptionProfile = getTranscriptionProfileStatus()
   const progressiveHq = getProgressiveHqSnapshot()
+  const richMedia = await getRichMediaProcessingCapabilities()
+  const videoUploadV2 = videoUploadV2Capability(richMedia.video)
   const cursorOptions = cursorCatalog.options.filter(option => !!option.id)
   res.json({
     ...catalog,
@@ -391,6 +401,20 @@ healthRouter.get('/models', async (req, res) => {
       // THIS surface, so a value present only on /api/health leaves the
       // live-cues indicator blind.
       liveCues: liveCuesCapability(),
+      richMedia: {
+        video: richMedia.video,
+        maxPromptVisuals: MAX_MODEL_IMAGE_INPUTS,
+        videoUploadV2: {
+          ...videoUploadV2,
+          // The first private train deliberately admits only one video and no
+          // other visual attachment. This keeps a server fallback at its
+          // proven 16-frame policy inside the provider-wide 16-image ceiling.
+          promptAdmission: {
+            maxVideos: 1,
+            maxOtherVisualsWithVideo: 0,
+          },
+        },
+      },
       ...(localFirstMeetings ? { localFirstMeetings } : {}),
     },
   })

package/server/routes/maintenance.ts

@@ -16,6 +16,7 @@ import { serverMetrics } from '../lib/server-metrics.js'
 import { getServerInstanceId } from '../lib/server-instance-id.js'
 import { getWhisperHealth } from '../lib/whisper-local.js'
 import { getActiveTranscriptionSessionCount, getTranscriptionSessionLiveness } from './transcribe-stream.js'
+import { getVideoUploadRegistry } from '../lib/video-upload-v2.js'
 
 export const maintenanceRouter = Router()
 
@@ -78,6 +79,21 @@ function statusSnapshot(credentials: MaintenanceOperationCredentials = {}) {
   // rather than counted, and are never deleted here.
   const sessionLiveness = getTranscriptionSessionLiveness()
   const managed = managedRuntimeCapability()
+  let videoUploads
+  try {
+    videoUploads = getVideoUploadRegistry().status()
+  } catch {
+    videoUploads = {
+      protocol: 1 as const,
+      enabled: false,
+      receiving: 0,
+      finalizing: 0,
+      unacknowledgedPublished: 0,
+      failed: 0,
+      blocksRestart: false,
+      blocksRollback: false,
+    }
+  }
   const tracked = maintenanceLifecycle.snapshot(credentials, {
     recording_session: sessionLiveness.live,
   })
@@ -107,7 +123,10 @@ function statusSnapshot(credentials: MaintenanceOperationCredentials = {}) {
     shuttingDown: jobs.shuttingDown,
     durableStoreState: jobs.store.state,
     lifecycle,
-    safeToRestart: lifecycle.safeToRestart && !jobs.shuttingDown,
+    videoUploads,
+    // Published receipts intentionally survive an ordinary restart. They only
+    // block a binary downgrade, where an old server could erase V2 evidence.
+    safeToRestart: lifecycle.safeToRestart && !jobs.shuttingDown && !videoUploads.blocksRestart,
     whisper: getWhisperHealth(),
   }
 }

package/server/routes/media.ts

@@ -57,6 +57,16 @@ import {
   isValidUploadId,
   type UploadSessionErrorCode,
 } from '../lib/upload-session.js'
+import {
+  VIDEO_UPLOAD_V2_CHUNK_BYTES,
+  VIDEO_UPLOAD_V2_MAX_FRAME_BYTES,
+  VideoUploadError,
+  getVideoUploadRegistry,
+  isValidVideoUploadId,
+  type VideoUploadErrorCode,
+} from '../lib/video-upload-v2.js'
+import { getServerInstanceId } from '../lib/server-instance-id.js'
+import { maintenanceAdmissionsOpen } from '../lib/maintenance-lifecycle.js'
 
 // Route-scoped parser: 16 MB covers the max valid batch after base64 + JSON
 // overhead. Mounted only for /api/media in server/index.ts — the global
@@ -301,6 +311,9 @@ export function createMediaChunkBodyParser(options: MediaChunkParserOptions = {}
 
 /** Chunk parser at the advertised chunk size. */
 export const mediaChunkBodyParser = createMediaChunkBodyParser()
+export const videoUploadChunkBodyParser = createMediaChunkBodyParser({
+  maxChunkBytes: Math.max(VIDEO_UPLOAD_V2_CHUNK_BYTES, VIDEO_UPLOAD_V2_MAX_FRAME_BYTES),
+})
 
 function takeChunkBody(req: Request): Buffer | undefined {
   const bytes = chunkBodies.get(req)
@@ -347,6 +360,19 @@ const UPLOAD_ERROR_STATUS: Record<UploadSessionErrorCode, number> = {
   upload_staging_failed: 500,
 }
 
+const VIDEO_UPLOAD_ERROR_STATUS: Record<VideoUploadErrorCode, number> = {
+  video_upload_disabled: 503,
+  video_upload_not_found: 404,
+  video_upload_conflict: 409,
+  video_upload_busy: 409,
+  video_upload_incomplete: 409,
+  video_upload_invalid: 400,
+  video_upload_quota: 507,
+  video_upload_cancelled: 410,
+  video_upload_failed: 500,
+  server_identity_mismatch: 409,
+}
+
 function sendMediaError(res: Response, err: unknown): void {
   // Chunked-upload failures go through the SAME funnel as every other media
   // error, so there is one place that decides the error body's shape.
@@ -354,6 +380,14 @@ function sendMediaError(res: Response, err: unknown): void {
     res.status(UPLOAD_ERROR_STATUS[err.code] ?? 500).json({ error: err.code, ...err.detail })
     return
   }
+  if (err instanceof VideoUploadError) {
+    res.status(VIDEO_UPLOAD_ERROR_STATUS[err.code] ?? 500).json({
+      error: err.code,
+      detail: err.message,
+      ...err.detail,
+    })
+    return
+  }
   if (err instanceof MediaStoreError) {
     res.status(MEDIA_ERROR_STATUS[err.code] ?? 500).json({ error: err.code })
     return
@@ -374,6 +408,26 @@ function sendMediaError(res: Response, err: unknown): void {
   res.status(500).json({ error: 'media_internal_error' })
 }
 
+function videoUploadServerIdentity(req: Request): string | undefined {
+  return safeString(req.header('x-cos-server-instance'), 160)
+    ?? safeString(req.header('x-cos-server-instance-id'), 160)
+}
+
+function requireVideoUploadAdmission(res: Response): boolean {
+  if (maintenanceAdmissionsOpen()) return true
+  res.status(503).json({ error: 'server_maintenance', retryable: true })
+  return false
+}
+
+function requireCurrentServerIdentity(req: Request): string {
+  const presented = videoUploadServerIdentity(req)
+  const current = getServerInstanceId()
+  if (!presented || presented !== current) {
+    throw new VideoUploadError('server_identity_mismatch', 'request targets a different COS server')
+  }
+  return presented
+}
+
 function safeString(v: unknown, max: number): string | undefined {
   return typeof v === 'string' && v.trim().length > 0 ? v.trim().slice(0, max) : undefined
 }
@@ -489,6 +543,124 @@ function uploadLabelFrom(req: Request): string | undefined {
   try { return decodeURIComponent(rawLabel).slice(0, 120) } catch { return rawLabel.slice(0, 120) }
 }
 
+// ── Resumable video upload V2 (private canary) ───────────────────────────────
+
+mediaRouter.post('/media/video-upload/init', (req: Request, res: Response) => {
+  try {
+    const serverInstanceId = requireCurrentServerIdentity(req)
+    const body = req.body ?? {}
+    const progress = getVideoUploadRegistry().init({
+      clientRequestId: body.clientRequestId,
+      serverInstanceId,
+      totalBytes: body.totalBytes,
+      mime: body.mime,
+      label: uploadLabelFrom(req),
+      capturedAt: safeString(req.header('x-cos-captured-at'), 40),
+      sessionId: safeString(req.header('x-cos-session-id'), 64),
+    })
+    res.json(progress)
+  } catch (err) {
+    sendMediaError(res, err)
+  }
+})
+
+mediaRouter.get('/media/video-upload/:uploadId', (req: Request, res: Response) => {
+  try {
+    const serverInstanceId = requireCurrentServerIdentity(req)
+    if (!isValidVideoUploadId(req.params.uploadId)) {
+      throw new VideoUploadError('video_upload_not_found', 'unknown or expired video upload')
+    }
+    res.json(getVideoUploadRegistry().get(req.params.uploadId, serverInstanceId))
+  } catch (err) {
+    sendMediaError(res, err)
+  }
+})
+
+mediaRouter.put(
+  '/media/video-upload/:uploadId/original/:index',
+  videoUploadChunkBodyParser,
+  async (req: Request, res: Response) => {
+    const bytes = takeChunkBody(req)
+    try {
+      if (!requireVideoUploadAdmission(res)) return
+      const serverInstanceId = requireCurrentServerIdentity(req)
+      if (!isValidVideoUploadId(req.params.uploadId) || bytes === undefined) {
+        throw new VideoUploadError('video_upload_invalid', 'valid upload id and raw chunk bytes are required')
+      }
+      res.json(await getVideoUploadRegistry().putOriginal(
+        req.params.uploadId,
+        req.params.index,
+        bytes,
+        serverInstanceId,
+      ))
+    } catch (err) {
+      sendMediaError(res, err)
+    }
+  },
+)
+
+mediaRouter.put(
+  '/media/video-upload/:uploadId/frame/:index',
+  videoUploadChunkBodyParser,
+  async (req: Request, res: Response) => {
+    const bytes = takeChunkBody(req)
+    try {
+      if (!requireVideoUploadAdmission(res)) return
+      const serverInstanceId = requireCurrentServerIdentity(req)
+      if (!isValidVideoUploadId(req.params.uploadId) || bytes === undefined) {
+        throw new VideoUploadError('video_upload_invalid', 'valid upload id and raw frame bytes are required')
+      }
+      res.json(await getVideoUploadRegistry().putFrame(
+        req.params.uploadId,
+        req.params.index,
+        bytes,
+        serverInstanceId,
+      ))
+    } catch (err) {
+      sendMediaError(res, err)
+    }
+  },
+)
+
+mediaRouter.post('/media/video-upload/:uploadId/finalize', async (req: Request, res: Response) => {
+  try {
+    if (!requireVideoUploadAdmission(res)) return
+    const serverInstanceId = requireCurrentServerIdentity(req)
+    if (!isValidVideoUploadId(req.params.uploadId)) {
+      throw new VideoUploadError('video_upload_not_found', 'unknown or expired video upload')
+    }
+    res.json(await getVideoUploadRegistry().finalize(req.params.uploadId, serverInstanceId))
+  } catch (err) {
+    sendMediaError(res, err)
+  }
+})
+
+mediaRouter.post('/media/video-upload/:uploadId/ack', async (req: Request, res: Response) => {
+  try {
+    const serverInstanceId = requireCurrentServerIdentity(req)
+    if (!isValidVideoUploadId(req.params.uploadId)) {
+      throw new VideoUploadError('video_upload_not_found', 'unknown or expired video upload')
+    }
+    res.json(await getVideoUploadRegistry().acknowledge(req.params.uploadId, serverInstanceId))
+  } catch (err) {
+    sendMediaError(res, err)
+  }
+})
+
+mediaRouter.delete('/media/video-upload/:uploadId', async (req: Request, res: Response) => {
+  try {
+    const serverInstanceId = requireCurrentServerIdentity(req)
+    if (!isValidVideoUploadId(req.params.uploadId)) {
+      res.json({ ok: true, dropped: false })
+      return
+    }
+    const progress = await getVideoUploadRegistry().cancel(req.params.uploadId, serverInstanceId)
+    res.json({ ok: true, dropped: progress !== null, ...(progress ? { upload: progress } : {}) })
+  } catch (err) {
+    sendMediaError(res, err)
+  }
+})
+
 mediaRouter.post('/media/upload/init', (req: Request, res: Response) => {
   try {
     const body = req.body ?? {}