feat(mobile): Connect Mobile: password-authenticated LAN bridge

AGENTS.md

@@ -77,7 +77,8 @@ For code entry points:
 
 ## Hard rules and boundaries
 
-- The daemon is a loopback-only sidecar. Do not make the bind host configurable or expose it beyond `127.0.0.1`.
+- The daemon's **primary (loopback) listener** stays bound to `127.0.0.1` and unauthenticated. Do not change its bind host or add auth to it.
+- The daemon MAY run a **second, opt-in LAN listener** (the "Connect Mobile" feature) that binds `0.0.0.0` **only while explicitly enabled**, **only** behind the bearer-password `authMiddleware`, serving the app API but never the loopback-gated control routes (`/shutdown`, telemetry, mobile control). It is plaintext and home-network-only by deliberate decision — see `docs/adr/0001-lan-listener-for-mobile.md` and `CONTEXT.md`. Do not add any other network-facing bind.
 - The CLI is a thin client. Do not port old in-process TypeScript CLI behavior that bypasses daemon HTTP routes.
 - Do not store derived/display session status. Status is derived from durable facts (`activity_state`, `is_terminated`, PR/check/comment facts) at service read time.
 - Do not treat failed/unknown runtime probes as proof a session is dead.

CONTEXT.md

@@ -0,0 +1,46 @@
+# Domain Glossary
+
+Canonical vocabulary for Agent Orchestrator. Terms only — no implementation
+details, no decisions (those live in `docs/adr/`).
+
+## Daemon surfaces
+
+- **Loopback Listener** — the daemon's original, always-on HTTP surface bound to
+  `127.0.0.1`. Serves the desktop app and CLI. Unauthenticated: safe only because
+  nothing off-box can reach it. Behaviour is unchanged by the mobile work.
+
+- **LAN Listener** — a second, network-facing HTTP surface the daemon exposes so a
+  physical phone can reach it. Off by default; exists only while **Connect Mobile**
+  is enabled. Authenticated (see **Connection Password**). Serves the app API but
+  **not** daemon-control routes (shutdown/lifecycle stay Loopback-only).
+
+## Mobile connectivity
+
+- **Connect Mobile** — the user-facing capability that opens the **LAN Listener**
+  and lets a paired phone use the app over the local network. A desktop toggle;
+  when off, no LAN surface exists.
+
+- **Connection Password** — the single, rotating secret that authorises a phone on
+  the **LAN Listener**. 8-char alphanumeric, generated by the desktop, shown to the
+  user out-of-band (read off the screen), typed into the phone. Rotating it drops
+  the currently-connected phone. It is the *sole* secret — it is never carried in
+  the **Pairing QR**.
+
+- **Pairing QR** — a scannable code that carries only the **LAN Listener** address
+  (`host` + `port`) and a schema version. Non-secret by design: it conveys *where*
+  to connect, never the **Connection Password**. A photo of it alone cannot connect.
+
+- **Pairing** — the act of a phone acquiring a working connection: scan the
+  **Pairing QR** (or type host/port manually), then enter the **Connection
+  Password** in a popup. A successful pairing is remembered on the phone.
+
+- **Paired Phone** — the phone currently authorised against the active **Connection
+  Password**. Only one is effectively connected at a time (single rotating password).
+
+- **Lockout** — the brute-force guard on the **LAN Listener**: repeated failed
+  password attempts from a source are throttled (per-source, not global, so a
+  hostile device cannot lock out the real phone). Resets on a successful auth.
+
+- **Home-network-only** — the trust boundary the feature assumes. Transport is
+  unencrypted, so the **LAN Listener** is only safe on a network the user trusts;
+  the desktop UI states this plainly.

backend/internal/daemon/daemon.go

@@ -18,6 +18,8 @@ import (
 	"github.com/aoagents/agent-orchestrator/backend/internal/daemon/supervisor"
 	"github.com/aoagents/agent-orchestrator/backend/internal/domain"
 	"github.com/aoagents/agent-orchestrator/backend/internal/httpd"
+	"github.com/aoagents/agent-orchestrator/backend/internal/httpd/controllers"
+	"github.com/aoagents/agent-orchestrator/backend/internal/mobilebridge"
 	"github.com/aoagents/agent-orchestrator/backend/internal/notify"
 	"github.com/aoagents/agent-orchestrator/backend/internal/ports"
 	"github.com/aoagents/agent-orchestrator/backend/internal/preview"
@@ -139,6 +141,18 @@ func Run() error {
 		}
 	}()
 
+	// Connect Mobile: the bridge service needs the LAN listener, but the LAN
+	// listener needs the built router's handler, which only exists once srv is
+	// constructed — and srv's router mounts the mobile controller, which needs
+	// the bridge service. Break the cycle with late binding: build bs with LAN
+	// left nil, hand its controller into NewWithDeps, then once srv exists,
+	// build the LAN listener over srv.Handler() and assign it onto bs.LAN.
+	bs := &controllers.BridgeService{
+		ConfigPath:  mobilebridge.Path(cfg.DataDir),
+		DefaultPort: mobilebridge.DefaultPort,
+	}
+	mc := &controllers.MobileController{Bridge: bs}
+
 	srv, err := httpd.NewWithDeps(cfg, log, termMgr, httpd.APIDeps{
 		Projects:           projectsvc.NewWithDeps(projectsvc.Deps{Store: store, Sessions: sessionSvc, DefaultHarness: domain.AgentHarness(cfg.Agent), Telemetry: telemetrySink}),
 		Agents:             agentSvc,
@@ -151,6 +165,7 @@ func Run() error {
 		Events:             cdcPipe.Broadcaster,
 		Activity:           lcStack.LCM,
 		Telemetry:          telemetrySink,
+		Mobile:             mc,
 	})
 	if err != nil {
 		stop()
@@ -162,6 +177,19 @@ func Run() error {
 		return err
 	}
 
+	// Late-bind: the LAN listener shares the exact loopback router instance so
+	// the LAN surface and loopback surface never drift apart.
+	lan := httpd.NewMobileLAN(srv.Handler(), mobilebridge.DefaultPort, log)
+	bs.LAN = lan
+
+	// Restore Connect Mobile across a daemon restart: if the bridge was left
+	// enabled, re-arm the listener on its last port with the same password
+	// hash so an already-paired phone keeps working with no new password.
+	// Best-effort: never blocks boot.
+	if err := restoreMobileOnBoot(mobilebridge.Path(cfg.DataDir), lan); err != nil {
+		log.Warn("restore mobile bridge on boot failed", "err", err)
+	}
+
 	// Reconcile sessions on boot: adopt crash-surviving runtimes, capture and
 	// terminate dead ones, reap leaked tmux, then restore shutdown-saved
 	// sessions. Best-effort: a failure is logged but never blocks boot. Placed
@@ -202,6 +230,11 @@ func Run() error {
 	stop()
 	<-previewDone
 	lcStack.Stop()
+	lanStopCtx, lanCancel := context.WithTimeout(context.Background(), cfg.ShutdownTimeout)
+	defer lanCancel()
+	if err := lan.Stop(lanStopCtx); err != nil {
+		log.Error("mobile LAN listener shutdown", "err", err)
+	}
 	if err := cdcPipe.Stop(); err != nil {
 		log.Error("cdc pipeline shutdown", "err", err)
 	}

backend/internal/daemon/mobile_restore.go

@@ -0,0 +1,30 @@
+package daemon
+
+import (
+	"fmt"
+
+	"github.com/aoagents/agent-orchestrator/backend/internal/httpd/controllers"
+	"github.com/aoagents/agent-orchestrator/backend/internal/mobilebridge"
+)
+
+// restoreMobileOnBoot re-arms the Connect Mobile LAN listener across daemon
+// restarts. If the persisted state says the bridge was enabled, it reuses the
+// existing password (no rotation — the paired phone keeps working), deriving the
+// auth hash in memory, and restarts the listener on its last bound port. A
+// non-nil return means the listener failed to (re)bind; the caller logs it as a
+// warning and continues booting regardless — Connect Mobile is best-effort, not
+// load-bearing.
+func restoreMobileOnBoot(path string, lan controllers.LANController) error {
+	state, err := mobilebridge.Load(path)
+	if err != nil {
+		return fmt.Errorf("load mobile bridge state: %w", err)
+	}
+	if !state.Enabled {
+		return nil
+	}
+	lan.SetPasswordHash(mobilebridge.HashPassword(state.Password))
+	if _, err := lan.Start(state.LastPort); err != nil {
+		return fmt.Errorf("restart mobile LAN listener: %w", err)
+	}
+	return nil
+}

backend/internal/daemon/mobile_restore_test.go

@@ -0,0 +1,64 @@
+package daemon
+
+import (
+	"context"
+	"testing"
+
+	"github.com/aoagents/agent-orchestrator/backend/internal/mobilebridge"
+)
+
+// fakeLAN is a minimal httpd.LANController fake for exercising
+// restoreMobileOnBoot without a real listener.
+type fakeLAN struct {
+	started bool
+	hash    string
+	port    int
+}
+
+func (f *fakeLAN) Start(port int) (int, error) {
+	f.started = true
+	f.port = port
+	return port, nil
+}
+func (f *fakeLAN) Stop(ctx context.Context) error { return nil }
+func (f *fakeLAN) Running() bool                  { return f.started }
+func (f *fakeLAN) BoundPort() int                 { return f.port }
+func (f *fakeLAN) SetPasswordHash(hash string)     { f.hash = hash }
+
+func TestRestoreEnabledStartsListener(t *testing.T) {
+	dir := t.TempDir()
+	path := mobilebridge.Path(dir)
+	if err := mobilebridge.Save(path, mobilebridge.State{Enabled: true, Password: "secret12", LastPort: 3011}); err != nil {
+		t.Fatalf("save state: %v", err)
+	}
+	lan := &fakeLAN{}
+	if err := restoreMobileOnBoot(path, lan); err != nil {
+		t.Fatalf("restoreMobileOnBoot: %v", err)
+	}
+	if !lan.started {
+		t.Fatal("expected LAN listener started from persisted enabled state")
+	}
+	// Restore derives the auth hash from the persisted plaintext password (no
+	// rotation), so the fake must have received HashPassword(persisted password).
+	if want := mobilebridge.HashPassword("secret12"); lan.hash != want {
+		t.Fatalf("expected hash derived from persisted password %q, got %q", want, lan.hash)
+	}
+	if lan.port != 3011 {
+		t.Fatalf("expected persisted port reused, got %d", lan.port)
+	}
+}
+
+func TestRestoreDisabledDoesNotStart(t *testing.T) {
+	dir := t.TempDir()
+	path := mobilebridge.Path(dir)
+	if err := mobilebridge.Save(path, mobilebridge.State{Enabled: false}); err != nil {
+		t.Fatalf("save state: %v", err)
+	}
+	lan := &fakeLAN{}
+	if err := restoreMobileOnBoot(path, lan); err != nil {
+		t.Fatalf("restoreMobileOnBoot: %v", err)
+	}
+	if lan.started {
+		t.Fatal("expected LAN listener NOT started when persisted state is disabled")
+	}
+}

backend/internal/httpd/api.go

@@ -31,6 +31,7 @@ type APIDeps struct {
 	CDC                cdc.Source
 	Events             cdcSubscriber
 	Telemetry          ports.EventSink
+	Mobile             *controllers.MobileController
 }
 
 // API owns one controller per resource and is the single Register call the

backend/internal/httpd/apispec/openapi.yaml

@@ -189,6 +189,100 @@ paths:
       summary: Run the legacy AO project import through the daemon store
       tags:
       - import
+  /api/v1/mobile/disable:
+    post:
+      operationId: disableMobile
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MobileStatusResponse'
+          description: OK
+        "403":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIError'
+          description: Forbidden
+        "500":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIError'
+          description: Internal Server Error
+      summary: Disable the Connect Mobile LAN bridge
+      tags:
+      - mobile
+  /api/v1/mobile/enable:
+    post:
+      operationId: enableMobile
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MobileStatusResponse'
+          description: OK
+        "403":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIError'
+          description: Forbidden
+        "500":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIError'
+          description: Internal Server Error
+      summary: Enable the Connect Mobile LAN bridge and issue a fresh password
+      tags:
+      - mobile
+  /api/v1/mobile/regenerate:
+    post:
+      operationId: regenerateMobile
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MobileStatusResponse'
+          description: OK
+        "403":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIError'
+          description: Forbidden
+        "500":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIError'
+          description: Internal Server Error
+      summary: Rotate the Connect Mobile password, dropping any connected phone
+      tags:
+      - mobile
+  /api/v1/mobile/status:
+    get:
+      operationId: getMobileStatus
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MobileStatusResponse'
+          description: OK
+        "403":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIError'
+          description: Forbidden
+      summary: Check whether Connect Mobile's LAN bridge is enabled
+      tags:
+      - mobile
   /api/v1/notifications:
     get:
       operationId: listNotifications
@@ -1910,6 +2004,25 @@ components:
       - prNumber
       - method
       type: object
+    MobileStatusResponse:
+      properties:
+        enabled:
+          type: boolean
+        host:
+          type: string
+        password:
+          type: string
+        port:
+          type: integer
+        warning:
+          type: string
+      required:
+      - enabled
+      - host
+      - port
+      - password
+      - warning
+      type: object
     NotificationEnvelope:
       properties:
         notification:
@@ -2750,3 +2863,5 @@ tags:
   name: events
 - description: Legacy AO project import (availability probe and run)
   name: import
+- description: Connect Mobile LAN bridge control (loopback/desktop only)
+  name: mobile

backend/internal/httpd/apispec/parity_test.go

@@ -13,14 +13,20 @@ import (
 	"github.com/aoagents/agent-orchestrator/backend/internal/config"
 	"github.com/aoagents/agent-orchestrator/backend/internal/httpd"
 	"github.com/aoagents/agent-orchestrator/backend/internal/httpd/apispec"
+	"github.com/aoagents/agent-orchestrator/backend/internal/httpd/controllers"
 )
 
 // TestRouteSpecParity asserts the mounted /api/v1 routes and the OpenAPI
 // operations are in 1:1 correspondence — so a route can't be added without
 // spec coverage, and the spec can't describe a route that isn't served.
 func TestRouteSpecParity(t *testing.T) {
 	log := slog.New(slog.NewTextHandler(io.Discard, nil))
-	router := httpd.NewRouterWithControl(config.Config{}, log, nil, httpd.APIDeps{}, httpd.ControlDeps{})
+	// Mobile carries a non-nil MobileController so mountMobile (which, like
+	// mountControl, skips mounting entirely on a nil controller) registers its
+	// routes here — otherwise the mobile spec operations below would have no
+	// mounted route to match.
+	deps := httpd.APIDeps{Mobile: &controllers.MobileController{}}
+	router := httpd.NewRouterWithControl(config.Config{}, log, nil, deps, httpd.ControlDeps{})
 
 	mounted := map[string]bool{}
 	err := chi.Walk(router, func(method, route string, _ http.Handler, _ ...func(http.Handler) http.Handler) error {