feat(voice): the call wakes its own machine now, and says so

A hibernated machine used to come back only as a side effect of the first
task, so that task absorbed the whole ~1min spin-up in silence and then
produced a result. The three lines written for this — MACHINE_WAKING,
MACHINE_AWAKE, MACHINE_WAKE_FAILED — have sat in Speech.kt unreferenced
since the port, because the client had no way to detect or cause a wake.
It does now (cloud-api #1635: POST /v1/agents/wake, plus status/canWake
on GET /machines), so this wires them up.

Decided behaviour: announce at the switch, and wake then. Not lazily on
the next task, which is the gap being closed, and not eagerly for
machines nobody switched to. The wake fires at first Live-ready and
inside applyMachineSwitch, which both switch paths — the voice tool and
the picker — already go through.

WakePolicy holds the decisions, apart from the service, for the same
reason GreetingGate and HangupPolicy do: each rule is a way of saying
something untrue about a computer the wearer cannot see, and none of them
is reachable from a JVM test while it lives in a foreground Service.

- Branch on `startingUp`, not `waking`. A machine already mid-wake
  answers waking=false — correctly, nothing was dispatched — and is
  still owed the minute. Reading `waking` alone reintroduces the silent
  wake one field over.
- Say nothing when canWake is false. That machine is asleep and staying
  that way, and the line promises about a minute.
- The wake happens while muted; only the announcement is dropped, the
  same call AgentEventRouter makes for a notice. But the WATCH continues,
  gated on the machine rather than on whether we spoke — so unmuting
  mid-wake still hears "the computer's awake now", which is fresh news
  rather than a stale replay.
- All three lines share one nudge kind, so a later one replaces an
  earlier one still held for the end of a turn. Otherwise the model gets
  "it's waking up" and "it's awake now" in one batch and reads out both.

waking=true only ever meant DISPATCHED — vm-service is fire-and-forget
and nothing polls it — so the three-minute timeout is this client's own
and MACHINE_WAKE_FAILED is the honest end of it.

Also adds check 8 to the on-device list, which had no switching check at
all and, with it, finally has the ten it claims.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: jamie-simular

docs/ON_DEVICE_CHECK.md

@@ -104,7 +104,7 @@ streams to a browser. DEBUG builds only, LAN only.
 > | The turn stream connects | `POST /v1/agents/message` answers with the turn's events. If that response is not read, nothing arrives from the agent at all — checks 2, 3 and 6 all go quiet together |
 > | Live opens with `?key=` | The URL form changed. The wrong one closes with `1007 api key not valid` |
 > | An idle call ends itself | The cost guard moved from the server to the phone. Leave a call silent for five minutes; it should hang up and say why |
-> | Waking a machine | The "it's waking / it's ready" lines now travel as `notice` over the stream |
+> | Waking a machine | **New on 2026-08-20 and never run on hardware.** The call now wakes its machine itself, at bind and at every switch, and narrates it: `MACHINE_WAKING` → `MACHINE_AWAKE`, or `MACHINE_WAKE_FAILED` after three minutes. Start a call on a **hibernated** machine — Sai should greet you and then say the computer is waking, verbatim, *before* you ask for anything. Silence there means `POST /v1/agents/wake` is not reaching the server (`wake:` lines in logcat say which); the old behaviour — a `notice` riding the first task's stream, a minute late — is the thing being replaced |
 > | Cancelling a queued task | Four endpoints deep, and the race answers are new — check 6 covers it |
 
 ## 1. The ten checks
@@ -256,6 +256,32 @@ mid-sentence.
 - **Then barge in while a task is running**, and let its completion land. Cutting Sai off must not
   cost you the result: it should still arrive after the exchange.
 
+### 8. Switching machines
+
+Mid-call, with more than one machine on the account:
+
+> "Switch to my ⟨other machine⟩"
+
+- **Expect:** a spoken "Switched to ⟨label⟩." and nothing more — then the **next** task runs on that
+  machine, and `recallHistory` stops reaching the old one. Live audio stays up, so the conversation
+  survives the switch.
+- **Exercises:** the `switchMachine` device tool, `MachineSwitcher.resolve` (exact, then containment
+  either way — so "studio" finds "Studio Mac"), and `applyMachineSwitch`'s reconnect. `switched
+  machine → ⟨label⟩` in logcat is the proof something was repointed; without it the next task still
+  goes to the old machine.
+- **Watch for:** the reply's parenthetical read aloud. "Context update, not to be spoken aloud" in
+  your ear is `RESELECT_NUDGE`'s failure in a new place. Switching from the **phone picker** instead
+  must be silent — a button press carries no tool response, so the correction goes in as a nudge, and
+  Sai narrating what you just pressed is the failure.
+- **Switch onto a hibernated machine** and it should wake, announced: "Switched to ⟨label⟩", then
+  `MACHINE_WAKING` verbatim, then `MACHINE_AWAKE` on its own a minute or so later — all before you ask
+  for anything. Both switch paths go through `applyMachineSwitch`, so the picker behaves the same.
+  **The wake must stay silent when `canWake` is false** (a machine no provider can wake): that one is
+  not coming back, and the line promises a minute. `WakePolicy` decides all of this and is JVM-tested;
+  what the device is answering is whether the model reads a verbatim line as one, and whether
+  "waking" and "awake now" ever arrive in the same breath — they share a nudge kind precisely so the
+  later replaces the earlier, and hearing both is the failure.
+
 ### 9. Stopping work
 
 The other half of the queue: check 6 is about work that waits, this is about work that dies.

meta-android-app/app/src/main/java/com/meta/wearable/dat/externalsampleapps/cameraaccess/saispike/CallService.kt

@@ -39,6 +39,7 @@ import com.meta.wearable.dat.externalsampleapps.cameraaccess.BuildConfig
 import androidx.core.app.ServiceCompat
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.cancel
 import kotlinx.coroutines.delay
@@ -106,6 +107,16 @@ class CallService : Service() {
    * are the only reason this is volatile at all.
    */
   @Volatile private var saiMuted = false
+
+  /**
+   * The bind-time wake has been asked for this call. One-shot, and deliberately NOT the greeting gate:
+   * `greetOnFirstReady` returns early when muted, and a muted call still needs its machine woken —
+   * mute suppresses the announcement, not the wake.
+   */
+  @Volatile private var wakeRequested = false
+
+  /** The in-flight "is it awake yet" watcher, if any. A machine switch supersedes the previous one. */
+  private var wakeWatch: Job? = null
   // Nudges withheld while muted (they'd be spoken into the void and lost). Replayed on unmute.
   private val heldNudges = HeldNudgeQueue(MAX_HELD_NUDGES)
   // Keepalive throttle: the last time we told the server a human is still present (see maybeKeepalive).
@@ -228,6 +239,9 @@ class CallService : Service() {
     audioPaused = false
     ending = false
     greetingGate.reset()
+    wakeRequested = false
+    wakeWatch?.cancel()
+    wakeWatch = null
     activityLog.reset()
 
     ServiceCompat.startForeground(
@@ -351,7 +365,17 @@ class CallService : Service() {
             // signal, and it is the only one that distinguishes a live call from an open mic.
             onUsage = { p, r, _ -> concierge?.onUsage(p, r) },
             onLog = { log(it) },
-            onReady = { greetOnFirstReady() },
+            onReady = {
+              greetOnFirstReady()
+              // AFTER the greeting, so the opening turn is the first thing heard rather than a status
+              // line, and only once per call. Waiting for the Live session rather than firing at
+              // startCall costs a second or two against a ~60s spin-up and buys both the ordering and
+              // not waking a machine for a call that never connected.
+              if (!wakeRequested) {
+                wakeRequested = true
+                wakeMachine(currentMachineId)
+              }
+            },
             onClosed = { if (callActive && !audioPaused && !ending) scheduleLiveReconnect() },
         )
     live = client
@@ -680,6 +704,9 @@ class CallService : Service() {
     hangupAt = 0L
     hangupJob?.cancel()
     hangupJob = null
+    // Nothing to narrate to: the watcher's only output is speech on a call that no longer exists.
+    wakeWatch?.cancel()
+    wakeWatch = null
     // Drop the clipboard with the call. Held metadata outlives the WS otherwise, and the next call
     // would open with a photo from the last one silently eligible to attach — a stale picture riding
     // an unrelated request is the exact bug the hold-until-asked design exists to prevent.
@@ -1029,6 +1056,117 @@ class CallService : Service() {
       if (notifyModel) {
         live?.injectNudge("machine-switch", MachineSwitcher.contextNudge(match.label))
       }
+      // Both switch paths land here — the voice tool and the picker — so the wake is wired once. It
+      // follows the context nudge for the same reason the bind-time one follows the greeting: the
+      // switch is what the user asked about, and the machine's state is the footnote.
+      wakeMachine(match.machineId)
+    }
+  }
+
+  /**
+   * Bring [machineId] up if it is asleep, and say so if it is.
+   *
+   * Decided behaviour: **announce at the switch, and wake then.** Not lazily on the first task — that
+   * is what this exists to fix. Until this path existed, the wake news could only ride a turn stream
+   * (`data-status` → `AgentEvent.Notice`), which is the response body of `POST /message`, so the first
+   * task of a call absorbed the whole ~1min spin-up in silence and then produced a result. Waking here
+   * moves the spin-up under the conversation instead.
+   *
+   * Three rules worth not undoing:
+   *
+   * 1. **Branch on `startingUp`, not `waking`.** A machine already mid-wake answers `waking = false` —
+   *    correctly, nothing was dispatched — and the user is still owed the minute. `startingUp` is also
+   *    false for a hibernated machine that cannot be woken, which is the case where saying the line
+   *    would be a lie: `MACHINE_WAKING` promises about a minute, and that machine is not coming back.
+   * 2. **The wake happens even while muted; only the announcement is suppressed.** These three lines
+   *    are true for about a minute and then describe a world that has moved on, so they are dropped
+   *    rather than held — the same call `AgentEventRouter` makes for a `notice`. Replayed on unmute
+   *    they would announce a wake that finished minutes ago.
+   * 3. **All three lines share one nudge kind**, so a later one REPLACES an earlier one still held for
+   *    the end of a turn. Without that the model is handed "it's waking up" and "it's awake now" in one
+   *    batch and reads out both — the contradiction `VoiceChannel.say`'s `supersedes` exists to stop.
+   *
+   * `waking = true` only means the wake was DISPATCHED: `ensureVmAwake` fires at vm-service
+   * fire-and-forget and never polls, so the timeout below is this client's own and
+   * [MACHINE_WAKE_FAILED] is the honest end of it.
+   */
+  private fun wakeMachine(machineId: String) {
+    val p = params ?: return
+    // A switch retires the previous machine's watcher: whether the one we just left ever came up is no
+    // longer anything to tell the user about.
+    wakeWatch?.cancel()
+    wakeWatch =
+        scope.launch {
+          val token = SaiAuth.idToken() ?: p.token
+          val outcome =
+              try {
+                ConciergeClient.wakeMachine(p.baseUrl, token, machineId)
+              } catch (e: Exception) {
+                // Best-effort by design. A machine that cannot be woken is not a reason to fail a
+                // call — the first task will wake it the old way, a minute late.
+                log("wake: could not reach the wake endpoint — ${e.message}")
+                return@launch
+              }
+
+          val opening =
+              WakePolicy.onWakeRequested(
+                  startingUp = outcome.startingUp,
+                  muted = saiMuted,
+                  audible = live != null,
+                  status = outcome.status,
+                  canWake = outcome.canWake,
+                  dispatched = outcome.waking,
+              )
+          say(opening)
+
+          // Gated on the MACHINE, not on whether we spoke. Silence because nothing is coming up is the
+          // end of it; silence because we were muted is not — the wake is real and still in flight, and
+          // the mute may be over by the time it lands. `onWatchEnded` re-reads `saiMuted` at that
+          // moment, so unmuting mid-wake still hears "the computer's awake now", which is fresh news
+          // rather than the stale replay the drop-while-muted rule exists to avoid.
+          if (!outcome.startingUp) return@launch
+
+          val deadline = SystemClock.elapsedRealtime() + WAKE_WATCH_MS
+          while (SystemClock.elapsedRealtime() < deadline) {
+            delay(WAKE_POLL_MS)
+            // Both matter: the call may have ended, and the user may have switched away from the
+            // machine we are watching, which makes its readiness someone else's news.
+            if (!callActive || machineId != currentMachineId) return@launch
+            val awake =
+                try {
+                  ConciergeClient.listMachines(p.baseUrl, SaiAuth.idToken() ?: p.token)
+                      .firstOrNull { it.machineId == machineId }
+                      ?.isActive == true
+                } catch (e: Exception) {
+                  log("wake: status poll failed — ${e.message}")
+                  false // keep waiting; a blip is not a failed wake
+                }
+            if (awake) {
+              log("wake: machine is active")
+              say(WakePolicy.onWatchEnded(active = true, muted = saiMuted, audible = live != null))
+              return@launch
+            }
+          }
+          log("wake: gave up after ${WAKE_WATCH_MS / 1000}s — never reached active")
+          say(WakePolicy.onWatchEnded(active = false, muted = saiMuted, audible = live != null))
+        }
+  }
+
+  /**
+   * Act on a [WakePolicy] decision: speak the line verbatim, or log why not.
+   *
+   * The shared `speak:machine-state` kind is what makes a later line REPLACE an earlier one still held
+   * for the end of a turn; see rule 3 on [wakeMachine]. Same wrapper as `LiveVoiceChannel.say`, because
+   * these are `say` constants — and a paraphrase of "about a minute" is how a waking VM once sounded
+   * like a running task.
+   */
+  private fun say(decision: WakeAnnouncement) {
+    when (decision) {
+      is WakeAnnouncement.Silent -> log("wake: not spoken — ${decision.why}")
+      is WakeAnnouncement.Speak ->
+          live?.injectNudge(
+              "speak:machine-state",
+              "[system] Say to the user, briefly and verbatim: \"${decision.line}\"")
     }
   }
 
@@ -1399,6 +1537,16 @@ class CallService : Service() {
      * as "they're still talking" would make ending a call by voice impossible.
      */
     private const val HANGUP_STRAGGLER_GUARD_MS = 600L
+    /**
+     * How long to keep watching for a woken machine to come up.
+     *
+     * `MACHINE_WAKING` promises "about a minute", so this is generous against that rather than tight:
+     * the failure it reports is real and unrecoverable, and calling one early on a machine that was
+     * merely slow would be the worse error.
+     */
+    private const val WAKE_WATCH_MS = 3 * 60_000L
+    /** Poll interval while waiting for a wake. Cheap (`GET /machines`), and nothing pushes this. */
+    private const val WAKE_POLL_MS = 10_000L
     private const val NOTIF_ID = 42
     private const val REASON_NOTIF_ID = 43
     /** Default "ask before delivering an update" threshold; overridable via StartParams (app setting). */

meta-android-app/app/src/main/java/com/meta/wearable/dat/externalsampleapps/cameraaccess/saispike/ConciergeClient.kt

@@ -54,12 +54,61 @@ data class SessionBootstrap(
 )
 
 /** A Sai machine (VM) the user can target, from GET /v1/agents/machines. */
-data class Machine(val machineId: String, val name: String?) {
+data class Machine(
+    val machineId: String,
+    val name: String?,
+    /**
+     * VM state as the server stores it: `active` · `hibernated` · `hibernating` · `wakingup`, or null
+     * when the machine has never reported one — read that as offline.
+     *
+     * Only [isActive] is read at present, by the wake watcher. Deliberately kept as the server's own
+     * string rather than an enum: a second spelling of these states is how the two drift apart, and
+     * an unknown value must degrade to "not active" rather than fail to parse.
+     */
+    val status: String? = null,
+    /**
+     * Whether a hibernated machine can be woken remotely at all — a property of where it is hosted,
+     * not of what it is doing now.
+     *
+     * The reason this is not inferable from [status]: a `hibernated` machine with `canWake = false` is
+     * asleep and staying that way, so announcing a wake for it promises a minute that never ends.
+     */
+    val canWake: Boolean = false,
+) {
   /** Display label for the picker. */
   val label: String
     get() = name?.takeIf { it.isNotBlank() } ?: machineId
+
+  /** Up and usable. Anything else — including an unrecognised state — is not. */
+  val isActive: Boolean
+    get() = status == "active"
 }
 
+/**
+ * What `POST /v1/agents/wake` answered.
+ *
+ * Four fields because the caller has four different sentences to choose between, and only one of them
+ * is true at a time. See [ConciergeClient.wakeMachine].
+ */
+data class WakeOutcome(
+    /**
+     * THIS call dispatched a wake. False for a machine that was already awake, already on its way, or
+     * cannot be woken — and false is not the same as "nothing to say" in the second case.
+     */
+    val waking: Boolean,
+    /**
+     * The machine is not usable yet but is coming up, whether or not we are the reason.
+     *
+     * **Branch on this, not [waking].** A machine already mid-wake answers `waking = false` — correctly,
+     * since nothing was dispatched — and the user is still owed the "about a minute" line. It is also
+     * false for a hibernated machine that cannot be woken, which is exactly when nothing should be said.
+     */
+    val startingUp: Boolean,
+    /** As stored, read server-side BEFORE the dispatch. Null when the field is absent. */
+    val status: String?,
+    val canWake: Boolean,
+)
+
 object ConciergeClient {
   /**
    * List the user's Sai machines (like `sai machine` in the CLI) so the app can offer a picker.
@@ -84,7 +133,14 @@ object ConciergeClient {
         val arr = JSONObject(body).optJSONArray("machines") ?: return@withContext emptyList()
         (0 until arr.length()).map {
           val m = arr.getJSONObject(it)
-          Machine(m.getString("machineId"), m.optString("name").ifEmpty { null })
+          Machine(
+              machineId = m.getString("machineId"),
+              name = m.optString("name").ifEmpty { null },
+              // Absent on a server older than 2026-08-20, which reads as "offline / cannot wake" —
+              // and the wake path degrades to doing nothing rather than to guessing.
+              status = m.optString("status").ifEmpty { null },
+              canWake = m.optBoolean("canWake", false),
+          )
         }
       }
 
@@ -171,4 +227,51 @@ object ConciergeClient {
         }
         JSONObject(body)
       }
+
+  /**
+   * Wake a hibernated machine, without sending it any work — `POST /v1/agents/wake`.
+   *
+   * The point of it having no payload: every other wake in the system rides a delivery, and a message
+   * arriving during a running turn is folded INTO that turn. So waking by sending a throwaway "hello"
+   * means the dummy and the user's next real request share one turn, and the dummy's completion ends
+   * it out from under the real work. There is nothing to deliver at call bind anyway.
+   *
+   * Safe to call redundantly — the server no-ops on a machine that is already awake. Throws
+   * [ConciergeHttpException] on a non-2xx; a 404 means the machine is not this account's.
+   */
+  suspend fun wakeMachine(
+      baseUrl: String,
+      bearerToken: String,
+      machineId: String,
+  ): WakeOutcome =
+      withContext(Dispatchers.IO) {
+        val conn =
+            (URL("$baseUrl/v1/agents/wake").openConnection() as HttpURLConnection).apply {
+              requestMethod = "POST"
+              doOutput = true
+              connectTimeout = 10_000
+              readTimeout = 15_000
+              applyCloudApiHeaders(bearerToken)
+              setRequestProperty("Content-Type", "application/json")
+            }
+        conn.outputStream.use {
+          it.write(JSONObject().put("machineId", machineId).toString().toByteArray())
+        }
+        val code = conn.responseCode
+        val stream = if (code in 200..299) conn.inputStream else conn.errorStream
+        val body = stream?.bufferedReader()?.use { it.readText() } ?: ""
+        conn.disconnect()
+        if (code !in 200..299) {
+          throw ConciergeHttpException(code, "POST /v1/agents/wake failed: HTTP $code — ${body.take(300)}")
+        }
+        val o = JSONObject(body)
+        WakeOutcome(
+            waking = o.optBoolean("waking", false),
+            // Absent on an older server: nothing is starting up as far as this client can tell, so the
+            // wake path stays silent rather than announcing a minute it cannot vouch for.
+            startingUp = o.optBoolean("startingUp", false),
+            status = o.optString("status").ifEmpty { null },
+            canWake = o.optBoolean("canWake", false),
+        )
+      }
 }