@gotcos/glasses-server 6.65.0 → 6.67.0

package/.env.example

@@ -340,3 +340,8 @@ BIND_HOST=0.0.0.0
 # additionally requires a client that acknowledges displaying continue_note.
 # Keep this in ~/.cos-glasses/.env; Control does not yet persist it on update.
 COS_CONTINUE_FULL_PERMISSIONS=1
+
+# Optional absolute executable paths for COS-managed whisper.cpp.
+# Unset uses Homebrew then PATH. An invalid explicit path fails closed.
+# COS_WHISPER_CLI_BIN=/absolute/path/to/whisper-cli
+# COS_WHISPER_SERVER_BIN=/absolute/path/to/whisper-server

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## 6.67.0 — 2026-10-09 — glasses pairing
+
+- Pair COS Glasses with your Mac by scanning a code instead of pasting the pairing token. COS Control shows a QR and a short code; the phone claims it, and nothing happens until you press Allow on the Mac. Pairs with COS Glasses 6.10.621 and the COS Control pairing release. Contract: `docs/pairing-contract.md`.
+  - `GET /api/health` adds `capabilities.pairing = { version: 1 }`. An older server leaves it out, which is how the phone knows to say "Update COS on your Mac".
+  - `POST /api/pairing/code` (token, and only from this Mac) makes an 8-character code, good for 5 minutes and one use, plus the QR text `COS1/MAC/<CODE>/<host>:<port>[+…]/<EXP>`, which uses only characters a QR can pack tightly. Tailscale addresses come first. A Wi-Fi address is offered only when "Allow pairing on this Wi-Fi" is on, and that lasts 10 minutes. A new code cancels the old one and any claim waiting for Allow.
+  - `POST /api/pairing/claim` and `GET /api/pairing/claim/<nonce>` need no token. A claim is accepted over Tailscale, or over the home Wi-Fi only while that is allowed. It waits up to 60 seconds for Allow. The phone then reads the pairing token once; a second read says `delivered` without it. The poll must come from the same address as the claim, and keeps answering during an update so an allowed token is never lost.
+  - `GET /api/pairing/status` and `POST /api/pairing/decision` (token, and only from this Mac) are how Control shows "wants to pair: Allow / Deny" and turns green, which happens only when the new phone makes its first signed-in request.
+  - Limits: 5 claims a minute per address, 20 tries per code (then it locks until a new code). The limits use the real connection address, never `X-Forwarded-For`.
+  - Everything is kept in memory. A restart forgets every code (`unknown_code`, a new `bootId`). The pairing routes write no files, so they never hold up an update; during one they answer `draining`.
+  - Logs carry the address, the result and a 2-character hash of the code, never the code, the nonce, the token or the QR text.
+- A rejected token now says "Paste the pairing token from COS Control, or scan its code with COS Glasses 6.10.621 or newer." The `reason` stays `pairing_token_rejected`.
+- The pairing token is still the only standing credential. See SECURITY.md.
+- Compatibility: nothing changes for existing users. Pasting the pairing token still works, and older COS Control and COS Glasses builds keep working with this server. Scanning needs COS Glasses 6.10.621 and the COS Control release with the Glasses setup section. The QR needs Tailscale on both the Mac and the iPhone, or the 10-minute "Allow pairing on this Wi-Fi" switch at home.
+- `docs/pairing-fixture.json` is a parity fixture the glasses app copies: the alphabet, real QR text, the reasons and the limits, checked against the server's code by its tests.
+
+## 6.66.0 — 2026-10-08 — Managed voice setup and Haiku polish
+
+- Advertise Haiku, Sonnet and GPT-5.6 Luna Fast. Default omitted-model polish to Haiku for lower cost, while honoring explicit model choices and retaining the transcript on failure.
+- Glasses app 6.10.616 explicitly sends the chosen model and already works with server 6.65.0.
+- Setup, live preview, committed transcription and HQ share explicit `COS_WHISPER_CLI_BIN` / `COS_WHISPER_SERVER_BIN` resolution. A broken explicit path fails closed; existing Homebrew/PATH detection remains the fallback.
+- COS Control can prepare Turbo first for a local benchmark, then the chosen tier, without overwriting saved voice settings. Both preparation flags require `--setup-transcription --prepare-only`.
+- Pairs with COS Control 0.5.273 and the signed/notarized whisper.cpp 1.9.1 runtime.
+- Claude health probes resolve the installed absolute binary path, including managed-service environments without the interactive shell PATH.
+
 ## 6.65.0 — 2026-10-07 — Work search by meaning, and task dates
 
 - `POST /api/work/search` `{ query, domain?, scope?, ids? }` finds the Work card the user means, not only the words they typed. Pairs with COS Control 0.5.259, which shows its own word matches at once and asks this after a pause.

package/README.md

@@ -646,18 +646,24 @@ and counts only, never a speaker name, path or error text; those stay in
 
 ## Final dictation polish (6.61.5)
 
-With glasses app 6.10.573, **Settings → Voice → Polish model** offers **Sonnet**
-(the default, using your Claude CLI sign-in) and **GPT-5.6 Luna Fast** (using your
-Cursor CLI sign-in). Luna uses `gpt-5.6-luna-none-fast`; it needs server 6.61.5.
-Both phone text and recovered audio drafts honor the choice. The server advertises
-these options in `capabilities.dictationCleanup.models` on health and models.
+With glasses app 6.10.616, **Settings → Voice → Polish model** offers **Haiku 5.5**
+(the lower-cost default), **Sonnet 5.5** (higher-quality polish), and **GPT-5.6 Luna Fast**.
+Haiku and Sonnet use your Claude CLI sign-in; Luna uses your Cursor CLI sign-in.
+Luna uses `gpt-5.6-luna-none-fast` and needs server 6.61.5. Existing explicit choices
+are preserved. Unset or unknown app preferences use Haiku. Both phone text and
+recovered audio drafts honor the choice. Existing server 6.65.0 already accepts
+explicit Haiku requests, so the new app does not require a server update.
+
+The next server release also defaults omitted-model requests to Haiku and advertises
+all three options in `capabilities.dictationCleanup.models`. Until that release,
+6.65.0 still defaults requests without a model to Sonnet; 6.10.616 sends its choice
+explicitly. This is a polish-model change, not a change to the speech recognition engine.
 
 Cleanup uses subscription CLIs only, with no API-key fallback or automatic model
 substitution. A failed or unavailable cleanup keeps the glossary-corrected
 transcript. Turn **Final polish (AI)** off to skip the model call. Claude tools
 and hooks are disabled; Cursor runs in read-only ask mode with a temporary profile
 and empty workspace. Live preview and canonical meeting transcription are unchanged.
-Older clients may still explicitly request Haiku.
 
 ## HQ dictation
 
@@ -917,3 +923,23 @@ This is a local owner instance, separate from app.gotcos.com tenants and hosted
 ## Provider parity in 6.62.0
 
 See [provider capabilities and limits](docs/provider-parity.md) for Continue permissions, client compatibility, hook trust, observation limits and rollback. Glasses 6.10.600 shows the server's Continue note. Older clients retain Cursor Ask behavior; forks remain read-only.
+
+### Managed Whisper runtime (6.66.0 candidate)
+
+COS Control 0.5.272 prepares a signed, notarized whisper.cpp 1.9.1 runtime during
+voice setup on Apple silicon. It supplies absolute `COS_WHISPER_CLI_BIN` and
+`COS_WHISPER_SERVER_BIN` paths to the server; Homebrew is not needed for that flow.
+Direct server installs still fall back to Homebrew and then PATH when overrides
+are unset. A configured but missing/non-executable override is an error, never a
+silent change of runtime.
+
+`--setup-transcription --prepare-only --voice-benchmark-prepare` prepares Turbo
+without changing saved tier keys. Control measures the device and follows with
+`--setup-transcription --prepare-only --transcription-tier balanced|max
+--preserve-voice-settings`. The latter prepares all required models, including
+Large-v3 for saved-meeting HQ in both tiers. Applying a tier remains Control's
+transactional action. Downloading or cancelling preparation does not change it.
+Runtime/model setup is local; the existing provider sign-in requirements remain.
+
+Candidate only: publish the versioned runtime asset and server package before
+promoting the matching Control appcast entry.

package/SECURITY.md

@@ -27,6 +27,22 @@ reproduction you have. Do not include real transcripts.
 
 - The pairing token (`X-Cos-Token`) is the only credential. Rotating it
   invalidates every display-stream ticket; there is no server-side ticket store.
+- Pairing codes (6.67.0, `docs/pairing-contract.md`) are not credentials. A code
+  lives 5 minutes in memory, works once, is made only over loopback with the token,
+  and releases the pairing token only after someone presses Allow on the Mac, and
+  then only once, to the address that claimed it. Claims are accepted over Tailscale
+  (100.64.0.0/10), or a private Wi-Fi address only while the user has allowed it for
+  10 minutes. Limits: 5 claims a minute per connection address, 20 tries per code.
+  Codes, nonces, tokens and QR text are never logged. The pairing token is still the
+  only standing credential.
+- A device on your tailnet can lock a live pairing code by guessing at it 20 times.
+  This is accepted: COS Control says why and offers a new code, and a code already
+  claimed is never locked by later guesses.
+- While "Allow pairing on this Wi-Fi" is on, the pairing token reaches the phone over
+  plain HTTP on that Wi-Fi, as the pasted token always has. Use it only at home; it
+  turns itself off after 10 minutes. Over Tailscale the traffic is encrypted.
+- Behind `tailscale serve` or `funnel`, requests arrive from a loopback proxy, so
+  every claim is refused (`not_allowed_network`): pairing fails closed there.
 - `GET /api/display-stream` is public by design and returns lifecycle events
   only. Content requires a ticket or the token header. See
   `server/routes/display.ts` for the allowlist.

package/bin/cli.cjs

@@ -25,7 +25,12 @@ const { homedir } = require('os')
 const PKG_ROOT = resolve(__dirname, '..')
 const CONFIG_DIR = join(homedir(), '.cos-glasses')
 const PREPARE_ONLY = process.argv.includes('--prepare-only')
+const VOICE_BENCHMARK_PREPARE = process.argv.includes('--voice-benchmark-prepare')
 const SETUP_TRANSCRIPTION = process.argv.includes('--setup-transcription')
+if ((VOICE_BENCHMARK_PREPARE || process.argv.includes('--preserve-voice-settings')) && !(SETUP_TRANSCRIPTION && PREPARE_ONLY)) {
+  console.error('Voice preparation flags require --setup-transcription --prepare-only.');
+  process.exit(64)
+}
 const SETUP_SPEAKER_MODEL = process.argv.includes('--setup-speaker-model')
 const HOOKS_ACTION = process.argv.includes('--hooks') ? process.argv[process.argv.indexOf('--hooks') + 1] : undefined
 function optionValue(name) {
@@ -540,12 +545,15 @@ function upsertEnvValue(file, key, value) {
   chmodSync(file, 0o600)
 }
 
-if (SETUP_TRANSCRIPTION) {
+if (SETUP_TRANSCRIPTION && !VOICE_BENCHMARK_PREPARE) {
+  const preserveVoiceSettings = process.argv.includes('--preserve-voice-settings')
   const previewModel = TRANSCRIPTION_TIER === 'max' ? 'turbo' : 'small.en'
   const commitModel = TRANSCRIPTION_TIER === 'max' ? 'large-v3' : 'turbo'
-  upsertEnvValue(ENV_FILE, 'COS_WHISPER_TRANSCRIPTION_TIER', TRANSCRIPTION_TIER)
-  upsertEnvValue(ENV_FILE, 'COS_WHISPER_PREVIEW_MODEL', previewModel)
-  upsertEnvValue(ENV_FILE, 'COS_WHISPER_COMMIT_MODEL', commitModel)
+  if (!preserveVoiceSettings) {
+    upsertEnvValue(ENV_FILE, 'COS_WHISPER_TRANSCRIPTION_TIER', TRANSCRIPTION_TIER)
+    upsertEnvValue(ENV_FILE, 'COS_WHISPER_PREVIEW_MODEL', previewModel)
+    upsertEnvValue(ENV_FILE, 'COS_WHISPER_COMMIT_MODEL', commitModel)
+  }
   process.env.COS_WHISPER_TRANSCRIPTION_TIER = TRANSCRIPTION_TIER
   process.env.COS_WHISPER_PREVIEW_MODEL = previewModel
   process.env.COS_WHISPER_COMMIT_MODEL = commitModel
@@ -573,8 +581,7 @@ if (!process.env.COS_PROFILE_PATH) process.env.COS_PROFILE_PATH = PROFILE_FILE
 
 // Step 5: local Whisper detection + model download. Voice stays local-only by
 // default; cloud fallback requires an explicit flag plus a configured key.
-const WHISPER_KNOWN_PATHS = ['/opt/homebrew/bin/whisper-cli', '/usr/local/bin/whisper-cli']
-const WHISPER_SERVER_KNOWN_PATHS = ['/opt/homebrew/bin/whisper-server', '/usr/local/bin/whisper-server']
+const { resolveWhisperBinary } = require('./whisper-runtime.cjs')
 const WHISPER_MODEL_DIR = join(homedir(), '.local/share/whisper-models')
 const WHISPER_MODEL_PATH = join(WHISPER_MODEL_DIR, 'ggml-large-v3-turbo.bin')
 const WHISPER_MODEL_PARTIAL = WHISPER_MODEL_PATH + '.partial'
@@ -591,24 +598,8 @@ const WHISPER_LARGE_MODEL_MIN_BYTES = 2_800_000_000
 const WHISPER_MODEL_EXPECTED_BYTES = 1_624_555_275
 const WHISPER_SMALL_MODEL_EXPECTED_BYTES = 487_614_201
 const WHISPER_LARGE_MODEL_EXPECTED_BYTES = 3_095_033_483
-function findWhisperCli() {
-  for (const p of WHISPER_KNOWN_PATHS) { if (existsSync(p)) return p }
-  try {
-    const found = execSync('command -v whisper-cli 2>/dev/null', { shell: '/bin/sh', stdio: 'pipe', timeout: 2000 }).toString().trim()
-    return found || null
-  } catch {
-    return null
-  }
-}
-function findWhisperServer() {
-  for (const p of WHISPER_SERVER_KNOWN_PATHS) { if (existsSync(p)) return p }
-  try {
-    const found = execSync('command -v whisper-server 2>/dev/null', { shell: '/bin/sh', stdio: 'pipe', timeout: 2000 }).toString().trim()
-    return found || null
-  } catch {
-    return null
-  }
-}
+function findWhisperCli() { return resolveWhisperBinary('whisper-cli') }
+function findWhisperServer() { return resolveWhisperBinary('whisper-server') }
 function isValidWhisperModel(p, minBytes = WHISPER_MODEL_MIN_BYTES) {
   if (!existsSync(p)) return false
   try { return statSync(p).size >= minBytes } catch { return false }
@@ -652,10 +643,10 @@ if (SETUP_TRANSCRIPTION && process.env.SKIP_WHISPER_DOWNLOAD !== '1') {
   mkdirSync(WHISPER_MODEL_DIR, { recursive: true })
   const targets = [
     [WHISPER_MODEL_PATH, WHISPER_MODEL_PARTIAL, WHISPER_MODEL_MIN_BYTES, WHISPER_MODEL_EXPECTED_BYTES],
-    ...(TRANSCRIPTION_TIER === 'balanced'
+    ...(!VOICE_BENCHMARK_PREPARE && TRANSCRIPTION_TIER === 'balanced'
       ? [[WHISPER_SMALL_MODEL_PATH, WHISPER_SMALL_MODEL_PARTIAL, WHISPER_SMALL_MODEL_MIN_BYTES, WHISPER_SMALL_MODEL_EXPECTED_BYTES]]
       : []),
-    [WHISPER_LARGE_MODEL_PATH, WHISPER_LARGE_MODEL_PARTIAL, WHISPER_LARGE_MODEL_MIN_BYTES, WHISPER_LARGE_MODEL_EXPECTED_BYTES],
+    ...(!VOICE_BENCHMARK_PREPARE ? [[WHISPER_LARGE_MODEL_PATH, WHISPER_LARGE_MODEL_PARTIAL, WHISPER_LARGE_MODEL_MIN_BYTES, WHISPER_LARGE_MODEL_EXPECTED_BYTES]] : []),
   ]
   const missingBytes = targets.reduce((sum, [path, , minimum, expected]) =>
     sum + (isValidWhisperModel(path, minimum) ? 0 : expected), 0)
@@ -716,7 +707,7 @@ if (process.env.COS_OPENAI_WHISPER_FALLBACK === '1') {
 
 const previewChoice = (process.env.COS_WHISPER_PREVIEW_MODEL || process.env.COS_WHISPER_REALTIME_MODEL || 'auto').trim().toLowerCase()
 const wantsSmallPreview = ['small', 'small.en', 'ggml-small.en.bin'].includes(previewChoice)
-if (whisperCliPath && wantsSmallPreview) {
+if (whisperCliPath && wantsSmallPreview && !VOICE_BENCHMARK_PREPARE) {
   if (isValidWhisperModel(WHISPER_SMALL_MODEL_PATH, WHISPER_SMALL_MODEL_MIN_BYTES)) {
     console.log(green('  ✓') + ' Small.en preview model ready ' + dim('— Turbo remains authoritative'))
   } else {
@@ -745,7 +736,7 @@ if (whisperCliPath && wantsSmallPreview) {
   }
 }
 
-if (whisperCliPath && SETUP_TRANSCRIPTION) {
+if (whisperCliPath && SETUP_TRANSCRIPTION && !VOICE_BENCHMARK_PREPARE) {
   if (isValidWhisperModel(WHISPER_LARGE_MODEL_PATH, WHISPER_LARGE_MODEL_MIN_BYTES)) {
     const largeRole = TRANSCRIPTION_TIER === 'max'
       ? 'live preview + commit and saved-meeting polish'
@@ -789,7 +780,7 @@ if (whisperCliPath && SETUP_TRANSCRIPTION) {
 // -- sixty times larger -- downloaded here with SKIP_WHISPER_DOWNLOAD as the
 // escape hatch. Same shape, same opt-out, so nobody on a metered or restricted
 // network is forced into it.
-if (!SETUP_SPEAKER_MODEL && process.env.SKIP_SPEAKER_MODEL_DOWNLOAD !== '1') {
+if (!VOICE_BENCHMARK_PREPARE && !SETUP_SPEAKER_MODEL && process.env.SKIP_SPEAKER_MODEL_DOWNLOAD !== '1') {
   const spkDest = join(CONFIG_DIR, 'models', SPEAKER_MODEL.filename)
   if (existsSync(spkDest) && sha256File(spkDest) === SPEAKER_MODEL.sha256) {
     console.log(green('  ✓') + ' Voiceprint model ready ' + dim('— named speakers available'))

package/bin/whisper-runtime.cjs

@@ -0,0 +1,17 @@
+// Shared by setup and both live Whisper workers. Explicit overrides fail closed.
+const { accessSync, constants, statSync } = require('node:fs')
+const { isAbsolute, join } = require('node:path')
+function executable(path) {
+  try { accessSync(path, constants.X_OK); return statSync(path).isFile() } catch { return false }
+}
+function resolveWhisperBinary(name, env = process.env, available = executable) {
+  if (!['whisper-cli', 'whisper-server'].includes(name)) throw new Error('Unknown Whisper binary')
+  const key = name === 'whisper-cli' ? 'COS_WHISPER_CLI_BIN' : 'COS_WHISPER_SERVER_BIN'
+  if (env[key] !== undefined && env[key] !== '') {
+    const path = env[key].trim()
+    return isAbsolute(path) && available(path) ? path : null
+  }
+  const candidates = ['/opt/homebrew/bin', '/usr/local/bin', ...(env.PATH || '').split(':')]
+  return candidates.filter(isAbsolute).map(p => join(p, name)).find(available) || null
+}
+module.exports = { resolveWhisperBinary }

package/bin/whisper-runtime.d.cts

@@ -0,0 +1 @@
+export function resolveWhisperBinary(name: 'whisper-cli' | 'whisper-server', env?: NodeJS.ProcessEnv, available?: (path: string) => boolean): string | null

package/docs/pairing-contract.md

@@ -0,0 +1,118 @@
+<!-- Copy of operations/personal/wk41_2026/CONTRACT_glasses_pairing_2026-10-09.md in the COS repo, the single source of truth for server 6.67.0, glasses 6.10.621 and the Control pairing branch. Server notes on what the contract left open are at the end. -->
+
+# Contract: glasses pairing (server 6.67.0, glasses 6.10.621, Control branch for Codex)
+
+This is the single source of truth for the three builders. Design and reasons: `PLAN_glasses_onboarding_quick_connect_2026-10-08.md`, sections v2 and v4.
+
+**Miles, 2026-10-09 07:23:** "We'll use the next version release as the canary. We'll start with Miles network, he should see the QR with the newer Activity setup view that contains the QR code for scanning."
+
+**Scope of this release: pairing only.** Durability (Part C), approve-from-glasses (Part B) and the tour come in later releases.
+
+## Capability
+- `GET /api/health` adds `capabilities.pairing = { version: 1 }`.
+- Clients check it before any pairing call. When it is missing, the phone says "Update COS on your Mac (server 6.67 or newer)" and Control shows "Update the server".
+
+## Code and QR grammar (the server builds both, clients only parse)
+- **Code:** 8 characters, Crockford base32 (`0123456789ABCDEFGHJKMNPQRSTVWXYZ`).
+  - Normalize input: uppercase it, map O→0, I and L→1, and strip spaces and dashes.
+  - Display it as `XXXX-XXXX`.
+- **QR text:** `COS1/MAC/<CODE>/<host>:<port>[+<host>:<port>]/<EXP>`
+  - All uppercase alphanumeric plus `/ : + .`, so the QR stays at version 3 or 4. (Changed from `,` after QA round 1: a comma is not in the QR alphanumeric set. The server writes `+`; clients accept `+` and `,`.)
+  - `<EXP>` is the expiry, in unix seconds, written in base36 uppercase.
+  - Hosts are IPv4 only, http. Tailscale (100.64.0.0/10) comes first; a LAN address (RFC1918) is included only while LAN pairing is armed.
+  - `MAC` is the kind. `CLOUD` is reserved for later. Any other kind, or a version other than `COS1`, is refused with "Update COS to use this code".
+  - Clients refuse hosts outside 100.64/10 and RFC1918.
+
+## Server routes (6.67.0)
+All under `/api/pairing`. Every response carries a `reason` string on failure. The reasons are:
+`expired`, `used`, `locked`, `rate_limited`, `not_loopback`, `not_allowed_network`, `unknown_code`, `denied`, `draining`, `bad_request`.
+
+| Route | Auth | Body or params | 200/202 response |
+|---|---|---|---|
+| `POST /pairing/code` | token **and** loopback socket (`req.socket.remoteAddress`, both forms; never `req.ip` or XFF) | `{ allowLan?: boolean }` (`allowLan` arms LAN claims for 10 minutes) | `{ code, display, qr, expiresAt, bootId, hosts:[{host,port,kind:'tailscale'|'lan'}], lanArmedUntil|null }`. A new code cancels the previous one and any pending claim. |
+| `POST /pairing/claim` | **public**, an exact `POST` match in `isPublicApiRequest`, with its own JSON parser capped at 1 KB | `{ code, nonce }` (`nonce` is 16 to 64 characters from `[A-Za-z0-9_-]`, made by the phone) | 202 `{ pending: true }`. Idempotent for the same nonce and code. |
+| `GET /pairing/claim/:nonce` | **public**, and the caller's socket IP must equal the claim's IP | | `{ state: 'pending'|'allowed'|'denied'|'expired'|'delivered', token?, serverName? }`. The token is returned **once** (the `allowed` state moves to `delivered`). A later read returns `delivered` with no token. |
+| `GET /pairing/status` | token and loopback | | `{ code: {display, expiresAt}|null, pending: {nonce, ip, at}|null, lastClaim: {ip, at, allowed}|null, firstAuthAfterClaimAt|null, lanArmedUntil|null, bootId }` |
+| `POST /pairing/decision` | token and loopback | `{ nonce, allow: boolean }` | `{ ok: true }` |
+
+### Rules
+- **Network:** a claim is accepted from 100.64/10. It is accepted from RFC1918 only while LAN is armed. Anything else gets `not_allowed_network`. This check sits on top of the existing network allowlist.
+- **Code lifetime:** 5 minutes, single use (the first successful claim moves it to `used`).
+- **Pending claims:** one at a time. A pending claim waits up to 60 s for a decision, then becomes `expired`. A second claim while one is pending is refused with `locked`, and that does not cancel the first.
+- **Limits:**
+  - 5 claim attempts per minute per socket IP, then `rate_limited`.
+  - 20 attempts per code, then the code is `locked` until a new code is made.
+  - The limiter keys on the socket IP. Trust-proxy is never enabled.
+- **State:** in memory only. A restart loses codes, so a claim with an old code gets `unknown_code`, and `bootId` changes.
+- **Drain:** the pairing routes are exempt from the mutation lease, since they write no files. When shutting down, `code`, `claim`, `status` and `decision` return 503 `draining`. The poll `GET /pairing/claim/:nonce` is still served (QA round 1), so a token already allowed reaches the phone even if the update gate closes before the next poll.
+- **First authenticated call:** when a request passes `requireApiToken` and its socket IP equals an allowed `lastClaim.ip`, stamp `firstAuthAfterClaimAt` once.
+- **Logging:** never the code, nonce, token or QR text. Log the IP, the result, and the first 2 characters of a sha256 of the code. A test must fail if any of those values appear in log output.
+- **Docs:**
+  - SECURITY.md: the pairing token is still the only standing credential; pairing codes are short-lived and single use.
+  - `docs/pairing-contract.md`: a copy of this file.
+  - Change the 401 copy to "Paste the pairing token from COS Control, or scan its code with COS Glasses 6.10.621 or newer." (QA round 1: older glasses show it word for word.) The `reason` value stays `pairing_token_rejected`.
+
+## Glasses 6.10.621
+- **Parser:** `src/lib/pair-code.ts` parses the QR grammar, normalizes codes and orders hosts. It is unit tested and exposed to the ES5 wizard as `window.__COS_PAIR`.
+- **Scan entry points:**
+  - the wizard Start screen (first option, "Scan code on your Mac")
+  - `setup-step1` (the reauth path)
+  - the Settings overlay
+  - the local starter banner's Connect Mac
+- **Ways in:**
+  - **Scan:** `window._evenBridge.captureImageFromCamera()`
+  - **Use a screenshot:** `pickImageFromAlbum()`
+  - **Type the code:** the code plus the Mac address
+  - Scan and screenshot are shown only when the bridge method is a function.
+- **Decoding:** jsQR, decoding at the native width capped at 1920, then a second pass at 1280. A miss shows "Move closer so the code fills your screen".
+- **Flow:**
+  1. Check health on the first host that answers (try hosts in order, 3 s each).
+  2. Make a nonce, then claim.
+  3. Poll `GET /pairing/claim/:nonce` every 1.5 s for up to 70 s. The screen and the lens say "Waiting for Allow on your Mac".
+  4. When the token arrives, write `cos_server_url = http://host:port` and `cos_api_token`, then run the existing `fetchAuthenticatedTarget`, then `finishConnectedSetup`, exactly as the IP form does.
+  5. Keep the token in memory and retry if `/api/models` fails.
+- **Re-pairing:** when a committed target already exists, ask "Replace <old host> with <host>?" first.
+- **Lens lines:** "Pairing with your Mac…", "Waiting for Allow on your Mac", "Paired", "Code expired: show a new one", "Mac is updating". Each fits 6 lines and the width, using only drawable glyphs. isWearing is never used.
+- **Manifest:** `camera` and `album` go in app.json **and** app-hub.json. Update `verify-timer-quarantine-build.mjs` and the `marketplace-hardening` pin. Strip URL-bearing comments from the jsQR bundle. Add a `THIRD_PARTY_NOTICES` entry.
+- **Version touchpoints:** COS_VERSION, package.json, package-lock (both fields), CHANGELOG, the index.html changelog, app.json, app-hub.json, and the Hub receipt.
+
+## Control (branch off `origin/codex/whisper-runtime` 601a944, released by Codex)
+- **New helper verbs:**
+  - `tailscale-status` runs the Tailscale bundle binary, `/Applications/Tailscale.app/Contents/MacOS/tailscale`, with **`SHLVL=1`** in the child's environment. It returns `{installed, running, selfIPv4, selfDNS, peers:[{os, dns, ipv4, online, sameUser}]}`, read from `status --json`. Use `Self.UserID` to work out `sameUser`; never use `HostName`.
+  - `tailscale-whois <ip>` returns `{node, os, user}`.
+  - `pairing-code [--allow-lan]`, `pairing-status` and `pairing-decision <nonce> allow|deny` call the server routes above over loopback with the token.
+- **Setup guide, new "Glasses" section.** It is **not counted** in Finish setup, and it replaces `GlassesGuideRow`. It has three rows:
+  1. **Tailscale on this Mac:**
+     - not installed: Get Tailscale (https://tailscale.com/download/mac)
+     - signed out: Open Tailscale
+     - running: green, with the address
+  2. **Tailscale on your iPhone:**
+     - shows a QR for `https://apps.apple.com/app/tailscale/id1470499037`
+     - copy: "Sign in with the same account as this Mac"
+     - turns green when a same-user iOS peer is online, naming it ("iphone-15-pro-max is on your tailnet")
+  3. **Connect your glasses:**
+     - Shown only when `capabilities.pairing` is present.
+     - The QR is drawn with CoreImage `CIQRCodeGenerator`, correction level Q, from the server's `qr` string, at least 220 pt. Show `display` and the first host as text, with the copy "Hold your phone so the code fills the screen".
+     - Re-mint only while the pane is visible: when the code expires or `bootId` changes, and on **Show a new code**.
+     - When `pending` appears, show the **Allow / Deny** card: "<whois node> (<user>) wants to pair". For a non-tailnet IP: "Device on Wi-Fi <ip>".
+     - It turns green on `firstAuthAfterClaimAt`, showing "Paired: <node>, <time>".
+     - "Allow pairing on this Wi-Fi (home only)" is a toggle (`--allow-lan`), off by default.
+- **Plumbing:** add new Swift files to every `Tests/run.sh` source list. Every compile goes through `Tests/compile-guard.sh`, one at a time.
+- **Reset pairing** (token rotation): **not in this release.** It ships with Part B.
+
+## Server 6.67.0: what the contract left open, as built
+
+- **Times** in JSON (`expiresAt`, `lanArmedUntil`, `at`, `firstAuthAfterClaimAt`) are ISO 8601 strings, or null. Only the QR `<EXP>` is base36 unix seconds.
+- **No host:** when the Mac has no Tailscale IPv4 and LAN is not armed, `POST /pairing/code` still mints, with `hosts: []` and `qr: null`, so Control can say why instead of drawing a QR no phone can use.
+- **Hosts:** at most 3, Tailscale first. LAN addresses come only from RFC1918 on interfaces a phone can reach (never `utun` VPNs that are not Tailscale, `bridge`, `awdl`, `llw`, `vmnet`, `vboxnet`).
+- **allowLan:** `true` arms LAN for 10 minutes; a mint without it disarms LAN, so Control's toggle is the source of truth.
+- **Failures** are `{ reason, message }`: 400 `bad_request`, 403 `not_loopback` / `not_allowed_network` / `denied`, 404 `unknown_code`, 409 `used` / `locked`, 410 `expired`, 429 `rate_limited` (with `Retry-After`), 503 `draining`.
+- **Poll:** an unknown nonce (for example after a restart) is 404 `unknown_code`; a poll from a different socket IP is 403 `not_allowed_network` and does not spend the token. `serverName` comes with the token and with `delivered`. Only a real GET may read the token: a HEAD (which needs the token header to get past the gate at all) is answered 405.
+- **Status:** `code` is present while the current code is unexpired and carries an extra `state: 'active'|'used'|'locked'`.
+- **Decision** on a nonce that is not pending: 404 `unknown_code`, 410 `expired`, or 409 `used` (already decided).
+- **Per-code limit:** every claim attempt while a code is active counts against it, right code or wrong; the 21st attempt locks it. Once a code is `used`, later attempts neither count nor lock it: the right code answers `locked` while its claim waits for Allow and `used` after, a wrong one `unknown_code`. Codes are compared in constant time.
+- **firstAuthAfterClaimAt** is stamped only after the allowed claim's token was delivered, on the first token-authenticated request from that claim's IP. A new Allow clears it.
+- **Draining** means the server is shutting down or the maintenance gate is closed (an update in progress, including the startup gate before Control releases it). The poll is never refused for draining.
+- **Loopback** accepts any 127.0.0.0/8, `::1` and `::ffff:127.x` socket at the pairing check, but the server's global network allowlist (unchanged) admits only `127.0.0.1` and `::1` exactly, so another 127.x address is refused before pairing sees it.
+- **QR alphabet:** hosts are joined with `+`, which is in the QR alphanumeric set (`0-9 A-Z space $ % * + - . / :`), so every QR the server writes can be encoded in alphanumeric mode.
+- **Parity fixture:** `docs/pairing-fixture.json` holds the alphabet, nonce pattern, QR pattern and charset, normalization cases, two real `buildPairingQr` outputs (one and two hosts), the reason list with statuses and messages, the poll states and the limits. `server/lib/glasses-pairing.test.ts` recomputes every value, so it fails if the fixture drifts. Clients copy it; nobody edits it by hand.

package/docs/pairing-fixture.json

@@ -0,0 +1,94 @@
+{
+  "$comment": "Server-generated parity fixture for glasses pairing (docs/pairing-contract.md). server/lib/glasses-pairing.test.ts fails if any value here stops matching what the server produces. Clients copy it; never hand-edit it.",
+  "protocolVersion": 1,
+  "capability": {
+    "pairing": {
+      "version": 1
+    }
+  },
+  "alphabet": "0123456789ABCDEFGHJKMNPQRSTVWXYZ",
+  "codeLength": 8,
+  "noncePattern": "^[A-Za-z0-9_-]{16,64}$",
+  "qrHostSeparator": "+",
+  "qrPattern": "^COS1\\/MAC\\/[0-9A-HJKMNP-TV-Z]{8}\\/(?:\\d{1,3}(?:\\.\\d{1,3}){3}:\\d{1,5})(?:\\+\\d{1,3}(?:\\.\\d{1,3}){3}:\\d{1,5})*\\/[0-9A-Z]+$",
+  "qrCharset": "^[0-9A-Z/:+.]+$",
+  "normalize": {
+    "abcd-efgh": "ABCDEFGH",
+    " oOil LI10 ": "00111110",
+    "7k3m 9pqr": "7K3M9PQR",
+    "ABCD-EFGU": null,
+    "ABCD-EFG": null
+  },
+  "examples": [
+    {
+      "code": "7K3M9PQR",
+      "display": "7K3M-9PQR",
+      "expiresAtMs": 1791547500000,
+      "hosts": [
+        {
+          "host": "100.100.10.20",
+          "port": 3141,
+          "kind": "tailscale"
+        }
+      ],
+      "qr": "COS1/MAC/7K3M9PQR/100.100.10.20:3141/TMN2WC"
+    },
+    {
+      "code": "7K3M9PQR",
+      "display": "7K3M-9PQR",
+      "expiresAtMs": 1791547500000,
+      "hosts": [
+        {
+          "host": "100.100.10.20",
+          "port": 3141,
+          "kind": "tailscale"
+        },
+        {
+          "host": "192.168.1.20",
+          "port": 3141,
+          "kind": "lan"
+        }
+      ],
+      "qr": "COS1/MAC/7K3M9PQR/100.100.10.20:3141+192.168.1.20:3141/TMN2WC"
+    }
+  ],
+  "reasons": {
+    "bad_request": 400,
+    "not_loopback": 403,
+    "not_allowed_network": 403,
+    "denied": 403,
+    "unknown_code": 404,
+    "used": 409,
+    "locked": 409,
+    "expired": 410,
+    "rate_limited": 429,
+    "draining": 503
+  },
+  "reasonMessages": {
+    "bad_request": "That pairing request was not understood. Scan the code again.",
+    "not_loopback": "Pairing codes are made only by COS Control on this Mac.",
+    "not_allowed_network": "Connect over Tailscale, or turn on \"Allow pairing on this Wi-Fi\" in COS Control.",
+    "denied": "Pairing was denied on the Mac.",
+    "unknown_code": "This code is not current. Show a new one in COS Control.",
+    "used": "This code was already used. Show a new one in COS Control.",
+    "locked": "Too many tries, or another device is waiting. Show a new code in COS Control.",
+    "expired": "Code expired: show a new one in COS Control.",
+    "rate_limited": "Too many tries. Wait a minute and try again.",
+    "draining": "Your Mac is updating. Try again in a minute."
+  },
+  "pollStates": [
+    "pending",
+    "allowed",
+    "denied",
+    "expired",
+    "delivered"
+  ],
+  "limits": {
+    "codeTtlMs": 300000,
+    "pendingTtlMs": 60000,
+    "lanArmMs": 600000,
+    "claimsPerIpPerMinute": 5,
+    "attemptsPerCode": 20,
+    "maxQrHosts": 3
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.65.0",
+  "version": "6.67.0",
   "description": "COS Glasses: 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": {
@@ -47,6 +47,7 @@
     "!server/scripts/work-intake-mutation-gate.mjs",
     "!server/scripts/work-progress-mutation-gate.mjs",
     "!server/scripts/work-search-mutation-gate.mjs",
+    "!server/scripts/pairing-mutation-gate.mjs",
     "!server/scripts/away-hold-mutation-gate.mjs",
     "!server/scripts/nemotron-mutation-gate.mjs",
     "!server/scripts/merged-scribe-mutation-gate.mjs",
@@ -77,7 +78,11 @@
     "docs/work-task-runtime.md",
     "!server/scripts/build-work-task-runtime.py",
     "bin/hooks/cos-cursor-observer.cjs",
-    "docs/provider-parity.md"
+    "docs/provider-parity.md",
+    "docs/pairing-contract.md",
+    "docs/pairing-fixture.json",
+    "bin/whisper-runtime.cjs",
+    "bin/whisper-runtime.d.cts"
   ],
   "author": "COS Contributors",
   "license": "MIT",

package/server/index.ts

@@ -8,7 +8,7 @@ import { fileURLToPath } from 'node:url'
 import { createServer as createHttpsServer } from 'node:https'
 import { createServer as createHttpServer } from 'node:http'
 import { readFileSync, existsSync } from 'node:fs'
-import { networkInterfaces, homedir } from 'node:os'
+import { networkInterfaces, homedir, hostname } from 'node:os'
 import { join } from 'node:path'
 import { execSync } from 'node:child_process'
 import { randomBytes, randomUUID } from 'node:crypto'
@@ -162,9 +162,12 @@ import {
 import {
   isAllowedNetworkIp,
   isAllowedNetworkOrigin,
-  isTailscaleIpv4,
+  isLoopbackSocket,
+  reachableIpv4Addresses,
 } from './lib/network-policy.js'
 import { requireApiToken } from './lib/api-auth.js'
+import { PairingState, pairingHostsFrom } from './lib/glasses-pairing.js'
+import { createPairingRouter } from './routes/pairing.js'
 import { isManagedRuntime } from './lib/managed-runtime.js'
 import { reportClaudeExtraToolConfiguration } from './lib/claude-tool-access.js'
 import {
@@ -317,7 +320,27 @@ if (threadAttachEnabled()) {
 // authenticated /tts/prepare for native audio players) and
 // /display-stream/<exp>.<hmac> GET/HEAD (minted on authenticated /api/models for
 // EventSource, which cannot set X-Cos-Token either). See api-auth.ts.
-app.use('/api', requireApiToken(API_TOKEN))
+// 6.67.0 glasses pairing state: in memory only, so a restart loses every code and
+// claim and `bootId` changes (docs/pairing-contract.md).
+const pairingState = new PairingState({
+  token: () => API_TOKEN,
+  // The Mac's name as the phone shows it ("Paired with <name>").
+  serverName: () => hostname().replace(/\.local$/i, ''),
+  hosts: lanArmed => pairingHostsFrom(reachableIpv4Addresses(networkInterfaces()), PORT, lanArmed),
+})
+app.use('/api', requireApiToken(API_TOKEN, {
+  onAuthenticated: req => pairingState.noteAuthenticated(req.socket?.remoteAddress),
+}))
+
+// Pairing routes sit HERE on purpose: after the token gate (mint, status and decision
+// need it; the claim and its poll are exact public doors in api-auth.ts), and BEFORE the
+// mutation-lease catch-all and the global 10 MB parser. They write no files, so they
+// never hold the lease, and each parses its own body at 1 KB. During a drain or
+// shutdown they answer 503 `draining`.
+app.use('/api', createPairingRouter({
+  state: () => pairingState,
+  isDraining: () => gracefulShutdownStarted || !maintenanceAdmissionsOpen(),
+}))
 
 // Fail-closed catch-all for mutation routes that do not own a more specific
 // lifecycle lease below. This closes the admission/drain race for secondary
@@ -375,9 +398,7 @@ app.use('/api', (req, res, next) => {
   // still closed. Permit only its two bounded loopback proofs, and only with
   // the controller-held operation receipt. Normal phone/LAN admissions stay
   // closed throughout the update.
-  const address = req.socket.remoteAddress ?? ''
-  const loopback = address === '::1' || address === '127.0.0.1'
-    || address.startsWith('127.') || address.startsWith('::ffff:127.')
+  const loopback = isLoopbackSocket(req)
   const controllerProofPath = req.path === '/diagnostics/provider-proof'
     || req.path === '/tts/prepare'
   const controllerProof = loopback && controllerProofPath
@@ -1225,17 +1246,11 @@ listenRequiredServers(listeners).then(() => {
   // Print ADDRESSES THE PHONE CAN ACTUALLY REACH. The bind address (0.0.0.0) is
   // not paste-able — enumerate real interfaces and label the Tailscale one.
   try {
-    const nets = networkInterfaces()
-    const addrs: Array<{ ip: string; label: string }> = []
-    for (const [name, infos] of Object.entries(nets)) {
-      for (const info of infos ?? []) {
-        if (info.family !== 'IPv4' || info.internal) continue
-        const isTailscale = isTailscaleIpv4(info.address) || name.startsWith('tailscale')
-        addrs.push({ ip: info.address, label: isTailscale ? 'Tailscale — works from anywhere' : `${name} — same Wi-Fi only` })
-      }
-    }
+    const addrs = reachableIpv4Addresses(networkInterfaces()).map(entry => ({
+      ip: entry.address,
+      label: entry.kind === 'tailscale' ? 'Tailscale — works from anywhere' : `${entry.name} — same Wi-Fi only`,
+    }))
     if (addrs.length > 0) {
-      addrs.sort((a, b) => Number(b.label.startsWith('Tailscale')) - Number(a.label.startsWith('Tailscale')))
       console.log('')
       console.log('[COS API] Server URL for the COS Glasses app:')
       for (const a of addrs) console.log(`[COS API]   http://${a.ip}:${PORT}   (${a.label})`)