@gotcos/glasses-server 6.87.0 → 6.89.0

package/.env.example

@@ -53,6 +53,13 @@ BIND_HOST=0.0.0.0
 # server after Wi-Fi/Tailscale changes and process restarts.
 # COS_SERVER_INSTANCE_ID_PATH=/path/to/server-instance-id
 
+# 6.89.0 Tailscale self-heal. After a restart, a wake from sleep, a Tailscale
+# restart or a network change, or when a recently active phone goes quiet while
+# Tailscale says it is online, the server runs a bounded `tailscale ping` at it
+# (at most one a minute per phone, 30 an hour). On by default; 0 turns it off.
+# See docs/tailscale-self-heal.md.
+# COS_TAILSCALE_NUDGE=0
+
 # Build 204+ uses server-owned durable query jobs by default. The server fsyncs an
 # accepted prompt before returning 202, then keeps provider work running if the
 # phone backgrounds, reloads, or changes networks. Reopening COS reattaches to

package/CHANGELOG.md

@@ -1,3 +1,100 @@
+## 6.89.0 - LAN first removed; the Mac nudges a stale Tailscale tunnel back to life
+
+Miles, 2026-10-23 19:57: no LAN-only code, because he uses COS away from home; and checks around the nudge so the
+Tailscale connection always comes back. After the 10/22 Mac restart the phone's Tailscale extension kept a stale tunnel:
+Tailscale's own ping went through, no COS request did, and only toggling Tailscale on the phone fixed it. Contract and
+field canary: `docs/tailscale-self-heal.md`.
+
+- **LAN first is gone.** Removed: public `GET /api/route-proof`, `routes` on `/api/models`, `capabilities.routeProof` and
+  `capabilities.lanRoutes`, `COS_LAN_FIRST`, `server/lib/lan-first.ts`, `server/routes/route-proof.ts`,
+  `docs/lan-first.md`, the SECURITY.md note, their tests and gate (reverts c593b91). `/api/models` is the 6.87.0 shape
+  path for path, and `/api/health` is 6.87.0 plus `tailscaleNudge`, both checked against goldens captured from
+  601d807. `/api/route-proof` is an unknown path behind the token again. `COS_LAN_FIRST` is read by nothing.
+- **Kept:** 6.88.0's transfer integrity against the phone's final index and the origin-wipe recovery save that waits
+  for it (fc52f49), and the older opt-in "Allow pairing on this Wi-Fi" pairing switch (6.67.0).
+- **The nudge** (`server/lib/tailscale-nudge.ts`). `tailscale ping -c 3 --timeout 5s <peer>` (disco: both ends redo
+  path discovery), then, only after a pong, `tailscale ping --icmp -c 1 --timeout 5s <peer>` (one packet through
+  WireGuard, which starts a fresh handshake on a stale session). `execFile` from a fixed path, never a shell.
+- **Triggers:** 30 s after boot; a wake from sleep (the wall clock outran the monotonic clock by 20 s); a change in
+  this Mac's IPv4 interfaces; a change in Tailscale's own state (BackendState, this Mac's Tailscale IPs, or peer byte
+  counters going backwards, meaning tailscaled restarted); and a phone that made an authenticated request in the last
+  5 minutes, or sent meeting chunks in the last 15 minutes while a meeting is open, silent for 45 s. Every one needs
+  the peer `Online` in a status read at most 15 s old and Tailscale `Running`: absence of requests alone never nudges.
+- **Caps:** one nudge per peer per 60 s, doubling per unanswered nudge to 15 minutes, reset by any request; 30 an hour
+  in all; one pass at a time; hard timeouts (5, 20 and 10 s, SIGKILL). `COS_TAILSCALE_NUDGE=0` turns it off, read
+  every tick, forwarded by the managed runtime contract. No LLM, no disk write, no new route.
+- **What it says.** `[tailscale-nudge]` log lines with trigger, outcome, timing, handshake age and byte movement, never
+  an address; `tailscaleNudge { enabled, available, lastAt, lastTrigger, lastOutcome, lastDataPath, lastRecoveredAt,
+  nudgesLastHour }` on public `/api/health`.
+- **Phone contract for glasses 6.10.653** (not built here): retry with fresh `no-store` requests on a 2, 4, 8, 15, 30 s
+  ladder, show 6.10.652's stuck-Tailscale message only after 90 s, read `tailscaleNudge`, and the iOS VPN On Demand note.
+
+## 6.88.0 - LAN first: a pre-token route proof and the Mac's addresses for the phone
+
+The server half of the glasses "LAN first" reconnect plan (plan of 2026-10-22, Miles's decisions of 2026-10-23: "Go
+with your picks on the reconnect plan. No regressions or loss of existing functionality."). After the 10/22 Mac restart
+the phone stayed on a stale Tailscale tunnel while the Mac answered fine on the same Wi-Fi. These two additions let a
+phone build reach the Mac over the home network first, without ever sending its token to the wrong machine. Contract
+for the phone side: `docs/lan-first.md`.
+
+- **`GET /api/route-proof?nonce=<22 to 64 base64url characters>`, public.** Answers `{ v: 1, serverInstanceId, proof }`,
+  where `proof` is lowercase hex HMAC-SHA256(token, "cos-route-proof:v1:" + nonce + ":" + serverInstanceId). The phone
+  computes the same HMAC with its stored token and sends `X-Cos-Token` to that address only on a match. The token is never
+  in the response, the nonce is never echoed or logged, and the caller chooses only the nonce, so the route is not a
+  general HMAC oracle; the fixed prefix also keeps a proof from ever being a display-stream ticket. Exact public door,
+  GET only (`server/lib/api-auth.ts`); every other verb and path stays behind the token. Errors: 400 `bad_nonce`,
+  404 `disabled`, 405 `method_not_allowed`, 429 `rate_limited` (with `Retry-After`), 503 `not_ready`.
+- **Rate limited.** 20 a minute per socket address and 240 a minute in all, in memory; bad nonces spend the same budget.
+- **Only for a strong token.** A proof lets anyone who reaches the port test guesses offline, so it is served (and
+  advertised) only when the token is 32 characters or more. Tokens made by COS Control (64) and by the server (44) qualify;
+  a short hand-set legacy token keeps today's behaviour.
+- **`routes` on authenticated `/api/models` only.** `{ v: 1, serverInstanceId, learnedAt, lan: [{ip, port, scheme}],
+  tailscale: [{ip, port, scheme}] }`: RFC1918 IPv4 on real interfaces (tunnels, Internet Sharing and VM bridges, Docker,
+  AirDrop and link-local left out) and 100.64/10 on Tailscale's own interface, plain http on `PORT` (3141). Re-read at
+  most every 10 s, so a new DHCP lease shows up; a failed interface read omits the field and leaves the rest of the
+  response alone. Never on public `/api/health`. The MagicDNS name is left out (reading it needs a `tailscale`
+  process per request).
+- **Capability flags.** `capabilities.routeProof: { protocol: 1 }` and `capabilities.lanRoutes: { protocol: 1 }` on
+  `/api/health` and `/api/models`, from one helper. An older server omits both, and a phone keeps today's single URL.
+- **Switch.** `COS_LAN_FIRST=0` turns both pieces off, read per request; the responses are then the 6.87.0 shape exactly.
+- **No regression.** Every existing field of `/api/health` and `/api/models` is unchanged, checked path for path against
+  a golden captured from the unmodified 6.87.0 base, and byte for byte against the same response with the switch off.
+- **Not built:** Phase 3's loopback `/api/glasses/link` for COS Control's banner. It needs new tracking of the phone's
+  last path and check-in, so it is not a purely additive change.
+- **No spend.** No LLM, no new caller, nothing written to disk.
+- **Checks (6.88.0 branch).** Full suite, serial (`--maxWorkers=1`), HOME, COS_DATA_DIR and COS_PROFILE_PATH in a scratch folder,
+  COS_SCRIPTS_DIR unset. Unmodified 6.87.0 base (601d807): 584 files (583 passed, 1 skipped), 8815 tests, 8801 passed,
+  14 skipped, 0 failed. This branch: 588 files (587 passed, 1 skipped), 8911 tests, 8897 passed, 14 skipped, 0 failed.
+  The 96 new tests are the only change per file (`lan-first.test.ts` 58, `route-proof.test.ts` 18, `health-lan-first.test.ts`
+  9, `lan-first-wiring.test.ts` 2, `api-auth.test.ts` 40 to 49); no existing test was changed. Mutation gate
+  `lan-first-mutation-gate.mjs` against a green baseline (136 tests in 5 files): 56 of 56 killed, each by a named test,
+  every target landing exactly once and restored byte for byte. Its first run left two survivors (the IPv4-only filter and
+  the de-duplication), each now covered by its own test and killed. `tsc --noEmit` clean. Pack dry run 549 files
+  (6.87.0: 546; the three new files are `server/lib/lan-first.ts`, `server/routes/route-proof.ts` and `docs/lan-first.md`).
+
+### Also in 6.88.0: transfer integrity counts what the phone captured, and recovery saves wait for it
+
+For glasses 6.10.652 (meeting t2xs9u, 2026-10-23 07:59): a relaunched COS window saved a meeting from the Mac's 74 chunks
+while the window still recording it had captured through index 120, and the file said "Transfer integrity 100%". One new
+file (`server/lib/transfer-integrity.ts`) and two edits in `performSave` (`server/routes/meeting.ts`).
+
+- **Integrity counts the phone's final index.** When the phone has said how far it captured (the Stop intent's
+  `finalChunkIndex`, or the save's own new optional `finalChunkIndex`), expected is that index plus one and every index past
+  the Mac's highest chunk is missing. 74 of 121 now reads 61.1% with 47 chunks not received, in the saved markdown, the
+  sidecar and the receipt. A final index more than 20,000 past the Mac's highest chunk is capped there; a malformed one is
+  ignored.
+- **A recovery save waits.** A save with `recovery: 'origin_wipe'` (glasses 6.10.652) is refused with 409
+  `chunks_outstanding` (`missingCount`, `finalChunkIndex`) while the phone's final index says the Mac lacks chunks, and
+  nothing is saved or closed. `acceptMissing: true` (the phone waited its 10 minutes) saves what the Mac has, honestly counted.
+- **Unchanged:** a save without `recovery` is never refused here; a save with no final index from anywhere writes exactly
+  what 6.87.0 wrote; an already saved meeting replays its receipt first; the autonomous save, the stop route and the status
+  route are untouched. No new log line, no LLM, no new disk write. Contract: `docs/meeting-autonomous-save.md`, section 6.88.0.
+- **Checks (integrity, on top of c593b91).** Full suite, serial, the same scratch folder rules: 590 files, 8926 tests, 8912
+  passed, 14 skipped, 0 failed (the LAN-first record above is 8911 tests; the 15 new ones are `transfer-integrity.test.ts` 5
+  and `meeting-save-integrity.test.ts` 10; no existing test was changed). Mutation gate `integrity-6880-mutation-gate.mjs`
+  against a green baseline (15 tests in 2 files): 15 of 15 killed, each by a named test. `tsc --noEmit` clean. Pack dry run
+  551 files (the LAN-first 549 plus `server/lib/transfer-integrity.ts` and the gate script).
+
 ## 6.87.0 - A rough level per chunk for COS Control's glasses meeting strip
 
 The server half of the level strip COS Control 0.5.339 draws in a glasses meeting's bottom bar (plan of 2026-10-23,

package/SECURITY.md

@@ -43,6 +43,11 @@ reproduction you have. Do not include real transcripts.
   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.
+- 6.89.0 Tailscale self-heal (`docs/tailscale-self-heal.md`): the server runs `tailscale status --json`
+  and `tailscale ping` at a peer that Tailscale reports online, with `execFile` from a fixed path and a
+  fixed argument list (the only variable is a 100.64.0.0/10 address read from Tailscale's own status).
+  Never a shell. Public `/api/health` shows when it last ran and the outcome, never an address.
+  `COS_TAILSCALE_NUDGE=0` turns it off.
 - `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/docs/tailscale-self-heal.md

@@ -0,0 +1,159 @@
+# Tailscale self-heal (server 6.89.0)
+
+COS is used away from home, over Tailscale. The problem this solves: after the Mac restarts, wakes
+from sleep, restarts Tailscale or changes network, the phone can stay on a stale Tailscale tunnel.
+Tailscale says the phone is online and its own ping gets through, yet no COS request arrives, and
+the only fix used to be toggling Tailscale on the phone. 6.89.0 adds a bounded Mac-side "nudge" and
+a contract for the phone side. Code: `server/lib/tailscale-nudge.ts`.
+
+6.89.0 also removes 6.88.0's LAN-first pieces (`GET /api/route-proof`, `routes` on `/api/models`,
+`capabilities.routeProof` and `capabilities.lanRoutes`, `COS_LAN_FIRST`). Tailscale already takes
+the direct path over the home Wi-Fi when both ends are home, so a separate LAN route added nothing
+for the away-from-home case. `COS_LAN_FIRST` is now read by nothing.
+
+## What the Mac can see (read-only probes, 2026-10-23, Tailscale 1.102.2 on macOS)
+
+`tailscale status --json`, the phone's peer entry while COS was working normally:
+
+| Field | Value seen | What it tells us |
+|---|---|---|
+| `Online` | `true` | Control-plane presence. It stays true while the iOS extension runs, stale tunnel or not, so on its own it proves nothing about the data path. |
+| `Active` | `true` | Recent traffic in the engine. |
+| `CurAddr` | the phone's home Wi-Fi address and port | A direct path. Away from home it is a public address, or empty when relayed. |
+| `Relay` | the home DERP region | The fallback relay. |
+| `LastHandshake` | 60 s old, refreshing about every 2 minutes | The WireGuard session is being renewed. A handshake much older than about 3 minutes while `Active` is true is suspicious. |
+| `LastSeen` | zero time | Only set while the peer is offline. |
+| `RxBytes` / `TxBytes` | grew by about 9 KB and 18 KB in 12 s | Per-peer counters for the life of tailscaled. They reset when tailscaled restarts, which is how the server detects a Mac-side Tailscale restart. |
+
+`tailscale ping -c 3 --timeout 5s <phone>` answered once, `via <home address>:41641 in 91ms`, and
+stopped: it stops at the first direct pong. `tailscale ping --icmp -c 1 --timeout 5s <phone>`
+answered `via ICMP in 27ms`. The CLI's own help says the plain (disco) ping does not go through the
+tunnel; the `--icmp` ping does go through WireGuard.
+
+The local signal for "the peer looks online but no COS request has arrived": the server's own last
+request time from that Tailscale address (any `/api` request, public routes included, because any
+request that arrives proves the tunnel carries COS traffic), together with `Online: true` from a
+status read no more than 15 s old. Each nudge log line also records the peer's handshake age and its
+`RxBytes` movement between the last two status reads, so the field canary can show which of them
+tells a stuck tunnel apart. The stuck state itself was not reproduced here.
+
+## The nudge
+
+A nudge is two bounded commands at one peer, run with `execFile` from a fixed path (never a shell,
+never a PATH lookup):
+
+1. `tailscale ping -c 3 --timeout 5s <peer>`: a disco ping. Both ends redo path discovery.
+2. Only after a pong: `tailscale ping --icmp -c 1 --timeout 5s <peer>`: one packet through
+   WireGuard, which makes WireGuard start a fresh handshake when its session is stale. On 10/22 the
+   disco ping got through while COS did not, so the disco ping alone is not enough.
+
+The CLI is looked for at `/Applications/Tailscale.app/Contents/MacOS/Tailscale`,
+`/opt/homebrew/bin/tailscale`, `/usr/local/bin/tailscale` and `/usr/bin/tailscale`, in that order.
+Without one the loop does nothing and health says `available: false`.
+
+Whether a Mac-side nudge un-sticks the iOS extension is not proven by tests. The field canary below
+is the proof.
+
+### Triggers
+
+Every trigger needs the positive signal: the peer is `Online` in a status read at most 15 s old, and
+Tailscale's `BackendState` is `Running`. Absence of requests alone never nudges.
+
+| Trigger | When | Who |
+|---|---|---|
+| `boot` | 30 s after the server starts | Event peers (below) |
+| `wake` | The wall clock moved 20 s or more past the monotonic clock between two 10 s ticks, which only happens across a sleep. Runs 15 s later. | Event peers |
+| `network` | This Mac's external IPv4 interfaces changed, Tailscale's tunnel interface included. Runs 10 s later. | Event peers |
+| `tailscale` | Tailscale's own state changed between status reads: `BackendState`, this Mac's Tailscale IPs, or the peer byte counters went backwards (tailscaled restarted). Runs 10 s later. | Event peers |
+| `silent` | A Tailscale address that made an authenticated request in the last 5 minutes, or sent meeting chunks in the last 15 minutes while a meeting is open, has made no request at all for 45 s. | That address |
+
+Event peers: Online peers this server has seen authenticate in the last 12 hours, plus Online iOS
+and Android peers (after a restart the server remembers no one), at most 4, known ones first. A peer
+that has already made a request since the event is skipped. An event that cannot run because
+Tailscale is not `Running` waits, and is dropped (with one log line) after 2 minutes.
+
+### Caps
+
+- One nudge per peer per 60 s. Each nudge that brings no request doubles the gap: 60, 120, 240,
+  480 s, then 900 s. Any request from that peer resets it.
+- 30 nudges an hour in all, across peers.
+- One pass at a time; each command has a hard timeout (status 5 s, disco 20 s, ICMP 10 s, killed
+  with SIGKILL).
+- A quiet phone outside a meeting is nudged at most 3 times (at about 45 s, 1:50 and 3:50) before its
+  5-minute window closes. In a meeting, at most 4 in 15 minutes.
+- Status is read once a minute while the loop is on, and otherwise only when a nudge could run.
+- `COS_TAILSCALE_NUDGE=0` (or `false`, `off`) stops all of it, read every tick. On by default.
+  Forwarded by the managed runtime contract.
+- No LLM, no disk write, no new route.
+
+### What it says
+
+Log lines, outcome and timing only, never an address:
+
+```
+[tailscale-nudge] trigger=silent outcome=pong_direct dataPath=ok pingMs=91 icmpMs=27 silentS=50 handshakeAgeS=61 rxDelta=9040/60s inRow=1 lastHour=1
+[tailscale-nudge] peer answered 4.2s after the silent nudge
+[tailscale-nudge] trigger=wake dropped: Tailscale not running for 121s
+```
+
+`outcome` is `pong_direct`, `pong_relay`, `no_pong`, `timeout`, `error` or `unavailable`.
+`dataPath` is `ok`, `failed` or `skipped` (no ICMP ping without a disco pong). A failed ping also
+logs `code`, `signal` and `killed`.
+
+Public `/api/health` carries:
+
+```json
+"tailscaleNudge": {
+  "enabled": true,
+  "available": true,
+  "lastAt": "2026-10-23T20:05:10.000Z",
+  "lastTrigger": "silent",
+  "lastOutcome": "pong_direct",
+  "lastDataPath": "ok",
+  "lastRecoveredAt": "2026-10-23T20:05:14.200Z",
+  "nudgesLastHour": 1
+}
+```
+
+`available` is `null` until the first look for the CLI. `lastRecoveredAt` is when a nudged peer next
+made a request, if that was within 90 s of the nudge. No address or device name is published.
+
+## The phone side (contract for glasses 6.10.653; not built in this release)
+
+- **Retry with a fresh request.** On a reconnect failure, retry `/api/health` and then the
+  authenticated `/api/models` with `cache: 'no-store'` and a cache-busting query, on a fresh
+  connection where the WebView allows it (do not reuse a stalled keep-alive socket; a new
+  `EventSource` for the display stream). Backoff ladder: 2, 4, 8, 15, then every 30 s while the app
+  is in the foreground. Never a tight loop.
+- **Wait out the Mac-side window before blaming Tailscale.** The Mac's nudge fires 45 s into a
+  silence (or 30 s after a Mac boot, 15 s after a wake) and its pings take up to about 30 s. Show
+  6.10.652's stuck-Tailscale message only after 90 s of failed fresh requests while the phone has
+  network (the gotcos.com reachability check). Before that, show the ordinary reconnecting state.
+- **Read the outcome.** `/api/health` is public, so once the phone reaches it, `tailscaleNudge`
+  tells it whether the Mac nudged and when. If health is reachable but authenticated calls are not,
+  the tunnel is fine and the problem is elsewhere: do not show the Tailscale message.
+- **Keep working offline.** Local-first capture and backfill are unchanged: record locally, upload
+  when the Mac answers.
+- **What to tell Miles about VPN On Demand.** In the iOS Tailscale app (Settings, VPN On Demand),
+  turning it on makes iOS bring the tunnel back by itself after it drops, for example after a network
+  change. It is a phone setting he can choose; COS cannot change it. It does not replace the nudge: a
+  tunnel iOS considers "up" but stale is not a drop, which is the case the Mac-side nudge targets.
+
+## Field canary (Miles)
+
+1. Note the time. Phone on cellular or away from home, COS open on the phone, Tailscale on.
+2. On the Mac, either quit and reopen Tailscale (menu bar, Quit, then open it), or restart the Mac.
+3. Do not touch Tailscale on the phone. Use COS on the phone within about two minutes.
+
+Success:
+
+- **Log** (the server log; with COS Control, `~/Library/Logs/COS Glasses/server.log`): a `[tailscale-nudge] trigger=tailscale` (Tailscale restart) or
+  `trigger=boot` (Mac restart) line with `outcome=pong_direct` or `pong_relay` and `dataPath=ok`,
+  then `peer answered ...s after the ... nudge`.
+- **Health:** `curl -s http://127.0.0.1:3141/api/health` shows `tailscaleNudge.lastTrigger` matching,
+  `lastOutcome` a pong, and `lastRecoveredAt` set a few seconds after `lastAt`.
+- **Phone:** COS reconnects by itself, without a Tailscale toggle, and a meeting started before the
+  restart keeps its chunks (transfer integrity 100%).
+
+If the phone still needs a toggle: record the nudge log line (its `handshakeAgeS` and `rxDelta` are
+the evidence for the next step) and the time of the toggle.

package/managed-runtime-contract.json

@@ -36,6 +36,7 @@
     "COS_LIVE_CUES_V2_MAX_PER_MEETING",
     "COS_LIVE_CUES_V2_DAILY_WRITER_CALLS",
     "COS_LIVE_CUES_V2_MAC",
+    "COS_TAILSCALE_NUDGE",
     "COS_LIVE_CUES_JEV_DAILY_TOKENS",
     "COS_LIVE_CUES_SUBQ_DAILY_TOKENS",
     "COS_DECISION_PROVIDER_CUES",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.87.0",
+  "version": "6.89.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": {
@@ -136,6 +136,9 @@
     "!server/scripts/question-hold-mutation-gate.mjs",
     "!server/scripts/live-meeting-6860-mutation-gate.mjs",
     "!server/scripts/live-meeting-6870-mutation-gate.mjs",
+    "!server/scripts/integrity-6880-mutation-gate.mjs",
+    "!server/scripts/tailscale-nudge-6890-mutation-gate.mjs",
+    "docs/tailscale-self-heal.md",
     "docs/test-plan-6.71.8.md",
     "docs/test-plan-6.71.9.md",
     "docs/test-plan-6.71.10.md",

package/server/index.ts

@@ -14,7 +14,8 @@ import { execSync } from 'node:child_process'
 import { randomBytes, randomUUID } from 'node:crypto'
 import { healthRouter } from './routes/health.js'
 import { diagRouter } from './routes/diag.js'
-import { createClientInstanceRouter } from './routes/client-instance.js'
+import { createClientInstanceRouter, isMeetingChunkPost } from './routes/client-instance.js'
+import { installTailscaleNudger } from './lib/tailscale-nudge.js'
 import { queryRouter } from './routes/query.js'
 import { providerProofRouter } from './routes/provider-proof.js'
 import { transcribeRouter } from './routes/transcribe.js'
@@ -188,7 +189,7 @@ import {
   isLoopbackSocket,
   reachableIpv4Addresses,
 } from './lib/network-policy.js'
-import { requireApiToken } from './lib/api-auth.js'
+import { isPublicApiRequest, 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'
@@ -355,9 +356,23 @@ const pairingState = new PairingState({
   serverName: () => hostname().replace(/\.local$/i, ''),
   hosts: lanArmed => pairingHostsFrom(reachableIpv4Addresses(networkInterfaces()), PORT, lanArmed),
 })
+// 6.89.0 Tailscale self-heal (lib/tailscale-nudge.ts, docs/tailscale-self-heal.md). Every /api
+// request from a Tailscale address is noted BEFORE the token check, public routes included: any
+// request that arrives proves the tunnel carries COS traffic. Authenticated ones also mark the
+// address as a paired phone. Notes only, never answers; noteRequest never throws.
+const tailscaleNudger = installTailscaleNudger({ activeMeetings: () => getActiveTranscriptionSessionCount() })
+app.use('/api', (req, _res, next) => {
+  tailscaleNudger.noteRequest(req.socket?.remoteAddress, { meetingChunk: isMeetingChunkPost(req.method, req.path) })
+  next()
+})
 app.use('/api', requireApiToken(API_TOKEN, {
   onAuthenticated: req => pairingState.noteAuthenticated(req.socket?.remoteAddress),
 }))
+// Past the token gate, a request on a non-public path carried the token: mark a paired phone.
+app.use('/api', (req, _res, next) => {
+  if (!isPublicApiRequest(req.method, req.path)) tailscaleNudger.noteRequest(req.socket?.remoteAddress, { authenticated: true })
+  next()
+})
 
 // 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
@@ -1274,6 +1289,7 @@ async function gracefulShutdown(): Promise<void> {
   await meetingAskRuntime.shutdown()
   stopMorningBriefScheduler()
   stopRoutineScheduler()
+  tailscaleNudger.stop()
   await workReviewRuntime?.close()
   workIntakeStore?.close()
   workHandoffRequestStore?.close()
@@ -1476,6 +1492,8 @@ listenRequiredServers(listeners).then(() => {
     // Hash the pinned FluidAudio CLI once at boot so the first Settings GET already knows `installable`.
     void findPinnedCli().catch(() => null)
     startPreviewWarmLoop()
+    // 6.89.0: the Tailscale nudge loop. Its boot trigger is due 30 s from here. COS_TAILSCALE_NUDGE=0 stops it.
+    tailscaleNudger.start()
   }
 
   // Durable recovery starts with the admitted runtime by default. A literal

package/server/lib/tailscale-nudge.ts

@@ -0,0 +1,536 @@
+// 6.89.0 Tailscale self-heal: the Mac-side "nudge" (docs/tailscale-self-heal.md).
+//
+// Why: on 2026-10-22 the Mac restarted at 14:09 and the server answered on every address from
+// 14:10:58, but the iPhone's Tailscale extension kept a stale tunnel. Tailscale's own ping got
+// through, no COS request did, and only toggling Tailscale on the phone (15:09) fixed it. The goal
+// is that a Mac restart, a wake from sleep, a Tailscale restart on the Mac or a network change heals
+// without anyone touching Tailscale.
+//
+// What a nudge is: two bounded `tailscale ping`s at one peer, run with execFile from a fixed path,
+// never a shell:
+//   1. `ping -c 3 --timeout 5s <ip>`: a disco ping. It makes both ends redo path discovery, and it
+//      stops early once a direct path answers.
+//   2. only after a pong, `ping --icmp -c 1 --timeout 5s <ip>`: a packet THROUGH WireGuard. The disco
+//      ping alone can succeed while the data path is stale (it does not use the tunnel, which is what
+//      10/22 looked like); a data packet makes WireGuard start a fresh handshake when its session is
+//      stale.
+// Whether this un-sticks the iOS extension in the field is NOT proven here; the field canary is.
+//
+// When (triggers), each needing the POSITIVE signal "tailscale status says this peer is Online"
+// from a status read at most STATUS_FRESH_MS old. Absence of requests alone never nudges.
+//   boot      30 s after the server starts.
+//   wake      the wall clock moved 20 s+ more than the monotonic clock (the Mac slept).
+//   network   this Mac's IPv4 interfaces changed (Tailscale's utun included).
+//   tailscale Tailscale's own state changed: BackendState, this Mac's Tailscale IPs, or the peer
+//             byte counters went backwards (tailscaled restarted).
+//   silent    a phone that made an authenticated request in the last 5 minutes, or sent meeting
+//             chunks in the last 15 minutes while a meeting is open, has made no request at all
+//             for 45 s, while its peer is Online.
+// Event triggers (boot, wake, network, tailscale) aim at peers this process has seen authenticate in
+// the last 12 hours, plus Online iOS and Android peers (after a restart the Mac remembers no one),
+// at most 4, and skip any peer that has already made a request since the event.
+//
+// Caps: one nudge per peer per 60 s, doubling per nudge that brings no request (60, 120, 240, 480,
+// then 900 s), reset by any request from that peer; 30 nudges an hour in all; one at a time.
+// COS_TAILSCALE_NUDGE=0 (or false/off) stops everything, read every tick, no restart needed.
+// No LLM, no disk write, no shell. Logs carry trigger, outcome and timing only, never an address.
+
+import { execFile } from 'node:child_process'
+import { accessSync, constants as fsConstants } from 'node:fs'
+import { networkInterfaces } from 'node:os'
+import { readSwitch } from './env-switch.js'
+import { isTailscaleIpv4, normalizeRemoteIp } from './network-policy.js'
+
+export const TAILSCALE_NUDGE_LIMITS = Object.freeze({
+  tickMs: 10_000,
+  bootDelayMs: 30_000,
+  wakeSettleMs: 15_000,
+  networkSettleMs: 10_000,
+  /** An event trigger that cannot run (Tailscale not Running yet) is dropped after this. */
+  eventExpiryMs: 120_000,
+  /** The monotonic clock stops while the Mac sleeps; a wall-clock lead past this is a wake. */
+  wakeGapMs: 20_000,
+  silenceMs: 45_000,
+  activeWindowMs: 5 * 60_000,
+  meetingWindowMs: 15 * 60_000,
+  knownPeerWindowMs: 12 * 60 * 60_000,
+  minIntervalMs: 60_000,
+  maxBackoffMs: 15 * 60_000,
+  maxPerHour: 30,
+  eventMaxPeers: 4,
+  statusPollMs: 60_000,
+  statusFreshMs: 15_000,
+  recoveredWithinMs: 90_000,
+  discoTimeoutMs: 20_000,
+  icmpTimeoutMs: 10_000,
+  statusTimeoutMs: 5_000,
+  binRecheckMs: 10 * 60_000,
+  maxTrackedPeers: 16,
+})
+
+/** Fixed places the Tailscale CLI lives. No PATH lookup and no override: the path is never input. */
+export const TAILSCALE_BIN_CANDIDATES = Object.freeze([
+  '/Applications/Tailscale.app/Contents/MacOS/Tailscale',
+  '/opt/homebrew/bin/tailscale',
+  '/usr/local/bin/tailscale',
+  '/usr/bin/tailscale',
+])
+
+export const DISCO_PING_ARGS = (ip: string): string[] => ['ping', '-c', '3', '--timeout', '5s', ip]
+export const ICMP_PING_ARGS = (ip: string): string[] => ['ping', '--icmp', '-c', '1', '--timeout', '5s', ip]
+export const STATUS_ARGS: readonly string[] = Object.freeze(['status', '--json'])
+
+export type NudgeTrigger = 'boot' | 'wake' | 'network' | 'tailscale' | 'silent'
+export type NudgeOutcome = 'pong_direct' | 'pong_relay' | 'no_pong' | 'timeout' | 'error' | 'unavailable'
+export type DataPathOutcome = 'ok' | 'failed' | 'skipped'
+
+export interface RunResult {
+  code: number | null
+  signal: string | null
+  killed: boolean
+  stdout: string
+  stderr: string
+  /** Set when the process could not be started at all (ENOENT, EACCES). */
+  spawnError?: string
+  elapsedMs: number
+}
+/** The one way this module runs Tailscale: a binary path and an argument array, never a shell. */
+export type TailscaleRunner = (bin: string, args: readonly string[], timeoutMs: number) => Promise<RunResult>
+
+export const execFileRunner: TailscaleRunner = (bin, args, timeoutMs) => new Promise(resolve => {
+  const started = Date.now()
+  execFile(bin, [...args], { timeout: timeoutMs, killSignal: 'SIGKILL', maxBuffer: 1024 * 1024, windowsHide: true, encoding: 'utf8' },
+    (error, stdout, stderr) => {
+      const err = error as (NodeJS.ErrnoException & { code?: number | string; killed?: boolean; signal?: string }) | null
+      const spawnError = err && typeof err.code === 'string' ? err.code : undefined
+      resolve({
+        code: err ? (typeof err.code === 'number' ? err.code : null) : 0,
+        signal: err?.signal ?? null,
+        killed: !!err?.killed,
+        stdout: String(stdout ?? ''),
+        stderr: String(stderr ?? ''),
+        ...(spawnError ? { spawnError } : {}),
+        elapsedMs: Date.now() - started,
+      })
+    })
+})
+
+export function resolveTailscaleBin(isExecutable: (p: string) => boolean = defaultIsExecutable): string | null {
+  for (const candidate of TAILSCALE_BIN_CANDIDATES) if (isExecutable(candidate)) return candidate
+  return null
+}
+function defaultIsExecutable(p: string): boolean {
+  try { accessSync(p, fsConstants.X_OK); return true } catch { return false }
+}
+
+export interface PeerStatus {
+  ip: string
+  online: boolean
+  os: string
+  rxBytes: number
+  txBytes: number
+  /** Epoch ms of the last WireGuard handshake, or 0 for none. */
+  lastHandshakeMs: number
+}
+export interface TailscaleStatus {
+  backendState: string
+  selfIps: string[]
+  peers: PeerStatus[]
+  at: number
+}
+
+/** Parse `tailscale status --json`. Returns null for anything that is not that shape. */
+export function parseTailscaleStatus(text: string, at: number): TailscaleStatus | null {
+  let raw: any
+  try { raw = JSON.parse(text) } catch { return null }
+  if (!raw || typeof raw !== 'object' || typeof raw.BackendState !== 'string') return null
+  const v4 = (ips: unknown): string[] => Array.isArray(ips) ? ips.filter((ip): ip is string => typeof ip === 'string' && isTailscaleIpv4(ip)) : []
+  const peers: PeerStatus[] = []
+  const peerMap = raw.Peer && typeof raw.Peer === 'object' ? raw.Peer : {}
+  for (const p of Object.values(peerMap) as any[]) {
+    const ip = v4(p?.TailscaleIPs)[0]
+    if (!ip) continue
+    const hs = typeof p.LastHandshake === 'string' ? Date.parse(p.LastHandshake) : NaN
+    peers.push({
+      ip,
+      online: p.Online === true,
+      os: typeof p.OS === 'string' ? p.OS : '',
+      rxBytes: Number.isFinite(p.RxBytes) ? p.RxBytes : 0,
+      txBytes: Number.isFinite(p.TxBytes) ? p.TxBytes : 0,
+      lastHandshakeMs: Number.isFinite(hs) && hs > 0 ? hs : 0,
+    })
+  }
+  return { backendState: raw.BackendState, selfIps: v4(raw.Self?.TailscaleIPs).sort(), peers, at }
+}
+
+/** Disco ping output: "pong from <name> (<ip>) via <DERP(x) | ip:port | peer-relay(...)> in 91ms". */
+export function classifyDiscoPing(result: RunResult): NudgeOutcome {
+  if (result.spawnError) return 'unavailable'
+  const pong = /pong from .* via (\S+) in [\d.]+ms/.exec(result.stdout)
+  if (pong) return /^(DERP|peer-relay)/i.test(pong[1]) ? 'pong_relay' : 'pong_direct'
+  if (result.killed || result.signal) return 'timeout'
+  if (/no reply|timed out|timeout/i.test(result.stdout + result.stderr)) return 'no_pong'
+  return result.code === 0 ? 'no_pong' : 'error'
+}
+export function classifyIcmpPing(result: RunResult): DataPathOutcome {
+  return !result.spawnError && /pong from .* via ICMP/i.test(result.stdout) ? 'ok' : 'failed'
+}
+
+/** Every external IPv4 interface address, sorted: changes when a network or the Tailscale tunnel changes. */
+type InterfaceInfo = { address: string; family: string | number; internal: boolean }
+export function networkFingerprint(nets: Record<string, InterfaceInfo[] | undefined> = networkInterfaces()): string {
+  const out: string[] = []
+  for (const [name, infos] of Object.entries(nets)) {
+    for (const info of infos ?? []) {
+      const family = typeof info.family === 'number' ? (info.family === 4 ? 'IPv4' : 'IPv6') : String(info.family)
+      if (family === 'IPv4' && !info.internal) out.push(`${name}=${info.address}`)
+    }
+  }
+  return out.sort().join(',')
+}
+
+/** Did Tailscale's own state change between two status reads? A failed read is not a change. */
+export function tailscaleStateChanged(prev: TailscaleStatus | null, next: TailscaleStatus | null): boolean {
+  if (!prev || !next) return false
+  if (prev.backendState !== next.backendState) return true
+  if (prev.selfIps.join(',') !== next.selfIps.join(',')) return true
+  // tailscaled keeps per-peer byte counters for its lifetime: a total that went DOWN means it restarted.
+  const total = (s: TailscaleStatus) => s.peers.reduce((n, p) => n + p.rxBytes + p.txBytes, 0)
+  return total(next) < total(prev)
+}
+
+/** Seconds between nudges for a peer, given how many nudges in a row brought no request. */
+export function backoffMs(consecutive: number): number {
+  if (consecutive <= 0) return 0
+  const { minIntervalMs, maxBackoffMs } = TAILSCALE_NUDGE_LIMITS
+  return Math.min(minIntervalMs * 2 ** (consecutive - 1), maxBackoffMs)
+}
+
+export function isMobileOs(os: string): boolean {
+  return /^(ios|android)$/i.test(os.trim())
+}
+
+interface PeerTrack {
+  /** Any /api request from this address, public routes included: proof the data path works. */
+  lastRequestAt: number
+  lastAuthenticatedAt: number
+  lastMeetingChunkAt: number
+  lastNudgeAt: number
+  /** Nudges since the last request from this peer. */
+  consecutive: number
+}
+
+export interface TailscaleNudgeDeps {
+  runner?: TailscaleRunner
+  now?: () => number
+  /** Monotonic milliseconds; it does not advance while the Mac sleeps. */
+  monotonic?: () => number
+  env?: () => NodeJS.ProcessEnv
+  resolveBin?: () => string | null
+  fingerprint?: () => string
+  activeMeetings?: () => number
+  log?: (line: string) => void
+}
+
+export interface TailscaleNudgeHealth {
+  enabled: boolean
+  /** null until the first look for the Tailscale CLI; false when it is not installed. */
+  available: boolean | null
+  lastAt: string | null
+  lastTrigger: NudgeTrigger | null
+  lastOutcome: NudgeOutcome | null
+  lastDataPath: DataPathOutcome | null
+  /** When a nudged peer next made a request, within 90 s of the nudge. */
+  lastRecoveredAt: string | null
+  nudgesLastHour: number
+}
+
+interface PendingEvent { trigger: Exclude<NudgeTrigger, 'silent'>; firedAt: number; dueAt: number }
+
+export class TailscaleNudger {
+  private readonly runner: TailscaleRunner
+  private readonly now: () => number
+  private readonly monotonic: () => number
+  private readonly env: () => NodeJS.ProcessEnv
+  private readonly resolveBinFn: () => string | null
+  private readonly fingerprintFn: () => string
+  private readonly activeMeetings: () => number
+  private readonly log: (line: string) => void
+
+  private readonly peers = new Map<string, PeerTrack>()
+  private readonly hourLog: number[] = []
+  private pending: PendingEvent | null = null
+  private bin: string | null | undefined = undefined
+  private binCheckedAt = 0
+  private status: TailscaleStatus | null = null
+  private previousStatus: TailscaleStatus | null = null
+  private lastStatusAttemptAt = 0
+  private lastFingerprint: string | null = null
+  private lastTick: { wall: number; mono: number } | null = null
+  private busy = false
+  private timer: ReturnType<typeof setInterval> | null = null
+  private lastNudge: { at: number; ip: string; trigger: NudgeTrigger; outcome: NudgeOutcome; dataPath: DataPathOutcome } | null = null
+  private lastRecoveredAt: number | null = null
+
+  constructor(deps: TailscaleNudgeDeps = {}) {
+    this.runner = deps.runner ?? execFileRunner
+    this.now = deps.now ?? Date.now
+    this.monotonic = deps.monotonic ?? (() => Number(process.hrtime.bigint() / 1_000_000n))
+    this.env = deps.env ?? (() => process.env)
+    this.resolveBinFn = deps.resolveBin ?? (() => resolveTailscaleBin())
+    this.fingerprintFn = deps.fingerprint ?? (() => networkFingerprint())
+    this.activeMeetings = deps.activeMeetings ?? (() => 0)
+    this.log = deps.log ?? (line => console.log(line))
+  }
+
+  enabled(): boolean {
+    return readSwitch(this.env().COS_TAILSCALE_NUDGE, true)
+  }
+
+  /** Start the tick. The boot trigger is due 30 s from now. Timers are unref'd. */
+  start(): void {
+    if (this.timer) return
+    const at = this.now()
+    this.pending = { trigger: 'boot', firedAt: at, dueAt: at + TAILSCALE_NUDGE_LIMITS.bootDelayMs }
+    this.timer = setInterval(() => { void this.tick() }, TAILSCALE_NUDGE_LIMITS.tickMs)
+    this.timer.unref?.()
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer)
+    this.timer = null
+  }
+
+  /**
+   * Called for every /api request (before the token check) with the socket address. Only
+   * Tailscale addresses are tracked. Never throws.
+   */
+  noteRequest(remoteAddress: string | undefined | null, kind: { authenticated?: boolean; meetingChunk?: boolean } = {}): void {
+    try {
+      const ip = normalizeRemoteIp(remoteAddress ?? '')
+      if (!isTailscaleIpv4(ip)) return
+      const at = this.now()
+      let track = this.peers.get(ip)
+      if (!track) {
+        track = { lastRequestAt: 0, lastAuthenticatedAt: 0, lastMeetingChunkAt: 0, lastNudgeAt: 0, consecutive: 0 }
+      }
+      this.peers.delete(ip)
+      this.peers.set(ip, track)
+      while (this.peers.size > TAILSCALE_NUDGE_LIMITS.maxTrackedPeers) this.peers.delete(this.peers.keys().next().value as string)
+      if (track.consecutive > 0 && this.lastNudge?.ip === ip && at - this.lastNudge.at <= TAILSCALE_NUDGE_LIMITS.recoveredWithinMs
+        && (this.lastRecoveredAt === null || this.lastRecoveredAt < this.lastNudge.at)) {
+        this.lastRecoveredAt = at
+        this.log(`[tailscale-nudge] peer answered ${((at - this.lastNudge.at) / 1000).toFixed(1)}s after the ${this.lastNudge.trigger} nudge`)
+      }
+      track.lastRequestAt = at
+      track.consecutive = 0
+      if (kind.authenticated) track.lastAuthenticatedAt = at
+      if (kind.meetingChunk) track.lastMeetingChunkAt = at
+    } catch { /* observer only */ }
+  }
+
+  health(): TailscaleNudgeHealth {
+    const at = this.now()
+    return {
+      enabled: this.enabled(),
+      available: this.bin === undefined ? null : this.bin !== null,
+      lastAt: this.lastNudge ? new Date(this.lastNudge.at).toISOString() : null,
+      lastTrigger: this.lastNudge?.trigger ?? null,
+      lastOutcome: this.lastNudge?.outcome ?? null,
+      lastDataPath: this.lastNudge?.dataPath ?? null,
+      lastRecoveredAt: this.lastRecoveredAt !== null ? new Date(this.lastRecoveredAt).toISOString() : null,
+      nudgesLastHour: this.hourLog.filter(t => at - t < 3_600_000).length,
+    }
+  }
+
+  /** One decision pass. Public for tests; the interval calls it. Never throws, never overlaps. */
+  async tick(): Promise<void> {
+    if (this.busy) return
+    this.busy = true
+    try { await this.tickInner() } catch { /* a failed pass waits for the next tick */ } finally { this.busy = false }
+  }
+
+  private async tickInner(): Promise<void> {
+    const at = this.now()
+    const mono = this.monotonic()
+    const L = TAILSCALE_NUDGE_LIMITS
+    // Wake and network detection run even when switched off, so turning it on later starts clean.
+    if (this.lastTick && (at - this.lastTick.wall) - (mono - this.lastTick.mono) > L.wakeGapMs) {
+      this.raise('wake', at, L.wakeSettleMs)
+    }
+    this.lastTick = { wall: at, mono }
+    const fp = safe(this.fingerprintFn, '')
+    if (this.lastFingerprint !== null && fp !== this.lastFingerprint) this.raise('network', at, L.networkSettleMs)
+    this.lastFingerprint = fp
+
+    if (!this.enabled()) return
+    if (!this.ensureBin(at)) return
+
+    if (at - this.lastStatusAttemptAt >= L.statusPollMs) {
+      // Compared only on a successful read: a failed one leaves the last good status in place.
+      const before = this.status
+      const read = await this.readStatus(at)
+      if (read && tailscaleStateChanged(before, read)) this.raise('tailscale', at, L.networkSettleMs)
+    }
+
+    const pending = this.pending
+    if (pending && at >= pending.dueAt) {
+      await this.runEvent(pending, at)
+      return
+    }
+    await this.runSilent(at)
+  }
+
+  private raise(trigger: PendingEvent['trigger'], at: number, settleMs: number): void {
+    // A boot still waiting keeps its own due time; any later event replaces an earlier one.
+    if (this.pending?.trigger === 'boot' && trigger !== 'boot') {
+      this.pending = { trigger, firedAt: this.pending.firedAt, dueAt: Math.max(this.pending.dueAt, at + settleMs) }
+      return
+    }
+    this.pending = { trigger, firedAt: at, dueAt: at + settleMs }
+  }
+
+  private ensureBin(at: number): boolean {
+    if (this.bin === undefined || (this.bin === null && at - this.binCheckedAt >= TAILSCALE_NUDGE_LIMITS.binRecheckMs)) {
+      this.bin = safe(this.resolveBinFn, null)
+      this.binCheckedAt = at
+    }
+    return this.bin !== null
+  }
+
+  private async readStatus(at: number): Promise<TailscaleStatus | null> {
+    this.lastStatusAttemptAt = at
+    const result = await this.runner(this.bin as string, STATUS_ARGS, TAILSCALE_NUDGE_LIMITS.statusTimeoutMs)
+    if (result.spawnError === 'ENOENT') this.bin = null
+    const parsed = result.spawnError ? null : parseTailscaleStatus(result.stdout, at)
+    if (parsed) {
+      this.previousStatus = this.status
+      this.status = parsed
+    }
+    return parsed
+  }
+
+  /** A status no older than STATUS_FRESH_MS, read now if needed; null when Tailscale cannot say. */
+  private async freshStatus(at: number): Promise<TailscaleStatus | null> {
+    if (this.status && at - this.status.at <= TAILSCALE_NUDGE_LIMITS.statusFreshMs) return this.status
+    const before = this.status
+    const read = await this.readStatus(at)
+    if (read && tailscaleStateChanged(before, read)) this.raise('tailscale', at, TAILSCALE_NUDGE_LIMITS.networkSettleMs)
+    return read
+  }
+
+  private async runEvent(pending: PendingEvent, at: number): Promise<void> {
+    const L = TAILSCALE_NUDGE_LIMITS
+    const status = await this.freshStatus(at)
+    if (!status || status.backendState !== 'Running') {
+      if (at - pending.firedAt > L.eventExpiryMs) {
+        this.pending = null
+        this.log(`[tailscale-nudge] trigger=${pending.trigger} dropped: Tailscale ${status ? 'not running' : 'did not answer'} for ${Math.round((at - pending.firedAt) / 1000)}s`)
+      }
+      return
+    }
+    if (this.pending === pending) this.pending = null
+    const known = (ip: string) => {
+      const t = this.peers.get(ip)
+      return !!t && t.lastAuthenticatedAt > 0 && at - t.lastAuthenticatedAt <= L.knownPeerWindowMs
+    }
+    const candidates = status.peers
+      .filter(p => p.online && (known(p.ip) || isMobileOs(p.os)))
+      // Already back since the event: nothing to heal.
+      .filter(p => (this.peers.get(p.ip)?.lastRequestAt ?? 0) < pending.firedAt)
+      .sort((a, b) => Number(known(b.ip)) - Number(known(a.ip)))
+      .slice(0, L.eventMaxPeers)
+    for (const peer of candidates) {
+      if (!this.enabled()) return
+      await this.maybeNudge(peer, pending.trigger, status, at, 0)
+    }
+  }
+
+  private async runSilent(at: number): Promise<void> {
+    const L = TAILSCALE_NUDGE_LIMITS
+    const meetingOpen = safe(this.activeMeetings, 0) > 0
+    const silent: Array<[string, PeerTrack]> = []
+    for (const [ip, t] of this.peers) {
+      const expected = (t.lastAuthenticatedAt > 0 && at - t.lastAuthenticatedAt <= L.activeWindowMs)
+        || (meetingOpen && t.lastMeetingChunkAt > 0 && at - t.lastMeetingChunkAt <= L.meetingWindowMs)
+      // Only a peer the caps would let us nudge now: a status read for one we cannot nudge is waste.
+      if (expected && at - t.lastRequestAt >= L.silenceMs && this.allowed(ip, at)) silent.push([ip, t])
+    }
+    if (silent.length === 0) return
+    // Never on absence alone: only a peer that Tailscale itself reports Online is nudged.
+    const status = await this.freshStatus(at)
+    if (!status || status.backendState !== 'Running') return
+    for (const [ip, t] of silent) {
+      const peer = status.peers.find(p => p.ip === ip)
+      if (!peer || !peer.online) continue
+      if (!this.enabled()) return
+      await this.maybeNudge(peer, 'silent', status, at, at - t.lastRequestAt)
+    }
+  }
+
+  private allowed(ip: string, at: number): boolean {
+    const L = TAILSCALE_NUDGE_LIMITS
+    while (this.hourLog.length > 0 && at - this.hourLog[0] >= 3_600_000) this.hourLog.shift()
+    if (this.hourLog.length >= L.maxPerHour) return false
+    const t = this.peers.get(ip)
+    if (!t || t.lastNudgeAt === 0) return true
+    return at - t.lastNudgeAt >= Math.max(L.minIntervalMs, backoffMs(t.consecutive))
+  }
+
+  private async maybeNudge(peer: PeerStatus, trigger: NudgeTrigger, status: TailscaleStatus, at: number, silentMs: number): Promise<void> {
+    if (!this.allowed(peer.ip, at)) return
+    let track = this.peers.get(peer.ip)
+    if (!track) {
+      track = { lastRequestAt: 0, lastAuthenticatedAt: 0, lastMeetingChunkAt: 0, lastNudgeAt: 0, consecutive: 0 }
+      this.peers.set(peer.ip, track)
+      while (this.peers.size > TAILSCALE_NUDGE_LIMITS.maxTrackedPeers) this.peers.delete(this.peers.keys().next().value as string)
+    }
+    track.lastNudgeAt = at
+    track.consecutive += 1
+    this.hourLog.push(at)
+    const bin = this.bin as string
+    const disco = await this.runner(bin, DISCO_PING_ARGS(peer.ip), TAILSCALE_NUDGE_LIMITS.discoTimeoutMs)
+    const outcome = classifyDiscoPing(disco)
+    if (disco.spawnError === 'ENOENT') this.bin = null
+    let dataPath: DataPathOutcome = 'skipped'
+    let icmpMs = 0
+    if (outcome === 'pong_direct' || outcome === 'pong_relay') {
+      const icmp = await this.runner(bin, ICMP_PING_ARGS(peer.ip), TAILSCALE_NUDGE_LIMITS.icmpTimeoutMs)
+      dataPath = classifyIcmpPing(icmp)
+      icmpMs = icmp.elapsedMs
+    }
+    this.lastNudge = { at, ip: peer.ip, trigger, outcome, dataPath }
+    const prev = this.previousStatus?.peers.find(p => p.ip === peer.ip)
+    const rx = prev && this.previousStatus ? ` rxDelta=${peer.rxBytes - prev.rxBytes}/${Math.round((status.at - this.previousStatus.at) / 1000)}s` : ''
+    const hs = peer.lastHandshakeMs > 0 ? ` handshakeAgeS=${Math.round((status.at - peer.lastHandshakeMs) / 1000)}` : ' handshakeAgeS=none'
+    const failure = outcome === 'error' || outcome === 'timeout' || outcome === 'unavailable'
+      ? ` code=${disco.code} signal=${disco.signal ?? 'none'} killed=${disco.killed}${disco.spawnError ? ` spawn=${disco.spawnError}` : ''}`
+      : ''
+    this.log(`[tailscale-nudge] trigger=${trigger} outcome=${outcome} dataPath=${dataPath} pingMs=${disco.elapsedMs} icmpMs=${icmpMs}`
+      + `${silentMs > 0 ? ` silentS=${Math.round(silentMs / 1000)}` : ''}${hs}${rx} inRow=${track.consecutive} lastHour=${this.hourLog.length}${failure}`)
+  }
+}
+
+function safe<T>(fn: () => T, fallback: T): T {
+  try { return fn() } catch { return fallback }
+}
+
+let singleton: TailscaleNudger | null = null
+/** The server's nudger. Created on first use so /api/health can read it before start(). */
+export function getTailscaleNudger(): TailscaleNudger {
+  if (!singleton) singleton = new TailscaleNudger()
+  return singleton
+}
+/** index.ts installs the server's nudger with its real meeting probe, before any request is noted. */
+export function installTailscaleNudger(deps: TailscaleNudgeDeps = {}): TailscaleNudger {
+  singleton?.stop()
+  singleton = new TailscaleNudger(deps)
+  return singleton
+}
+export function __setTailscaleNudgerForTests(nudger: TailscaleNudger | null): void {
+  singleton = nudger
+}
+/** `{ tailscaleNudge }` for /api/health. Public route: no address, no peer name, counts and times only. */
+export function tailscaleNudgeHealthField(): { tailscaleNudge: TailscaleNudgeHealth } {
+  return { tailscaleNudge: getTailscaleNudger().health() }
+}

package/server/lib/transfer-integrity.ts

@@ -0,0 +1,59 @@
+// 6.88.0: transfer integrity counts what the phone captured, not only what the Mac heard of.
+//
+// WHAT HAPPENED. 2026-10-23 07:59, meeting t2xs9u (glasses 6.10.651). A relaunched COS window saved
+// the meeting from the 74 chunks the Mac held while the window still recording it had captured
+// through index 120. The saved file said "Transfer integrity 100%": the gap report only looks for
+// holes in [0, highest index received], so 47 chunks the Mac never heard of did not count.
+//
+// THE RULE. When the phone has said how far it captured (the Stop's `finalChunkIndex`, or a save's
+// own `finalChunkIndex`, glasses 6.10.652), the expected count is that index plus one, and every
+// index from the Mac's highest received chunk to it is missing. 74 of 121 reads 61.1%.
+//
+// And a phone's ORIGIN-WIPE RECOVERY save (`recovery: 'origin_wipe'`, glasses 6.10.652) is refused
+// with 409 `chunks_outstanding` while the phone has said it captured chunks the Mac does not hold,
+// unless it says it waited them out (`acceptMissing: true`). The phone checks the same thing before
+// it asks; this closes the moment between its status read and its save (a Stop landing in between).
+// A save without `recovery` is never refused here: every existing caller behaves as before.
+
+import type { TranscriptGapReport } from '../routes/transcribe-stream.js'
+
+/** The stop route's own bound on a final index. */
+export const PHONE_FINAL_INDEX_LIMIT = 1_000_000
+/** A phone-said index this far past the Mac's highest chunk is capped (about 30 hours of 6 s chunks),
+ *  so one bad number cannot write a huge missing list into the sidecar. */
+export const PHONE_FINAL_INDEX_MAX_AHEAD = 20_000
+
+/** A final index as the stop route accepts it (a whole number, -1 or more), else null. */
+export function parsePhoneFinalChunkIndex(value: unknown): number | null {
+  return typeof value === 'number' && Number.isInteger(value) && value >= -1 && value <= PHONE_FINAL_INDEX_LIMIT ? value : null
+}
+
+/** The highest index any phone window said it captured, or null when none said. */
+export function phoneFinalChunkIndex(...said: Array<number | null | undefined>): number | null {
+  const known = said.filter((v): v is number => typeof v === 'number' && Number.isInteger(v) && v >= 0)
+  return known.length > 0 ? Math.max(...known) : null
+}
+
+/** The gap report with the phone's final index counted. Unchanged when the phone said nothing new. */
+export function withPhoneFinalIndex(report: TranscriptGapReport | null, phoneFinal: number | null): TranscriptGapReport | null {
+  if (!report || phoneFinal === null || phoneFinal <= report.maxIndex) return report
+  const final = Math.min(phoneFinal, Math.max(report.maxIndex, 0) + PHONE_FINAL_INDEX_MAX_AHEAD)
+  const missingIndices = [...report.missingIndices]
+  for (let index = report.maxIndex + 1; index <= final; index++) missingIndices.push(index)
+  const expected = final + 1
+  return {
+    ...report,
+    maxIndex: final,
+    expected,
+    missingIndices,
+    completeness: expected > 0 ? report.received / expected : 1,
+  }
+}
+
+/** Chunks in [0, phoneFinal] the Mac does not hold. */
+export function chunksOutstanding(report: TranscriptGapReport | null, phoneFinal: number | null): number {
+  if (phoneFinal === null) return 0
+  const counted = withPhoneFinalIndex(report, phoneFinal)
+  if (!counted) return phoneFinal + 1
+  return counted.missingIndices.filter(index => index <= phoneFinal).length
+}

package/server/routes/health.ts

@@ -75,6 +75,7 @@ import { liveCuesCapability } from '../lib/live-cues-capability.js'
 import { liveCuesV2Advertised } from '../lib/live-cues-v2.js'
 import { liveMeetingCapability } from '../lib/live-provisional.js'
 import { CUE_KINDS } from '../../shared/live-cues-v2.js'
+import { tailscaleNudgeHealthField } from '../lib/tailscale-nudge.js'
 
 /** 6.86.0: `capabilities.liveCues.kinds`, the cue kinds this server can write (additive; an older server omits it, which
  *  is how a client knows to expect only reinforce and challenge). Which kinds a given meeting gets is in its arm answer. */
@@ -445,6 +446,8 @@ healthRouter.get('/health', async (_req, res) => {
     ...continueLiveHealthFields(),
     // 6.62.0 /qa (W6): spawn isolation, posture and Cursor model read counters.
     ...continueReadHealthFields(),
+    // 6.89.0 Tailscale self-heal: switch, last nudge and its outcome, count this hour. No address.
+    ...tailscaleNudgeHealthField(),
     // 6.62.0: ONE providers object per engine. `act` (plan 3.11): what each provider can do,
     // with a reason for every "no". `observe` (plan 1.10): what COS can see of its sessions.
     providers: mergeProviderSections(

package/server/routes/meeting.ts

@@ -12,6 +12,7 @@ import { Router } from 'express'
 import { emitDisplay } from '../lib/display-bus.js'
 import { createStopRequestStore, isStopRequestRefusal, STOP_REQUEST_CLAIM_WINDOW_MS, type StopRequest, type StopRequestStore } from '../lib/meeting-stop-requests.js'
 import { appendAutonomousSaveLog, getStopIntentStore, type StopIntent, type StopIntentStore } from '../lib/meeting-stop-intents.js'
+import { chunksOutstanding, parsePhoneFinalChunkIndex, phoneFinalChunkIndex, withPhoneFinalIndex } from '../lib/transfer-integrity.js'
 import {
   AUTONOMOUS_FINALIZE_POLL_MS,
   AUTONOMOUS_FINALIZE_SETTLE_MS,
@@ -1128,6 +1129,24 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
       if (MAC_CAPTURE_ID.test(sessionId)) {
         requireMacRecordingForSave(sessionId, body?.expectedChunkCount)
       }
+      // 6.88.0 (lib/transfer-integrity.ts): how far a phone window said it captured, from its Stop or
+      // from this save (glasses 6.10.652). The saved file's integrity counts against it.
+      const phoneFinal = phoneFinalChunkIndex(stopIntents.get(sessionId)?.finalChunkIndex, parsePhoneFinalChunkIndex(body?.finalChunkIndex))
+      // An origin-wipe recovery never finalizes a meeting a phone window still holds chunks for, unless
+      // it says it waited them out. A save without `recovery` is never refused here.
+      if (body?.recovery === 'origin_wipe' && body?.acceptMissing !== true) {
+        const report = sessions.getIntegrity(sessionId)
+        const outstanding = report ? chunksOutstanding(report, phoneFinal) : 0
+        if (outstanding > 0) {
+          respond(409, {
+            error: 'A phone window captured chunks this Mac does not hold yet',
+            reason: 'chunks_outstanding',
+            missingCount: outstanding,
+            finalChunkIndex: phoneFinal,
+          })
+          return null
+        }
+      }
       if (savingSessions.has(sessionId)) {
         respond(409, { error: 'Meeting save already in progress', reason: 'save_in_progress' })
         return null
@@ -1166,7 +1185,7 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
       const durationMs = durationFromTimeline > 0
         ? durationFromTimeline
         : Math.max(0, Date.now() - startTime)
-      const integrity = sessions.getIntegrity(sessionId)
+      const integrity = withPhoneFinalIndex(sessions.getIntegrity(sessionId), phoneFinal)
       const needsOperations = cosOpsPipelineConfigured() && !macRecording
       // Standalone saves need a finalization pass too, for summary enrichment.
       // Before 6.37 a standalone save with no audio nulled the job below and