@elizaos/app-core 2.0.0-beta.3 → 2.0.3-beta.3

package/platforms/android/app/src/main/java/ai/elizaos/app/ElizaAgentService.java

@@ -16,7 +16,10 @@ import android.util.Log;
 
 import androidx.core.app.NotificationCompat;
 
-import ByteArrayOutputStream;
+import ai.elizaos.app.BuildConfig;
+import ai.elizaos.app.R;
+
+import java.io.ByteArrayOutputStream;
 import java.io.File;
 import java.io.FileOutputStream;
 import java.io.IOException;
@@ -24,12 +27,18 @@ import java.io.InputStream;
 import java.io.OutputStream;
 import java.nio.charset.StandardCharsets;
 import java.net.HttpURLConnection;
+import java.net.InetSocketAddress;
+import java.net.Socket;
 import java.net.URL;
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
+import java.util.Locale;
 import java.util.Map;
 
+import org.json.JSONException;
+import org.json.JSONObject;
+
 /**
  * Foreground service that owns the local Eliza agent process on Android.
  *
@@ -53,10 +62,10 @@ public class ElizaAgentService extends Service {
     private static final int NOTIFICATION_ID = 2;
 
     // Intent actions
-    public static final String ACTION_START = "ai.elizaos.app.action.START_AGENT";
-    public static final String ACTION_STOP = "ai.elizaos.app.action.STOP_AGENT";
-    public static final String ACTION_RESTART = "ai.elizaos.app.action.RESTART_AGENT";
-    public static final String ACTION_UPDATE_STATUS = "ai.elizaos.app.action.UPDATE_AGENT_STATUS";
+    public static final String ACTION_START = "app.eliza.action.START_AGENT";
+    public static final String ACTION_STOP = "app.eliza.action.STOP_AGENT";
+    public static final String ACTION_RESTART = "app.eliza.action.RESTART_AGENT";
+    public static final String ACTION_UPDATE_STATUS = "app.eliza.action.UPDATE_AGENT_STATUS";
 
     // Extras
     private static final String EXTRA_STATUS = "status";
@@ -87,9 +96,28 @@ public class ElizaAgentService extends Service {
     private static final int AGENT_PORT = 31337;
     private static final String HEALTH_URL = "http://127.0.0.1:" + AGENT_PORT + "/api/health";
 
+    /**
+     * Abstract-namespace AF_UNIX socket the in-process bionic GPU inference
+     * server ({@link ElizaBionicInferenceServer}) binds, and the musl agent's
+     * BionicHostLoader connects to. Abstract namespace (no filesystem path)
+     * avoids SELinux file-label issues under the priv_app domain. The musl
+     * agent reaches it as {@code Bun.connect({unix:"\0" + name})}.
+     */
+    static final String BIONIC_INFERENCE_SOCKET_NAME = "eliza_bionic_infer_v1";
+    private static final String LOCAL_AGENT_BASE_URL = "http://127.0.0.1:" + AGENT_PORT;
+    private static final int LOCAL_REQUEST_DEFAULT_TIMEOUT_MS = 10_000;
+    private static final int LOCAL_REQUEST_MAX_TIMEOUT_MS = 600_000;
+    // Read-timeout budget applied to slow on-device inference routes (ASR / TTS
+    // / transcription / chat generation) when the caller doesn't pin its own —
+    // matches LOCAL_REQUEST_MAX_TIMEOUT_MS and the agent's chat-generation
+    // budget so a cold model load never trips a spurious local_agent_unavailable.
+    private static final int LOCAL_INFERENCE_REQUEST_TIMEOUT_MS = 600_000;
+    private static final int LOCAL_REQUEST_MAX_BODY_BYTES = 10 * 1024 * 1024;
+    private static final int LOCAL_REQUEST_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+
     // The on-device boot path is heavy: PGlite extension extraction +
     // plugin resolution + libllama dlopen + first-time model load can
-    // exceed 240 s on a cold cuttlefish x86_64 image. The chat path is
+    // exceed several minutes on a cold cuttlefish x86_64 image. The chat path is
     // even heavier: a single planner-produced prompt at ~12k tokens,
     // chunked through llama_decode on emulated CPU, can run 15–30 min
     // wall-clock for a single chat turn (multiple model invocations:
@@ -102,7 +130,7 @@ public class ElizaAgentService extends Service {
     // event loop yet), we DO NOT count a strike — the process is doing
     // exactly what it should be doing, just synchronously inside a
     // native call. We only count strikes when the process is actually
-    // dead OR returns 5xx from /api/health (a real crash signal).
+    // dead OR returns non-2xx / non-ready health (a real crash signal).
     // Strikes accumulate when the process is dead, which forces a
     // restart via the existing scheduleRestart() path.
     //
@@ -116,16 +144,29 @@ public class ElizaAgentService extends Service {
     private static final long WATCHDOG_INTERVAL_MS = 600_000L;
     private static final int HEALTH_FAIL_STRIKES = 3;
     private static final long HEALTH_TIMEOUT_MS = 30_000L;
+    // Keep this aligned with packages/app/scripts/mobile-local-chat-smoke.mjs:
+    // ANDROID_HEALTH_ATTEMPTS (240) × 2000 ms = 480 s.
+    private static final long STARTUP_HEALTH_GRACE_MS = 480_000L;
+    private static final long STARTUP_HEALTH_POLL_MS = 5_000L;
     private static final int MAX_RESTART_ATTEMPTS = 5;
     private static final long PROCESS_TERMINATE_GRACE_MS = 5_000L;
+    // How long after a detached launch we treat a not-yet-listening agent as
+    // "still cold-booting" and refuse to relaunch it (the boot — plugin
+    // resolution + first model load — runs ~60-90s on an emulated CPU). Past
+    // this the boot is considered failed and a relaunch is allowed.
+    private static final long AGENT_BOOT_GRACE_MS = 120_000L;
 
     private final Object processLock = new Object();
     private Process agentProcess;
     private Thread stdoutPump;
     private Thread stderrPump;
     private WatchdogThread watchdog;
+    /** In-process bionic GPU inference host; non-null only when delegating. */
+    private volatile ElizaBionicInferenceServer bionicInferenceServer;
     private Thread startWorker;
     private volatile boolean shuttingDown;
+    private volatile boolean detachedAgentMode;
+    private volatile long detachedLaunchStartedAtMs;
     private int restartAttempts;
     private String currentStatus = "starting";
 
@@ -136,12 +177,424 @@ public class ElizaAgentService extends Service {
     // include `Authorization: Bearer <token>`. The agent enforces the
     // token via ELIZA_REQUIRE_LOCAL_AUTH=1.
     private static volatile String currentLocalAgentToken;
+    private static volatile String currentTerminalRunToken;
 
     /** Called by the Capacitor agent plugin Android binding. */
     public static String localAgentToken() {
         return currentLocalAgentToken;
     }
 
+    /**
+     * Cross-process token recovery. The token is a per-process static, but the
+     * bun agent is a DETACHED process that outlives the app process that started
+     * it — so a freshly-launched WebView process (e.g. after a boot autostart)
+     * sees a null static even though a healthy agent is running, which dead-ends
+     * the dashboard at the pairing screen. Fall back to the recovery file that
+     * {@link #writeLocalAgentTokenFile} persists, and cache it for this process.
+     */
+    public static String localAgentToken(Context context) {
+        String token = currentLocalAgentToken;
+        if (token != null && !token.trim().isEmpty()) {
+            return token;
+        }
+        if (context == null) {
+            return token;
+        }
+        String fromFile = readLocalAgentTokenFile(context);
+        if (fromFile != null && !fromFile.trim().isEmpty()) {
+            currentLocalAgentToken = fromFile.trim();
+            return currentLocalAgentToken;
+        }
+        return token;
+    }
+
+    private static String readLocalAgentTokenFile(Context context) {
+        File file = new File(new File(context.getFilesDir(), "auth"), "local-agent-token");
+        if (!file.isFile()) {
+            return null;
+        }
+        try (java.io.FileInputStream in = new java.io.FileInputStream(file)) {
+            java.io.ByteArrayOutputStream bos = new java.io.ByteArrayOutputStream();
+            byte[] buf = new byte[256];
+            int n;
+            while ((n = in.read(buf)) != -1) {
+                bos.write(buf, 0, n);
+            }
+            return new String(bos.toByteArray(), java.nio.charset.StandardCharsets.UTF_8).trim();
+        } catch (IOException error) {
+            Log.w(TAG, "Unable to read local-agent token file: " + error.getMessage());
+            return null;
+        }
+    }
+
+    /** Called by trusted in-app code that needs to route shell requests. */
+    public static String terminalRunToken() {
+        return currentTerminalRunToken;
+    }
+
+    /**
+     * Shared in-process request surface for Android native plugins and workers.
+     *
+     * The current Android agent still serves routes from the Bun child process
+     * over loopback, but callers should route through this method instead of
+     * opening their own sockets. That keeps auth, header filtering, body caps,
+     * and future Binder/stdio replacement behind one app-owned boundary.
+     */
+    /**
+     * Routes whose on-device handler does a synchronous, multi-second (cold
+     * model load) or open-ended (token-by-token generation) llama call before
+     * the HTTP response completes — they need the long inference read-timeout
+     * budget, not the 10s default used for ordinary CRUD API calls.
+     */
+    private static boolean isLongRunningInferencePath(String path) {
+        if (path == null) return false;
+        String p = path.toLowerCase(Locale.US);
+        return p.contains("/asr")
+            || p.contains("/tts")
+            || p.contains("/transcription")
+            || p.contains("/speech")
+            || p.contains("/local-inference")
+            || p.contains("/messages/stream")
+            || p.contains("/messages")
+            || p.contains("/greeting")
+            || p.contains("/voice");
+    }
+
+    public static String requestLocalAgent(String requestJson) throws IOException, JSONException {
+        JSONObject request = requestJson == null || requestJson.trim().isEmpty()
+            ? new JSONObject()
+            : new JSONObject(requestJson);
+        String path = request.optString("path", "").trim();
+        if (!isSafeLocalAgentPath(path)) {
+            throw new IllegalArgumentException("Local agent request requires a path that starts with /");
+        }
+        String method = request.optString("method", "GET")
+            .trim()
+            .toUpperCase(Locale.US);
+        if (!method.matches("^[A-Z]{1,16}$")) {
+            throw new IllegalArgumentException("Unsupported HTTP method");
+        }
+        int timeoutMs = request.optInt("timeoutMs", LOCAL_REQUEST_DEFAULT_TIMEOUT_MS);
+        // On-device inference is inherently slow: a cold model load alone — the
+        // ~1 GB ASR GGUF, the OmniVoice TTS GGUFs, or evicting + reloading the
+        // chat model — is a multi-second synchronous llama load before the agent
+        // emits a single byte, and transcription/synthesis/generation on
+        // emulated or low-end CPU runs well past 10 s. The WebView transport
+        // sends its generic 10 s fetch timeout for these calls too, which aborts
+        // them mid-decode and surfaces "Local agent request failed" /
+        // local_agent_unavailable, failing the whole voice turn (and every route
+        // that touches inference). FLOOR inference/voice routes at the inference
+        // budget — raise a too-short caller timeout, never lower a longer one.
+        if (isLongRunningInferencePath(path)) {
+            timeoutMs = Math.max(timeoutMs, LOCAL_INFERENCE_REQUEST_TIMEOUT_MS);
+        }
+        timeoutMs = Math.max(1_000, Math.min(timeoutMs, LOCAL_REQUEST_MAX_TIMEOUT_MS));
+        JSONObject headers = request.optJSONObject("headers");
+        Object rawBody = request.opt("body");
+        String body = rawBody == null || rawBody == JSONObject.NULL ? null : rawBody.toString();
+
+        return performLocalAgentRequest(
+            method,
+            path,
+            headers == null ? new JSONObject() : headers,
+            body,
+            timeoutMs,
+            currentLocalAgentToken
+        ).toString();
+    }
+
+    /**
+     * Streaming variant of {@link #requestLocalAgent}. Where that buffers the
+     * whole loopback response into one JSON string (so an SSE body's token
+     * frames arrive all at once and the chat reply never streams on mobile),
+     * this opens the same request and reads the response InputStream
+     * INCREMENTALLY, pushing each fragment to {@code onEvent} as a small JSON
+     * envelope the AgentPlugin maps to Capacitor events:
+     *   {"type":"response","status":..,"statusText":..,"headers":{..}}  (once, first)
+     *   {"type":"chunk","dataBase64":".."}                              (per read)
+     *   {"type":"complete"}  or  {"type":"complete","error":".."}        (terminal)
+     *
+     * Single attempt by design: a connect failure emits a terminal error event
+     * and the WebView falls back to the buffered {@link #requestLocalAgent}
+     * (which carries the cold-load connect retry), so non-idempotent POSTs are
+     * never replayed here. Runs on the caller's thread (AgentPlugin spawns one).
+     */
+    public static void requestLocalAgentStream(String requestJson, java.util.function.Consumer<String> onEvent) {
+        try {
+            JSONObject request = requestJson == null || requestJson.trim().isEmpty()
+                ? new JSONObject()
+                : new JSONObject(requestJson);
+            String path = request.optString("path", "").trim();
+            if (!isSafeLocalAgentPath(path)) {
+                throw new IllegalArgumentException("Local agent request requires a path that starts with /");
+            }
+            String method = request.optString("method", "GET").trim().toUpperCase(Locale.US);
+            if (!method.matches("^[A-Z]{1,16}$")) {
+                throw new IllegalArgumentException("Unsupported HTTP method");
+            }
+            int timeoutMs = request.optInt("timeoutMs", LOCAL_REQUEST_DEFAULT_TIMEOUT_MS);
+            if (isLongRunningInferencePath(path)) {
+                timeoutMs = Math.max(timeoutMs, LOCAL_INFERENCE_REQUEST_TIMEOUT_MS);
+            }
+            timeoutMs = Math.max(1_000, Math.min(timeoutMs, LOCAL_REQUEST_MAX_TIMEOUT_MS));
+            JSONObject headers = request.optJSONObject("headers");
+            if (headers == null) headers = new JSONObject();
+            Object rawBody = request.opt("body");
+            String body = rawBody == null || rawBody == JSONObject.NULL ? null : rawBody.toString();
+            streamLocalAgentRequest(method, path, headers, body, timeoutMs, currentLocalAgentToken, onEvent);
+        } catch (Exception error) {
+            emitStreamComplete(onEvent, error.getMessage() == null ? "Local agent stream failed" : error.getMessage());
+        }
+    }
+
+    private static void streamLocalAgentRequest(
+        String method,
+        String path,
+        JSONObject headers,
+        String body,
+        int timeoutMs,
+        String token,
+        java.util.function.Consumer<String> onEvent
+    ) throws IOException, JSONException {
+        byte[] bodyBytes = body == null ? null : body.getBytes(StandardCharsets.UTF_8);
+        if (bodyBytes != null && bodyBytes.length > LOCAL_REQUEST_MAX_BODY_BYTES) {
+            throw new IOException("Request body is too large");
+        }
+
+        HttpURLConnection conn = null;
+        try {
+            URL url = new URL(LOCAL_AGENT_BASE_URL + path);
+            conn = (HttpURLConnection) url.openConnection();
+            conn.setRequestMethod(method);
+            conn.setConnectTimeout(timeoutMs);
+            conn.setReadTimeout(timeoutMs);
+            conn.setInstanceFollowRedirects(false);
+            conn.setUseCaches(false);
+            applyLocalAgentHeaders(conn, headers);
+            if (token != null && !token.trim().isEmpty() && !hasHeader(headers, "authorization")) {
+                conn.setRequestProperty("Authorization", "Bearer " + token.trim());
+            }
+            if (bodyBytes != null && !"GET".equals(method) && !"HEAD".equals(method)) {
+                if (!hasHeader(headers, "content-type")) {
+                    conn.setRequestProperty("Content-Type", "application/json; charset=utf-8");
+                }
+                conn.setDoOutput(true);
+                try (OutputStream out = conn.getOutputStream()) {
+                    out.write(bodyBytes);
+                    out.flush();
+                }
+            }
+
+            int status = conn.getResponseCode();
+            JSONObject responseHeaders = new JSONObject();
+            for (Map.Entry<String, List<String>> entry : conn.getHeaderFields().entrySet()) {
+                String key = entry.getKey();
+                List<String> values = entry.getValue();
+                if (key == null || values == null || values.isEmpty()) continue;
+                responseHeaders.put(key.toLowerCase(Locale.US), String.join(", ", values));
+            }
+            onEvent.accept(new JSONObject()
+                .put("type", "response")
+                .put("status", status)
+                .put("statusText", conn.getResponseMessage() == null ? "" : conn.getResponseMessage())
+                .put("headers", responseHeaders)
+                .toString());
+
+            // Read the body as it arrives. The agent flushes each SSE frame, so a
+            // blocking read returns per-frame rather than waiting for the whole
+            // body — that is exactly the incremental delivery the WebView needs.
+            InputStream stream = status >= 400 ? conn.getErrorStream() : conn.getInputStream();
+            if (stream != null) {
+                byte[] buffer = new byte[8192];
+                int read;
+                while ((read = stream.read(buffer)) != -1) {
+                    if (read == 0) continue;
+                    String dataBase64 = android.util.Base64.encodeToString(
+                        java.util.Arrays.copyOf(buffer, read), android.util.Base64.NO_WRAP);
+                    onEvent.accept(new JSONObject()
+                        .put("type", "chunk")
+                        .put("dataBase64", dataBase64)
+                        .toString());
+                }
+            }
+            emitStreamComplete(onEvent, null);
+        } finally {
+            if (conn != null) conn.disconnect();
+        }
+    }
+
+    private static void emitStreamComplete(java.util.function.Consumer<String> onEvent, String error) {
+        try {
+            JSONObject complete = new JSONObject().put("type", "complete");
+            if (error != null) complete.put("error", error);
+            onEvent.accept(complete.toString());
+        } catch (JSONException ignored) {
+            // A complete event with no error is the worst case if JSON fails.
+            onEvent.accept("{\"type\":\"complete\"}");
+        }
+    }
+
+    private static boolean isSafeLocalAgentPath(String path) {
+        return path != null
+            && path.startsWith("/")
+            && !path.startsWith("//")
+            && !path.contains("://");
+    }
+
+    private static JSONObject performLocalAgentRequest(
+        String method,
+        String path,
+        JSONObject headers,
+        String body,
+        int timeoutMs,
+        String token
+    ) throws IOException, JSONException {
+        // The on-device agent is single-threaded: while bun is inside a long
+        // synchronous FFI call (a cold ASR/TTS model load, or a llama_decode for
+        // a chat reply) its HTTP listener briefly stops accepting connections, so
+        // a concurrent request — e.g. createConversation right after a voice
+        // transcription — can hit "connection refused". The request bytes were
+        // never sent, so it is safe to back off and re-dial rather than surface a
+        // spurious local_agent_unavailable that fails the whole voice turn. Only
+        // connection-establishment failures are retried; a read timeout (request
+        // already sent) propagates so non-idempotent POSTs are never replayed.
+        // The window must outlast the longest event-loop stall: after a voice
+        // transcription the agent evicts + cold-reloads the chat model (a
+        // synchronous ~10-15 s llama load on phone CPU) before generating the
+        // reply, during which the HTTP listener refuses connections.
+        final int connectRetries = 15;
+        IOException lastConnectError = null;
+        for (int attempt = 0; attempt <= connectRetries; attempt++) {
+            try {
+                return performLocalAgentRequestOnce(
+                    method, path, headers, body, timeoutMs, token);
+            } catch (java.net.ConnectException connectError) {
+                lastConnectError = connectError;
+            } catch (java.net.SocketTimeoutException timeoutError) {
+                // Distinguish connect-timeout (never sent → retry) from
+                // read-timeout (sent → must not replay). HttpURLConnection
+                // surfaces both as SocketTimeoutException; the connect phase
+                // message contains "connect".
+                String msg = timeoutError.getMessage();
+                if (msg != null && msg.toLowerCase(Locale.US).contains("connect")) {
+                    lastConnectError = timeoutError;
+                } else {
+                    throw timeoutError;
+                }
+            }
+            if (attempt < connectRetries) {
+                try {
+                    Thread.sleep(250L * (attempt + 1));
+                } catch (InterruptedException interrupted) {
+                    Thread.currentThread().interrupt();
+                    throw lastConnectError;
+                }
+            }
+        }
+        throw lastConnectError != null
+            ? lastConnectError
+            : new IOException("local agent unreachable");
+    }
+
+    private static JSONObject performLocalAgentRequestOnce(
+        String method,
+        String path,
+        JSONObject headers,
+        String body,
+        int timeoutMs,
+        String token
+    ) throws IOException, JSONException {
+        byte[] bodyBytes = body == null ? null : body.getBytes(StandardCharsets.UTF_8);
+        if (bodyBytes != null && bodyBytes.length > LOCAL_REQUEST_MAX_BODY_BYTES) {
+            throw new IOException("Request body is too large");
+        }
+
+        HttpURLConnection conn = null;
+        try {
+            URL url = new URL(LOCAL_AGENT_BASE_URL + path);
+            conn = (HttpURLConnection) url.openConnection();
+            conn.setRequestMethod(method);
+            conn.setConnectTimeout(timeoutMs);
+            conn.setReadTimeout(timeoutMs);
+            conn.setInstanceFollowRedirects(false);
+            conn.setUseCaches(false);
+            applyLocalAgentHeaders(conn, headers);
+            if (token != null && !token.trim().isEmpty() && !hasHeader(headers, "authorization")) {
+                conn.setRequestProperty("Authorization", "Bearer " + token.trim());
+            }
+            if (bodyBytes != null && !"GET".equals(method) && !"HEAD".equals(method)) {
+                if (!hasHeader(headers, "content-type")) {
+                    conn.setRequestProperty("Content-Type", "application/json; charset=utf-8");
+                }
+                conn.setDoOutput(true);
+                try (OutputStream out = conn.getOutputStream()) {
+                    out.write(bodyBytes);
+                    out.flush();
+                }
+            }
+
+            int status = conn.getResponseCode();
+            InputStream stream = status >= 400 ? conn.getErrorStream() : conn.getInputStream();
+            // Read the raw response bytes so binary payloads (e.g. local TTS WAV
+            // audio, images) survive the bridge intact. `body` is a best-effort
+            // UTF-8 view for text callers; `bodyBase64` carries the lossless raw
+            // bytes that binary callers decode — encoding the bytes as a UTF-8
+            // String first (the old path) replaced every non-UTF-8 byte with
+            // U+FFFD, corrupting WAV/PNG payloads beyond recovery.
+            byte[] responseBytes = readResponseBytes(stream, LOCAL_REQUEST_MAX_RESPONSE_BYTES);
+            String responseBody = new String(responseBytes, StandardCharsets.UTF_8);
+            JSONObject responseHeaders = new JSONObject();
+            for (Map.Entry<String, List<String>> entry : conn.getHeaderFields().entrySet()) {
+                String key = entry.getKey();
+                List<String> values = entry.getValue();
+                if (key == null || values == null || values.isEmpty()) continue;
+                responseHeaders.put(key.toLowerCase(Locale.US), String.join(", ", values));
+            }
+            return new JSONObject()
+                .put("status", status)
+                .put("statusText", conn.getResponseMessage() == null ? "" : conn.getResponseMessage())
+                .put("headers", responseHeaders)
+                .put("body", responseBody)
+                .put(
+                    "bodyBase64",
+                    android.util.Base64.encodeToString(responseBytes, android.util.Base64.NO_WRAP)
+                )
+                .put("bodyEncoding", "base64");
+        } finally {
+            if (conn != null) conn.disconnect();
+        }
+    }
+
+    private static void applyLocalAgentHeaders(HttpURLConnection conn, JSONObject headers) {
+        if (headers == null) return;
+        java.util.Iterator<String> keys = headers.keys();
+        while (keys.hasNext()) {
+            String key = keys.next();
+            if (isBlockedForwardedHeader(key)) continue;
+            Object value = headers.opt(key);
+            if (value == null || value == JSONObject.NULL) continue;
+            String stringValue = value.toString();
+            if (!stringValue.trim().isEmpty()) {
+                conn.setRequestProperty(key, stringValue);
+            }
+        }
+    }
+
+    private static boolean hasHeader(JSONObject headers, String expected) {
+        if (headers == null) return false;
+        java.util.Iterator<String> keys = headers.keys();
+        while (keys.hasNext()) {
+            if (expected.equalsIgnoreCase(keys.next())) return true;
+        }
+        return false;
+    }
+
+    private static boolean isBlockedForwardedHeader(String key) {
+        return "host".equalsIgnoreCase(key)
+            || "connection".equalsIgnoreCase(key)
+            || "content-length".equalsIgnoreCase(key);
+    }
+
     // ── Lifecycle ────────────────────────────────────────────────────────
 
     @Override
@@ -201,6 +654,10 @@ public class ElizaAgentService extends Service {
             watchdog.interrupt();
             watchdog = null;
         }
+        if (bionicInferenceServer != null) {
+            bionicInferenceServer.stop();
+            bionicInferenceServer = null;
+        }
         stopAgentProcess();
         NotificationManager mgr = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
         if (mgr != null) {
@@ -226,7 +683,11 @@ public class ElizaAgentService extends Service {
         String[] supported = Build.SUPPORTED_ABIS;
         if (supported != null) {
             for (String abi : supported) {
-                if ("arm64-v8a".equals(abi) || "x86_64".equals(abi)) return abi;
+                if (
+                    "arm64-v8a".equals(abi) ||
+                    "x86_64".equals(abi) ||
+                    "riscv64".equals(abi)
+                ) return abi;
             }
             if (supported.length > 0) return supported[0];
         }
@@ -316,6 +777,10 @@ public class ElizaAgentService extends Service {
             if (initDbWasm.exists()) initDbWasm.delete();
             File pgData = new File(root, "pglite.data");
             if (pgData.exists()) pgData.delete();
+            File ortWasmLoader = new File(root, "ort-wasm-simd-threaded.mjs");
+            if (ortWasmLoader.exists()) ortWasmLoader.delete();
+            File ortWasmBinary = new File(root, "ort-wasm-simd-threaded.wasm");
+            if (ortWasmBinary.exists()) ortWasmBinary.delete();
             File vec = new File(getFilesDir(), "vector.tar.gz");
             if (vec.exists()) vec.delete();
             File fuzzy = new File(getFilesDir(), "fuzzystrmatch.tar.gz");
@@ -359,6 +824,13 @@ public class ElizaAgentService extends Service {
         copyAssetIfPresent(assets, "agent/pglite.wasm", new File(root, "pglite.wasm"));
         copyAssetIfPresent(assets, "agent/initdb.wasm", new File(root, "initdb.wasm"));
         copyAssetIfPresent(assets, "agent/pglite.data", new File(root, "pglite.data"));
+        // Legacy ONNX Runtime Web sidecars used by the removed Android Kokoro
+        // TTS path. Current AOSP TTS uses fused OmniVoice, so fresh bundles do
+        // not ship these files; keep extraction best-effort for older APKs.
+        copyAssetIfPresent(assets, "agent/ort-wasm-simd-threaded.mjs",
+            new File(root, "ort-wasm-simd-threaded.mjs"));
+        copyAssetIfPresent(assets, "agent/ort-wasm-simd-threaded.wasm",
+            new File(root, "ort-wasm-simd-threaded.wasm"));
         // aapt2 not only strips `.gz` from `*.tar.gz` asset names, it also
         // DECOMPRESSES them into raw tar bytes. PGlite's loader does
         // `new URL("../X.tar.gz", ...)` then pipes the bytes through
@@ -394,6 +866,8 @@ public class ElizaAgentService extends Service {
 
         File bun = new File(abiDir, BUN_BINARY);
         if (bun.exists()) bun.setExecutable(true, false);
+        File llamaServer = new File(abiDir, "llama-server");
+        if (llamaServer.exists()) llamaServer.setExecutable(true, false);
         File launch = new File(root, AGENT_LAUNCH_SCRIPT);
         if (launch.exists()) launch.setExecutable(true, false);
         for (String name : abiFiles) {
@@ -511,6 +985,7 @@ public class ElizaAgentService extends Service {
     private String packagedMuslLoaderName(String abi) {
         if ("arm64-v8a".equals(abi)) return "libeliza_ld_musl_aarch64.so";
         if ("x86_64".equals(abi)) return "libeliza_ld_musl_x86_64.so";
+        if ("riscv64".equals(abi)) return "libeliza_ld_musl_riscv64.so";
         return null;
     }
 
@@ -590,10 +1065,8 @@ public class ElizaAgentService extends Service {
 
     /**
      * Like copyAssetIfMissing, but silently no-ops when the source asset is
-     * absent. Used for PGlite + plugin-manifest payload that Phase D
-     * generates only when the real agent bundle is built; with the spike
-     * placeholder bundle the assets are simply not present and the agent
-     * runs without them.
+     * absent. Used for optional PGlite + plugin-manifest payloads; minimal
+     * mobile bundles can run without those embedded database extensions.
      */
     private void copyAssetIfPresent(AssetManager assets, String assetPath, File target) throws IOException {
         try (InputStream probe = assets.open(assetPath)) {
@@ -642,11 +1115,65 @@ public class ElizaAgentService extends Service {
 
     // ── Process lifecycle ────────────────────────────────────────────────
 
+    /**
+     * Start the in-process bionic inference host whenever the fused native lib
+     * AND a local voice bundle (kokoro) are present — independent of the LLM
+     * runtime mode and of whether the agent process spawns fresh or adopts a
+     * surviving one.
+     *
+     * <p>Previously the host was started ONLY inside {@link #startAgentProcess()}'s
+     * fresh-spawn {@code delegateToBionicHost} block, so after a process restart
+     * that adopts a surviving agent (or when the agent runs cloud-routed) the
+     * host never bound its abstract UDS, and {@code TalkMode}'s local Kokoro TTS
+     * silently fell back to the system (Google) TTS. The voice host serves Kokoro
+     * from {@code libelizainference} + the staged bundle and needs no LLM, so its
+     * lifecycle is decoupled from agent inference here.
+     *
+     * <p>{@link ElizaBionicInferenceServer#start()} is idempotent and never throws
+     * (it logs + returns on lib-load / socket-bind failure), so this is purely
+     * additive: worst case the host stays down and TalkMode falls back to system
+     * TTS exactly as before — it cannot affect agent startup.
+     */
+    private synchronized void ensureBionicVoiceHost() {
+        if (bionicInferenceServer != null) {
+            return;
+        }
+        File fusedLib = new File(nativeLibraryDir(), "libelizainference.so");
+        if (!fusedLib.isFile()) {
+            return;
+        }
+        File kokoroVoice = new File(getFilesDir(), "eliza-1/bundle/tts/kokoro");
+        if (!kokoroVoice.isDirectory()) {
+            return;
+        }
+        try {
+            String defaultBundleDir =
+                new File(getFilesDir(), "eliza-1/bundle").getAbsolutePath();
+            ElizaBionicInferenceServer host =
+                new ElizaBionicInferenceServer(BIONIC_INFERENCE_SOCKET_NAME, defaultBundleDir);
+            host.start();
+            bionicInferenceServer = host;
+            Log.i(TAG, "ensureBionicVoiceHost: local voice host started"
+                + " (kokoro bundle present, independent of LLM mode)");
+        } catch (Throwable t) {
+            Log.w(TAG, "ensureBionicVoiceHost: could not start local voice host", t);
+        }
+    }
+
     private void requestAgentStart(boolean restartFirst) {
+        // Bring up the local-voice (Kokoro TTS) bionic host on every service
+        // start, before the agent-already-running guards below — so it binds
+        // even when the agent is adopted rather than freshly spawned.
+        ensureBionicVoiceHost();
         synchronized (processLock) {
             if (!restartFirst && agentProcess != null && agentProcess.isAlive()) {
                 return;
             }
+            if (!restartFirst
+                    && detachedAgentMode
+                    && ("starting".equals(currentStatus) || "running".equals(currentStatus))) {
+                return;
+            }
             if (startWorker != null && startWorker.isAlive()) {
                 return;
             }
@@ -674,6 +1201,47 @@ public class ElizaAgentService extends Service {
                 return;
             }
 
+            // Detached agents outlive the service/app process that launched
+            // them. If a prior instance's agent is still bound to the loopback
+            // port, ADOPT it instead of relaunching: launch.sh pkills any
+            // running bun before forking a fresh one, so a needless relaunch
+            // tears the live HTTP listener down for tens of seconds and the
+            // WebView's /api/auth/me startup probe fails with "Backend
+            // Unreachable". That is the emulator e2e churn — the Activity/FGS
+            // gets recreated mid-run and onStartCommand → startAgentProcess
+            // would relaunch a perfectly healthy agent. Gate on the raw TCP
+            // listener (not /api/health), so a bun that is alive but busy
+            // mid-llama_decode — when an HTTP probe would time out — is still
+            // recognised as running and left alone.
+            if (detachedAgentMode && isLoopbackAgentListening()) {
+                if (!"running".equals(currentStatus)) {
+                    currentStatus = "running";
+                    updateNotification();
+                }
+                Log.i(TAG, "Detached agent already listening on port " + AGENT_PORT
+                    + "; adopting it (no relaunch).");
+                return;
+            }
+
+            // The agent may have been launched moments ago and still be in its
+            // (slow) cold boot — plugin resolution + first model load can take
+            // 60-90s on an emulated CPU before bun binds the port. During that
+            // window isLoopbackAgentListening() is false, so without this guard a
+            // recreated Activity/FGS (onStartCommand fires repeatedly as the e2e
+            // foregrounds/navigates) would relaunch.sh-pkill the booting bun and
+            // restart the whole boot — an endless churn that never reaches ready.
+            // If we launched within the boot grace window, assume it is still
+            // coming up and leave it alone rather than kill + restart it.
+            if (detachedAgentMode
+                    && detachedLaunchStartedAtMs > 0
+                    && (System.currentTimeMillis() - detachedLaunchStartedAtMs)
+                        < AGENT_BOOT_GRACE_MS) {
+                Log.i(TAG, "Detached agent still in cold boot (launched "
+                    + (System.currentTimeMillis() - detachedLaunchStartedAtMs)
+                    + "ms ago); not relaunching.");
+                return;
+            }
+
             String abi = resolveRuntimeAbi();
             try {
                 extractAssetsIfNeeded(abi);
@@ -687,6 +1255,7 @@ public class ElizaAgentService extends Service {
             File root = agentRoot();
             File abiDir = agentAbiDir(abi);
             File bundle = new File(root, AGENT_BUNDLE_NAME);
+            File launchScript = new File(root, AGENT_LAUNCH_SCRIPT);
             File bun = new File(abiDir, BUN_BINARY);
             String loaderName = findMuslLoader(abiDir);
 
@@ -702,6 +1271,12 @@ public class ElizaAgentService extends Service {
                 updateNotification();
                 return;
             }
+            if (!launchScript.exists()) {
+                Log.e(TAG, "Agent launch script missing at " + launchScript);
+                currentStatus = "missing-launcher";
+                updateNotification();
+                return;
+            }
             if (loaderName == null) {
                 Log.e(TAG, "musl loader missing under " + abiDir);
                 currentStatus = "missing-loader";
@@ -723,21 +1298,25 @@ public class ElizaAgentService extends Service {
             // Android. ELIZA_REQUIRE_LOCAL_AUTH on the server side flips
             // that heuristic off so every request needs the bearer token.
             String token = generateLocalAgentToken();
+            String terminalToken = generateLocalAgentToken();
             currentLocalAgentToken = token;
+            currentTerminalRunToken = terminalToken;
             try {
                 writeLocalAgentTokenFile(token);
             } catch (IOException error) {
                 Log.w(TAG, "Failed to persist local-agent token file: " + error.getMessage());
             }
 
-            // Invocation:
-            //   LD_LIBRARY_PATH=<agent/{abi}>  PORT=31337  ELIZA_*=…
-            //   ELIZA_API_TOKEN=<token>
-            //   agent/{abi}/ld-musl-…so.1  agent/{abi}/bun  agent/agent-bundle.js
+            // Invocation goes through launch.sh instead of keeping bun as a
+            // Java child process. Android has repeatedly killed the direct
+            // child path after ~30-50 s with SIGTRAP-like exit 133 while the
+            // same runtime stays alive when it is session-detached. The
+            // service still owns auth, env, foreground lifetime, and health
+            // supervision; launch.sh only performs the setsid double-fork and
+            // writes raw Bun stdio to agent/agent.log.
             List<String> command = new ArrayList<>();
-            command.add(loader.getAbsolutePath());
-            command.add(bun.getAbsolutePath());
-            command.add(bundle.getAbsolutePath());
+            command.add("/system/bin/sh");
+            command.add(launchScript.getAbsolutePath());
 
             ProcessBuilder pb = new ProcessBuilder(command);
             pb.directory(root);
@@ -747,8 +1326,38 @@ public class ElizaAgentService extends Service {
                 "LD_LIBRARY_PATH",
                 nativeLibraryDir().getAbsolutePath() + ":" + abiDir.getAbsolutePath()
             );
+            // Native voice libs (Silero VAD + WeSpeaker/pyannote voice classifier)
+            // ship as jniLibs and extract into nativeLibraryDir. The on-device bun
+            // agent's bun:ffi loaders (vad-ggml.ts / encoder-ggml.ts /
+            // diarizer-ggml.ts) honor these env overrides; without them they fall
+            // back to the repo-local CMake build dirs, which do not exist on a
+            // packaged install, so live diarization would report library-missing.
+            // Only export when the .so actually shipped, so a stale env never
+            // points the loader at a missing path.
+            File sileroVadLib = new File(nativeLibraryDir(), "libsilero_vad.so");
+            File voiceClassifierLib = new File(nativeLibraryDir(), "libvoice_classifier.so");
+            if (sileroVadLib.isFile() && !env.containsKey("ELIZA_SILERO_VAD_LIB")) {
+                agentEnv.put("ELIZA_SILERO_VAD_LIB", sileroVadLib.getAbsolutePath());
+                Log.i(TAG, "libsilero_vad.so present; exporting ELIZA_SILERO_VAD_LIB="
+                    + sileroVadLib.getAbsolutePath());
+            }
+            if (voiceClassifierLib.isFile() && !env.containsKey("ELIZA_VOICE_CLASSIFIER_LIB")) {
+                agentEnv.put("ELIZA_VOICE_CLASSIFIER_LIB", voiceClassifierLib.getAbsolutePath());
+                Log.i(TAG, "libvoice_classifier.so present; exporting ELIZA_VOICE_CLASSIFIER_LIB="
+                    + voiceClassifierLib.getAbsolutePath());
+            }
+            agentEnv.put("AGENT_ROOT", root.getAbsolutePath());
+            agentEnv.put("RUNTIME_DIR", abiDir.getAbsolutePath());
+            agentEnv.put("DEVICE_DIR", abiDir.getAbsolutePath());
+            agentEnv.put("LD_NAME", loaderName);
+            agentEnv.put("LD_PATH", loader.getAbsolutePath());
+            agentEnv.put("BUN_PATH", bun.getAbsolutePath());
+            agentEnv.put("AGENT_BUNDLE", AGENT_BUNDLE_NAME);
+            agentEnv.put("AGENT_BUNDLE_PATH", bundle.getAbsolutePath());
+            agentEnv.put("LOG_FILE", new File(root, AGENT_LOG_NAME).getAbsolutePath());
             agentEnv.put("PORT", String.valueOf(AGENT_PORT));
             agentEnv.put("ELIZA_API_PORT", String.valueOf(AGENT_PORT));
+            agentEnv.put("ELIZA_API_BIND", "127.0.0.1");
             // The agent's runtime-env resolver reads ELIZA_PORT / ELIZA_UI_PORT
             // (defaulting to 2138) before falling back to PORT. Without
             // these the agent binds 2138 even though the service advertises
@@ -759,25 +1368,274 @@ public class ElizaAgentService extends Service {
             agentEnv.put("ELIZA_UI_PORT", String.valueOf(AGENT_PORT));
             agentEnv.put("ELIZA_STATE_DIR", agentStateDir().getAbsolutePath());
             agentEnv.put("ELIZA_PLATFORM", "android");
+            agentEnv.put("ELIZA_MOBILE_PLATFORM", "android");
+            agentEnv.put("ELIZA_RUNTIME_MODE", "local-yolo");
+            agentEnv.put("AGENT_COMMAND", "android-bridge");
             agentEnv.put("ELIZA_DISABLE_DIRECT_RUN", "1");
-            // Android loopback is shared across apps. Require the per-boot
-            // bearer token; the Capacitor Agent plugin exposes it to the
-            // WebView before local-agent API calls are retried.
-            agentEnv.put("ELIZA_REQUIRE_LOCAL_AUTH", "1");
+            // Local passwordless mode: the on-device agent trusts its own
+            // loopback so the single device owner never hits a login/pairing
+            // gate. The per-boot bearer-token guard (ELIZA_REQUIRE_LOCAL_AUTH=1)
+            // is intentionally OFF — the WebView cannot reliably present that
+            // token at cold start, which otherwise dead-ends the dashboard at
+            // 401 ("Connecting to backend…" forever). Tradeoff: other apps on
+            // THIS device can reach 127.0.0.1:31337. The token is still minted
+            // and exposed via the Agent plugin for callers that opt to use it.
+            agentEnv.put("ELIZA_REQUIRE_LOCAL_AUTH", "0");
             agentEnv.put("ELIZA_API_TOKEN", token);
+            agentEnv.put("ELIZA_TERMINAL_RUN_TOKEN", terminalToken);
             // The Capacitor APK always hosts @elizaos/capacitor-llama in the
             // WebView, so the runtime should always be ready to broker
             // inference over the device-bridge WSS at /api/local-inference/
             // device-bridge. The WebView dials it over loopback once the
             // user picks the local runtime mode in onboarding.
             agentEnv.put("ELIZA_DEVICE_BRIDGE_ENABLED", "1");
-            // AOSP builds ship libllama.so under agent/{abi}/ and load it
-            // directly into the bun process via bun:ffi (see
-            // eliza/packages/agent/src/runtime/aosp-llama-adapter.ts). The
-            // gradle BuildConfig.AOSP_BUILD field is wired by sub-task 2B;
-            // the Capacitor APK keeps its DeviceBridge loopback path.
-            if (BuildConfig.AOSP_BUILD) {
+            agentEnv.put("ELIZA_DEVICE_PAIRING_TOKEN", token);
+            // CPU-only inference on a stock-Android Capacitor APK runs the
+            // same on-device chat path as the AOSP variant — Snapdragon
+            // 4 Gen 1 / Tensor G1 class hardware lands at 3–7 tok/s and a
+            // ~4.5 k-token system prompt + 256-token reply needs the
+            // same 600 s native/chat budget the bridge uses by default.
+            // The upstream gate that previously bumped these (under
+            // `BuildConfig.AOSP_BUILD && isBrandedDevice()` further down)
+            // only fires for branded AOSP builds; stock-Android sideloads
+            // get the defaults and time out on every first turn with
+            // "Chat generation failed with no streamed text
+            // (err=Chat generation timed out after 180000ms)". Set the
+            // same 10 min budget here unconditionally so both build
+            // types finish their cold first turn.
+            if (!env.containsKey("ELIZA_CHAT_GENERATION_TIMEOUT_MS")) {
+                agentEnv.put("ELIZA_CHAT_GENERATION_TIMEOUT_MS", "600000");
+            }
+            if (!env.containsKey("ELIZA_DEVICE_GENERATE_TIMEOUT_MS")) {
+                agentEnv.put("ELIZA_DEVICE_GENERATE_TIMEOUT_MS", "600000");
+            }
+            // The mobile bridge ships the bge embedding GGUF disabled
+            // by default (`ELIZA_LOCAL_EMBEDDING_ENABLED!="1"`) because
+            // mmapping it alongside the chat GGUF would OOM a 4 GB
+            // Moto G Play class device. With the embedding handler
+            // returning the zero vector for every call, the chat-
+            // augmentation document-retrieval branch never lands a
+            // match above `CHAT_DOCUMENTS_THRESHOLD`, and its LLM-
+            // driven query recovery fallback wastes one full
+            // generate-text round-trip per turn (~60–90 s on this
+            // hardware) producing queries that themselves match
+            // nothing. Skip the whole augmentation path when the
+            // embedding handler is in the disabled state.
+            if (!env.containsKey("ELIZA_DOCUMENT_AUGMENTATION_DISABLED")
+                    && !"1".equals(env.get("ELIZA_LOCAL_EMBEDDING_ENABLED"))) {
+                agentEnv.put("ELIZA_DOCUMENT_AUGMENTATION_DISABLED", "1");
+            }
+            // Skip the auto-download of recommended GGUF models that
+            // mobile-device-bridge-bootstrap kicks off at registration
+            // time. On Android the bun process cannot reach the network
+            // without specific SELinux carve-outs and the download fail
+            // cascades into a mid-init crash with no stderr captured
+            // (agent.log empty, no exit code). The WebView side handles
+            // model selection + persistence; the bun process only needs
+            // the bridge handlers registered, not pre-warmed.
+            agentEnv.put("ELIZA_DISABLE_MODEL_AUTO_DOWNLOAD", "1");
+            // Native bun:ffi inference path. When the APK bundles the eliza
+            // llama.cpp fork's fused native lib under agent/{abi}/
+            // (libelizainference.so), opt the bun process into loading it
+            // directly via bun:ffi — see
+            // eliza/plugins/plugin-aosp-local-inference/src/aosp-local-inference-bootstrap.ts
+            // (tryBuildAospFusedTextLoader) and aosp-llama-paths.ts
+            // (isAospEnabled reads ELIZA_LOCAL_LLAMA).
+            // This is required, not optional: the eliza-1 model tiers are
+            // Gemma-4-arch GGUFs (TurboQuant-quantized; stock f16/q8_0 KV — the
+            // legacy QJL/PolarQuant/TBQ KV kernels are retired post-#9033), and
+            // the stock llama-cpp-capacitor JNI lib cannot load those GGUFs at
+            // all (`context->loadModel() returned false`). The fused
+            // libelizainference.so carries the kernels + Gemma arch and is
+            // the SOLE text/voice native library the bun agent loads.
+            //
+            // This was previously gated on `BuildConfig.AOSP_BUILD &&
+            // isBrandedDevice()`. That gate's sole rationale was the
+            // aosp loader's first-run model auto-download crashing a
+            // network-restricted bun process — but that download is already
+            // suppressed unconditionally above
+            // (ELIZA_DISABLE_MODEL_AUTO_DOWNLOAD=1), and the loader itself
+            // self-gates + defensively no-ops when the lib is absent or
+            // incompatible. Presence of the bundled fused lib is therefore
+            // the correct, sufficient signal for both build types.
+            //
+            // libelizainference.so is the lib actually dlopen'd at runtime;
+            // libllama.so is kept as a legacy OR-condition so the gate still
+            // activates on any APK that predates the fused-lib cutover (where
+            // only libllama.so + shim were staged). Once libllama.so stops
+            // being built the fused lib alone trips the gate.
+            File abiFusedInference = new File(abiDir, "libelizainference.so");
+            File abiLibllama = new File(abiDir, "libllama.so");
+            File abiLlamaShim = new File(abiDir, "libeliza-llama-shim.so");
+            File abiGgmlVulkan = new File(abiDir, "libggml-vulkan.so");
+            boolean fusedInferenceBundled = abiFusedInference.isFile();
+            boolean legacyLibllamaBundled = abiLibllama.isFile() && abiLlamaShim.isFile();
+            boolean nativeLlamaBundled = fusedInferenceBundled || legacyLibllamaBundled;
+            boolean brandedAospBuild = BuildConfig.AOSP_BUILD && isBrandedDevice();
+            // When the dynamic-Vulkan fused lib is staged (libelizainference.so +
+            // libggml-vulkan.so), the GPU is only reachable from THIS bionic app
+            // process — the musl agent's ld can't load libvulkan's HIDL closure
+            // (project_android_gpu_vulkan_wall). So instead of pointing the musl
+            // agent at the bun:ffi AOSP loader (ELIZA_LOCAL_LLAMA=1 → the wall),
+            // delegate inference over an abstract-namespace UDS to the in-process
+            // ElizaBionicInferenceServer, which runs libelizainference on the Mali
+            // GPU. The musl agent never tries to load the native lib itself.
+            boolean delegateToBionicHost = fusedInferenceBundled && abiGgmlVulkan.isFile();
+            if (delegateToBionicHost) {
+                agentEnv.put("ELIZA_BIONIC_HOST_DELEGATED", "1");
+                agentEnv.put("ELIZA_BIONIC_INFERENCE_SOCK", BIONIC_INFERENCE_SOCKET_NAME);
+                // The bionic host reloads the model per call (the fork's Vulkan
+                // backend corrupts shared GPU weights on reuse), so even a
+                // token-capped post-turn reflection runs ~40-60s — past the
+                // 30s default post-delivery side-effect timeout. That reflection
+                // is non-blocking background work (the reply is already
+                // delivered), so give it room to finish and persist instead of
+                // logging a spurious timeout every turn. Don't clobber an
+                // explicit operator override.
+                if (!agentEnv.containsKey("ELIZA_POST_DELIVERY_SIDE_EFFECT_TIMEOUT_MS")) {
+                    agentEnv.put("ELIZA_POST_DELIVERY_SIDE_EFFECT_TIMEOUT_MS", "120000");
+                }
+                Log.i(TAG, "agent/" + abiDir.getName()
+                    + "/libggml-vulkan.so present; delegating inference to the in-process"
+                    + " bionic Vulkan host over UDS \"" + BIONIC_INFERENCE_SOCKET_NAME
+                    + "\" (NOT taking the musl bun:ffi AOSP path)");
+                // Stand up the in-process GPU inference server BEFORE the agent
+                // spawns so the abstract socket is already bound when the agent's
+                // BionicHostLoader first connects. Idempotent across restarts.
+                if (bionicInferenceServer == null) {
+                    String defaultBundleDir =
+                        new File(getFilesDir(), "eliza-1/bundle").getAbsolutePath();
+                    bionicInferenceServer =
+                        new ElizaBionicInferenceServer(BIONIC_INFERENCE_SOCKET_NAME, defaultBundleDir);
+                }
+                bionicInferenceServer.start();
+            }
+            if (!delegateToBionicHost && nativeLlamaBundled
+                    && !env.containsKey("ELIZA_LOCAL_LLAMA")) {
+                agentEnv.put("ELIZA_LOCAL_LLAMA", "1");
+                String bundledLib = fusedInferenceBundled
+                    ? "libelizainference.so"
+                    : "libllama.so + shim (legacy)";
+                Log.i(TAG, "agent/" + abiDir.getName()
+                    + "/" + bundledLib + " present; enabling native bun:ffi inference (ELIZA_LOCAL_LLAMA=1)");
+            }
+            if (nativeLlamaBundled) {
+                // When the Vulkan ggml backend (libggml-vulkan.so) is bundled —
+                // i.e. the arm64 GPU build — offload the model to the GPU. The
+                // aosp loader pins n_gpu_layers=0 by default, so without
+                // this a Vulkan-capable build still runs entirely on CPU. CPU-
+                // only builds (riscv64, or arm64 without the Vulkan backend) ship
+                // no libggml-vulkan.so, so they correctly stay on CPU.
+                // Skipped when delegating: the GPU offload happens in the bionic
+                // host, not the musl bun:ffi path (which can't reach Vulkan).
+                if (!delegateToBionicHost
+                        && abiGgmlVulkan.isFile()
+                        && !env.containsKey("ELIZA_AOSP_LLAMA_USE_GPU")
+                        && !env.containsKey("ELIZA_LLAMA_N_GPU_LAYERS")) {
+                    agentEnv.put("ELIZA_AOSP_LLAMA_USE_GPU", "true");
+                    Log.i(TAG, "agent/" + abiDir.getName()
+                        + "/libggml-vulkan.so present; offloading inference to GPU (ELIZA_AOSP_LLAMA_USE_GPU=true)");
+                }
+                if (!env.containsKey("ELIZA_MOBILE_LOCAL_DIRECT_REPLY")) {
+                    agentEnv.put("ELIZA_MOBILE_LOCAL_DIRECT_REPLY", "1");
+                }
+                if (!env.containsKey("ELIZA_KOKORO_PREWARM")) {
+                    agentEnv.put("ELIZA_KOKORO_PREWARM", "1");
+                }
+                if (!env.containsKey("ELIZA_KOKORO_PREWARM_DELAY_MS")) {
+                    // Kokoro's first on-device ORT/WASM synthesis can be
+                    // CPU-bound for tens of seconds. Keep the warmup opt-in,
+                    // but schedule it well after the local HTTP server should
+                    // be listening so app readiness is not blocked by audio
+                    // cache priming.
+                    agentEnv.put("ELIZA_KOKORO_PREWARM_DELAY_MS", "60000");
+                }
+                // MTP (multi-token / speculative decode) is compiled into the
+                // single fused libelizainference.so (the eliza_mtp::Engine over
+                // common/speculative.cpp, exported as eliza_inference_llm_mtp_supported).
+                // It is controlled in-process by ELIZA_BIONIC_MTP and the FFI
+                // capability probe — NOT by a separate speculative-shim .so (that
+                // shim is retired and never staged). No env wiring needed here.
+                if (BuildConfig.DEBUG && !env.containsKey("ELIZA_AOSP_LLAMA_DEBUG_LOG")) {
+                    File debugLog = new File(agentStateDir(), "aosp-llama-debug.log");
+                    agentEnv.put("ELIZA_AOSP_LLAMA_DEBUG_LOG", debugLog.getAbsolutePath());
+                }
+                // Mobile llama.cpp defaults for the in-process fork loader.
+                // The adapter has safe fallbacks, but Java is the only layer
+                // that can reliably read the Android CPU count before bun's
+                // seccomp-limited runtime starts. Keep these tied to the
+                // bundled fork libs, not to full-AOSP branding: the regular
+                // debug APK uses the same bun:ffi path when those libs ship.
+                //
+                // The Eliza-1 native context is 128k. The regular debug APK
+                // runs the model in-process on phone CPU, so default to a
+                // small interactive context and let the adapter keep the tail
+                // of oversized prompts. Full branded AOSP builds keep the
+                // larger 16k context used by CVD/system smoke tests. This
+                // keeps the debug APK's first message-handler prefill bounded
+                // on Pixel-class devices instead of pinning bun behind a
+                // multi-minute FFI call before it can answer health checks or
+                // honor aborts.
+                if (!env.containsKey("ELIZA_LLAMA_N_CTX")) {
+                    agentEnv.put("ELIZA_LLAMA_N_CTX", brandedAospBuild ? "16384" : "4096");
+                }
+
+                if (!env.containsKey("ELIZA_LLAMA_THREADS")) {
+                    int cores = Runtime.getRuntime().availableProcessors();
+                    if (cores < 1) cores = 1;
+                    agentEnv.put("ELIZA_LLAMA_THREADS", String.valueOf(cores));
+                }
+
+                // Keep decode chunks bounded for stock APK runs while avoiding
+                // unnecessary multi-chunk prompt prefill. Pixel validation on
+                // eliza-1-0_8b showed 256-token chunks reduce native prefill
+                // time versus the older 64-token default, without blocking
+                // health/startup probes because the HTTP server binds after
+                // model prewarm. Branded AOSP keeps the historical 512-token
+                // chunk size for its longer smoke budget.
+                if (!env.containsKey("ELIZA_LLAMA_N_BATCH")) {
+                    agentEnv.put("ELIZA_LLAMA_N_BATCH", brandedAospBuild ? "512" : "256");
+                }
+                if (!env.containsKey("ELIZA_LLAMA_N_UBATCH")) {
+                    agentEnv.put("ELIZA_LLAMA_N_UBATCH", brandedAospBuild ? "512" : "256");
+                }
+
+                // Stage-1 RESPONSE_HANDLER is an internal structured planning
+                // call, not the user's requested chat completion budget. On the
+                // debug APK's in-process phone-CPU path, leaving it at the
+                // core default (1024) lets an unconstrained or malformed local
+                // decode run for minutes before the trajectory can record the
+                // first stage. The AOSP adapter now honors the Stage-1 GBNF
+                // grammar, so 384 tokens is ample for the HANDLE_RESPONSE
+                // envelope while still bounding failure cases tightly. Full
+                // branded AOSP keeps the core default unless explicitly set.
+                if (!brandedAospBuild && !env.containsKey("RESPONSE_HANDLER_MAX_TOKENS")) {
+                    agentEnv.put("RESPONSE_HANDLER_MAX_TOKENS", "384");
+                }
+                // Bound every native llama generation on debug APKs, not only
+                // Stage-1. Some downstream TEXT_LARGE calls request 8192
+                // tokens while the debug APK uses n_ctx=4096; without this cap
+                // the adapter must reserve the whole context for output and
+                // drops the prompt to a single token.
+                if (!brandedAospBuild && !env.containsKey("ELIZA_LLAMA_MAX_OUTPUT_TOKENS")) {
+                    agentEnv.put("ELIZA_LLAMA_MAX_OUTPUT_TOKENS", "384");
+                }
+            }
+            if (BuildConfig.AOSP_BUILD && isBrandedDevice()) {
+                agentEnv.put("ELIZA_AOSP_BUILD", "1");
                 agentEnv.put("ELIZA_LOCAL_LLAMA", "1");
+                // Branded AOSP unconditionally opts the bun agent into native
+                // inference. If neither the fused libelizainference.so nor the
+                // legacy libllama.so + shim shipped in this APK, that opt-in
+                // cannot be honored — the bun agent's fused loader will fail at
+                // its first TEXT_* call. Surface the broken pipeline LOUDLY here
+                // (Commandment 8: no silent fallback) rather than letting the
+                // failure first appear minutes later mid-inference.
+                if (!nativeLlamaBundled) {
+                    Log.e(TAG, "agent/" + abiDir.getName()
+                        + ": branded AOSP set ELIZA_LOCAL_LLAMA=1 but no native inference lib is bundled "
+                        + "(libelizainference.so absent, libllama.so + shim absent); local inference WILL fail.");
+                }
                 // CPU-only inference of a 12k-token prompt on cuttlefish
                 // x86_64 / Eliza-1 lands well past the 180 s default
                 // chat-generation timeout (chat-routes.ts). On cvd a
@@ -791,52 +1649,52 @@ public class ElizaAgentService extends Service {
                 // (Tensor / Adreno) finishes in seconds, so this only
                 // matters for AOSP cvd runs.
                 agentEnv.put("ELIZA_CHAT_GENERATION_TIMEOUT_MS", "3600000");
-
-                // Eliza-1 native context is 128k. We pin to 16k
-                // because 16k easily fits the planner's ~12k-token
-                // prompts plus output reserve. KV-cache for 16k ctx on
-                // 1B-Q4_K_M / fp16 KV is ~512 MB (16384 cells × 16 layers
-                // × (256 MiB K + 256 MiB V) per llama.cpp's sched_reserve),
-                // which alongside the ~770 MB weights and ~290 MB compute
-                // buffer puts the model alone close to 1.6 GB. cvd has 4
-                // GB total RAM with ~640 MB free at agent start, and bun's
-                // heap routinely peaks at 1.5–2.0 GB during long planner
-                // cycles — the combined footprint hits OOM-killer
-                // territory and bun panics with a SIGSEGV mid-request.
-                // Override via env on real-device builds when ctx vs RAM
-                // trade-offs change.
-                if (!env.containsKey("ELIZA_LLAMA_N_CTX")) {
-                    agentEnv.put("ELIZA_LLAMA_N_CTX", "16384");
-                }
-
-                // Pin n_threads to the actual CPU count. The default of
-                // 0 in the adapter (and llama.cpp's auto-detect path)
-                // frequently returns 1 on Android because Android's
-                // seccomp filter blocks sched_getaffinity for app
-                // domains and llama.cpp's /proc/cpuinfo parse misses
-                // the core count on cvd. Cuttlefish x86_64 has 4 vCPUs;
-                // most real phones have 6–8 big.LITTLE cores. Read
-                // from the JVM at startup and pass through so the FFI
-                // side doesn't need to call any blocked syscall.
-                if (!env.containsKey("ELIZA_LLAMA_THREADS")) {
-                    int cores = Runtime.getRuntime().availableProcessors();
-                    if (cores < 1) cores = 1;
-                    agentEnv.put("ELIZA_LLAMA_THREADS", String.valueOf(cores));
-                }
-
-                // Smaller decode chunks → more event-loop yield points
-                // during prompt prefill. 2048 holds bun inside a single
-                // llama_decode call for ~30 s on cvd CPU; the watchdog
-                // probe sits on a closed listener queue that whole
-                // time. 512-token chunks land each call in ~6–8 s, so
-                // the 30 s probe timeout has a realistic chance to
-                // wake the listener between chunks.
-                if (!env.containsKey("ELIZA_LLAMA_N_BATCH")) {
-                    agentEnv.put("ELIZA_LLAMA_N_BATCH", "512");
-                }
+                // Device bridge is unused on AOSP (ELIZA_LOCAL_LLAMA=1 routes
+                // inference through the fused libelizainference.so loader
+                // instead). Set the same 1h budget explicitly so the intent is clear and
+                // operator overrides above are not inadvertently in effect.
+                agentEnv.put("ELIZA_DEVICE_GENERATE_TIMEOUT_MS", "3600000");
+
+                // Native llama.cpp ctx/thread/batch defaults are applied above
+                // whenever the fork libs are bundled. Full AOSP only needs
+                // its longer timeout budget here.
             }
             agentEnv.put("HOME", getFilesDir().getAbsolutePath());
-            agentEnv.put("TMPDIR", getCacheDir().getAbsolutePath());
+            if (!env.containsKey("TMPDIR")) {
+                agentEnv.put("TMPDIR", getCacheDir().getAbsolutePath());
+            }
+            agentEnv.put("SHELL", "/system/bin/sh");
+            agentEnv.put("CODING_TOOLS_SHELL", "/system/bin/sh");
+            agentEnv.put("SHELL_ALLOWED_DIRECTORY", agentStateDir().getAbsolutePath());
+            agentEnv.put("CODING_TOOLS_WORKSPACE_ROOTS", agentStateDir().getAbsolutePath());
+            String inheritedPath = env.get("PATH");
+            StringBuilder pathBuilder = new StringBuilder();
+            pathBuilder.append(abiDir.getAbsolutePath()).append("/bin");
+            pathBuilder.append(":").append(abiDir.getAbsolutePath());
+            pathBuilder.append(":").append(new File(root, "tools/bin").getAbsolutePath());
+            pathBuilder.append(":").append(new File(root, "bin").getAbsolutePath());
+            pathBuilder.append(":/system/bin:/system/xbin:/vendor/bin:/apex/com.android.runtime/bin");
+            if (inheritedPath != null && !inheritedPath.trim().isEmpty()) {
+                pathBuilder.append(":").append(inheritedPath);
+            }
+            agentEnv.put("PATH", pathBuilder.toString());
+
+            // ── No-terminal env hints for bun's stdio probe ───────────────
+            // Untrusted-app SELinux policy denies `ioctl(TIOCGWINSZ)` on
+            // both app_data_file and the Java-pipe fifo with `permissive=0`.
+            // Bun's stdio init calls `ioctl(stdout, TIOCGWINSZ)` to detect
+            // terminal width; on EACCES it has historically returned mid-
+            // init without writing any diagnostic, leaving agent.log empty
+            // and the watchdog probing a non-existent listener. The env
+            // hints below put bun on its non-terminal path so it does not
+            // bother probing — TERM=dumb gates the terminfo lookups,
+            // NO_COLOR=1 + FORCE_COLOR=0 disable the ANSI emitter, and
+            // CI=1 routes through bun's CI-mode logger (no progress bars,
+            // no spinners, no width detection).
+            agentEnv.put("TERM", "dumb");
+            agentEnv.put("NO_COLOR", "1");
+            agentEnv.put("FORCE_COLOR", "0");
+            agentEnv.put("CI", "1");
 
             // ── Android seccomp compatibility (SIGSYS / code 159 fix) ──────
             //
@@ -935,13 +1793,16 @@ public class ElizaAgentService extends Service {
             //   - On AOSP cvd we want a deterministic agent binary, not
             //     one that mutates its prompts mid-smoke.
             //
-            // Hard-disable both the bootstrap and the trajectory ingest
-            // path so the agent never spins up a training round on-device.
-            // Trajectories are still useful for live chat context, but
-            // this disables PERSISTENCE — the optimizer has no input data
-            // and no-ops at boot.
+            // Hard-disable the bootstrap so the agent never spins up a
+            // training round on-device. Keep trajectory persistence available
+            // in debug APKs: Android local-llama bringup depends on the
+            // per-turn trace files as the ground-truth failure record. Release
+            // builds keep the historical opt-out unless an operator overrides
+            // the env explicitly.
             agentEnv.put("ELIZA_DISABLE_AUTO_BOOTSTRAP", "1");
-            agentEnv.put("ELIZA_DISABLE_TRAJECTORY_LOGGING", "1");
+            if (!env.containsKey("ELIZA_DISABLE_TRAJECTORY_LOGGING")) {
+                agentEnv.put("ELIZA_DISABLE_TRAJECTORY_LOGGING", BuildConfig.DEBUG ? "0" : "1");
+            }
 
             // ── Vault passphrase ──────────────────────────────────────
             // The runtime's vault-bootstrap mirrors process.env secrets
@@ -988,13 +1849,46 @@ public class ElizaAgentService extends Service {
 
             env.putAll(agentEnv);
 
-            // Merge stderr into stdout so a single pump captures both streams
-            // and one failure mode — bun crashing mid-write before the buffered
-            // stderr line is flushed — can't lose the diagnostic. The previous
-            // BufferedReader.readLine() pump silently dropped any partial line
-            // that wasn't terminated with a newline, which is exactly what
-            // happens when a panic interrupts a Logger call mid-string.
+            // ── Stdio redirection (TIOCGWINSZ SELinux workaround) ─────────
+            // On Android `untrusted_app`, SELinux denies
+            // `ioctl(fd, TIOCGWINSZ)` (cmd 0x5413) on every non-tty class
+            // accessible to the app with `permissive=0`:
+            //   - `pipe:[...]` (Java ProcessBuilder PIPE) → fifo_file ioctl
+            //   - `/data/data/<pkg>/files/agent/agent.log` → app_data_file ioctl
+            // The denial returns EACCES; bun's stdio init (or musl's
+            // `__init_libc` terminal-width probe) treats the EACCES as a
+            // hard failure and exits within ~100ms before any line is
+            // flushed, leaving agent.log at 0 bytes and the watchdog
+            // probing nothing. The one fd class that *does* allow ioctl
+            // for untrusted_app is `null_device:chr_file` (rw_file_perms
+            // grants ioctl, no xperm whitelist restriction). Verified
+            // empirically: same ProcessBuilder spawn from `runas_app`
+            // context (more permissive) reaches `/api/health 200`;
+            // identical spawn from `untrusted_app` (service context)
+            // dies silently on the file ioctl.
+            //
+            // Workaround: redirect all three fds to /dev/null so every
+            // TIOCGWINSZ returns ENOTTY (kernel-level, no SELinux check
+            // needed). We sacrifice stdout/stderr capture for liveness;
+            // the agent runtime still writes structured logs to
+            // `<stateDir>/logs/agent.log` via its own pino transport,
+            // and Android's logcat captures every line emitted via
+            // `Log.i(TAG, …)` from the Java side. For local debug
+            // sessions that need raw bun stdio, set `ELIZA_LOG_STDOUT=1`
+            // in the parent service env — that opts into the legacy
+            // file-redirect path (which only works on rooted devices
+            // or via `adb shell run-as`).
+            File devNull = new File("/dev/null");
+            pb.redirectInput(ProcessBuilder.Redirect.from(devNull));
             pb.redirectErrorStream(true);
+            if ("1".equals(env.get("ELIZA_LOG_STDOUT"))) {
+                File logFile = new File(root, AGENT_LOG_NAME);
+                try { logFile.createNewFile(); } catch (IOException ignored) {}
+                pb.redirectOutput(ProcessBuilder.Redirect.appendTo(logFile));
+                Log.i(TAG, "Agent stdout/stderr capture enabled at " + logFile.getAbsolutePath());
+            } else {
+                pb.redirectOutput(ProcessBuilder.Redirect.to(devNull));
+            }
 
             Process started;
             try {
@@ -1008,14 +1902,60 @@ public class ElizaAgentService extends Service {
             }
 
             agentProcess = started;
-            File logFile = new File(root, AGENT_LOG_NAME);
-            stdoutPump = startStreamPump(started.getInputStream(), logFile, "out");
-            // stderrPump intentionally null — redirectErrorStream(true) merges
-            // both streams into getInputStream() so one pump captures everything.
+            detachedAgentMode = true;
+            detachedLaunchStartedAtMs = System.currentTimeMillis();
+            // stdoutPump/stderrPump no longer needed — bun writes straight
+            // to agent.log on disk via the OS-level redirect above.
+            stdoutPump = null;
             stderrPump = null;
-            currentStatus = "running";
+            currentStatus = "starting";
             updateNotification();
-            Log.i(TAG, "Agent process started (pid=" + safePid(started) + ").");
+            final long startedAtMs = System.currentTimeMillis();
+            final long launchStartedAtMs = detachedLaunchStartedAtMs;
+            final long pidForLog = safePid(started);
+            Log.i(TAG, "Agent launcher started (pid=" + pidForLog + ").");
+            // Immediate-exit watcher: bun on `untrusted_app` has been
+            // observed dying within ~50ms with no stderr / no tombstone /
+            // no audit hint past the standard musl init probe denials.
+            // The 10-minute watchdog tick is far too slow to surface a
+            // useful exit code. This thread blocks on `process.waitFor()`
+            // and logs the exit value the moment the kernel reaps the
+            // child, then hands off to the existing watchdog restart
+            // path via scheduleRestart().
+            final Process watched = started;
+            Thread exitWatcher = new Thread(() -> {
+                int code;
+                try {
+                    code = watched.waitFor();
+                } catch (InterruptedException ex) {
+                    Thread.currentThread().interrupt();
+                    return;
+                }
+                long aliveMs = System.currentTimeMillis() - startedAtMs;
+                if (detachedAgentMode && code == 0) {
+                    Log.i(TAG, "Agent launcher exited after detached start (pid="
+                            + pidForLog + " alive=" + aliveMs + "ms).");
+                } else {
+                    Log.w(TAG, "Agent process exited early (pid=" + pidForLog
+                            + " code=" + code + " alive=" + aliveMs + "ms).");
+                }
+                boolean stillThisProcess;
+                synchronized (processLock) {
+                    stillThisProcess = (agentProcess == watched);
+                    if (stillThisProcess) {
+                        agentProcess = null;
+                    }
+                }
+                if (stillThisProcess && !shuttingDown && detachedAgentMode && code == 0) {
+                    startDetachedStartupProbe(launchStartedAtMs);
+                    return;
+                }
+                if (stillThisProcess && !shuttingDown) {
+                    scheduleRestart();
+                }
+            }, "ElizaAgent-exit-watcher");
+            exitWatcher.setDaemon(true);
+            exitWatcher.start();
         }
     }
 
@@ -1023,6 +1963,7 @@ public class ElizaAgentService extends Service {
         Process toStop;
         Thread outPump;
         Thread errPump;
+        boolean wasDetached;
         synchronized (processLock) {
             toStop = agentProcess;
             outPump = stdoutPump;
@@ -1030,6 +1971,14 @@ public class ElizaAgentService extends Service {
             agentProcess = null;
             stdoutPump = null;
             stderrPump = null;
+            wasDetached = detachedAgentMode;
+            detachedAgentMode = false;
+            detachedLaunchStartedAtMs = 0L;
+            currentLocalAgentToken = null;
+            currentTerminalRunToken = null;
+        }
+        if (wasDetached) {
+            stopDetachedAgentProcess();
         }
         if (toStop == null) {
             return;
@@ -1053,6 +2002,38 @@ public class ElizaAgentService extends Service {
         if (errPump != null) errPump.interrupt();
     }
 
+    private void stopDetachedAgentProcess() {
+        String abi = resolveRuntimeAbi();
+        File abiDir = agentAbiDir(abi);
+        File bun = preferPackagedExecutable(new File(abiDir, BUN_BINARY), "libeliza_bun.so");
+        File bundle = new File(agentRoot(), AGENT_BUNDLE_NAME);
+        String killCommand = "pkill -f " + shellQuote(bun.getAbsolutePath())
+            + " 2>/dev/null || true; pkill -f "
+            + shellQuote(bundle.getAbsolutePath()) + " 2>/dev/null || true";
+        try {
+            Process killer = new ProcessBuilder("/system/bin/sh", "-c", killCommand)
+                .redirectInput(ProcessBuilder.Redirect.from(new File("/dev/null")))
+                .redirectOutput(ProcessBuilder.Redirect.to(new File("/dev/null")))
+                .redirectError(ProcessBuilder.Redirect.to(new File("/dev/null")))
+                .start();
+            long deadline = System.currentTimeMillis() + PROCESS_TERMINATE_GRACE_MS;
+            while (killer.isAlive() && System.currentTimeMillis() < deadline) {
+                Thread.sleep(100);
+            }
+            if (killer.isAlive()) {
+                killer.destroyForcibly();
+            }
+        } catch (IOException error) {
+            Log.w(TAG, "Failed to stop detached agent process: " + error.getMessage());
+        } catch (InterruptedException error) {
+            Thread.currentThread().interrupt();
+        }
+    }
+
+    private static String shellQuote(String value) {
+        return "'" + value.replace("'", "'\\''") + "'";
+    }
+
     private static final java.security.SecureRandom TOKEN_RNG = new java.security.SecureRandom();
 
     private static String generateLocalAgentToken() {
@@ -1160,6 +2141,163 @@ public class ElizaAgentService extends Service {
         return t;
     }
 
+    private void startDetachedStartupProbe(final long launchStartedAtMs) {
+        Thread probe = new Thread(() -> {
+            long deadline = launchStartedAtMs + STARTUP_HEALTH_GRACE_MS;
+            while (!shuttingDown && System.currentTimeMillis() < deadline) {
+                ProbeResult result = probeHealth();
+                if (result == ProbeResult.OK) {
+                    restartAttempts = 0;
+                    synchronized (processLock) {
+                        if (!detachedAgentMode || detachedLaunchStartedAtMs != launchStartedAtMs) {
+                            return;
+                        }
+                        currentStatus = "running";
+                    }
+                    updateNotification();
+                    Log.i(TAG, "Detached agent health check passed.");
+                    return;
+                }
+                try {
+                    Thread.sleep(STARTUP_HEALTH_POLL_MS);
+                } catch (InterruptedException error) {
+                    Thread.currentThread().interrupt();
+                    return;
+                }
+            }
+            boolean stillCurrent;
+            synchronized (processLock) {
+                stillCurrent = detachedAgentMode && detachedLaunchStartedAtMs == launchStartedAtMs;
+            }
+            if (stillCurrent && !shuttingDown) {
+                Log.w(TAG, "Detached agent did not become healthy within "
+                    + STARTUP_HEALTH_GRACE_MS + "ms. Scheduling restart.");
+                scheduleRestart();
+            }
+        }, "ElizaAgent-detached-startup-probe");
+        probe.setDaemon(true);
+        probe.start();
+    }
+
+    /**
+     * Quick liveness probe for an already-running detached agent: can a TCP
+     * connection be opened to the loopback agent port? Unlike {@link
+     * #probeHealth()} this only completes the socket handshake, so it returns
+     * true even while bun is busy inside a synchronous native call
+     * (mid-llama_decode) and the HTTP layer is unresponsive — precisely the
+     * state we must NOT mistake for a dead agent and relaunch over. Used by
+     * {@link #startAgentProcess()} to adopt a surviving detached agent instead
+     * of killing + restarting it when the service/Activity is recreated.
+     */
+    private boolean isLoopbackAgentListening() {
+        try (Socket socket = new Socket()) {
+            socket.connect(new InetSocketAddress("127.0.0.1", AGENT_PORT), 2000);
+            return true;
+        } catch (IOException ignored) {
+            return false;
+        }
+    }
+
+    private ProbeResult probeHealth() {
+        HttpURLConnection conn = null;
+        try {
+            URL url = new URL(HEALTH_URL);
+            conn = (HttpURLConnection) url.openConnection();
+            conn.setConnectTimeout((int) HEALTH_TIMEOUT_MS);
+            conn.setReadTimeout((int) HEALTH_TIMEOUT_MS);
+            conn.setRequestMethod("GET");
+            String token = currentLocalAgentToken;
+            if (token != null && !token.trim().isEmpty()) {
+                conn.setRequestProperty("Authorization", "Bearer " + token.trim());
+            }
+            int status = conn.getResponseCode();
+            if (status >= 200 && status < 300) {
+                String body = readResponseBody(conn);
+                if (!isReadyHealthBody(body)) {
+                    Log.w(TAG, "Agent health endpoint responded before ready: " + compactForLog(body));
+                    return ProbeResult.DEAD;
+                }
+                return ProbeResult.OK;
+            }
+            // Non-2xx: agent process is up but not healthy/authenticated.
+            // Treat as DEAD so strikes accumulate — this is a crash or
+            // readiness signal, not a busy signal.
+            return ProbeResult.DEAD;
+        } catch (IOException error) {
+            // HTTP request failed (timeout / connect refused / read
+            // interrupt). If the direct child process is still alive the
+            // most likely cause is bun synchronously inside a native FFI
+            // call. Detached mode has no live Java child to inspect, so a
+            // closed port is treated as DEAD and the startup probe/watchdog
+            // owns retry timing.
+            Process current;
+            synchronized (processLock) {
+                current = agentProcess;
+            }
+            if (current != null && current.isAlive()) {
+                return ProbeResult.BUSY;
+            }
+            return ProbeResult.DEAD;
+        } finally {
+            if (conn != null) conn.disconnect();
+        }
+    }
+
+    private static String readResponseBody(HttpURLConnection conn) throws IOException {
+        try (InputStream in = conn.getInputStream()) {
+            ByteArrayOutputStream out = new ByteArrayOutputStream();
+            byte[] buf = new byte[4096];
+            int n;
+            while ((n = in.read(buf)) >= 0) {
+                out.write(buf, 0, n);
+            }
+            return out.toString(StandardCharsets.UTF_8.name());
+        }
+    }
+
+    private static String readResponseBody(InputStream in, int maxBytes) throws IOException {
+        return new String(readResponseBytes(in, maxBytes), StandardCharsets.UTF_8);
+    }
+
+    private static byte[] readResponseBytes(InputStream in, int maxBytes) throws IOException {
+        if (in == null) return new byte[0];
+        try (InputStream input = in) {
+            ByteArrayOutputStream out = new ByteArrayOutputStream();
+            byte[] buf = new byte[8192];
+            int total = 0;
+            int n;
+            while ((n = input.read(buf)) >= 0) {
+                total += n;
+                if (total > maxBytes) {
+                    throw new IOException("Response body is too large");
+                }
+                out.write(buf, 0, n);
+            }
+            return out.toByteArray();
+        }
+    }
+
+    private static boolean isReadyHealthBody(String body) {
+        if (body == null || body.trim().isEmpty()) return false;
+        try {
+            JSONObject json = new JSONObject(body);
+            if (!json.optBoolean("ready", false)) return false;
+            String runtime = json.optString("runtime", "");
+            if (!runtime.isEmpty() && !"ok".equals(runtime)) return false;
+            String agentState = json.optString("agentState", "");
+            return agentState.isEmpty() || "running".equals(agentState);
+        } catch (JSONException error) {
+            return false;
+        }
+    }
+
+    private static String compactForLog(String value) {
+        if (value == null) return "";
+        String compact = value.replaceAll("\\s+", " ").trim();
+        if (compact.length() <= 240) return compact;
+        return compact.substring(0, 240) + "…";
+    }
+
     private void scheduleRestart() {
         if (shuttingDown) return;
         if (restartAttempts >= MAX_RESTART_ATTEMPTS) {
@@ -1216,7 +2354,28 @@ public class ElizaAgentService extends Service {
                     current = agentProcess;
                 }
                 if (current == null) {
-                    // Service is up but no process — caller must explicitly start.
+                    if (detachedAgentMode) {
+                        ProbeResult probe = probeHealth();
+                        if (probe == ProbeResult.OK) {
+                            if (unhealthyTicks > 0) {
+                                Log.i(TAG, "Detached agent health restored.");
+                            }
+                            unhealthyTicks = 0;
+                            restartAttempts = 0;
+                            if (!"running".equals(currentStatus)) {
+                                currentStatus = "running";
+                                updateNotification();
+                            }
+                        } else if (probe == ProbeResult.DEAD) {
+                            unhealthyTicks++;
+                            Log.w(TAG, "Detached agent health probe failed ("
+                                + unhealthyTicks + " consecutive).");
+                            if (unhealthyTicks >= HEALTH_FAIL_STRIKES) {
+                                unhealthyTicks = 0;
+                                scheduleRestart();
+                            }
+                        }
+                    }
                     continue;
                 }
                 if (!current.isAlive()) {
@@ -1261,7 +2420,7 @@ public class ElizaAgentService extends Service {
                     Log.i(TAG, "Agent HTTP probe timed out but process is alive — likely mid-decode. No strike.");
                 } else {
                     // ProbeResult.DEAD: process is dead, OR /api/health
-                    // returned 5xx (a real crash signal). Only here do we
+                    // did not return 2xx with ready=true. Only here do we
                     // accumulate strikes toward a force-restart.
                     unhealthyTicks++;
                     Log.w(TAG, "Agent health probe failed (" + unhealthyTicks + " consecutive).");
@@ -1275,44 +2434,6 @@ public class ElizaAgentService extends Service {
             }
         }
 
-        private ProbeResult probeHealth() {
-            HttpURLConnection conn = null;
-            try {
-                URL url = new URL(HEALTH_URL);
-                conn = (HttpURLConnection) url.openConnection();
-                conn.setConnectTimeout((int) HEALTH_TIMEOUT_MS);
-                conn.setReadTimeout((int) HEALTH_TIMEOUT_MS);
-                conn.setRequestMethod("GET");
-                int status = conn.getResponseCode();
-                if (status >= 200 && status < 500) {
-                    return ProbeResult.OK;
-                }
-                // 5xx: agent process is up but reported a server error.
-                // Treat as DEAD so strikes accumulate — a 5xx on
-                // /api/health is a crash signal, not a busy signal.
-                return ProbeResult.DEAD;
-            } catch (IOException error) {
-                // HTTP request failed (timeout / connect refused / read
-                // interrupt). If the agent process is still alive the
-                // most likely cause is bun synchronously inside a native
-                // FFI call (long llama_decode on a multi-thousand-token
-                // prompt). The event loop will resume when the FFI call
-                // returns. If the process IS dead, scheduleRestart()
-                // already fired from the outer loop on the
-                // !current.isAlive() path on the previous tick — a
-                // strike here would be redundant.
-                Process current;
-                synchronized (processLock) {
-                    current = agentProcess;
-                }
-                if (current != null && current.isAlive()) {
-                    return ProbeResult.BUSY;
-                }
-                return ProbeResult.DEAD;
-            } finally {
-                if (conn != null) conn.disconnect();
-            }
-        }
     }
 
     /**
@@ -1323,8 +2444,9 @@ public class ElizaAgentService extends Service {
      *          HEALTH_TIMEOUT_MS. Typically means bun is synchronously
      *          inside a native FFI call (llama_decode on a long prompt).
      *          No strike.
-     *   DEAD → process is dead, OR the HTTP server returned 5xx, OR a
-     *          hard connection failure (port closed). Count a strike.
+     *   DEAD → process is dead, OR the HTTP server did not return 2xx
+     *          with ready=true, OR a hard connection failure (port
+     *          closed). Count a strike.
      */
     private enum ProbeResult {
         OK,
@@ -1430,7 +2552,7 @@ public class ElizaAgentService extends Service {
     /**
      * Storage key for the persisted mobile runtime mode. Must match
      * MOBILE_RUNTIME_MODE_STORAGE_KEY in
-     * eliza/packages/app-core/src/onboarding/mobile-runtime-mode.ts.
+     * eliza/packages/app-core/src/first-run/mobile-runtime-mode.ts.
      */
     private static final String RUNTIME_MODE_KEY = "eliza:mobile-runtime-mode";
 
@@ -1448,17 +2570,37 @@ public class ElizaAgentService extends Service {
         if (isBrandedDevice()) {
             return true;
         }
+        // This APK is the on-device local-agent sideload build (the cloud
+        // thin-client is a separate build). Autostart the agent unless the
+        // user has explicitly chosen a cloud runtime mode. A fresh install
+        // has no persisted mode yet (the renderer writes it only after the
+        // WebView boots), so default to autostart instead of stranding the
+        // dashboard with no agent to connect to.
         String mode = readRuntimeMode(context);
-        return "local".equals(mode);
+        return !"cloud".equals(mode);
+    }
+
+    /**
+     * True once the user (or the device image) has actually committed to
+     * running the on-device agent — a branded device, or a stock phone whose
+     * runtime mode has been explicitly persisted by the onboarding picker.
+     *
+     * Distinct from {@link #shouldAutoStart}: a fresh stock install has no
+     * persisted mode yet, so the agent still auto-starts (so the dashboard has
+     * something to talk to) but the user has chosen nothing. We use this to
+     * avoid cold-asking for notification consent during first-run onboarding —
+     * iOS-style, we ask only after there is a committed reason (the foreground
+     * service still runs without the grant; its notification is just
+     * suppressed until later granted).
+     */
+    public static boolean hasCommittedRuntimeChoice(Context context) {
+        return isBrandedDevice() || readRuntimeMode(context) != null;
     }
 
     private static boolean isBrandedDevice() {
-        if (!readSystemProperty("ro.elizaos.product").isEmpty()) return true;
-        // White-label forks set ro.<brand>os.product (e.g. ro.miladyos.product).
-        // We can't enumerate every fork's namespace from native code, so
-        // probe the most common ones used by current forks. Forks that
-        // need a different sysprop should override shouldAutoStart locally.
-        return !readSystemProperty("ro.miladyos.product").isEmpty();
+        // AOSP / ElizaOS images set ro.elizaos.product. White-label forks
+        // that use a different sysprop should override shouldAutoStart locally.
+        return !readSystemProperty("ro.elizaos.product").isEmpty();
     }
 
     private static String readRuntimeMode(Context context) {