From 8af8449b77dd859754ed6204051be183762adf87 Mon Sep 17 00:00:00 2001
From: opencode <opencode@echohello.dev>
Date: Sat, 18 Jul 2026 00:11:09 +1000
Subject: [PATCH 1/4] feat(app): scaffold mobile UI for
 connect/sessions/transcript

Adds the three-screen MVP on top of @echohello/client:

- connect:    manual ws:// endpoint + label, saved to AsyncStorage,
              connects via SupaplaneClient
- sessions:   workspace list grouped by freshness, tap to drill in
- session:    transcript + composer (send/abort/start) bound to
              ClientCommand wire types

Shared infrastructure:
- zustand connection-store: single SupaplaneClient instance,
  status, workspaces, sessions, per-session event buffer
- AsyncStorage wrapper (v3 API: setMany/removeMany) for the
  saved endpoint and TOFU-pinned server fingerprint
- dark theme tokens, Button, TextField, ConnectionBanner

Bundler plumbing: metro.config.cjs with explicit watchFolders
and nodeModulesPaths so Bun's hoisting doesn't trip the
resolver on a monorepo root.

Co-authored-by: opencode <opencode@echohello.dev>
---
 packages/app/app/_layout.tsx                  |  45 ++-
 packages/app/app/connect.tsx                  | 125 +++++++
 packages/app/app/index.tsx                    |  48 +--
 packages/app/app/session/[id].tsx             | 311 ++++++++++++++++++
 packages/app/app/sessions.tsx                 | 170 ++++++++++
 packages/app/expo-env.d.ts                    |   1 -
 packages/app/metro.config.cjs                 |  20 ++
 packages/app/package.json                     |   3 +-
 packages/app/src/components/Button.tsx        |  66 ++++
 .../app/src/components/ConnectionBanner.tsx   |  59 ++++
 packages/app/src/components/TextField.tsx     |  45 +++
 packages/app/src/state/connection-store.ts    | 216 ++++++++++++
 packages/app/src/storage.ts                   |  52 +++
 packages/app/src/theme.ts                     |  41 +++
 packages/app/tsconfig.json                    |  29 +-
 packages/app/tsconfig.typecheck.json          |   3 +
 16 files changed, 1179 insertions(+), 55 deletions(-)
 create mode 100644 packages/app/app/connect.tsx
 create mode 100644 packages/app/app/session/[id].tsx
 create mode 100644 packages/app/app/sessions.tsx
 delete mode 100644 packages/app/expo-env.d.ts
 create mode 100644 packages/app/metro.config.cjs
 create mode 100644 packages/app/src/components/Button.tsx
 create mode 100644 packages/app/src/components/ConnectionBanner.tsx
 create mode 100644 packages/app/src/components/TextField.tsx
 create mode 100644 packages/app/src/state/connection-store.ts
 create mode 100644 packages/app/src/storage.ts
 create mode 100644 packages/app/src/theme.ts
 create mode 100644 packages/app/tsconfig.typecheck.json

diff --git a/packages/app/app/_layout.tsx b/packages/app/app/_layout.tsx
index fbf4426..06b0f8d 100644
--- a/packages/app/app/_layout.tsx
+++ b/packages/app/app/_layout.tsx
@@ -1,19 +1,48 @@
-import { Stack } from "expo-router";
+import { useEffect } from "react";
+import { Stack, useRouter } from "expo-router";
 import { StatusBar } from "expo-status-bar";
+import { SafeAreaProvider } from "react-native-safe-area-context";
+
+import { useConnectionStore } from "../src/state/connection-store.js";
 
 export default function RootLayout(): React.JSX.Element {
+  const router = useRouter();
+  const hydrate = useConnectionStore((s) => s.hydrate);
+  const status = useConnectionStore((s) => s.status);
+
+  useEffect(() => {
+    void hydrate();
+  }, [hydrate]);
+
+  useEffect(() => {
+    if (status === "idle" || status === "disconnected" || status === "error" || status === "exhausted") {
+      router.replace("/connect");
+    } else if (status === "connected" || status === "connecting" || status === "reconnecting") {
+      router.replace("/sessions");
+    }
+  }, [status, router]);
+
   return (
-    <>
+    <SafeAreaProvider>
+      <StatusBar style="light" />
       <Stack
         screenOptions={{
-          headerStyle: { backgroundColor: "#0a0a0f" },
-          headerTintColor: "#e5e5e5",
-          contentStyle: { backgroundColor: "#0a0a0f" },
+          headerStyle: { backgroundColor: colors.bg },
+          headerTintColor: colors.text,
+          headerTitleStyle: { color: colors.text },
+          contentStyle: { backgroundColor: colors.bg },
         }}
       >
-        <Stack.Screen name="index" options={{ title: "Supaplane" }} />
+        <Stack.Screen name="index" options={{ headerShown: false }} />
+        <Stack.Screen name="connect" options={{ headerShown: false }} />
+        <Stack.Screen name="sessions" options={{ headerShown: false }} />
+        <Stack.Screen name="session/[id]" options={{ headerShown: true }} />
       </Stack>
-      <StatusBar style="light" />
-    </>
+    </SafeAreaProvider>
   );
 }
+
+const colors = {
+  bg: "#0a0a0f",
+  text: "#e5e5e5",
+};
diff --git a/packages/app/app/connect.tsx b/packages/app/app/connect.tsx
new file mode 100644
index 0000000..81aaa1c
--- /dev/null
+++ b/packages/app/app/connect.tsx
@@ -0,0 +1,125 @@
+import { useMemo, useState } from "react";
+import { KeyboardAvoidingView, Platform, ScrollView, StyleSheet, Text, View } from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
+import { useRouter } from "expo-router";
+
+import { Button } from "../src/components/Button.js";
+import { ConnectionBanner } from "../src/components/ConnectionBanner.js";
+import { TextField } from "../src/components/TextField.js";
+import { useConnectionStore } from "../src/state/connection-store.js";
+import { colors, spacing, typography } from "../src/theme.js";
+
+function isValidWsUrl(value: string): boolean {
+  return /^wss?:\/\/.+/i.test(value.trim());
+}
+
+export default function ConnectScreen() {
+  const router = useRouter();
+  const status = useConnectionStore((s) => s.status);
+  const saved = useConnectionStore((s) => s.saved);
+  const error = useConnectionStore((s) => s.error);
+  const connect = useConnectionStore((s) => s.connect);
+  const disconnect = useConnectionStore((s) => s.disconnect);
+
+  const [endpoint, setEndpoint] = useState(saved?.endpoint ?? "ws://");
+  const [label, setLabel] = useState(saved?.label ?? "");
+  const [validation, setValidation] = useState<string | null>(null);
+
+  const connecting = status === "connecting" || status === "reconnecting";
+  const isConnected = status === "connected";
+
+  const helper = useMemo(() => {
+    if (isConnected) {
+      return "Connected. Use Sessions to pick a workspace, or Disconnect to pair a different daemon.";
+    }
+    return "Enter the WebSocket URL of your Supaplane daemon. QR pairing arrives once the relay ships.";
+  }, [isConnected]);
+
+  const onConnect = async () => {
+    if (!isValidWsUrl(endpoint)) {
+      setValidation("Endpoint must start with ws:// or wss://");
+      return;
+    }
+    setValidation(null);
+    const trimmedLabel = label.trim();
+    await connect(
+      trimmedLabel ? { endpoint: endpoint.trim(), label: trimmedLabel } : { endpoint: endpoint.trim() },
+    );
+  };
+
+  return (
+    <SafeAreaView style={styles.root} edges={["top", "left", "right"]}>
+      <ConnectionBanner />
+      <KeyboardAvoidingView
+        behavior={Platform.OS === "ios" ? "padding" : undefined}
+        style={styles.flex}
+      >
+        <ScrollView
+          contentContainerStyle={styles.content}
+          keyboardShouldPersistTaps="handled"
+        >
+          <View style={styles.header}>
+            <Text style={typography.display}>Supaplane</Text>
+            <Text style={[typography.bodyMuted, styles.lede]}>{helper}</Text>
+          </View>
+
+          <View style={styles.form}>
+            <TextField
+              label="Daemon endpoint"
+              value={endpoint}
+              onChangeText={setEndpoint}
+              placeholder="ws://192.168.1.10:7700/ws"
+              autoCapitalize="none"
+              autoCorrect={false}
+              keyboardType="url"
+              {...(validation ? { error: validation } : {})}
+              hint={error && status === "error" ? error : "WebSocket URL of the daemon"}
+            />
+            <TextField
+              label="Label (optional)"
+              value={label}
+              onChangeText={setLabel}
+              placeholder="Work Mac"
+              hint="Shown in the connection banner"
+            />
+          </View>
+
+          {error && status === "error" ? (
+            <Text style={styles.errorInline}>Last attempt failed: {error}</Text>
+          ) : null}
+
+          <View style={styles.actions}>
+            {isConnected ? (
+              <>
+                <Button label="Open sessions" onPress={() => router.push("/sessions")} />
+                <Button
+                  label="Disconnect"
+                  onPress={disconnect}
+                  variant="secondary"
+                />
+              </>
+            ) : (
+              <Button
+                label={connecting ? "Connecting…" : "Connect"}
+                onPress={onConnect}
+                loading={connecting}
+                disabled={connecting}
+              />
+            )}
+          </View>
+        </ScrollView>
+      </KeyboardAvoidingView>
+    </SafeAreaView>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1, backgroundColor: colors.bg },
+  flex: { flex: 1 },
+  content: { padding: spacing.xl, gap: spacing.xl, flexGrow: 1 },
+  header: { gap: spacing.sm },
+  lede: { lineHeight: 22 },
+  form: { gap: spacing.lg },
+  errorInline: { ...typography.caption, color: colors.danger },
+  actions: { gap: spacing.md, marginTop: "auto" },
+});
diff --git a/packages/app/app/index.tsx b/packages/app/app/index.tsx
index 8ebe7c4..ad19036 100644
--- a/packages/app/app/index.tsx
+++ b/packages/app/app/index.tsx
@@ -1,42 +1,10 @@
-import { StyleSheet, Text, View } from "react-native";
+import { Redirect } from "expo-router";
+import { useConnectionStore } from "../src/state/connection-store.js";
 
-export default function Home(): React.JSX.Element {
-  return (
-    <View style={styles.container}>
-      <Text style={styles.title}>Supaplane</Text>
-      <Text style={styles.subtitle}>
-        Connect to a daemon via QR code or an access code to start a session.
-      </Text>
-      <Text style={styles.footnote}>
-        Mobile app scaffold — wire to @echohello/client in a follow-up.
-      </Text>
-    </View>
-  );
+export default function Index(): React.JSX.Element {
+  const status = useConnectionStore((s) => s.status);
+  if (status === "connected" || status === "connecting" || status === "reconnecting") {
+    return <Redirect href="/sessions" />;
+  }
+  return <Redirect href="/connect" />;
 }
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    alignItems: "center",
-    justifyContent: "center",
-    paddingHorizontal: 24,
-    backgroundColor: "#0a0a0f",
-  },
-  title: {
-    fontSize: 36,
-    fontWeight: "700",
-    color: "#e5e5e5",
-    marginBottom: 12,
-  },
-  subtitle: {
-    fontSize: 16,
-    color: "#a3a3a3",
-    textAlign: "center",
-    marginBottom: 24,
-  },
-  footnote: {
-    fontSize: 12,
-    color: "#525252",
-    textAlign: "center",
-  },
-});
diff --git a/packages/app/app/session/[id].tsx b/packages/app/app/session/[id].tsx
new file mode 100644
index 0000000..cac2ca8
--- /dev/null
+++ b/packages/app/app/session/[id].tsx
@@ -0,0 +1,311 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import {
+  KeyboardAvoidingView,
+  Platform,
+  Pressable,
+  ScrollView,
+  StyleSheet,
+  Text,
+  TextInput,
+  View,
+} from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
+import { Stack, useLocalSearchParams, useRouter } from "expo-router";
+import type { AgentEvent } from "@echohello/protocol";
+
+import { ConnectionBanner } from "../../src/components/ConnectionBanner.js";
+import { Button } from "../../src/components/Button.js";
+import { useConnectionStore } from "../../src/state/connection-store.js";
+import { colors, radius, spacing, typography } from "../../src/theme.js";
+
+export default function SessionScreen() {
+  const router = useRouter();
+  const params = useLocalSearchParams<{ id: string }>();
+  const workspaceId = typeof params.id === "string" ? params.id : Array.isArray(params.id) ? (params.id[0] ?? "") : "";
+
+  const workspace = useConnectionStore((s) =>
+    workspaceId ? (s.workspaces.get(workspaceId) ?? null) : null,
+  );
+  const sessions = useConnectionStore((s) => s.sessions);
+  const client = useConnectionStore((s) => s.client);
+  const recordEvent = useConnectionStore((s) => s.recordEvent);
+  const clearEvents = useConnectionStore((s) => s.clearEvents);
+  const status = useConnectionStore((s) => s.status);
+
+  const activeSessionId = workspace?.activeSessionId ?? null;
+  const activeSession = activeSessionId ? (sessions.get(activeSessionId) ?? null) : null;
+
+  const allEvents = useConnectionStore((s) => s.events);
+  const events = useMemo(() => {
+    if (!activeSessionId) return [] as AgentEvent[];
+    return allEvents.get(activeSessionId) ?? [];
+  }, [allEvents, activeSessionId]);
+
+  const [draft, setDraft] = useState("");
+  const [sessionInput, setSessionInput] = useState(activeSessionId ?? "");
+  const scrollRef = useRef<ScrollView>(null);
+
+  useEffect(() => {
+    if (activeSessionId) setSessionInput(activeSessionId);
+  }, [activeSessionId]);
+
+  useEffect(() => {
+    if (!client) return;
+    const off = client.onAgentEvent((event) => recordEvent(event));
+    return off;
+  }, [client, recordEvent]);
+
+  useEffect(() => {
+    if (events.length === 0) return;
+    const id = setTimeout(() => scrollRef.current?.scrollToEnd({ animated: true }), 50);
+    return () => clearTimeout(id);
+  }, [events.length]);
+
+  const send = (): void => {
+    if (!client) return;
+    const target = sessionInput.trim() || activeSessionId;
+    const prompt = draft.trim();
+    if (!target || !prompt) return;
+    client.sendCommand({
+      type: "session.send",
+      sessionId: target,
+      prompt,
+      attachments: [],
+    });
+    setDraft("");
+  };
+
+  const start = (): void => {
+    if (!client || !workspace) return;
+    client.sendCommand({
+      type: "session.start",
+      workspaceId: workspace.workspaceId,
+      providerId: "claude",
+    });
+  };
+
+  const abort = (): void => {
+    if (!client) return;
+    const target = sessionInput.trim() || activeSessionId;
+    if (!target) return;
+    client.sendCommand({ type: "session.abort", sessionId: target });
+  };
+
+  return (
+    <SafeAreaView style={styles.root} edges={["top", "left", "right"]}>
+      <Stack.Screen
+        options={{
+          title: workspace?.repoName ?? workspace?.cwd ?? "Session",
+          headerRight: () => (
+            <Pressable onPress={() => router.back()} hitSlop={8}>
+              <Text style={styles.back}>Back</Text>
+            </Pressable>
+          ),
+        }}
+      />
+      <ConnectionBanner />
+
+      <View style={styles.metaRow}>
+        <Text style={styles.meta} numberOfLines={1}>
+          {workspace?.branch ?? "no branch"} · {workspace?.cwd ?? "unknown cwd"}
+        </Text>
+        <Text style={styles.metaDim}>
+          {activeSession
+            ? `${activeSession.providerId} · ${activeSession.status}`
+            : "no active session"}
+        </Text>
+      </View>
+
+      <KeyboardAvoidingView
+        behavior={Platform.OS === "ios" ? "padding" : undefined}
+        style={styles.flex}
+        keyboardVerticalOffset={Platform.OS === "ios" ? 64 : 0}
+      >
+        <ScrollView
+          ref={scrollRef}
+          style={styles.transcript}
+          contentContainerStyle={styles.transcriptContent}
+        >
+          {events.length === 0 ? (
+            <Text style={styles.empty}>
+              {activeSession
+                ? "Waiting for the agent. Send a prompt below to get started."
+                : "No active session. Start one to begin streaming events."}
+            </Text>
+          ) : (
+            events.map((event, index) => (
+              <TranscriptLine
+                key={`${event.type}-${index}-${event.ts}`}
+                event={event}
+              />
+            ))
+          )}
+        </ScrollView>
+
+        <View style={styles.composer}>
+          <View style={styles.sessionRow}>
+            <TextInput
+              style={styles.sessionInput}
+              value={sessionInput}
+              onChangeText={setSessionInput}
+              placeholder="session id"
+              placeholderTextColor={colors.textDim}
+              autoCapitalize="none"
+              autoCorrect={false}
+            />
+            {activeSessionId ? (
+              <Pressable
+                onPress={() => activeSessionId && clearEvents(activeSessionId)}
+                style={styles.linkButton}
+              >
+                <Text style={styles.linkText}>clear</Text>
+              </Pressable>
+            ) : null}
+          </View>
+          <View style={styles.inputRow}>
+            <TextInput
+              style={styles.prompt}
+              value={draft}
+              onChangeText={setDraft}
+              placeholder={
+                activeSession
+                  ? "Send a prompt…"
+                  : "Start a session first (provider defaults to claude)"
+              }
+              placeholderTextColor={colors.textDim}
+              multiline
+              editable={!!client && status === "connected"}
+            />
+            <View style={styles.actionStack}>
+              {activeSession ? (
+                <Button label="Send" onPress={send} disabled={!draft.trim()} />
+              ) : (
+                <Button label="Start" onPress={start} disabled={!client || !workspace} />
+              )}
+              {activeSession ? (
+                <Button label="Abort" onPress={abort} variant="danger" />
+              ) : null}
+            </View>
+          </View>
+        </View>
+      </KeyboardAvoidingView>
+    </SafeAreaView>
+  );
+}
+
+function TranscriptLine({ event }: { event: AgentEvent }) {
+  switch (event.type) {
+    case "message.delta":
+    case "message.final":
+      return (
+        <View style={styles.line}>
+          <Text style={styles.lineKind}>msg</Text>
+          <Text style={styles.lineText}>{event.text}</Text>
+        </View>
+      );
+    case "tool.start":
+      return (
+        <View style={styles.line}>
+          <Text style={[styles.lineKind, styles.toolKind]}>tool</Text>
+          <Text style={styles.lineText}>▶ {event.name}</Text>
+        </View>
+      );
+    case "tool.result":
+      return (
+        <View style={styles.line}>
+          <Text style={[styles.lineKind, styles.toolKind]}>tool</Text>
+          <Text style={styles.lineText}>✓ {event.toolCallId} · {event.durationMs}ms</Text>
+        </View>
+      );
+    case "status":
+      return (
+        <View style={styles.line}>
+          <Text style={[styles.lineKind, styles.statusKind]}>status</Text>
+          <Text style={styles.lineText}>{event.status}</Text>
+        </View>
+      );
+    case "error":
+      return (
+        <View style={styles.line}>
+          <Text style={[styles.lineKind, styles.errorKind]}>error</Text>
+          <Text style={styles.lineText}>{event.code}: {event.message}</Text>
+        </View>
+      );
+    case "permission_request":
+      return (
+        <View style={styles.line}>
+          <Text style={[styles.lineKind, styles.warnKind]}>perm</Text>
+          <Text style={styles.lineText}>{event.reason}</Text>
+        </View>
+      );
+    case "tool.progress":
+      return null;
+    default: {
+      const _exhaustive: never = event;
+      return _exhaustive ? null : null;
+    }
+  }
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1, backgroundColor: colors.bg },
+  flex: { flex: 1 },
+  back: { color: colors.accent, fontSize: 15 },
+  metaRow: {
+    paddingHorizontal: spacing.lg,
+    paddingVertical: spacing.sm,
+    borderBottomWidth: StyleSheet.hairlineWidth,
+    borderBottomColor: colors.border,
+    backgroundColor: colors.surface,
+    gap: 2,
+  },
+  meta: { ...typography.caption, color: colors.text },
+  metaDim: { ...typography.caption, color: colors.textDim },
+  transcript: { flex: 1 },
+  transcriptContent: { padding: spacing.lg, gap: spacing.sm, paddingBottom: spacing.xxl },
+  empty: { ...typography.bodyMuted, textAlign: "center", marginTop: spacing.xl },
+  line: { flexDirection: "row", gap: spacing.sm, alignItems: "flex-start" },
+  lineKind: {
+    ...typography.monoDim,
+    width: 56,
+    textTransform: "uppercase",
+    paddingTop: 2,
+  },
+  lineText: { ...typography.mono, flex: 1, lineHeight: 20 },
+  toolKind: { color: colors.info },
+  statusKind: { color: colors.warning },
+  errorKind: { color: colors.danger },
+  warnKind: { color: colors.warning },
+  composer: {
+    padding: spacing.lg,
+    borderTopWidth: StyleSheet.hairlineWidth,
+    borderTopColor: colors.border,
+    backgroundColor: colors.surface,
+    gap: spacing.sm,
+  },
+  sessionRow: { flexDirection: "row", alignItems: "center", gap: spacing.sm },
+  sessionInput: {
+    flex: 1,
+    backgroundColor: colors.bg,
+    borderRadius: radius.sm,
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.sm,
+    color: colors.text,
+    fontFamily: "Menlo",
+    fontSize: 12,
+  },
+  inputRow: { flexDirection: "row", gap: spacing.sm, alignItems: "flex-end" },
+  prompt: {
+    flex: 1,
+    backgroundColor: colors.bg,
+    borderRadius: radius.md,
+    padding: spacing.md,
+    color: colors.text,
+    fontSize: 15,
+    minHeight: 44,
+    maxHeight: 140,
+  },
+  actionStack: { gap: spacing.xs },
+  linkButton: { paddingHorizontal: spacing.sm, paddingVertical: spacing.xs },
+  linkText: { ...typography.caption, color: colors.accent },
+});
diff --git a/packages/app/app/sessions.tsx b/packages/app/app/sessions.tsx
new file mode 100644
index 0000000..5ae5dcf
--- /dev/null
+++ b/packages/app/app/sessions.tsx
@@ -0,0 +1,170 @@
+import { useEffect, useMemo } from "react";
+import { FlatList, Pressable, RefreshControl, StyleSheet, Text, View } from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
+import { Stack, useRouter } from "expo-router";
+import type { SessionState, WorkspaceState } from "@echohello/protocol";
+
+import { ConnectionBanner } from "../src/components/ConnectionBanner.js";
+import { Button } from "../src/components/Button.js";
+import { useConnectionStore } from "../src/state/connection-store.js";
+import { colors, radius, spacing, typography } from "../src/theme.js";
+
+interface Row {
+  workspace: WorkspaceState;
+  session: SessionState | null;
+}
+
+export default function SessionsScreen() {
+  const router = useRouter();
+  const status = useConnectionStore((s) => s.status);
+  const workspaces = useConnectionStore((s) => s.workspaces);
+  const sessions = useConnectionStore((s) => s.sessions);
+  const connect = useConnectionStore((s) => s.connect);
+  const saved = useConnectionStore((s) => s.saved);
+
+  useEffect(() => {
+    if (status === "idle" || status === "disconnected") {
+      if (saved) {
+        void connect({ endpoint: saved.endpoint, label: saved.label });
+      } else {
+        router.replace("/connect");
+      }
+    }
+  }, [status, saved, connect, router]);
+
+  const rows = useMemo<Row[]>(() => {
+    const list = Array.from(workspaces.values()).sort((a, b) => {
+      if (a.freshness === b.freshness) return a.cwd.localeCompare(b.cwd);
+      if (a.freshness === "active") return -1;
+      if (b.freshness === "active") return 1;
+      return 0;
+    });
+    return list.map((workspace) => {
+      const activeId = workspace.activeSessionId;
+      const session =
+        activeId !== null && activeId !== undefined
+          ? (sessions.get(activeId) ?? null)
+          : null;
+      return { workspace, session };
+    });
+  }, [workspaces, sessions]);
+
+  return (
+    <SafeAreaView style={styles.root} edges={["top", "left", "right"]}>
+      <Stack.Screen options={{ title: "Sessions" }} />
+      <ConnectionBanner />
+      <View style={styles.headerRow}>
+        <Text style={typography.title}>Workspaces</Text>
+        <Button
+          label="Pair new"
+          onPress={() => router.push("/connect")}
+          variant="secondary"
+        />
+      </View>
+      <FlatList
+        data={rows}
+        keyExtractor={(row) => row.workspace.workspaceId}
+        contentContainerStyle={rows.length === 0 ? styles.emptyWrap : styles.list}
+        refreshControl={<RefreshControl refreshing={false} onRefresh={() => undefined} tintColor={colors.textMuted} />}
+        ListEmptyComponent={
+          <View style={styles.empty}>
+            <Text style={typography.bodyMuted}>
+              No workspaces yet. Start one from the CLI:
+            </Text>
+            <Text style={[typography.mono, styles.code]}>supaplane agent start</Text>
+          </View>
+        }
+        renderItem={({ item }) => (
+          <Pressable
+            onPress={() =>
+              router.push({
+                pathname: "/session/[id]",
+                params: { id: item.workspace.workspaceId },
+              })
+            }
+            style={({ pressed }) => [styles.card, pressed && styles.cardPressed]}
+          >
+            <View style={styles.cardHeader}>
+              <Text style={styles.cardTitle} numberOfLines={1}>
+                {item.workspace.repoName ?? item.workspace.cwd}
+              </Text>
+              <FreshnessPill freshness={item.workspace.freshness} />
+            </View>
+            <Text style={styles.cardSubtitle} numberOfLines={1}>
+              {item.workspace.branch ?? "no branch"} · {item.workspace.cwd}
+            </Text>
+            {item.session ? (
+              <Text style={styles.sessionLabel} numberOfLines={1}>
+                {labelForSession(item.session)}
+              </Text>
+            ) : (
+              <Text style={styles.sessionLabelDim}>No active session</Text>
+            )}
+          </Pressable>
+        )}
+      />
+    </SafeAreaView>
+  );
+}
+
+function labelForSession(session: SessionState): string {
+  const status = session.status === "running" ? "●" : session.status === "waiting" ? "◐" : "○";
+  const title = session.title ?? `${session.providerId} session`;
+  return `${status} ${title}`;
+}
+
+function FreshnessPill({ freshness }: { freshness: WorkspaceState["freshness"] }) {
+  const palette =
+    freshness === "active"
+      ? { bg: "#0e2a22", fg: colors.success }
+      : freshness === "blocked"
+        ? { bg: "#2a2010", fg: colors.warning }
+        : freshness === "done"
+          ? { bg: "#10202e", fg: colors.info }
+          : { bg: colors.surfaceRaised, fg: colors.textMuted };
+  return (
+    <View style={[styles.pill, { backgroundColor: palette.bg }]}>
+      <Text style={[styles.pillLabel, { color: palette.fg }]}>{freshness}</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1, backgroundColor: colors.bg },
+  headerRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+    paddingHorizontal: spacing.xl,
+    paddingVertical: spacing.md,
+  },
+  list: { padding: spacing.xl, gap: spacing.md, paddingTop: 0 },
+  emptyWrap: { flexGrow: 1, justifyContent: "center", padding: spacing.xl },
+  empty: { alignItems: "center", gap: spacing.md },
+  code: {
+    backgroundColor: colors.surface,
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.sm,
+    borderRadius: radius.md,
+  },
+  card: {
+    backgroundColor: colors.surface,
+    borderRadius: radius.lg,
+    padding: spacing.lg,
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: colors.border,
+    gap: spacing.xs,
+  },
+  cardPressed: { opacity: 0.7 },
+  cardHeader: { flexDirection: "row", alignItems: "center", justifyContent: "space-between" },
+  cardTitle: { ...typography.body, fontWeight: "600", flex: 1, marginRight: spacing.md },
+  cardSubtitle: { ...typography.caption, color: colors.textMuted },
+  sessionLabel: { ...typography.caption, color: colors.text, marginTop: spacing.xs },
+  sessionLabelDim: { ...typography.caption, color: colors.textDim, marginTop: spacing.xs },
+  pill: {
+    paddingHorizontal: spacing.sm,
+    paddingVertical: 2,
+    borderRadius: radius.pill,
+  },
+  pillLabel: { fontSize: 11, textTransform: "uppercase", fontWeight: "600" },
+});
diff --git a/packages/app/expo-env.d.ts b/packages/app/expo-env.d.ts
deleted file mode 100644
index e6394b2..0000000
--- a/packages/app/expo-env.d.ts
+++ /dev/null
@@ -1 +0,0 @@
-/// <reference types="expo/types" />
diff --git a/packages/app/metro.config.cjs b/packages/app/metro.config.cjs
new file mode 100644
index 0000000..a9c5008
--- /dev/null
+++ b/packages/app/metro.config.cjs
@@ -0,0 +1,20 @@
+const { getDefaultConfig } = require("expo/metro-config");
+const path = require("path");
+
+const projectRoot = __dirname;
+
+console.log("[metro.config.cjs] projectRoot=", projectRoot);
+
+const config = getDefaultConfig(projectRoot);
+
+config.watchFolders = [projectRoot];
+
+const monorepoRoot = path.resolve(projectRoot, "..", "..");
+config.resolver.nodeModulesPaths = [
+  path.resolve(projectRoot, "node_modules"),
+  path.resolve(monorepoRoot, "node_modules"),
+];
+
+console.log("[metro.config.cjs] nodeModulesPaths=", config.resolver.nodeModulesPaths);
+
+module.exports = config;
diff --git a/packages/app/package.json b/packages/app/package.json
index d055686..bae210e 100644
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -8,12 +8,13 @@
     "android": "expo run:android",
     "ios": "expo run:ios",
     "web": "expo start --web",
-    "typecheck": "tsgo --noEmit",
+    "typecheck": "tsgo -p tsconfig.typecheck.json --noEmit",
     "lint": "oxlint . --config ../../oxlint.jsonc"
   },
   "dependencies": {
     "@echohello/client": "workspace:*",
     "@echohello/protocol": "workspace:*",
+    "@react-native-async-storage/async-storage": "^3.1.1",
     "expo": "^54.0.18",
     "expo-router": "~6.0.13",
     "expo-status-bar": "~3.0.8",
diff --git a/packages/app/src/components/Button.tsx b/packages/app/src/components/Button.tsx
new file mode 100644
index 0000000..fd2d835
--- /dev/null
+++ b/packages/app/src/components/Button.tsx
@@ -0,0 +1,66 @@
+import { ActivityIndicator, Pressable, StyleSheet, Text, View } from "react-native";
+
+import { colors, radius, spacing, typography } from "../theme.js";
+
+interface Props {
+  label: string;
+  onPress: () => void;
+  disabled?: boolean;
+  loading?: boolean;
+  variant?: "primary" | "secondary" | "danger";
+}
+
+export function Button({ label, onPress, disabled, loading, variant = "primary" }: Props) {
+  const isDisabled = disabled || loading;
+  return (
+    <Pressable
+      onPress={isDisabled ? undefined : onPress}
+      style={({ pressed }) => [
+        styles.base,
+        variant === "primary" && styles.primary,
+        variant === "secondary" && styles.secondary,
+        variant === "danger" && styles.danger,
+        isDisabled && styles.disabled,
+        pressed && !isDisabled && styles.pressed,
+      ]}
+    >
+      {loading ? (
+        <ActivityIndicator color={colors.text} />
+      ) : (
+        <Text
+          style={[
+            styles.label,
+            variant === "secondary" && styles.labelSecondary,
+            variant === "danger" && styles.labelDanger,
+          ]}
+        >
+          {label}
+        </Text>
+      )}
+      <View />
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  base: {
+    minHeight: 44,
+    paddingHorizontal: spacing.lg,
+    borderRadius: radius.md,
+    alignItems: "center",
+    justifyContent: "center",
+    flexDirection: "row",
+  },
+  primary: { backgroundColor: colors.accent },
+  secondary: {
+    backgroundColor: colors.surfaceRaised,
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: colors.border,
+  },
+  danger: { backgroundColor: colors.danger },
+  disabled: { opacity: 0.4 },
+  pressed: { opacity: 0.8 },
+  label: { ...typography.body, fontWeight: "600" },
+  labelSecondary: { color: colors.text },
+  labelDanger: { color: "#1f1014" },
+});
diff --git a/packages/app/src/components/ConnectionBanner.tsx b/packages/app/src/components/ConnectionBanner.tsx
new file mode 100644
index 0000000..604ad19
--- /dev/null
+++ b/packages/app/src/components/ConnectionBanner.tsx
@@ -0,0 +1,59 @@
+import { StyleSheet, Text, View } from "react-native";
+
+import { useConnectionStore } from "../state/connection-store.js";
+import { colors, spacing, typography } from "../theme.js";
+
+export function ConnectionBanner() {
+  const status = useConnectionStore((s) => s.status);
+  const error = useConnectionStore((s) => s.error);
+  const serverId = useConnectionStore((s) => s.serverId);
+  const serverLabel = useConnectionStore((s) => s.serverLabel);
+  const reconnectAttempt = useConnectionStore((s) => s.reconnectAttempt);
+
+  const tone =
+    status === "connected"
+      ? { bg: "#0e2a22", fg: colors.success }
+      : status === "error" || status === "exhausted"
+        ? { bg: "#2a0e0e", fg: colors.danger }
+        : status === "reconnecting" || status === "connecting"
+          ? { bg: "#1a1a2a", fg: colors.warning }
+          : { bg: colors.surface, fg: colors.textMuted };
+
+  let label: string;
+  if (status === "connected") {
+    label = `Connected · ${serverLabel ?? serverId ?? "unknown"}`;
+  } else if (status === "connecting") {
+    label = "Connecting…";
+  } else if (status === "reconnecting") {
+    label = `Reconnecting (attempt ${reconnectAttempt})…`;
+  } else if (status === "exhausted") {
+    label = "Reconnect attempts exhausted";
+  } else if (status === "error") {
+    label = `Error — ${error ?? "unknown"}`;
+  } else if (status === "disconnected") {
+    label = "Disconnected";
+  } else {
+    label = "Not connected";
+  }
+
+  return (
+    <View style={[styles.bar, { backgroundColor: tone.bg }]}>
+      <View style={[styles.dot, { backgroundColor: tone.fg }]} />
+      <Text style={[styles.label, { color: tone.fg }]} numberOfLines={1}>
+        {label}
+      </Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  bar: {
+    flexDirection: "row",
+    alignItems: "center",
+    paddingHorizontal: spacing.lg,
+    paddingVertical: spacing.sm,
+    gap: spacing.sm,
+  },
+  dot: { width: 8, height: 8, borderRadius: 4 },
+  label: { ...typography.caption, flex: 1, fontFamily: "Menlo" },
+});
diff --git a/packages/app/src/components/TextField.tsx b/packages/app/src/components/TextField.tsx
new file mode 100644
index 0000000..2eecdcf
--- /dev/null
+++ b/packages/app/src/components/TextField.tsx
@@ -0,0 +1,45 @@
+import { StyleSheet, Text, TextInput, View, type TextInputProps } from "react-native";
+
+import { colors, radius, spacing, typography } from "../theme.js";
+
+interface Props extends TextInputProps {
+  label: string;
+  hint?: string;
+  error?: string;
+}
+
+export function TextField({ label, hint, error, style, ...rest }: Props) {
+  return (
+    <View style={styles.wrapper}>
+      <Text style={styles.label}>{label}</Text>
+      <TextInput
+        placeholderTextColor={colors.textDim}
+        selectionColor={colors.accent}
+        style={[styles.input, error ? styles.inputError : null, style]}
+        autoCapitalize="none"
+        autoCorrect={false}
+        {...rest}
+      />
+      {hint && !error ? <Text style={styles.hint}>{hint}</Text> : null}
+      {error ? <Text style={styles.error}>{error}</Text> : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  wrapper: { gap: spacing.xs },
+  label: { ...typography.caption, color: colors.textMuted, textTransform: "uppercase" },
+  input: {
+    backgroundColor: colors.surface,
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: colors.border,
+    borderRadius: radius.md,
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.md,
+    color: colors.text,
+    fontSize: 15,
+  },
+  inputError: { borderColor: colors.danger },
+  hint: { ...typography.caption, color: colors.textDim },
+  error: { ...typography.caption, color: colors.danger },
+});
diff --git a/packages/app/src/state/connection-store.ts b/packages/app/src/state/connection-store.ts
new file mode 100644
index 0000000..2c8ea3f
--- /dev/null
+++ b/packages/app/src/state/connection-store.ts
@@ -0,0 +1,216 @@
+import { create } from "zustand";
+import { SupaplaneClient } from "@echohello/client";
+import type {
+  AgentEvent,
+  HelloAckMessage,
+  SessionState,
+  WorkspaceState,
+} from "@echohello/protocol";
+
+import {
+  clearConnection,
+  loadSavedConnection,
+  loadTrustedServer,
+  saveConnection,
+  saveTrustedServer,
+  type SavedConnection,
+} from "../storage.js";
+
+export type ConnectionStatus =
+  | "idle"
+  | "connecting"
+  | "connected"
+  | "disconnected"
+  | "error"
+  | "reconnecting"
+  | "exhausted";
+
+interface ConnectionState {
+  status: ConnectionStatus;
+  error: string | null;
+  serverId: string | null;
+  serverLabel: string | null;
+  serverVersion: string | null;
+  fingerprint: string | null;
+  trusted: boolean;
+  client: SupaplaneClient | null;
+  endpoint: string | null;
+  reconnectAttempt: number;
+
+  workspaces: Map<string, WorkspaceState>;
+  sessions: Map<string, SessionState>;
+  events: Map<string, AgentEvent[]>;
+
+  saved: SavedConnection | null;
+
+  hydrate: () => Promise<void>;
+  connect: (input: { endpoint: string; label?: string }) => Promise<void>;
+  disconnect: () => void;
+  forget: () => Promise<void>;
+  recordEvent: (event: AgentEvent) => void;
+  clearEvents: (sessionId: string) => void;
+}
+
+const makeClientId = (): string =>
+  `mobile-${Math.random().toString(36).slice(2, 10)}${Date.now().toString(36)}`;
+
+export const useConnectionStore = create<ConnectionState>((set, get) => ({
+  status: "idle",
+  error: null,
+  serverId: null,
+  serverLabel: null,
+  serverVersion: null,
+  fingerprint: null,
+  trusted: false,
+  client: null,
+  endpoint: null,
+  reconnectAttempt: 0,
+  workspaces: new Map(),
+  sessions: new Map(),
+  events: new Map(),
+  saved: null,
+
+  async hydrate() {
+    const saved = await loadSavedConnection();
+    set({ saved });
+    if (saved) {
+      await get().connect({ endpoint: saved.endpoint, label: saved.label });
+    }
+  },
+
+  async connect({ endpoint, label }) {
+    const previous = get().client;
+    previous?.close();
+
+    set({
+      status: "connecting",
+      error: null,
+      endpoint,
+      serverId: null,
+      serverLabel: label ?? null,
+      serverVersion: null,
+      fingerprint: null,
+      trusted: false,
+      client: null,
+      workspaces: new Map(),
+      sessions: new Map(),
+      events: new Map(),
+      reconnectAttempt: 0,
+    });
+
+    const client = new SupaplaneClient({
+      endpoint,
+      clientId: makeClientId(),
+      clientType: "mobile",
+      capabilities: { reconnect: true, binaryFrames: false },
+    });
+
+    client.on("error", (err) => {
+      set({ status: "error", error: err.message });
+    });
+    client.on("reconnecting", ({ attempt }) => {
+      set({ status: "reconnecting", reconnectAttempt: attempt });
+    });
+    client.on("exhausted", () => {
+      set({ status: "exhausted", error: "Reconnect attempts exhausted" });
+    });
+
+    client.onWorkspaceState((workspace) => {
+      set((state) => {
+        const next = new Map(state.workspaces);
+        next.set(workspace.workspaceId, workspace);
+        return { workspaces: next };
+      });
+    });
+    client.onSessionState((session) => {
+      set((state) => {
+        const next = new Map(state.sessions);
+        next.set(session.sessionId, session);
+        return { sessions: next };
+      });
+    });
+
+    set({ client });
+
+    try {
+      const ack: HelloAckMessage = await client.connect();
+      const fingerprint = ack.pairing?.serverPublicKeyFingerprint ?? null;
+      const trusted = ack.pairing?.trusted ?? false;
+
+      const savedServer = fingerprint ? await loadTrustedServer() : null;
+      const isTrusted =
+        fingerprint !== null &&
+        savedServer !== null &&
+        savedServer.fingerprint === fingerprint;
+
+      if (fingerprint && isTrusted) {
+        await saveTrustedServer({ serverId: ack.serverId, fingerprint });
+      }
+
+      set({
+        status: "connected",
+        serverId: ack.serverId,
+        serverLabel: ack.daemon.label ?? label ?? null,
+        serverVersion: ack.serverVersion,
+        fingerprint,
+        trusted: trusted || isTrusted,
+      });
+
+      const saved: SavedConnection = { endpoint, label: label ?? "" };
+      await saveConnection(saved);
+      set({ saved });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      set({ status: "error", error: message, client: null });
+    }
+  },
+
+  disconnect() {
+    get().client?.close();
+    set({
+      status: "disconnected",
+      client: null,
+      workspaces: new Map(),
+      sessions: new Map(),
+      events: new Map(),
+    });
+  },
+
+  async forget() {
+    get().client?.close();
+    await clearConnection();
+    set({
+      status: "idle",
+      client: null,
+      endpoint: null,
+      serverId: null,
+      serverLabel: null,
+      serverVersion: null,
+      fingerprint: null,
+      trusted: false,
+      workspaces: new Map(),
+      sessions: new Map(),
+      events: new Map(),
+      saved: null,
+      error: null,
+    });
+  },
+
+  recordEvent(event) {
+    set((state) => {
+      const next = new Map(state.events);
+      const list = next.get(event.sessionId) ?? [];
+      next.set(event.sessionId, [...list, event]);
+      return { events: next };
+    });
+  },
+
+  clearEvents(sessionId) {
+    set((state) => {
+      if (!state.events.has(sessionId)) return state;
+      const next = new Map(state.events);
+      next.delete(sessionId);
+      return { events: next };
+    });
+  },
+}));
diff --git a/packages/app/src/storage.ts b/packages/app/src/storage.ts
new file mode 100644
index 0000000..1c06bbb
--- /dev/null
+++ b/packages/app/src/storage.ts
@@ -0,0 +1,52 @@
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+const ENDPOINT_KEY = "@supaplane/saved-endpoint";
+const LABEL_KEY = "@supaplane/saved-label";
+const SERVER_ID_KEY = "@supaplane/trusted-server-id";
+const FINGERPRINT_KEY = "@supaplane/trusted-fingerprint";
+
+export interface SavedConnection {
+  endpoint: string;
+  label: string;
+}
+
+export interface TrustedServer {
+  serverId: string;
+  fingerprint: string;
+}
+
+export async function loadSavedConnection(): Promise<SavedConnection | null> {
+  const [endpoint, label] = await Promise.all([
+    AsyncStorage.getItem(ENDPOINT_KEY),
+    AsyncStorage.getItem(LABEL_KEY),
+  ]);
+  if (!endpoint) return null;
+  return { endpoint, label: label ?? "" };
+}
+
+export async function saveConnection(conn: SavedConnection): Promise<void> {
+  await AsyncStorage.setMany({
+    [ENDPOINT_KEY]: conn.endpoint,
+    [LABEL_KEY]: conn.label,
+  });
+}
+
+export async function clearConnection(): Promise<void> {
+  await AsyncStorage.removeMany([ENDPOINT_KEY, LABEL_KEY]);
+}
+
+export async function loadTrustedServer(): Promise<TrustedServer | null> {
+  const [serverId, fingerprint] = await Promise.all([
+    AsyncStorage.getItem(SERVER_ID_KEY),
+    AsyncStorage.getItem(FINGERPRINT_KEY),
+  ]);
+  if (!serverId || !fingerprint) return null;
+  return { serverId, fingerprint };
+}
+
+export async function saveTrustedServer(server: TrustedServer): Promise<void> {
+  await AsyncStorage.setMany({
+    [SERVER_ID_KEY]: server.serverId,
+    [FINGERPRINT_KEY]: server.fingerprint,
+  });
+}
diff --git a/packages/app/src/theme.ts b/packages/app/src/theme.ts
new file mode 100644
index 0000000..5a35ae9
--- /dev/null
+++ b/packages/app/src/theme.ts
@@ -0,0 +1,41 @@
+export const colors = {
+  bg: "#0a0a0f",
+  surface: "#111118",
+  surfaceRaised: "#181822",
+  border: "#26263a",
+  text: "#e5e5e5",
+  textMuted: "#a3a3a3",
+  textDim: "#6b6b7b",
+  accent: "#7c5cff",
+  accentSoft: "#9d83ff",
+  success: "#34d399",
+  warning: "#fbbf24",
+  danger: "#f87171",
+  info: "#60a5fa",
+} as const;
+
+export const spacing = {
+  xs: 4,
+  sm: 8,
+  md: 12,
+  lg: 16,
+  xl: 24,
+  xxl: 32,
+} as const;
+
+export const radius = {
+  sm: 6,
+  md: 10,
+  lg: 14,
+  pill: 999,
+} as const;
+
+export const typography = {
+  display: { fontSize: 28, fontWeight: "700" as const, color: colors.text },
+  title: { fontSize: 20, fontWeight: "600" as const, color: colors.text },
+  body: { fontSize: 15, color: colors.text },
+  bodyMuted: { fontSize: 15, color: colors.textMuted },
+  caption: { fontSize: 12, color: colors.textMuted },
+  mono: { fontSize: 13, fontFamily: "Menlo", color: colors.text },
+  monoDim: { fontSize: 12, fontFamily: "Menlo", color: colors.textDim },
+} as const;
diff --git a/packages/app/tsconfig.json b/packages/app/tsconfig.json
index 759d19c..764ee23 100644
--- a/packages/app/tsconfig.json
+++ b/packages/app/tsconfig.json
@@ -4,13 +4,32 @@
     "module": "ESNext",
     "moduleResolution": "Bundler",
     "jsx": "react-jsx",
-    "lib": ["ES2022", "DOM"],
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
     "noEmit": true,
     "allowImportingTsExtensions": true,
     "composite": false,
-    "types": ["expo-router/types"]
+    "types": [
+      "expo-router/types"
+    ]
   },
-  "include": ["**/*.ts", "**/*.tsx", ".expo/types/**/*.ts", "expo-env.d.ts"],
-  "exclude": ["node_modules", "android", "ios"],
-  "references": [{ "path": "../protocol" }, { "path": "../client" }]
+  "include": [
+    "**/*.ts",
+    "**/*.tsx"
+  ],
+  "exclude": [
+    "node_modules",
+    "android",
+    "ios"
+  ],
+  "references": [
+    {
+      "path": "../protocol"
+    },
+    {
+      "path": "../client"
+    }
+  ]
 }
diff --git a/packages/app/tsconfig.typecheck.json b/packages/app/tsconfig.typecheck.json
new file mode 100644
index 0000000..fc8520e
--- /dev/null
+++ b/packages/app/tsconfig.typecheck.json
@@ -0,0 +1,3 @@
+{
+  "extends": "./tsconfig.json"
+}

From 3eb8b0dc8fdcf251f91c1345f4506c097d2b2e46 Mon Sep 17 00:00:00 2001
From: opencode <opencode@echohello.dev>
Date: Sat, 18 Jul 2026 00:12:06 +1000
Subject: [PATCH 2/4] chore(dev): wire desktop build + shift dev ports off
 6767/5173

Desktop build wiring:
- packages/desktop/tsconfig.build.json emits ESM to dist/
- packages/desktop/package.json: dev now runs tsc -> electron
- main.js (dist) replaces main.ts as the package entry, and
  preload.js resolves to the dist sibling
- @echohello/server and @echohello/protocol exports point at
  dist/ so Electron's Node can resolve them. Run
  'bun run build:server' (or 'bun run build') before
  'desktop dev'.

Dev port scheme (avoiding Paseo + Vite + Metro defaults):
- Daemon listenPort: 6767 -> 17687 (IANA-sparse range,
  visually echoes 6767)
- Vite port: 5173 -> 5179 (adjacent to Vite default so it
  reads as 'the Supaplane Vite port')
- vite.config.ts reads SUPAPLANE_DAEMON_PORT and VITE_PORT
  envs; defaults updated
- AGENTS.md + docs/development.md updated to reflect the
  new ports

Server hygiene:
- daemon-keypair.ts: replace require('node:crypto') with
  a top-level import so it builds cleanly to ESM

Co-authored-by: opencode <opencode@echohello.dev>
---
 AGENTS.md                             |  8 +++-
 docs/development.md                   |  4 +-
 packages/desktop/package.json         |  7 ++--
 packages/desktop/src/main.ts          | 11 +++++-
 packages/desktop/tsconfig.build.json  |  9 +++++
 packages/protocol/package.json        | 16 ++++----
 packages/server/package.json          |  6 +--
 packages/server/src/config.test.ts    |  2 +-
 packages/server/src/config.ts         |  8 ++--
 packages/server/src/daemon-keypair.ts |  6 +--
 packages/web/package.json             |  2 +-
 packages/web/vite.config.ts           | 56 +++++++++++++++------------
 12 files changed, 85 insertions(+), 50 deletions(-)
 create mode 100644 packages/desktop/tsconfig.build.json

diff --git a/AGENTS.md b/AGENTS.md
index e4cb0bf..b71b8f3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,6 +12,12 @@ The architectural decisions are documented in `docs/` — read them before makin
 
 If you need to know _why_ a decision was made, the build-research notes in the operator's Obsidian vault (`/Users/johnny/projects/github.com/johnnyhuy/one-obsidian/Notes/2026-06-26 - Spanner*.md`) contain the full reasoning.
 
+## Default dev ports
+
+- Daemon (HTTP + WS): `17687` — avoids Paseo (`6767`), HTTP (`8080`), Metro/Expo (`8081`).
+- Web renderer (Vite): `5179` — sits next to Vite's default `5173` so it's recognisable.
+- Override with `SUPAPLANE_LISTEN_PORT`, `SUPAPLANE_DAEMON_PORT`, `SUPAPLANE_WEB_PORT`, or `VITE_PORT` env vars.
+
 ## Build / dev commands
 
 ```bash
@@ -82,7 +88,7 @@ Supaplane ships agent skills in two locations, both using the Paseo/Supaplane `S
 
 | Location                         | Audience                                                                                                              | Installed via                                  | Tracked?                                      |
 | -------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------- |
-| `skills/<name>/SKILL.md` (root)  | **External** users — published for the world to install                                                               | `npx skills add echohello-dev/supaplane`         | ✅ committed                                  |
+| `skills/<name>/SKILL.md` (root)  | **External** users — published for the world to install                                                               | `npx skills add echohello-dev/supaplane`       | ✅ committed                                  |
 | `.agents/skills/<name>/SKILL.md` | **Internal** — auto-installed machine-local copies of third-party skills (e.g. `impeccable`, vendor-specific tooling) | Tool hooks (lefthook, opencode, claude, codex) | ✅ committed, with scoped `.gitignore` inside |
 
 The `.agents/skills/` convention keeps every skill in the same shape regardless of which tool installed it, so the same `SKILL.md` frontmatter (name + description) is machine-parseable everywhere. **Do not blanket-ignore `.agents/`** — only ignore caches/`node_modules`/dist inside the per-skill subdirs (the gitignore already does this scoped).
diff --git a/docs/development.md b/docs/development.md
index a7b9f4b..75a26eb 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -56,7 +56,7 @@ bun run knip         # dead-code detection
 # Run the daemon in dev mode (auto-reload on src/ changes)
 mise run dev:daemon
 
-# Run the web renderer (Vite HMR on http://127.0.0.1:5173)
+# Run the web renderer (Vite HMR on http://127.0.0.1:5179)
 mise run dev:web
 
 # Run the desktop shell (Electron + the running daemon)
@@ -66,7 +66,7 @@ mise run dev:desktop
 mise run dev:all
 ```
 
-The Vite dev server proxies `/api` and `/ws` to `http://127.0.0.1:6767` (the daemon). The desktop shell expects the daemon to be running separately.
+The Vite dev server proxies `/api` and `/ws` to `http://127.0.0.1:17687` (the daemon). The desktop shell expects the daemon to be running separately. Default ports avoid conflicts with Paseo (6767), Vite default (5173), Metro/Expo (8081, 19000), and other well-known dev tools.
 
 ## Day-to-day workflow
 
diff --git a/packages/desktop/package.json b/packages/desktop/package.json
index 34ae277..2afbf55 100644
--- a/packages/desktop/package.json
+++ b/packages/desktop/package.json
@@ -3,11 +3,12 @@
   "version": "0.0.0",
   "private": true,
   "type": "module",
-  "main": "./src/main.ts",
+  "main": "./dist/main.js",
   "scripts": {
-    "dev": "electron .",
+    "build:electron": "tsc -p tsconfig.build.json",
+    "dev": "bun run build:electron && electron .",
     "build:web-assets": "echo \"(placeholder) bundle @echohello/web first\"",
-    "build": "tsc -p tsconfig.typecheck.json --noEmit",
+    "build": "bun run build:electron && tsc -p tsconfig.typecheck.json --noEmit",
     "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
     "lint": "oxlint src --config ../../oxlint.jsonc"
   },
diff --git a/packages/desktop/src/main.ts b/packages/desktop/src/main.ts
index 43e46c8..2ab8e70 100644
--- a/packages/desktop/src/main.ts
+++ b/packages/desktop/src/main.ts
@@ -13,8 +13,16 @@ let mainWindow: BrowserWindow | null = null;
 async function ensureDaemon(): Promise<DaemonHandle> {
   if (daemonHandle) return daemonHandle;
   log.info("starting embedded Supaplane daemon");
+  const configOverrides: { listenPort?: number; listenHost?: string } = {};
+  const envPort = process.env.SUPAPLANE_LISTEN_PORT;
+  if (envPort && !Number.isNaN(Number.parseInt(envPort, 10))) {
+    configOverrides.listenPort = Number.parseInt(envPort, 10);
+  }
+  const envHost = process.env.SUPAPLANE_LISTEN_HOST;
+  if (envHost) configOverrides.listenHost = envHost;
   daemonHandle = await startDaemon({
     supaplaneHome: path.join(app.getPath("userData"), "supaplane-home"),
+    ...(Object.keys(configOverrides).length > 0 ? { config: configOverrides } : {}),
   });
   return daemonHandle;
 }
@@ -39,7 +47,8 @@ function createMainWindow(): BrowserWindow {
   win.once("ready-to-show", () => win.show());
 
   if (isDev) {
-    void win.loadURL("http://127.0.0.1:5173");
+    const webPort = process.env.SUPAPLANE_WEB_PORT ?? "5179";
+    void win.loadURL(`http://127.0.0.1:${webPort}`);
     win.webContents.openDevTools({ mode: "detach" });
   } else {
     void win.loadFile(path.join(__dirname, "..", "..", "web", "dist", "index.html"));
diff --git a/packages/desktop/tsconfig.build.json b/packages/desktop/tsconfig.build.json
new file mode 100644
index 0000000..94ff2a0
--- /dev/null
+++ b/packages/desktop/tsconfig.build.json
@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"]
+}
diff --git a/packages/protocol/package.json b/packages/protocol/package.json
index 79ef7dd..821aef5 100644
--- a/packages/protocol/package.json
+++ b/packages/protocol/package.json
@@ -3,15 +3,15 @@
   "version": "0.0.0",
   "private": true,
   "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./connection-offer": "./src/connection-offer.ts",
-    "./messages": "./src/messages.ts",
-    "./provider-manifest": "./src/provider-manifest.ts",
-    "./errors": "./src/errors.ts",
-    "./daemon-endpoints": "./src/daemon-endpoints.ts"
+    ".": "./dist/index.js",
+    "./connection-offer": "./dist/connection-offer.js",
+    "./messages": "./dist/messages.js",
+    "./provider-manifest": "./dist/provider-manifest.js",
+    "./errors": "./dist/errors.js",
+    "./daemon-endpoints": "./dist/daemon-endpoints.js"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
diff --git a/packages/server/package.json b/packages/server/package.json
index 28eb5f3..34ff1e4 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -3,10 +3,10 @@
   "version": "0.0.0",
   "private": true,
   "type": "module",
-  "main": "./src/index.ts",
+  "main": "./dist/index.js",
   "exports": {
-    ".": "./src/index.ts",
-    "./exports": "./src/server/exports.ts"
+    ".": "./dist/index.js",
+    "./exports": "./dist/server/exports.js"
   },
   "publishConfig": {
     "exports": {
diff --git a/packages/server/src/config.test.ts b/packages/server/src/config.test.ts
index 2d59cca..266d35d 100644
--- a/packages/server/src/config.test.ts
+++ b/packages/server/src/config.test.ts
@@ -5,7 +5,7 @@ describe("loadDaemonConfig", () => {
   it("returns defaults when no env vars are set", () => {
     const cfg = loadDaemonConfig({});
     expect(cfg.listenHost).toBe("127.0.0.1");
-    expect(cfg.listenPort).toBe(6767);
+    expect(cfg.listenPort).toBe(17687);
     expect(cfg.logLevel).toBe("info");
     expect(cfg.relayEnabled).toBe(false);
     expect(cfg.appBaseUrl).toBe("https://app.supaplane.com");
diff --git a/packages/server/src/config.ts b/packages/server/src/config.ts
index c58a1ac..1695c1d 100644
--- a/packages/server/src/config.ts
+++ b/packages/server/src/config.ts
@@ -11,8 +11,8 @@ import { z } from "zod";
 export const DaemonConfigSchema = z.object({
   /** Bind host for the WebSocket + HTTP listener. Default `127.0.0.1` (no LAN). */
   listenHost: z.string().default("127.0.0.1"),
-  /** Bind port. Default 6767 (matches Paseo). */
-  listenPort: z.number().int().positive().default(6767),
+  /** Bind port. Default 17687 (avoids Paseo on 6767 and other well-known dev ports). */
+  listenPort: z.number().int().positive().default(17687),
   /** Log level. */
   logLevel: z.enum(["trace", "debug", "info", "warn", "error", "fatal"]).default("info"),
   /** Path to the daemon log file (rotated by `rotating-file-stream` if set). */
@@ -38,7 +38,9 @@ export type DaemonConfig = z.infer<typeof DaemonConfigSchema>;
 export function loadDaemonConfig(env: NodeJS.ProcessEnv = process.env): DaemonConfig {
   const raw = {
     listenHost: env.SUPAPLANE_LISTEN_HOST,
-    listenPort: env.SUPAPLANE_LISTEN_PORT ? Number.parseInt(env.SUPAPLANE_LISTEN_PORT, 10) : undefined,
+    listenPort: env.SUPAPLANE_LISTEN_PORT
+      ? Number.parseInt(env.SUPAPLANE_LISTEN_PORT, 10)
+      : undefined,
     logLevel: env.SUPAPLANE_LOG_LEVEL,
     logFile: env.SUPAPLANE_LOG_FILE,
     pairingQr: env.SUPAPLANE_PAIRING_QR
diff --git a/packages/server/src/daemon-keypair.ts b/packages/server/src/daemon-keypair.ts
index 0890eaa..1bcca91 100644
--- a/packages/server/src/daemon-keypair.ts
+++ b/packages/server/src/daemon-keypair.ts
@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 
 /**
  * NaCl box (Curve25519 ECDH + XSalsa20-Poly1305) keypair for the daemon's
@@ -30,8 +30,8 @@ export interface DaemonKeyPair {
 }
 
 function placeholderKeyPair(): DaemonKeyPair {
-  const seed = require("node:crypto").randomBytes(32);
-  const publicKey = require("node:crypto").createHash("sha256").update(seed).digest();
+  const seed = randomBytes(32);
+  const publicKey = createHash("sha256").update(seed).digest();
   const secretKey = seed;
   const publicKeyB64 = publicKey.toString("base64");
   const secretKeyB64 = secretKey.toString("base64");
diff --git a/packages/web/package.json b/packages/web/package.json
index f25c831..217117b 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -7,7 +7,7 @@
   "scripts": {
     "dev": "vite",
     "build": "tsc -p tsconfig.typecheck.json --noEmit && vite build",
-    "preview": "vite preview --port 5173",
+    "preview": "vite preview --port 5179",
     "typecheck": "tsgo -p tsconfig.typecheck.json --noEmit",
     "lint": "oxlint src --config ../../oxlint.jsonc"
   },
diff --git a/packages/web/vite.config.ts b/packages/web/vite.config.ts
index 474e47e..49babda 100644
--- a/packages/web/vite.config.ts
+++ b/packages/web/vite.config.ts
@@ -1,29 +1,37 @@
-import { defineConfig } from "vite";
+import { defineConfig, loadEnv } from "vite";
 import react from "@vitejs/plugin-react";
 
-export default defineConfig({
-  root: "src",
-  base: "./",
-  plugins: [react()],
-  server: {
-    port: 5173,
-    strictPort: true,
-    host: "127.0.0.1",
-    proxy: {
-      "/api": {
-        target: "http://127.0.0.1:6767",
-        changeOrigin: true,
-      },
-      "/ws": {
-        target: "ws://127.0.0.1:6767",
-        ws: true,
-        changeOrigin: true,
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), "");
+  const daemonHost = env.SUPAPLANE_DAEMON_HOST ?? "127.0.0.1";
+  const daemonPort = env.SUPAPLANE_DAEMON_PORT ?? "17687";
+  const daemonHttp = `http://${daemonHost}:${daemonPort}`;
+  const daemonWs = `ws://${daemonHost}:${daemonPort}`;
+
+  return {
+    root: "src",
+    base: "./",
+    plugins: [react()],
+    server: {
+      port: Number(env.VITE_PORT ?? 5179),
+      strictPort: true,
+      host: "127.0.0.1",
+      proxy: {
+        "/api": {
+          target: daemonHttp,
+          changeOrigin: true,
+        },
+        "/ws": {
+          target: daemonWs,
+          ws: true,
+          changeOrigin: true,
+        },
       },
     },
-  },
-  build: {
-    outDir: "../dist",
-    emptyOutDir: true,
-    sourcemap: true,
-  },
+    build: {
+      outDir: "../dist",
+      emptyOutDir: true,
+      sourcemap: true,
+    },
+  };
 });

From 4ff951686bccbd2a59320fa1e3133820b502d221 Mon Sep 17 00:00:00 2001
From: Johnny Huynh <27847622+johnnyhuy@users.noreply.github.com>
Date: Mon, 20 Jul 2026 17:29:49 +1000
Subject: [PATCH 3/4] fix(ci): seed release-please manifest so the action stops
 failing

release-please-action@v4 requires .release-please-manifest.json (or the
deprecated release-please-config.json versions field) on first run.
Without it the action exits non-zero on every push to main, masking
real failures with a 'Missing required manifest versions' error.

Seed it at "0.0.0" so the next conventional commit produces a real
release PR.

Co-authored-by: opencode-agent <hello@sst.dev>
---
 .release-please-manifest.json | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 .release-please-manifest.json

diff --git a/.release-please-manifest.json b/.release-please-manifest.json
new file mode 100644
index 0000000..e18ee07
--- /dev/null
+++ b/.release-please-manifest.json
@@ -0,0 +1,3 @@
+{
+  ".": "0.0.0"
+}

From 0295cfde166689c4896c46a2ef5caf7089a742af Mon Sep 17 00:00:00 2001
From: Johnny Huynh <27847622+johnnyhuy@users.noreply.github.com>
Date: Mon, 20 Jul 2026 22:07:47 +1000
Subject: [PATCH 4/4] chore(release): drop release-please, use calver only
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

release-please bumped straight from 0.0.0 to 1.0.0 on the first
conventional-commit push to main (release-please seeds 1.0.0 on the
debut release). That's the wrong starting line for Supaplane — we want
calver tags on every push to main, not semver release PRs.

Removed:
- .github/workflows/release-please.yml
- release-please-config.json
- .release-please-manifest.json

Closed release-please's first PR (#6) and deleted its branch
(release-please--branches--main--components--supaplane) so the action
has nothing to point at when its trigger fires.

Kept calver-release.yml and the 2026.07.20 / -2 / -3 tags that it
produced. Updated README.md and AGENTS.md to reflect that calver is now
the sole release surface.

Co-authored-by: opencode-agent <hello@sst.dev>
---
 .github/workflows/release-please.yml | 23 -----------------------
 .release-please-manifest.json        |  3 ---
 AGENTS.md                            |  2 +-
 README.md                            |  2 +-
 release-please-config.json           | 13 -------------
 5 files changed, 2 insertions(+), 41 deletions(-)
 delete mode 100644 .github/workflows/release-please.yml
 delete mode 100644 .release-please-manifest.json
 delete mode 100644 release-please-config.json

diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
deleted file mode 100644
index 9fa1f9c..0000000
--- a/.github/workflows/release-please.yml
+++ /dev/null
@@ -1,23 +0,0 @@
-name: release-please
-
-on:
-  push:
-    branches: [main]
-
-permissions:
-  contents: write
-  pull-requests: write
-
-jobs:
-  release-please:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: googleapis/release-please-action@v4
-        id: release
-        with:
-          config-file: release-please-config.json
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: build workspace packages after release PR opens
-        if: ${{ steps.release.outputs.release-created }}
-        run: bun install --frozen-lockfile
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
deleted file mode 100644
index e18ee07..0000000
--- a/.release-please-manifest.json
+++ /dev/null
@@ -1,3 +0,0 @@
-{
-  ".": "0.0.0"
-}
diff --git a/AGENTS.md b/AGENTS.md
index b71b8f3..ea1181b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -78,7 +78,7 @@ Never import backwards — if you find yourself needing to import `@echohello/we
 
 ## Git
 
-- Branch from `main`. Conventional commits (release-please manages versions).
+- Branch from `main`. Conventional commits for readability (calver tags are stamped on push to main, not derived from commit messages).
 - PRs target `main`. CI runs typecheck + lint + test.
 - Never commit `.env`, `dist/`, `node_modules/`, `*.log`, `daemon-keypair.json`, `server-id`.
 
diff --git a/README.md b/README.md
index 42ae7b2..334c9cb 100644
--- a/README.md
+++ b/README.md
@@ -91,7 +91,7 @@ See [docs/providers.md](docs/providers.md).
 
 ## Project status
 
-Alpha scaffold. Daemon, protocol, client, and surface stubs are in place. CI and release-please are follow-ups. Architecture decisions live in `docs/` and the build-research notes that fed this repo.
+Alpha scaffold. Daemon, protocol, client, and surface stubs are in place. CI runs on every PR; calver `YYYY.MM.DD[-N]` release tags are stamped on every push to main. Architecture decisions live in `docs/` and the build-research notes that fed this repo.
 
 ## License
 
diff --git a/release-please-config.json b/release-please-config.json
deleted file mode 100644
index 934059a..0000000
--- a/release-please-config.json
+++ /dev/null
@@ -1,13 +0,0 @@
-{
-  "packages": {
-    ".": {
-      "release-type": "node",
-      "package-name": "supaplane",
-      "changelog-path": "CHANGELOG.md",
-      "bump-minor-pre-major": true,
-      "bump-patch-for-minor-pre-major": true,
-      "draft": false,
-      "include-component-in-tag": false
-    }
-  }
-}