@gotcos/glasses-server 6.50.2 → 6.50.4

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 6.50.4
+
+- **The ring never moves in a way that stops the only recording.** A copy told to yield stops its recording (that is how a duplicate ends). QA of 6.50.3, with glasses 6.9.507 on the phone: reopening COS on a blank phone page mid-meeting (the 2026-09-18 08:15 symptom) gave the ring to the newer copy, so the meeting ended within 15 s and the new window was not recording. The referee now notes every meeting-chunk POST as it passes: a live chunk, or an iPhone offline chunk replayed; the preview does not count. The router is mounted before the transcribe-stream router and only notes, never answers. It records whose chunk it was (`?clientInstance=`, glasses 6.9.509+) or, for an untagged chunk, which device sent it. Two rules follow. (1) While the owner's OWN chunks arrive (30 s window, `CLIENT_INSTANCE_CAPTURE_LIVE_MS`), a newer copy is told to wait, however quiet the owner's claims. A hidden or locked WebView throttles its timers, but chunk uploads follow the audio. The ring moves on the first claim after the meeting stops. (2) A claimant whose own chunks arrive while the owner's do not takes the ring. That covers the case QA found in the first draft of this release, which held the ring on ANY chunk: COS reopened offline, a meeting started on the new copy, and on reconnect that copy's own chunks switched the hold on for the dead copy the Mac still remembered, so its claim was told to yield and the only recording stopped. (3) A claim now says whether its copy is recording (`recording`, glasses 6.9.510+). A recording claimant takes the ring from an owner that is not recording, and an owner's last `recording: true` holds the ring while it keeps claiming (45 s). Chunk arrival alone lags: after an outage the uploader backs off up to 60 s, and only a visible page resets it, which a hidden recording copy never gets. QA round 3 found that gap: a reopened copy that reclaimed offline took the ring back on reconnect, and the recording copy was then told to stop. Untagged chunks (glasses 6.9.507/6.9.508) count for the owner only while it still claims (45 s), so a dead owner is never pinned by them or by a stale flag. When both copies record, the owner keeps the ring and the claimant stops. The answer's `captureLive` means the owner is recording; glasses 6.9.510 refuse a yield while recording when it is `false`. `lastRecordingChunkAt` (first draft) is gone.
+- **One owner per device.** Owners are kept by the request's address (`::ffff:` mapped addresses folded), up to 16 devices, so an Even simulator on the Mac or a second phone on the same token cannot take the ring from the glasses.
+- **A boot time from the future is refused** (400) past an hour ahead of the server clock: a phone clock set ahead would otherwise outrank every later copy.
+- Tests: the rules executed. The owner's chunks hold however quiet its claims, and release after. A recording claimant takes from a dead owner and from a newer owner that is not recording. With both recording, the owner keeps the ring. Untagged chunks hold only up to the owner's 45 s edge. The ledger's window edges, per-device untagged tracking, and bound are covered, and so are what counts as a chunk and what is a valid tag. The QA round 3 replay: a recording copy's own word takes the ring back from a fresher copy that is not recording, then holds it until 45 s after its last claim. The flag follows the latest claim, and only a literal `true` counts. Over HTTP, stub chunk routes are mounted behind the referee as in `index.ts`: the owner's tagged chunk holds; a recording claim takes the ring back and the other copy then gets `captureLive: true`; the QA round-2 replay (dead owner, a new copy's own chunk first) gives that copy the ring; a tagged iPhone offline replay holds; a preview does not; untagged chunks hold, then release past 45 s; a dual-stack server treats `127.0.0.1` and `::1` as two devices; a future boot is a 400. The mount test pins the referee before `transcribeStreamRouter`. Gate: 18/18 referee cases, including `referee-claimed-recording-ignored`, `referee-recording-flag-never-refreshed`, `referee-recording-parsed-loosely`, `referee-owner-recording-flag-ignored`, `referee-stops-the-only-recorder`, `referee-duplicate-claimant-wins`, `referee-dead-owner-pinned-by-untagged`, `referee-untagged-ignored`, `referee-any-copy-chunk-is-the-owners`, `referee-preview-is-a-chunk`, `referee-chunks-unnoted`.
+
+## 6.50.3
+
+- **The server referees between copies of the COS Glasses app.** 2026-09-18 10:06: the Even Realities app kept an older WebView copy of the plugin alive (hidden since at least 09:30) behind the one Miles opened, both answered one Start Meeting to the millisecond, and the same 90-minute meeting was recorded and HQ-polished twice. Glasses 6.9.505's claim in the Even app's storage could not stop it: the new copy read the old copy's claim 36 minutes stale, and the hidden copy never refreshed its claim or read the new one, while its HTTP calls to this server kept working (it uploaded all 827 chunks). `POST /api/client-instance/claim` `{ id, bootAt, version }` answers `{ verdict: 'owner' | 'yield', owner }`: the newest boot that is still posting owns the ring (ties by id); a claim from an older boot takes over only after the owner has been quiet for 45 s (`CLIENT_INSTANCE_LIVE_MS`, three 15 s ticks). `check: true` answers without taking, so a copy that already yielded can ask whether the owner is gone without stealing the ring after a phone lock froze both copies' timers. Behind the API token. In memory: a restart forgets the owner and the next posts re-establish it within a tick. Glasses 6.9.507 asks this route first and falls back to the storage claim when the Mac is unreachable or older.
+- Tests (`client-instance.test.ts`): the arbitration executed (the zombie yields, the owner refreshes, the older reclaims one ms past the live edge, a same-millisecond tie has one owner, malformed claims refused) and over HTTP (state kept across requests, a 400 changes nothing); the mount sits after `requireApiToken` and is not a public path. Gate: `referee-dead-owner-never-released`, `referee-older-boot-wins`, `referee-not-mounted`, 3/3.
+
 ## 6.50.2
 
 - **The Turbo meeting preview no longer switches itself off for good.** Miles, 2026-09-18 08:43: the `~` provisional line on the lens was gone, Mac-reachable, Turbo configured. The preview route had answered "no text" to 5,719 requests since 2026-09-17 16:00 (in under a millisecond) while the Turbo sidecar itself transcribed the same audio in 0.27 s. One failed request (`The operation was aborted due to timeout`, then `fetch failed`, with the Mac under build load) set `previewAvailable = false`, and the only code that sets it back is the sidecar's own start, which runs once per server boot. Now a failure against a sidecar that is still running is a 10 s cooldown (`PREVIEW_FAILURE_COOLDOWN_MS`) and the next request after it tries again; five failures in a row (`PREVIEW_RECYCLE_AFTER_FAILURES`) recycle the sidecar; a sidecar that exited is restarted from the request path, at most once per 60 s window, doubling to 15 min while restarts keep failing and resetting on any answer. A missing model, a missing binary or a foreign listener on port 8177 is never restarted (a restart cannot fix it). After the server's own shutdown stop, nothing revives the sidecar (a request arriving during shutdown could otherwise have spawned one that outlived the process). Prompt previews were never affected (they fall back to the canonical worker); canonical meeting ASR never was. The preview log lines now carry an ISO timestamp: the lines that recorded this failure had none.

package/package.json

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

package/server/index.ts

@@ -14,6 +14,7 @@ import { execSync } from 'node:child_process'
 import { randomBytes } from 'node:crypto'
 import { healthRouter } from './routes/health.js'
 import { diagRouter } from './routes/diag.js'
+import { createClientInstanceRouter } from './routes/client-instance.js'
 import { queryRouter } from './routes/query.js'
 import { providerProofRouter } from './routes/provider-proof.js'
 import { transcribeRouter } from './routes/transcribe.js'
@@ -530,6 +531,9 @@ const forkThreadForRoute = (request: {
 // API routes
 app.use('/api', healthRouter)
 app.use('/api', diagRouter)
+// 6.50.3: the referee between copies of the COS Glasses app (routes/client-instance.ts).
+// Mounted BEFORE transcribeStreamRouter: it notes each meeting chunk on its way past.
+app.use('/api', createClientInstanceRouter())
 app.use('/api', createQueryJobsRouter(queryJobCoordinator, {
   prepareAdmission: preparePublicDurableQueryAdmission,
 }))

package/server/lib/client-instance-claim.ts

@@ -0,0 +1,147 @@
+// Which copy of the COS Glasses app owns the ring (6.50.3). PURE: the clock is passed in.
+//
+// WHY THE SERVER. On 2026-09-18 the Even Realities app kept an older WebView copy of the
+// plugin alive behind a newly opened one and delivered every ring event to both, so one
+// Start Meeting recorded the same 90 minutes twice. Glasses 6.9.505 put a claim in the Even
+// app's own storage: the newest boot wins, the copy behind it yields. It failed in the field
+// because the hidden copy's storage calls went unanswered (its claim sat 36 min stale and it
+// never read the newer one), while its HTTP calls to this server kept working (it uploaded
+// all 827 chunks). This server is the one party every copy can still reach.
+//
+// RULE. One owner at a time. A claim from the owner refreshes it. A claim from a NEWER boot
+// (ties broken by id) takes ownership. A claim from an older boot takes ownership only when
+// the owner has gone quiet for CLIENT_INSTANCE_LIVE_MS (the newer copy died). In memory: a
+// server restart forgets the owner, and the next posts re-establish it within one tick.
+
+export const CLIENT_INSTANCE_TICK_MS = 15_000
+/** Three missed ticks: the owner is gone. */
+export const CLIENT_INSTANCE_LIVE_MS = 3 * CLIENT_INSTANCE_TICK_MS
+/**
+ * 6.50.4: a meeting chunk inside this window means that copy is recording. Five chunk
+ * intervals (~6 s each), so a stretch of silence or a slow upload does not end the hold.
+ */
+export const CLIENT_INSTANCE_CAPTURE_LIVE_MS = 30_000
+/** App copies whose newest chunk is remembered; the least recent is dropped past this. */
+export const CLIENT_INSTANCE_MAX_TAGGED = 64
+/** A boot time this far past the server clock is a phone clock set wrong, not a newer copy. */
+export const CLIENT_INSTANCE_MAX_FUTURE_BOOT_MS = 60 * 60_000
+
+export interface ClientInstanceClaim {
+  id: string
+  bootAt: number
+  version: string
+  /**
+   * The copy says it is recording (glasses 6.9.509+; false when absent). Chunk arrival
+   * alone lags: after an outage the uploader backs off up to 60 s, and only a visible page
+   * or a display reconnect resets it, which a hidden recording copy never gets (QA round 3).
+   */
+  recording: boolean
+}
+
+export interface ClientInstanceOwner extends ClientInstanceClaim {
+  seenAt: number
+}
+
+export type ClientInstanceVerdict = 'owner' | 'yield'
+
+const ID_PATTERN = /^[a-z0-9]{1,16}-[a-z0-9]{1,8}$/
+
+/** The `clientInstance` a chunk POST names (glasses 6.9.509+), or null. Never throws. */
+export function parseInstanceTag(value: unknown): string | null {
+  return typeof value === 'string' && ID_PATTERN.test(value) ? value : null
+}
+
+/**
+ * What the chunk stream says about who is recording, for one claim from one device.
+ * `owner` / `claimant`: that copy's OWN tagged chunks arrived inside
+ * CLIENT_INSTANCE_CAPTURE_LIVE_MS. `untagged`: chunks without a tag (glasses before 6.9.509)
+ * arrived from this device, so they could be anyone's.
+ */
+export interface CaptureEvidence {
+  owner: boolean
+  claimant: boolean
+  untagged: boolean
+}
+
+export const NO_CAPTURE: CaptureEvidence = { owner: false, claimant: false, untagged: false }
+
+/**
+ * Newest chunk arrival per tagged app copy, and per device for untagged chunks. The clock
+ * is passed in. Bounded: a copy that stopped sending is forgotten once 64 newer ones have.
+ */
+export class ClientChunkLedger {
+  private readonly tagged = new Map<string, number>()
+  private readonly untagged = new Map<string, number>()
+
+  note(device: string, instance: string | null, at: number): void {
+    const map = instance ? this.tagged : this.untagged
+    const key = instance ?? device
+    map.delete(key)
+    map.set(key, at)
+    while (map.size > CLIENT_INSTANCE_MAX_TAGGED) map.delete(map.keys().next().value as string)
+  }
+
+  evidence(device: string, ownerId: string, claimId: string, now: number): CaptureEvidence {
+    const live = (at: number | undefined) => at !== undefined && now - at < CLIENT_INSTANCE_CAPTURE_LIVE_MS
+    return {
+      owner: live(this.tagged.get(ownerId)),
+      claimant: live(this.tagged.get(claimId)),
+      untagged: live(this.untagged.get(device)),
+    }
+  }
+}
+
+/**
+ * Whether the owner is recording. Its own tagged chunks are proof however quiet its claims
+ * (a hidden or locked WebView throttles its timers; chunk uploads follow the audio). Its
+ * own last claim saying `recording`, and untagged chunks from the device (which could be
+ * anyone's), count only while it is still claiming: a dead owner must never be pinned by
+ * a stale flag or by the chunks of the copy that replaced it (QA round 2).
+ */
+export function ownerIsRecording(owner: ClientInstanceOwner, evidence: CaptureEvidence, now: number): boolean {
+  if (evidence.owner) return true
+  return (owner.recording || evidence.untagged) && now - owner.seenAt <= CLIENT_INSTANCE_LIVE_MS
+}
+
+/** A body the route may act on, or null. Never throws. */
+export function parseClientInstanceClaim(body: unknown, now = Date.now()): ClientInstanceClaim | null {
+  if (!body || typeof body !== 'object') return null
+  const o = body as Record<string, unknown>
+  if (typeof o.id !== 'string' || !ID_PATTERN.test(o.id)) return null
+  if (typeof o.bootAt !== 'number' || !Number.isFinite(o.bootAt) || o.bootAt <= 0) return null
+  // A copy that booted with the phone clock set ahead would outrank every later copy for
+  // as long as the clock stayed wrong (QA, 6.50.3).
+  if (o.bootAt > now + CLIENT_INSTANCE_MAX_FUTURE_BOOT_MS) return null
+  const version = typeof o.version === 'string' ? o.version.slice(0, 32) : ''
+  return { id: o.id, bootAt: o.bootAt, version, recording: o.recording === true }
+}
+
+function isNewer(a: ClientInstanceClaim, b: ClientInstanceClaim): boolean {
+  return a.bootAt > b.bootAt || (a.bootAt === b.bootAt && a.id > b.id)
+}
+
+/** The owner after `claim` arrives at `now`, and what to tell its sender. */
+export function arbitrateClientInstance(
+  owner: ClientInstanceOwner | null,
+  claim: ClientInstanceClaim,
+  now: number,
+  evidence: CaptureEvidence = NO_CAPTURE,
+): { owner: ClientInstanceOwner; verdict: ClientInstanceVerdict; took: boolean } {
+  const fresh: ClientInstanceOwner = { ...claim, seenAt: now }
+  if (!owner) return { owner: fresh, verdict: 'owner', took: true }
+  if (owner.id === claim.id) return { owner: { ...owner, seenAt: now, recording: claim.recording }, verdict: 'owner', took: false }
+  // 6.50.4: the yielding copy stops its recording (that is how a duplicate ends), so the
+  // ring must never move in a way that stops the only recording.
+  // (1) The claimant is recording and the owner is not: the claimant is the meeting.
+  // Reopened offline, the Mac still names the dead copy from before; when signal returns,
+  // the new copy's chunks land first and its claim must not be told to stop (QA round 2).
+  // Its chunks or its own word: after an outage the uploads lag the claims (QA round 3).
+  if ((evidence.claimant || claim.recording) && !ownerIsRecording(owner, evidence, now)) return { owner: fresh, verdict: 'owner', took: true }
+  // (2) The owner is recording: a newer copy waits, however quiet the owner's claims.
+  // Reopening COS on a blank phone page mid-meeting ended the meeting on 6.50.3 (QA).
+  // The ring moves on the newer copy's first claim after the meeting stops.
+  if (ownerIsRecording(owner, evidence, now)) return { owner, verdict: 'yield', took: false }
+  if (isNewer(claim, owner)) return { owner: fresh, verdict: 'owner', took: true }
+  if (now - owner.seenAt > CLIENT_INSTANCE_LIVE_MS) return { owner: fresh, verdict: 'owner', took: true }
+  return { owner, verdict: 'yield', took: false }
+}

package/server/routes/client-instance.ts

@@ -0,0 +1,83 @@
+// POST /api/client-instance/claim — the referee between copies of the COS Glasses app (6.50.3).
+// See lib/client-instance-claim.ts for the why. Behind the global API token like every /api
+// route except health and diag. Body: { id, bootAt, version, check? }. Answer: { verdict, owner }.
+//
+// `check: true` answers without taking: a copy that already yielded asks whether the owner
+// is still there, and must not steal the ring by asking (after a phone lock both copies'
+// timers were frozen, so the owner only LOOKS quiet; the older copy's first tick would
+// otherwise take it).
+//
+// 6.50.4: one owner PER DEVICE (the request's address), so an Even simulator on this Mac or
+// a second phone on the same token cannot take the ring from the glasses (QA, 6.50.3); and
+// the ring never moves in a way that stops the only recording. The router notes every
+// meeting-chunk POST as it passes (it is mounted BEFORE the transcribe-stream router, and
+// only notes, never answers): whose chunk it was (`?clientInstance=`, glasses 6.9.509+) or,
+// untagged, which device sent it. `captureLive` in the answer: the owner is recording.
+
+import { Router } from 'express'
+import {
+  arbitrateClientInstance,
+  ownerIsRecording,
+  parseClientInstanceClaim,
+  parseInstanceTag,
+  ClientChunkLedger,
+  NO_CAPTURE,
+  type ClientInstanceOwner,
+} from '../lib/client-instance-claim.js'
+
+/** Owners kept at once; the least recently seen device is dropped past this. */
+export const CLIENT_INSTANCE_MAX_DEVICES = 16
+
+export interface ClientInstanceRouterDeps {
+  now?: () => number
+}
+
+/** A POST that carries a meeting chunk: a live one, or an iPhone offline chunk replayed. The preview is not one. */
+export function isMeetingChunkPost(method: string, path: string): boolean {
+  return method === 'POST' && (path === '/transcribe-stream' || /^\/transcribe-stream\/offline-sessions\/[^/]+\/chunks$/.test(path))
+}
+
+/** `::ffff:100.64.1.2` and `100.64.1.2` are one device. */
+export function deviceKey(address: string | undefined): string {
+  const a = (address ?? '').trim()
+  return a.startsWith('::ffff:') ? a.slice(7) : (a || 'unknown')
+}
+
+export function createClientInstanceRouter(deps: ClientInstanceRouterDeps | (() => number) = {}): Router {
+  const opts: ClientInstanceRouterDeps = typeof deps === 'function' ? { now: deps } : deps
+  const now = opts.now ?? Date.now
+  const router = Router()
+  const owners = new Map<string, ClientInstanceOwner>()
+  const chunks = new ClientChunkLedger()
+  router.use((req, _res, next) => {
+    if (isMeetingChunkPost(req.method, req.path)) chunks.note(deviceKey(req.socket?.remoteAddress ?? req.ip), parseInstanceTag(req.query?.clientInstance), now())
+    next()
+  })
+  router.post('/client-instance/claim', (req, res) => {
+    const at = now()
+    const claim = parseClientInstanceClaim(req.body, at)
+    if (!claim) return void res.status(400).json({ error: 'invalid_claim' })
+    const device = deviceKey(req.socket?.remoteAddress ?? req.ip)
+    const previous = owners.get(device) ?? null
+    const evidence = previous ? chunks.evidence(device, previous.id, claim.id, at) : NO_CAPTURE
+    const captureLive = previous ? ownerIsRecording(previous, evidence, at) : false
+    const result = arbitrateClientInstance(previous, claim, at, evidence)
+    if (req.body?.check === true) {
+      const shown = previous ?? result.owner
+      return void res.json({ verdict: result.verdict, owner: { id: shown.id, bootAt: shown.bootAt, version: shown.version, seenAt: shown.seenAt }, check: true, captureLive })
+    }
+    owners.delete(device)
+    owners.set(device, result.owner)
+    while (owners.size > CLIENT_INSTANCE_MAX_DEVICES) owners.delete(owners.keys().next().value as string)
+    const owner = result.owner
+    if (result.took && previous && previous.id !== claim.id) {
+      console.log(`[client-instance] ${new Date(at).toISOString()} ${claim.id} (${claim.version}) took the ring from ${previous.id} on ${device}`)
+    }
+    res.json({
+      verdict: result.verdict,
+      owner: { id: owner.id, bootAt: owner.bootAt, version: owner.version, seenAt: owner.seenAt },
+      captureLive,
+    })
+  })
+  return router
+}