aigentive · adriandemian · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026
diff --git a/.claude/rules/production-cli-resolution.md b/.claude/rules/production-cli-resolution.md
@@ -21,6 +21,7 @@ paths:
 |---|---|
 | `claude` | Claude harness chat/execution and reserved user-scope `ralphx` MCP registration cleanup |
 | `codex` | Codex harness chat/execution and capability probes |
+| `tailscale` | remote host tailnet discovery and Serve exposure |
 | `gh` | GitHub auth, PR polling, PR/release operations |
 | `git` | repository state, diffs, worktrees, merge/cleanup |
 | `node` | bundled RalphX MCP servers |

diff --git a/.claude/rules/remote-facade.md b/.claude/rules/remote-facade.md
@@ -0,0 +1,29 @@
+---
+paths:
+  - "src-tauri/src/remote_server/**"
+  - "src-tauri/src/commands/remote_*.rs"
+  - "src-tauri/crates/ralphx-remote-protocol/**"
+  - "frontend/src/lib/remote/**"
+  - "frontend/src/api/*.ts"
+---
+
+> **Maintainer note:** This file optimizes for LLM context efficiency. Rules: (1) Tables > prose (2) One example max per concept (3) No redundant explanations (4) Use symbols: → = leads to, | = or, ❌/✅ = wrong/right (5) Before adding content, ask: "Can this be a single line?" If yes, make it one line.
+
+# Remote Facade
+
+Scoped rules for the `:3849` host/client surface. These were root `CLAUDE.md` principles 27-28; they moved here so they load only for the code they govern.
+
+| Rule | Detail |
+|---|---|
+| Command registration (NON-NEGOTIABLE) | Every `:3849`-reachable command is a hand-audited `remote_server/registry.rs` allowlist entry with a `capability_ledger.rs` class; never a passthrough, a `generate_handler!` edit, or a command fork. Details: `docs/architecture/remote-protocol.md` |
+| Event fan-out (NON-NEGOTIABLE) | Remote events travel by classification-table delivery class — Durable rides the sequencer, Transient broadcasts with no seq and is never persisted, LocalOnly never leaves the host. ❌ Re-deriving remote event sources from `EventSink`/`AppState.events` |
+| Twin naming | A spawn-free twin is named for what its closure does (persists an intent), not for what the host later does (starts an agent). |
+| Absence is the signal | Client gates derive `unavailable` from a command's absence in the generated manifest — never from a hardcoded name list. |
+| Spawn-distinct paths are distinct FUNCTIONS (NON-NEGOTIABLE) | When a local path may reach a spawn/recovery seam and its twin may not, express the difference as two functions sharing only work that names NEITHER seam. ❌ One body behind a `bool`/enum flag: the ledger detectors are call-graph based, so a shared body that names both seams puts the spawned side in the twin's closure whatever the flag does at runtime. Measured 2026-08-05 on `set_agent_conversation_muted`: the flag form ran 18 hops into `reconcile_reserved_claude_registration` and the corrective-transition sinks, failing `detector_c_floors_process_spawn_authority`, `batch13_detector_gap_is_measured_not_inherited`, and `no_registered_facade_target_reaches_a_corrective_transition`. Same reason a closure/bare-fn indirection must not be used to *hide* a launch — the gate is only worth what the graph can see. |
+| Test the real envelope | Remote client tests assert the shapes the transport actually produces — `{outcome: "commandError", error: <the command's own error value, unwrapped>}` per `network-invoke.ts`, explicit nulls, real casing. ❌ Mock-convenient envelopes (`{outcome: "error", …}`) that no client path can emit; they pass while proving nothing. |
+
+## Client surfaces
+
+- **Remote Connection Journal** — `stores/remoteConnectionJournalStore.ts` is the per-environment connection diagnostics ring buffer; `lib/remote/environment-runtime.ts` is its single writer, the banner Details dialog its reader. Remote HTTP reads must lift the host's `REMOTE_COMMAND_UNAVAILABLE` envelope into `RemoteTransportError` (capability boundary, tolerated by the hydration barrier) — ❌ flattening it into generic HTTP errors.
+- **Tauri Plugin Prefix Rule** — every `plugin:*` command (opener/dialog/fs/updater/process/global-shortcut/notification) routes to THIS device via the one prefix rule in `lib/remote/local-only-commands.ts`; their subject is the machine showing the UI. Host-targeted plugin calls need a reviewed row in `HOST_TARGETED_PLUGIN_COMMANDS` (empty today) and then a registration or ledger row. ❌ Per-call-site remote branching for plugin invokes; ❌ passing a host filesystem path to `openPath`/`revealItemInDir` — those degrade through host-affordance gating to `HostPathCopyButton`.
+- **Syncing Presentation** — `lib/remote/supervisor-presentation.ts` owns the `syncing` projection (live socket mid-hydration → chip-only accent pulse in `EnvironmentSwitcher`, no banner) with K=2 barrier-failure / T=12s one-way escalation back to `reconnecting`; still read-only. ❌ New surfaces reading FSM state directly to infer "connection dropped".
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -62,6 +62,10 @@ jobs:
                   - 'scripts/tests/test-ci-path-filters.py'
                   - 'scripts/tests/test-claude-rule-utils.py'
                   - 'scripts/tests/test-claude-rules-activation.py'
+                  - 'scripts/check-raw-tauri-event-listen.mjs'
+                  - 'scripts/tests/test-raw-tauri-event-listen-guard.sh'
+                  - 'scripts/event-manifest-scanner/**'
+                  - 'scripts/event-manifest.json'
                   - 'scripts/build-prod-release.sh'
                   - 'scripts/render-homebrew-cask.sh'
                   - 'scripts/reconcile-homebrew-cask.sh'
@@ -206,6 +210,10 @@ jobs:
         shell: bash
         run: bash scripts/tests/test-coverage-rust-shards.sh
 
+      - name: Validate raw Tauri event listen guard
+        shell: bash
+        run: bash scripts/tests/test-raw-tauri-event-listen-guard.sh
+
       - name: Validate CI path filters
         shell: bash
         run: python3 scripts/tests/test-ci-path-filters.py
@@ -252,6 +260,76 @@ jobs:
       - name: Check JavaScript and Rust Tauri package alignment
         run: node scripts/check-tauri-package-alignment.mjs .
 
+  # UNCONDITIONAL BY DESIGN — no `needs: changes`, no path filter.
+  #
+  # These guards enforce the remote command facade's P-11 invariant (zero
+  # unclassified commands) and the currency of the generated manifest/mirrors.
+  # A backend-only PR that registers or reclassifies a Tauri command, and a
+  # docs-only PR that hand-edits docs/generated/remote-commands.json, both
+  # violate these invariants without touching `frontend/**` or `src-tauri/**`.
+  # Gating this job would restore the "merge first, discover red on main"
+  # behaviour it exists to prevent.
+  remote-facade-guards:
+    name: Remote Facade Guards
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      # check-remote-transport-drift.mjs parses frontend TypeScript with the
+      # compiler resolved from frontend/package.json, so the frontend dev
+      # dependencies must be present.
+      - name: Install frontend dependencies
+        run: npm ci --no-audit --no-fund
+        working-directory: frontend
+
+      - name: Guard self-test (drift detector)
+        run: node scripts/check-remote-transport-drift.mjs --self-test
+
+      - name: Raw Tauri event listen guard
+        run: node scripts/check-raw-tauri-event-listen.mjs .
+
+      - name: Remote transport drift (P-11 — zero unclassified)
+        run: node scripts/check-remote-transport-drift.mjs .
+
+      - name: Local-only backend event mirror is current
+        run: node scripts/check-local-only-event-mirror.mjs .
+
+      - name: Remote protocol vocabulary mirror is current
+        run: node scripts/check-remote-vocabulary-mirror.mjs .
+
+      - name: Agent-control capability mirror is current
+        run: node scripts/check-agent-control-command-mirror.mjs .
+
+      - name: Remote coverage census is current
+        run: node scripts/generate-remote-coverage-census.mjs --check
+
+  event-manifest:
+    name: Event Manifest
+    needs: changes
+    if: needs.changes.outputs.run_automation == 'true' || needs.changes.outputs.run_rust == 'true' || needs.changes.outputs.run_frontend == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8
+        with:
+          toolchain: 1.91.0
+
+      - name: Test event manifest scanner
+        run: cargo test --manifest-path scripts/event-manifest-scanner/Cargo.toml --test scanner
+
+      - name: Verify event manifest is current
+        run: cargo run --manifest-path scripts/event-manifest-scanner/Cargo.toml -- --check
+
   rust-ipc-contracts:
     name: Rust IPC Contracts
     needs: changes
@@ -315,6 +393,12 @@ jobs:
     env:
       CARGO_PROFILE_TEST_DEBUG: "1"
       RALPHX_TEST_MODE: "1"
+      # Archiving every test binary is the heaviest link step in CI. On this branch's Rust
+      # surface the job went silent mid-compile and the runner was reaped (exit 143) on every
+      # recent attempt, with 100+ GB of disk free — the signature of a memory kill on a 16 GB
+      # `ubuntu-latest`. Same value the Rust IPC Coverage job already uses; the 40 min budget
+      # absorbs the slower build (deaths were at ~7 min). Raise it if the runners grow.
+      CARGO_BUILD_JOBS: "1"
     steps:
       - uses: actions/checkout@v6
 
@@ -356,7 +440,7 @@ jobs:
           retention-days: 1
 
   rust-lib-tests:
-    name: Rust Lib Tests (Shard ${{ matrix.shard }}/2)
+    name: Rust Lib Tests (Shard ${{ matrix.shard }}/3)
     needs:
       - changes
       - rust-lib-nextest-archive
@@ -366,7 +450,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        shard: [1, 2]
+        shard: [1, 2, 3]
     env:
       RALPHX_TEST_MODE: "1"
     steps:
@@ -391,19 +475,19 @@ jobs:
           name: rust-lib-tests-nextest-archive
           path: .
 
-      - name: Run Rust lib tests shard ${{ matrix.shard }}/2
+      - name: Run Rust lib tests shard ${{ matrix.shard }}/3
         run: |
           cargo nextest run \
             --archive-file rust-lib-tests.tar.zst \
             --workspace-remap "${GITHUB_WORKSPACE}/src-tauri" \
             --profile ci \
-            --partition hash:${{ matrix.shard }}/2
+            --partition hash:${{ matrix.shard }}/3
 
       - name: Upload Rust lib test timings
         if: always()
         uses: actions/upload-artifact@v7
         with:
-          name: rust-lib-tests-junit-${{ matrix.shard }}-of-2
+          name: rust-lib-tests-junit-${{ matrix.shard }}-of-3
           path: src-tauri/target/nextest/ci/junit.xml
           if-no-files-found: warn
           retention-days: 7
@@ -451,6 +535,11 @@ jobs:
     timeout-minutes: 30
     env:
       RALPHX_TEST_MODE: "1"
+      # --all-targets --all-features peaks past the 16 GB on ubuntu-latest once the
+      # crate graph is this large: the job was reaped mid-compile with exit 143
+      # ("runner has received a shutdown signal"), not a lint failure. Same cap, and
+      # same reason, as the coverage archive job. Raise if the runner grows.
+      CARGO_BUILD_JOBS: "1"
     steps:
       - uses: actions/checkout@v6
 

diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
@@ -149,8 +149,12 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 40
     env:
-      # Coverage-instrumented lib builds exceed the hosted runner memory limit
-      # when Cargo compiles crates concurrently.
+      # Coverage-instrumented lib builds exceed the hosted runner memory limit when Cargo
+      # compiles crates concurrently. Observed on this branch, whose Rust surface is larger:
+      # the job went silent mid-compile and the runner was reaped (exit 143, "runner has
+      # received a shutdown signal") on 3 of 4 attempts at 4 parallel rustc processes,
+      # against the 16 GB on `ubuntu-latest`. Raise it back if the crate graph shrinks or
+      # the runner size grows.
       CARGO_BUILD_JOBS: "1"
       CARGO_TERM_COLOR: never
       RALPHX_TEST_MODE: "1"

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -15,7 +15,7 @@ If one is missing, skip it and continue; do not fail work or run bare `sed`/`cat
 
 ## Project: RalphX
 Native Mac GUI for autonomous AI dev: Kanban, multi-agent orchestration, ideation chat.
-Code quality: `.claude/rules/code-quality-standards.md` | State machine: `.claude/rules/task-state-machine.md` | Stateful review: `.claude/rules/stateful-workflow-review.md` | Big-PR checks: `.claude/rules/big-pr-review-checklist.md` | Git/merge: `.claude/rules/task-git-branching.md` | Merge recovery: `.claude/rules/merge-recovery-consistency.md` | Review modes: `.claude/rules/agent-workspace-review-modes.md` | Agents: `.claude/rules/task-execution-agents.md` | Delegation: `.claude/rules/delegation-topology.md` | Thinking: `.claude/rules/agent-thinking-capture.md` | Runtime roots: `.claude/rules/runtime-root-vs-target-project.md` | Prod CLI: `.claude/rules/production-cli-resolution.md` | CodeQL paths: `.claude/rules/codeql-path-safety.md` | Ideation verification: `.claude/rules/ideation-verification-architecture.md` | Blocker dedupe: `.claude/rules/followup-blocker-dedupe.md` | Agent types: `.claude/rules/agent-type-map.md` | Detail views: `.claude/rules/task-detail-views.md` | Frontend perf: `.claude/rules/frontend-interaction-performance.md` | Icons: `.claude/rules/icon-only-buttons.md` | Rust API: `.claude/rules/rust-stable-apis.md` | Rust tests: `.claude/rules/rust-test-execution.md` | WKWebView CSS: `.claude/rules/wkwebview-css-vars.md` | Release scripts: `.claude/rules/release-script-validation.md` | Assets: `.claude/rules/assets.md` | Tauri invoke: `.claude/rules/tauri-invoke-conventions.md` | PR body (READ): `.claude/rules/pr-descriptions.md`
+Code quality: `.claude/rules/code-quality-standards.md` | State machine: `.claude/rules/task-state-machine.md` | Stateful review: `.claude/rules/stateful-workflow-review.md` | Big-PR checks: `.claude/rules/big-pr-review-checklist.md` | Git/merge: `.claude/rules/task-git-branching.md` | Merge recovery: `.claude/rules/merge-recovery-consistency.md` | Review modes: `.claude/rules/agent-workspace-review-modes.md` | Agents: `.claude/rules/task-execution-agents.md` | Delegation: `.claude/rules/delegation-topology.md` | Thinking: `.claude/rules/agent-thinking-capture.md` | Runtime roots: `.claude/rules/runtime-root-vs-target-project.md` | Prod CLI: `.claude/rules/production-cli-resolution.md` | CodeQL paths: `.claude/rules/codeql-path-safety.md` | Ideation verification: `.claude/rules/ideation-verification-architecture.md` | Blocker dedupe: `.claude/rules/followup-blocker-dedupe.md` | Agent types: `.claude/rules/agent-type-map.md` | Detail views: `.claude/rules/task-detail-views.md` | Frontend perf: `.claude/rules/frontend-interaction-performance.md` | Icons: `.claude/rules/icon-only-buttons.md` | Rust API: `.claude/rules/rust-stable-apis.md` | Rust tests: `.claude/rules/rust-test-execution.md` | WKWebView CSS: `.claude/rules/wkwebview-css-vars.md` | Release scripts: `.claude/rules/release-script-validation.md` | Remote facade: `.claude/rules/remote-facade.md` | Assets: `.claude/rules/assets.md` | Tauri invoke: `.claude/rules/tauri-invoke-conventions.md` | PR body (READ): `.claude/rules/pr-descriptions.md`
 CodeQL path safety applies to production and tests; use process-owned runtime roots, fixed entry lists, pure test builders, and suppress `rust/path-injection` only after containment validation.
 Production CLI resolution applies to installed app launches; all runtime subprocess binaries must go through the shared resolver surface.
 
@@ -107,6 +107,7 @@ style={{ boxShadow: "none", outline: "none" }}
 - **Session Recovery** — Expired Claude session recovery with history preservation. Docs: `docs/features/session-recovery.md`
 - **Plan Verification** — Automated adversarial review loop for ideation plans. Docs: `docs/features/plan-verification.md` | Architecture: `.claude/rules/ideation-verification-architecture.md`
 - **Agent Personas** — Conversation-bound prompt-only behavior profiles for Project Agent conversations. Docs: `docs/features/agent-personas.md`
+- **Remote Access** — Two-instance host/client mode over an authenticated `:3849` listener. Docs: `docs/features/remote-access.md` | Protocol: `docs/architecture/remote-protocol.md`
 
 ## Git Conventions
 ❌ git init/push/remotes | Prefixes: `docs:` | `feat:` | `fix:` | `chore:`

diff --git a/config/ralphx.yaml b/config/ralphx.yaml
@@ -67,6 +67,13 @@ ui:
     standalone_conversations: false
     # A20 escape hatch: skip --resume on the send after a persona switch.
     persona_switch_forces_fresh_provider_session: false
+    # Remote multi-environment client UI.
+    # Env override: RALPHX_UI_REMOTE_ENVIRONMENTS=true|false
+    # Shows the Remote Access + Connections settings panes, the environment
+    # switcher, and the connection banner. It does NOT expose this host — that
+    # is a separate DB-persisted toggle (RemoteHostSettings.enabled, default
+    # false) inside the Remote Access pane.
+    remote_environments: true
 
 # Compatibility runtime row for the PersonaBuilder-only extractor. Canonical
 # `agents/ralphx-persona-extractor/agent.yaml` remains authoritative.
@@ -249,6 +256,8 @@ git:
   workspace_freshness_cache_ttl_ms: 2000 # Env: RALPHX_GIT_WORKSPACE_FRESHNESS_CACHE_TTL_MS
   # diff_commands.rs — short backend TTL for workspace review context/payload reuse
   workspace_review_cache_ttl_ms: 2000 # Env: RALPHX_GIT_WORKSPACE_REVIEW_CACHE_TTL_MS
+  # diff_commands.rs — long TTL for spawn-free paired-device workspace snapshots
+  remote_workspace_snapshot_ttl_ms: 86400000 # Env: RALPHX_GIT_REMOTE_WORKSPACE_SNAPSHOT_TTL_MS
   # agent_workspace_pr_description.rs — short backend TTL for precomputed publish PR descriptions
   workspace_pr_description_cache_ttl_ms: 300000 # Env: RALPHX_GIT_WORKSPACE_PR_DESCRIPTION_CACHE_TTL_MS
   # diff_commands.rs — short backend TTL for live GitHub PR annotation payload reuse