Cut legacy instance presence paths

[TraderSamwise]

Summary

• remove legacy instances.json registry/directory ownership paths from runtime, dashboard, debug, and project discovery
• add daemon defense-in-depth for relay guest requests with session-scoped read-only authorization
• align relay shared-route gating and app auth failure handling with the daemon contract

Verification

• yarn verify
• yarn build
• cd app && yarn test lib/relay-transport.test.ts && yarn typecheck
• cd relay && yarn typecheck
• yarn vitest relay/src/sharing.test.ts src/daemon.test.ts src/relay-client.test.ts

Notes

• cd app && yarn lint still reports pre-existing app-wide prettier/react warnings outside the touched files.

Summary by CodeRabbit

• New Features

  • Relay reports an authentication-failed status and stops reconnecting.
  • Shared-session requests include an injected share-session header.
  • Guest relay access is tightened: session ID is now required and allowed routes narrowed.

• Bug Fixes / Tests

  • Added tests covering relay handshake/auth-failure and reconnection stopping.

• Documentation

  • Clarified relay authorization boundaries and runtime authority expectations.

• Chores

  • Removed legacy remote-instance registry and related runtime plumbing.
  • Updated project .gitignore and simplified dashboard session handling.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9d9a0266-b789-4cdd-b7a3-27ae1f8c0ce4

📥 Commits

Reviewing files that changed from the base of the PR and between 134c497 and 49795cb.

📒 Files selected for processing (3)

• app/lib/relay-transport.test.ts
• docs/multi-user-chat.md
• src/remote-access.ts

✅ Files skipped from review due to trivial changes (1)

• docs/multi-user-chat.md

---

📝 Walkthrough

Walkthrough

This PR removes the multi-instance heartbeat tracking infrastructure and multi-instance session linking, tightens relay guest authorization with a daemon-side gate, adds relay transport auth-failure detection and status, and simplifies runtime/session handling to local and offline sources.

Changes

Multi-Instance Removal & Relay Guest Auth Enforcement

Layer / File(s)	Summary
Relay Transport Auth Failure Detection app/lib/relay-transport.ts, app/components/RelayIndicator.tsx, app/lib/relay-transport.test.ts	Relay transport detects authentication rejection via specific WebSocket close codes and consecutive handshake failures, emits an auth_failed status, and stops reconnection attempts. Indicator UI renders the new auth-blocked state with red styling.
Remote Actor Authorization Framework src/remote-access.ts, src/daemon.ts, src/daemon.test.ts	New remote-access module parses remote actor identity from request headers and JSON and provides authorization decision logic. Daemon applies this gate in routeRequest() before processing remote requests, blocking unauthorized mutations and guest access violations.
Relay Guest Request Authorization Tightening relay/src/sharing.ts, relay/src/sharing.test.ts, relay/src/relay-object.ts	Relay shared-session authorization now requires sessionId presence and exact match with share.sessionId, narrows allowed endpoints to specific GET routes, removes attachment-path allowlisting, and propagates session ID to daemon via X-Aimux-Share-Session-Id header.
Instance Registry & Directory Module Removal src/instance-registry.ts, src/instance-directory.ts (and test files)	Removes instance registry and directory modules that previously handled multi-instance PID/heartbeat tracking, cross-instance session discovery, and heartbeat claim reconciliation.
Dashboard Session Model Simplification src/dashboard/index.ts, src/dashboard/session-registry.ts, src/dashboard/session-registry.test.ts, src/multiplexer/dashboard-model.ts	Removes remote-instance linkage fields from DashboardSession. Session registry now builds sessions only from local and offline sources using a composite deduplication key on session.id + backendSessionId.
Multiplexer & Runtime State Cleanup src/multiplexer/index.ts, src/multiplexer/runtime-lifecycle-methods.ts, src/multiplexer/runtime-state.ts, src/multiplexer/runtime-sync.ts, src/multiplexer/session-launch.ts, and test files	Removes instanceId, confirmedRegistered state, and InstanceDirectory from Multiplexer. Removes remote-instance helper functions from runtime modules. Heartbeat now loads offline sessions instead of reconciling instance claims. Instance registration calls were removed from session launch flows.
Project Configuration & Path Cleanup src/paths.ts, src/project-scanner.ts, src/config.ts	Removes instances.json path exports and legacy filesystem fallback scanning for .aimux/instances.json. Updates .gitignore template to remove instances.json and add runtime artifact ignores.
Debug State Report & Authority Documentation src/debug-state.ts, src/debug-state.test.ts, docs/runtime-authority-*.md, docs/multi-user-chat.md	Removes instances source from DebugStateReport and adds unavailable placeholders for runtimeRows/pendingActions/dashboardSnapshot. Updates runtime-authority docs to remove instances.json references and expands multi-user-chat docs with relay authorization and x-aimux-* header details.
Dashboard UI Session Rendering Unification src/tui/screens/dashboard-renderers.ts, src/multiplexer/dashboard-control.ts, src/multiplexer/dashboard-interaction.ts	Removes special-case rendering for remote sessions. Unifies session rendering and UI actions (tool picker, thread navigation, label editing) so remote and local sessions are treated identically.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• TraderSamwise/aimux#18: Both PRs touch relay guest authorization and shared-request handling logic.
• TraderSamwise/aimux#32: Related changes to debug-state/report shapes and runtime topology handling.
• TraderSamwise/aimux#4: Related relay transport auth-failure state and connection behavior.

"🐰 I nibbled old instances.json away,
Guests now peek, but only where they may,
Relays will flag auth with a red dot bright,
Sessions stay local — hop on, all's right."

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 7.69% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and directly describes the main change: removing legacy instance presence paths from the codebase, which aligns with the substantial removal of instance-registry, instance-directory, and related path tracking throughout the PR.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch phase/remote-multiclient-semantics

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

app/lib/relay-transport.test.ts

ESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@app/lib/relay-transport.test.ts`:
- Around line 36-47: The test setup enables fake timers (vi.useFakeTimers()) and
stubs globalThis.WebSocket with a MockWebSocket subclass while pushing instances
into sockets, but it doesn't guarantee teardown on assertion failures; wrap each
test's setup and assertions in a try/finally (or move teardown to afterEach) to
always restore state: ensure vi.useRealTimers() is called and
globalThis.WebSocket is reset to originalWebSocket, and clear/close any entries
in the sockets array (references: vi.useFakeTimers, MockWebSocket subclass,
sockets, globalThis.WebSocket) in the finally/afterEach block so subsequent
tests aren't affected.

In `@docs/multi-user-chat.md`:
- Around line 64-66: The guest-route allowlist is inconsistent: the first list
only shows GET /agents/output and GET /events while another section also allows
history routes; update both places to use the same explicit wording and route
set — e.g., list GET /agents/output, GET /events, and the agent history
endpoints (GET /agents/:id/history or equivalent history routes used elsewhere)
and use the same phrase “guest-readable routes” or “guest allowlist” in both
sections so the documentation matches exactly.

In `@src/remote-access.ts`:
- Around line 94-106: The shared-guest session check in
assertRemoteAccessAllowed currently accepts session OR sessionId but downstream
handlers (/events and /agents/output) only honor sessionId, allowing bypass when
only session= is provided; update the authorization to normalize the query so
downstream sees sessionId: when searchParams has "session" but not "sessionId",
copy/set that value into "sessionId" (or require "sessionId" explicitly) before
comparing to actor.shareSessionId, ensuring the handlers receive a sessionId
query param and per-session filtering cannot be bypassed.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 10f654f1-c187-4e35-8446-8b2e3037e80e

📥 Commits

Reviewing files that changed from the base of the PR and between cc4b9bf and 134c497.

📒 Files selected for processing (36)

• app/components/RelayIndicator.tsx
• app/lib/relay-transport.test.ts
• app/lib/relay-transport.ts
• docs/multi-user-chat.md
• docs/runtime-authority-dead-paths.md
• docs/runtime-authority-inventory.md
• relay/src/relay-object.ts
• relay/src/sharing.test.ts
• relay/src/sharing.ts
• src/config.ts
• src/daemon.test.ts
• src/daemon.ts
• src/dashboard/index.ts
• src/dashboard/session-registry.test.ts
• src/dashboard/session-registry.ts
• src/debug-state.test.ts
• src/debug-state.ts
• src/instance-directory.test.ts
• src/instance-directory.ts
• src/instance-registry.test.ts
• src/instance-registry.ts
• src/multiplexer/dashboard-control.ts
• src/multiplexer/dashboard-interaction.ts
• src/multiplexer/dashboard-model.ts
• src/multiplexer/index.ts
• src/multiplexer/runtime-lifecycle-methods.test.ts
• src/multiplexer/runtime-lifecycle-methods.ts
• src/multiplexer/runtime-state.test.ts
• src/multiplexer/runtime-state.ts
• src/multiplexer/runtime-sync.ts
• src/multiplexer/session-launch.test.ts
• src/multiplexer/session-launch.ts
• src/paths.ts
• src/project-scanner.ts
• src/remote-access.ts
• src/tui/screens/dashboard-renderers.ts

💤 Files with no reviewable changes (17)

• src/instance-directory.ts
• src/instance-registry.test.ts
• src/config.ts
• src/multiplexer/dashboard-model.ts
• src/multiplexer/session-launch.ts
• src/instance-registry.ts
• src/multiplexer/runtime-sync.ts
• src/instance-directory.test.ts
• src/dashboard/session-registry.ts
• src/multiplexer/index.ts
• src/paths.ts
• src/debug-state.ts
• src/dashboard/index.ts
• src/multiplexer/runtime-state.ts
• src/multiplexer/runtime-lifecycle-methods.ts
• src/multiplexer/runtime-state.test.ts
• src/multiplexer/session-launch.test.ts