feat: discover Talkies hosts from Android companion

docs/platforms/linux.md

@@ -18,14 +18,25 @@ across platforms, see the
   screen, a live panel while you dictate, searchable transcript history saved on this computer, and a
   status tray icon.
 - **Works across desktops**: GNOME, KDE Plasma, Hyprland, Sway and X11 window managers.
+- **Android companion discovery**: when Avahi and a network-reachable SSH server are available,
+  Talkies advertises this computer so the Android companion can find it without manual host entry.
 - **`talkies doctor`** checks audio, microphone, hotkey, typing, clipboard, tray and model, and
   tells you how to fix anything that isn't ready.
 
 Ollama and LM Studio cleanup only accept `localhost`, `127.0.0.0/8` or `::1` endpoints. Remote
 endpoints are rejected and HTTP redirects are disabled, so transcripts never leave the machine.
 
-Besides the model downloads you ask for, the only network request Talkies makes is the update
-check described in [Updates](#updates), which sends no user data and can be turned off.
+Besides the model downloads you ask for, Talkies makes no outbound Internet requests except the
+update check described in [Updates](#updates), which sends no user data and can be turned off. When
+enabled, companion discovery is a local-network DNS-SD announcement only.
+
+For Android companion discovery, install and run Avahi (`avahi-daemon` and
+`avahi-publish-service`) and enable an SSH server on the desktop. Talkies publishes the SSH service
+only while its daemon is running and only when `ss` reports a non-loopback SSH listener. It advertises
+the service as `_ssh._tcp` with a `talkies=1` marker, allowing the Android companion to prefill the
+host and port. The default SSH port is 22; set `TALKIES_SSH_PORT` in the Talkies daemon environment
+when sshd listens on a different port. Discovery is optional and does not affect Talkies when Avahi,
+`ss`, or SSH is unavailable.
 
 ## Install
 

docs/platforms/mobile.md

@@ -25,9 +25,12 @@ A runtime is skipped when its model is missing or fails verification, or when it
 ### Cleanup, keyboard, and supported devices
 
 Talkies also includes an Android remote companion for Linux development sessions. Add a host name,
-address, SSH port, and username, then connect with a password that is requested for each session and
-never saved. New SSH host keys are shown for explicit trust-on-first-use approval and stored in the
-app-private `known_hosts` file; changed keys fail closed. The embedded ConnectBot/libvterm terminal
+address, SSH port, and username. SSH passwords are requested on first connection, then can be
+remembered with an explicit opt-in. Saved passwords are encrypted with an Android Keystore key,
+bound to the host profile, and stored outside device backup; reconnects use them without another
+prompt. Removing a host also removes its saved password. New SSH host keys are shown for explicit
+trust-on-first-use approval and stored in the app-private `known_hosts` file; changed keys fail
+closed. The embedded ConnectBot/libvterm terminal
 supports interactive shells, terminal resizing and colors, and reconnecting to long-lived sessions
 such as Herdr with `herdr session list` or `herdr session attach`. The local **Dictate** control
 transcribes on-device and types into the shell without Enter, so the user reviews before running it.
@@ -80,7 +83,7 @@ cd mobile/android
 ./gradlew assembleRelease :inference:testReleaseUnitTest :app:testReleaseUnitTest
 ```
 
-Requires JDK 17, Android SDK API 36, CMake 3.31.6, and NDK 27.2. Android runtime support starts at API 28. Android CI builds and tests both debug and release variants, checks that the APKs contain the native runtimes and their license notices but omit model weights, and uploads the tested debug APK as a seven-day artifact. Core JVM tests cover transcript spacing, bounded PCM behavior, the shared cleanup prompt/output contract, and speech-engine selection and fallback. Inference module tests cover pinned model integrity and verified installation for Whisper tiny and Phonon-2, including its attribution files. App tests cover speech-engine status and download-size text, history text, and the keyboard's password and incognito exclusion. Core tests cover the history schema, row rules, UUIDs, search escaping, and keyset paging. `SqliteTranscriptHistoryStoreTest` runs the SQLite store on the emulator in a throwaway database: WAL mode, schema, paging, literal search, delete, and clear. `LocalPhononOfflineAcceptanceTest` runs real Phonon-2 recognition with networking disabled when `files/models/Phonon-2-<revision>/` and `files/fixtures/jfk.wav` are pre-provisioned, and is skipped otherwise. API 28 emulator acceptance verifies real Whisper transcription and S1-mini transcript cleanup with external networking disabled. The app includes the whisper.cpp, llama.cpp, CrispASR, and CrispASR ggml MIT license notices. It retains S1-mini's upstream Apache 2.0 files and Phonon-2's CC-BY-4.0 files beside their separately downloaded weights.
+Requires JDK 17, Android SDK API 36, CMake 3.31.6, and NDK 27.2. Android runtime support starts at API 28. Android CI builds and tests both debug and release variants, checks that the APKs contain the native runtimes and their license notices but omit model weights, and uploads the tested debug APK as a seven-day artifact. Core JVM tests cover transcript spacing, bounded PCM behavior, the shared cleanup prompt/output contract, and speech-engine selection and fallback. Inference module tests cover pinned model integrity and verified installation for Whisper tiny and Phonon-2, including its attribution files. App tests cover speech-engine status and download-size text, history text, and the keyboard's password and incognito exclusion. The emulator's `AndroidSshCredentialStoreTest` verifies Android Keystore encryption, profile binding, and credential deletion. Core tests cover the history schema, row rules, UUIDs, search escaping, and keyset paging. `SqliteTranscriptHistoryStoreTest` runs the SQLite store on the emulator in a throwaway database: WAL mode, schema, paging, literal search, delete, and clear. `LocalPhononOfflineAcceptanceTest` runs real Phonon-2 recognition with networking disabled when `files/models/Phonon-2-<revision>/` and `files/fixtures/jfk.wav` are pre-provisioned, and is skipped otherwise. API 28 emulator acceptance verifies real Whisper transcription and S1-mini transcript cleanup with external networking disabled. The app includes the whisper.cpp, llama.cpp, CrispASR, and CrispASR ggml MIT license notices. It retains S1-mini's upstream Apache 2.0 files and Phonon-2's CC-BY-4.0 files beside their separately downloaded weights.
 
 ## Deprecated Flutter prototype
 

linux/src/app/companion_discovery.zig

@@ -0,0 +1,84 @@
+//! Optional DNS-SD advertisement for the Android Talkies companion.
+//!
+//! Android scans `_ssh._tcp` to find machines it can securely connect to.
+//! Publish only when this machine has a non-loopback SSH listener, and let
+//! Avahi's child lifetime match the Talkies daemon lifetime. Discovery is an
+//! enhancement; missing Avahi/ss must never prevent dictation from starting.
+
+const std = @import("std");
+const utils = @import("core").utils;
+
+const default_ssh_port: u16 = 22;
+
+pub const Publisher = struct {
+    child: ?std.process.Child = null,
+
+    pub fn start(allocator: std.mem.Allocator) Publisher {
+        const port = sshPort() orelse return .{};
+        const ss_output = utils.runCapture(allocator, &.{ "ss", "-H", "-ltn" }) catch return .{};
+        defer allocator.free(ss_output);
+        if (!hasReachableListener(ss_output, port)) return .{};
+
+        const port_text = std.fmt.allocPrintSentinel(allocator, "{d}", .{port}, 0) catch return .{};
+        defer allocator.free(port_text);
+        const child = std.process.spawn(utils.io(), .{
+            .argv = &.{ "avahi-publish-service", "-s", "Talkies", "_ssh._tcp", port_text, "talkies=1" },
+            .stdin = .ignore,
+            .stdout = .ignore,
+            .stderr = .ignore,
+        }) catch |err| {
+            // Avahi is optional on many Linux desktops.
+            if (err != error.FileNotFound) utils.logError("Companion discovery unavailable: {}", .{err});
+            return .{};
+        };
+        utils.log("Advertising the SSH host for the Talkies companion on port {d}", .{port});
+        return .{ .child = child };
+    }
+
+    pub fn stop(self: *Publisher) void {
+        if (self.child) |*child| {
+            child.kill(utils.io());
+            self.child = null;
+        }
+    }
+};
+
+fn sshPort() ?u16 {
+    const value = utils.getEnv("TALKIES_SSH_PORT") orelse return default_ssh_port;
+    const port = std.fmt.parseInt(u16, value, 10) catch return null;
+    return if (port == 0) null else port;
+}
+
+fn hasReachableListener(ss_output: []const u8, port: u16) bool {
+    var lines = std.mem.tokenizeScalar(u8, ss_output, '\n');
+    while (lines.next()) |line| {
+        var fields = std.mem.tokenizeAny(u8, line, " \t");
+        _ = fields.next() orelse continue; // state
+        _ = fields.next() orelse continue; // recv-q
+        _ = fields.next() orelse continue; // send-q
+        const local = fields.next() orelse continue;
+        const remote = fields.next() orelse continue;
+        _ = remote;
+
+        var suffix_buf: [6]u8 = undefined;
+        const suffix = std.fmt.bufPrint(&suffix_buf, ":{d}", .{port}) catch continue;
+        if (!std.mem.endsWith(u8, local, suffix)) continue;
+        const address_with_brackets = local[0 .. local.len - suffix.len];
+        const address = if (std.mem.startsWith(u8, address_with_brackets, "[") and
+            std.mem.endsWith(u8, address_with_brackets, "]"))
+            address_with_brackets[1 .. address_with_brackets.len - 1]
+        else
+            address_with_brackets;
+        if (std.mem.eql(u8, address, "127.0.0.1") or std.mem.eql(u8, address, "::1")) continue;
+        return true;
+    }
+    return false;
+}
+
+test "detects only externally reachable SSH listeners" {
+    try std.testing.expect(hasReachableListener("LISTEN 0 128 0.0.0.0:22 0.0.0.0:*\n", 22));
+    try std.testing.expect(hasReachableListener("LISTEN 0 128 [::]:2222 [::]:*\n", 2222));
+    try std.testing.expect(!hasReachableListener("LISTEN 0 128 127.0.0.1:22 0.0.0.0:*\n", 22));
+    try std.testing.expect(!hasReachableListener("LISTEN 0 128 [::1]:22 [::]:*\n", 22));
+    try std.testing.expect(!hasReachableListener("LISTEN 0 128 0.0.0.0:2200 0.0.0.0:*\n", 22));
+}

linux/src/app/daemon.zig

@@ -32,6 +32,7 @@ const yap_sessions = @import("yap_sessions.zig");
 const yap_window = @import("yap_window.zig");
 const history = @import("history.zig");
 const updater = @import("updater.zig");
+const companion_discovery = @import("companion_discovery.zig");
 const trigger_mod = @import("trigger.zig");
 const build_options = @import("build_options");
 
@@ -516,12 +517,14 @@ pub const Daemon = struct {
     yap_sb: ?*yap_sandbox.Sandbox = null,
     yap_session_manager: ?*yap_sessions.SessionManager = null,
     yap_session_id: ?i64 = null,
+    companion_publisher: companion_discovery.Publisher = .{},
 
     // -----------------------------------------------------------------
     // Lifecycle
     // -----------------------------------------------------------------
 
     fn deinit(self: *Daemon) void {
+        self.companion_publisher.stop();
         if (self.capture) |cap| {
             cap.stop_requested.store(true, .release);
             cap.thread.join();
@@ -2351,6 +2354,9 @@ pub fn run(allocator: std.mem.Allocator) !?[]u8 {
     defer daemon.deinit();
 
     try daemon.cfg.load();
+    // The publisher is optional and process-scoped. Android can discover a
+    // reachable SSH daemon without manual host/port entry when Avahi is used.
+    daemon.companion_publisher = companion_discovery.Publisher.start(allocator);
     daemon.cleanup_service.threads = daemon.cfg.threads;
     // Opened even while saving is off, so the history page can show (and
     // delete) what was saved before.

mobile/android/app/src/androidTest/java/com/talkies/android/AndroidSshCredentialStoreTest.kt

@@ -0,0 +1,67 @@
+package com.talkies.android
+
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Test
+import org.junit.runner.RunWith
+import java.io.File
+import java.nio.charset.StandardCharsets
+import java.util.UUID
+
+@RunWith(AndroidJUnit4::class)
+class AndroidSshCredentialStoreTest {
+    private val context = InstrumentationRegistry.getInstrumentation().targetContext
+
+    @Test
+    fun remembersPasswordEncryptedAndBindsItToItsHostProfile() {
+        val store = AndroidSshCredentialStore(context)
+        val profile = profile()
+        val password = "Correct horse 🔐 battery".toCharArray()
+        try {
+            val directory = File(context.noBackupFilesDir, "ssh-credentials")
+            val existing = directory.listFiles().orEmpty().map { it.absolutePath }.toSet()
+            store.save(profile, password)
+            val files = directory.listFiles()
+            assertNotNull(files)
+            val encryptedFile = requireNotNull(files).single {
+                it.extension == "credential" && it.absolutePath !in existing
+            }
+            assertFalse(String(encryptedFile.readBytes(), StandardCharsets.UTF_8).contains(String(password)))
+            assertArrayEquals(password, requireNotNull(store.load(profile)))
+
+            val changedHost = profile.copy(host = "other.example")
+            assertNull(store.load(changedHost))
+            assertNull(store.load(profile))
+        } finally {
+            password.fill('\u0000')
+            store.delete(profile.id)
+        }
+    }
+
+    @Test
+    fun deletingAHostCredentialMakesItUnavailable() {
+        val store = AndroidSshCredentialStore(context)
+        val profile = profile()
+        val password = "secret".toCharArray()
+        try {
+            store.save(profile, password)
+            store.delete(profile.id)
+            assertNull(store.load(profile))
+        } finally {
+            password.fill('\u0000')
+            store.delete(profile.id)
+        }
+    }
+
+    private fun profile() = SshHostProfile(
+        id = UUID.randomUUID().toString(),
+        name = "Test host",
+        host = "192.0.2.4",
+        port = 2222,
+        username = "tester",
+    )
+}

mobile/android/app/src/main/AndroidManifest.xml

@@ -2,6 +2,7 @@
     <uses-permission android:name="android.permission.RECORD_AUDIO" />
     <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
     <uses-feature android:name="android.hardware.microphone" android:required="false" />
 
     <application