clawdex-mobile 1.3.2 → 2.0.0

package/apps/mobile/src/screens/PrivacyScreen.tsx

@@ -4,7 +4,6 @@ import {
   Alert,
   Linking,
   Pressable,
-  SafeAreaView,
   ScrollView,
   StyleSheet,
   Text,
@@ -12,6 +11,7 @@ import {
 } from 'react-native';
 import { BlurView } from 'expo-blur';
 import { LinearGradient } from 'expo-linear-gradient';
+import { SafeAreaView } from 'react-native-safe-area-context';
 
 import { colors, radius, spacing, typography } from '../theme';
 

package/apps/mobile/src/screens/SettingsScreen.tsx

@@ -6,12 +6,12 @@ import {
   ActivityIndicator,
   Modal,
   Pressable,
-  SafeAreaView,
   ScrollView,
   StyleSheet,
   Text,
   View,
 } from 'react-native';
+import { SafeAreaView } from 'react-native-safe-area-context';
 
 import type { HostBridgeApiClient } from '../api/client';
 import type { ApprovalMode, ModelOption, ReasoningEffort } from '../api/types';
@@ -30,6 +30,8 @@ interface SettingsScreenProps {
     effort: ReasoningEffort | null
   ) => void;
   onApprovalModeChange?: (mode: ApprovalMode) => void;
+  onEditBridgeUrl?: () => void;
+  onResetOnboarding?: () => void;
   onOpenDrawer: () => void;
   onOpenPrivacy: () => void;
   onOpenTerms: () => void;
@@ -44,6 +46,8 @@ export function SettingsScreen({
   approvalMode,
   onDefaultModelSettingsChange,
   onApprovalModeChange,
+  onEditBridgeUrl,
+  onResetOnboarding,
   onOpenDrawer,
   onOpenPrivacy,
   onOpenTerms,
@@ -301,6 +305,26 @@ export function SettingsScreen({
             <Text selectable style={styles.valueText}>
               {bridgeUrl}
             </Text>
+            <Pressable
+              onPress={onEditBridgeUrl}
+              style={({ pressed }) => [
+                styles.bridgeEditBtn,
+                pressed && styles.bridgeEditBtnPressed,
+              ]}
+            >
+              <Ionicons name="swap-horizontal-outline" size={15} color={colors.textPrimary} />
+              <Text style={styles.bridgeEditBtnText}>Change bridge URL</Text>
+            </Pressable>
+            <Pressable
+              onPress={onResetOnboarding}
+              style={({ pressed }) => [
+                styles.bridgeResetBtn,
+                pressed && styles.bridgeResetBtnPressed,
+              ]}
+            >
+              <Ionicons name="refresh-circle-outline" size={15} color={colors.error} />
+              <Text style={styles.bridgeResetBtnText}>Reset onboarding</Text>
+            </Pressable>
           </BlurView>
 
           <Text style={[styles.sectionLabel, styles.sectionLabelGap]}>Health</Text>
@@ -569,6 +593,46 @@ const styles = StyleSheet.create({
     paddingVertical: spacing.md,
     fontSize: 14,
   },
+  bridgeEditBtn: {
+    marginBottom: spacing.md,
+    borderRadius: radius.md,
+    borderWidth: 1,
+    borderColor: colors.border,
+    backgroundColor: colors.bgMain,
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: spacing.xs,
+    paddingVertical: spacing.sm,
+  },
+  bridgeEditBtnPressed: {
+    opacity: 0.82,
+  },
+  bridgeEditBtnText: {
+    ...typography.caption,
+    color: colors.textPrimary,
+    fontWeight: '600',
+  },
+  bridgeResetBtn: {
+    marginBottom: spacing.md,
+    borderRadius: radius.md,
+    borderWidth: 1,
+    borderColor: colors.error,
+    backgroundColor: 'rgba(239, 68, 68, 0.08)',
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: spacing.xs,
+    paddingVertical: spacing.sm,
+  },
+  bridgeResetBtnPressed: {
+    opacity: 0.82,
+  },
+  bridgeResetBtnText: {
+    ...typography.caption,
+    color: colors.error,
+    fontWeight: '700',
+  },
   row: {
     flexDirection: 'row',
     justifyContent: 'space-between',

package/apps/mobile/src/screens/TerminalScreen.tsx

@@ -5,13 +5,13 @@ import {
   KeyboardAvoidingView,
   Platform,
   Pressable,
-  SafeAreaView,
   ScrollView,
   StyleSheet,
   Text,
   TextInput,
   View,
 } from 'react-native';
+import { SafeAreaView } from 'react-native-safe-area-context';
 
 import type { HostBridgeApiClient } from '../api/client';
 import type { HostBridgeWsClient } from '../api/ws';

package/apps/mobile/src/screens/TermsScreen.tsx

@@ -4,7 +4,6 @@ import {
   Alert,
   Linking,
   Pressable,
-  SafeAreaView,
   ScrollView,
   StyleSheet,
   Text,
@@ -12,6 +11,7 @@ import {
 } from 'react-native';
 import { BlurView } from 'expo-blur';
 import { LinearGradient } from 'expo-linear-gradient';
+import { SafeAreaView } from 'react-native-safe-area-context';
 
 import { colors, radius, spacing, typography } from '../theme';
 

package/docs/app-review-notes.md

@@ -57,12 +57,17 @@ BRIDGE_CORS_ORIGINS=http://localhost:19006,http://localhost:8081
 - In `apps/mobile/.env`, set:
 
 ```env
-EXPO_PUBLIC_HOST_BRIDGE_URL=http://<mac-lan-ip>:8787
 EXPO_PUBLIC_HOST_BRIDGE_TOKEN=<review-token>
 EXPO_PUBLIC_PRIVACY_POLICY_URL=https://<your-policy-url>
 EXPO_PUBLIC_TERMS_OF_SERVICE_URL=https://<your-terms-url>
 ```
 
+- In app onboarding, enter:
+
+```text
+http://<mac-lan-ip>:8787
+```
+
 ## Reviewer Walkthrough
 
 1. Launch app.
@@ -76,7 +81,7 @@ EXPO_PUBLIC_TERMS_OF_SERVICE_URL=https://<your-terms-url>
 ## Security And Privacy Notes For Review
 
 - Bridge auth token is required by default.
-- WebSocket auth uses Authorization header (query-token fallback is opt-in only).
+- WebSocket auth uses Authorization headers and supports query-token fallback for Android compatibility.
 - Bridge can be run localhost-only; LAN mode is user-configured.
 - Terminal commands are constrained by server-side allowlist and can be fully disabled.
 - Requested command working directory is constrained within configured bridge root.

package/docs/eas-builds.md

@@ -0,0 +1,91 @@
+# EAS Builds and Distribution
+
+Use this guide for standalone app builds/distribution.
+
+## Where To Run EAS Commands
+
+Run EAS commands from `apps/mobile`.
+
+Why:
+
+- Expo app config is in `apps/mobile/app.json`
+- EAS config is in `apps/mobile/eas.json`
+
+```bash
+cd apps/mobile
+```
+
+You can also run from repo root with workspace scoping:
+
+```bash
+npm exec --workspace apps/mobile -- eas <command>
+```
+
+## Prerequisites
+
+- `eas-cli` installed (`npm install -g eas-cli`)
+- Logged in (`eas login`)
+- Expo project linked (`eas project:info`)
+
+## Build Profiles
+
+Current profiles in `apps/mobile/eas.json`:
+
+- `development` (dev client, internal distribution)
+- `preview` (internal distribution)
+- `production` (store/prod, auto-increment)
+
+## Common Build Commands
+
+From `apps/mobile`:
+
+```bash
+# Internal/dev-client builds
+eas build --platform ios --profile development
+eas build --platform android --profile development
+
+# Internal preview builds
+eas build --platform ios --profile preview
+eas build --platform android --profile preview
+
+# Production builds
+eas build --platform ios --profile production
+eas build --platform android --profile production
+
+# Both platforms
+eas build --platform all --profile preview
+```
+
+Track builds:
+
+```bash
+eas build:list --limit 10
+eas build:view <BUILD_ID>
+```
+
+## Submit To Stores
+
+```bash
+eas submit --platform ios --latest --profile production
+eas submit --platform android --latest --profile production
+```
+
+## Local Native Build Option (No EAS Cloud)
+
+If you want local native builds instead:
+
+```bash
+npx expo run:ios
+npx expo run:android
+```
+
+For iOS local device/signed builds, Apple signing/tooling is still required.
+
+## iOS Distribution Reality
+
+Without a public App Store release, iOS distribution still requires Apple provisioning paths:
+
+1. Internal/dev provisioning with device allowlist
+2. TestFlight private testing
+
+Cloud builds are possible without public App Store listing, but signing/provisioning requirements still apply.

package/docs/realtime-streaming-limitations.md

@@ -75,3 +75,87 @@ To get strict realtime parity across CLI and mobile, move to a single live event
 2. Make clients attach to the exact same running app-server stream/session boundary.
 
 Without this architectural change, the hybrid model remains the pragmatic and low-risk approach.
+
+## Incident Note: February 28, 2026 Live-Sync Regression
+
+### Symptom
+Mobile chat showed persisted messages, but did not show live activity/reasoning updates (`codex/event/*`, `thread/status/changed`) for CLI-origin turns.
+
+### Root Cause
+Rust bridge rollout discovery scheduler used a modulo condition that could never become true when the discovery interval was `1`.
+
+- Previous behavior: discovery did not run for that interval value.
+- Effect: rollout files were not tracked, so no CLI live-tail notifications were emitted.
+
+### Fix Applied
+Live-sync discovery scheduling was hardened so it is valid for all interval values and always runs on first tick.
+
+Operational result:
+
+1. Rollout files are discovered consistently.
+2. CLI-origin event lines are tailed and converted into bridge notifications.
+3. Mobile receives activity/reasoning status in realtime again.
+
+## Optimization Backlog (Live-Sync Observability + Reliability)
+
+### 1) Add `bridge/liveSync/status` RPC (recommended next)
+
+Goal: make rollout tailing state visible from mobile/Postman without guessing.
+
+Suggested response payload:
+
+1. Sessions root currently in use (`CODEX_HOME` resolved path).
+2. Discovery config (`pollIntervalMs`, `discoveryIntervalTicks`, `maxTrackedFiles`).
+3. Tracked files list:
+   - file path
+   - thread id
+   - originator
+   - include/exclude flag
+   - include/exclude reason
+   - current offset
+   - last seen timestamp
+4. Summary counters:
+   - files discovered
+   - files included
+   - lines parsed
+   - lines dropped (invalid JSON / filtered / duplicate)
+   - notifications emitted by method bucket
+5. Last error (if any) in discovery/poll loop.
+
+Why this helps:
+
+1. Explains "why no live updates" immediately.
+2. Reduces debugging time for CLI vs mobile parity issues.
+3. Enables lightweight health checks and QA verification.
+
+### 2) Add discovery/poll loop metrics
+
+Expose counters for:
+
+1. discovery runs
+2. poll runs
+3. per-file parse errors
+4. event mapping misses
+5. replay buffer writes/drops
+
+These can be returned by the status RPC and optionally logged to stderr in dev mode.
+
+### 3) Add dedup + mapping diagnostics for dropped events
+
+Track bounded recent reasons for dropped lines:
+
+1. duplicate hash
+2. unsupported rollout record type
+3. missing thread id
+4. originator filtered
+
+This will clarify whether events are not emitted due to filtering or malformed source lines.
+
+### 4) Add a short runbook for operators
+
+When live updates are missing, check in this order:
+
+1. `bridge/events/replay` contains recent `codex/event/*` or not.
+2. `bridge/liveSync/status` include/exclude reason for newest rollout file.
+3. newest rollout file `session_meta.originator` and resolved thread id fields.
+4. mobile selected thread id matches emitted thread id.

package/docs/setup-and-operations.md

@@ -0,0 +1,239 @@
+# Setup and Operations
+
+This guide is the detailed companion to the top-level `README.md`.
+
+## Onboarding Output Cues
+
+After `clawdex init`, expected sequence:
+
+1. Bridge health passes (`Bridge health check passed.`)
+2. Expo starts (`Starting Expo (mobile) in background...`)
+3. You may briefly see a spinner (`Waiting for Expo output - ...`)
+4. Expo output begins (`expo start --host lan`, QR block, `Metro waiting on exp://...`)
+5. Press Enter to detach onboarding while Expo + bridge keep running
+
+## Manual Secure Setup (No Wizard)
+
+### 1) Install dependencies
+
+```bash
+npm install
+```
+
+### 2) Generate secure runtime config
+
+```bash
+npm run secure:setup
+```
+
+Creates/updates:
+
+- `.env.secure` (bridge runtime config + token)
+- `apps/mobile/.env` (mobile token + optional runtime knobs)
+
+### 3) Start bridge
+
+```bash
+npm run secure:bridge
+```
+
+### 4) Start Expo
+
+```bash
+npm run mobile
+```
+
+`npm run mobile` uses `scripts/start-expo.sh`, which sets `REACT_NATIVE_PACKAGER_HOSTNAME` from your secure config so QR resolution is predictable.
+
+On first app launch, onboarding will ask for your bridge URL (for example `http://100.x.y.z:8787` or `http://192.168.x.y:8787`). This URL is stored on-device and can be changed later in Settings.
+
+## Advanced Knobs
+
+Optional environment variables:
+
+- `CLAWDEX_SETUP_VERBOSE=true` — show full installer output
+- `BRIDGE_HEALTH_WAIT_SECS=300` — max wait for bridge `/health`
+- `EXPO_OUTPUT_WAIT_SECS=90` — spinner timeout before streaming Expo logs
+- `EXPO_AUTO_REPAIR=true` — auto-repair React Native runtime on `npm run mobile`
+- `EXPO_CLEAR_CACHE=true` — force `expo start --clear` via `npm run mobile`
+
+## Teardown / Cleanup
+
+```bash
+npm run teardown
+```
+
+Can:
+
+- stop Expo + bridge
+- remove generated artifacts (`.env.secure`, `.bridge.log`, `.expo.log`, pid files)
+- optionally reset `apps/mobile/.env` from `.env.example`
+- optionally run `tailscale down`
+
+Non-interactive mode:
+
+```bash
+npm run teardown -- --yes
+```
+
+## Environment Reference
+
+### Bridge runtime (`.env.secure`, generated)
+
+| Variable | Purpose |
+|---|---|
+| `BRIDGE_HOST` | bind host for rust bridge |
+| `BRIDGE_PORT` | bridge port (default `8787`) |
+| `BRIDGE_AUTH_TOKEN` | required auth token |
+| `BRIDGE_ALLOW_QUERY_TOKEN_AUTH` | query-token auth fallback |
+| `CODEX_CLI_BIN` | codex executable |
+| `BRIDGE_WORKDIR` | absolute working directory for terminal/git |
+| `BRIDGE_ALLOW_OUTSIDE_ROOT_CWD` | allow terminal/git `cwd` outside `BRIDGE_WORKDIR` |
+
+### Mobile runtime (`apps/mobile/.env`, generated/updated)
+
+| Variable | Purpose |
+|---|---|
+| `EXPO_PUBLIC_HOST_BRIDGE_TOKEN` | token sent by mobile client |
+| `EXPO_PUBLIC_ALLOW_QUERY_TOKEN_AUTH` | query-token behavior for WebSocket auth fallback |
+| `EXPO_PUBLIC_ALLOW_INSECURE_REMOTE_BRIDGE` | suppress insecure-HTTP warning |
+| `EXPO_PUBLIC_PRIVACY_POLICY_URL` | in-app Privacy link |
+| `EXPO_PUBLIC_TERMS_OF_SERVICE_URL` | in-app Terms link |
+
+## Production Readiness Checklist
+
+- Keep bridge network-private only (Tailscale/private LAN/VPN + host firewall)
+- Require `BRIDGE_AUTH_TOKEN`
+- Keep `BRIDGE_ALLOW_QUERY_TOKEN_AUTH=true` only on private networks (required for Android WS auth fallback)
+- Do not set `BRIDGE_ALLOW_INSECURE_NO_AUTH=true` outside local debugging
+- Scope `BRIDGE_WORKDIR` to minimal required root
+- Use strict default approvals on mobile
+- Treat `Session`/`Allow similar` approval actions as privileged
+- Run bridge under a supervisor with restart policy
+- Rotate bridge tokens periodically and on device loss
+- Keep `codex`, Node deps, Expo SDK, and OS patches updated
+
+## Verifying Setup
+
+### Bridge health
+
+```bash
+source .env.secure
+curl "http://$BRIDGE_HOST:$BRIDGE_PORT/health"
+```
+
+Expected response contains `"status":"ok"`.
+
+### In-app smoke test
+
+1. Open app and verify Settings reports bridge connected
+2. Set `Start Directory` from sidebar (optional)
+3. Create a chat and send a prompt
+4. Switch to Plan mode and send prompt that triggers clarifying options
+5. Verify clarification flow can submit
+6. Open Git from header and verify status/diff/commit/push behavior
+7. Test attachment menu (`+`) with workspace path + phone file/image
+8. Run long task and verify stop button interrupts run and transcript logs stop
+
+## Chat Controls (Workspace, Model, Mode, Approvals)
+
+### Choosing Start Directory
+
+1. Open sidebar
+2. Under `Start Directory`, pick:
+   - `Bridge default workspace`, or
+   - a discovered workspace path from existing chats
+
+Behavior:
+
+- Applies to new chats
+- Existing chats retain their own workspace unless changed
+
+### Model and Slash Commands
+
+Supported mobile slash commands:
+
+- `/help`
+- `/new`
+- `/model [model-id]`
+- `/plan [on|off|prompt]`
+- `/status`
+- `/rename <new-name>`
+- `/compact`
+- `/review`
+- `/fork`
+- `/diff`
+
+### Plan Mode and Clarifications
+
+- Plan mode is sent through `turn/start` via structured `collaborationMode`
+- App can auto-switch to plan mode on plan events or when server requests it
+- Structured clarifications open a dedicated modal
+- Numbered plain-text options are rendered as tappable fallback choices
+
+### Approval UX
+
+Approval banner actions:
+
+- `Deny`
+- `Allow once`
+- `Session`
+- `Allow similar` (when available)
+
+Approval events are surfaced via `bridge/approval.requested` and `bridge/approval.resolved`.
+
+## NPM Release Automation
+
+Workflow: `.github/workflows/npm-release.yml`
+
+Required repo secret:
+
+- `NPM_TOKEN`
+
+Typical release flow (from `main`):
+
+```bash
+npm version patch
+git push origin main --follow-tags
+```
+
+Automation verifies tag/version consistency and publishes to npm.
+
+## API Summary (Rust Bridge)
+
+### Endpoints
+
+- `GET /health`
+- `GET /rpc` (WebSocket JSON-RPC)
+
+### Forwarded methods
+
+- `thread/*`
+- `turn/*` (includes `turn/interrupt`)
+- `review/start`
+- `model/list`
+- `skills/list`
+- `app/list`
+
+### Bridge RPC methods
+
+- `bridge/health/read`
+- `bridge/terminal/exec`
+- `bridge/attachments/upload`
+- `bridge/voice/transcribe`
+- `bridge/git/status`
+- `bridge/git/diff`
+- `bridge/git/commit`
+- `bridge/git/push`
+- `bridge/approvals/list`
+- `bridge/approvals/resolve`
+- `bridge/userInput/resolve`
+
+### Notifications (examples)
+
+- `turn/*`, `item/*`
+- `bridge/approval.*`
+- `bridge/userInput.*`
+- `bridge/terminal/completed`
+- `bridge/git/updated`
+- `bridge/connection/state`