# Stargate Remote Session Reference

Last updated: 2026-04-20
Purpose: persistent handoff context for future VS Code Remote SSH sessions.

## Environment Snapshot
- Workspace root (this Linux remote): /home/ubuntu/Stargate
- Windows local path reference (deployment script context): D:/Stargate
- Main stack: LSL scripts + Node API + Nginx + PostgreSQL
- Production API base: https://api.exoticsg.net
- Documented live server IP: 104.171.126.236
- Production DB name: esn_production

## SSH and Host Access
- Recommended SSH: ssh esnAdmin@104.171.126.236
- Bootstrap SSH (first-time only): ssh root@104.171.126.236
- Deployment script defaults from esn-api/deploy/scripts/upload_from_windows.ps1:
  - Default server user: esnAdmin
  - Default local path: d:\Stargate\esn-api
  - Default remote path: /opt/esn-api

## Proxmox Quick Checks
- In Proxmox LXC, container name is the hostname.
- List containers: pct list
- Get hostname: pct config <CTID> | grep ^hostname
- Get current IP: pct exec <CTID> -- hostname -I

## Stargate System Overview
- System model: distributed in-world Stargate scripts with centralized cloud authority.
- Runtime model: each gate object runs modular scripts for control, effects, security, power, and API bridge.
- Network model: self-registration + heartbeat + address-book sync through HTTPS API.
- Operational status snapshot: registration, heartbeat, and directory sync are established; GDO/IDC server integration is next major integration item.

## Primary Script Responsibilities
- stargate_gate_controller_skeleton_v1.lsl: core dialing state machine, local/region/hypergrid modes, iris/shield coordination, route auth requests.
- stargate_api_bridge_v1.lsl: gate registration, heartbeat POST, address-book fetch/cache, API bridge messaging.
- stargate_dhd_controller_v3.lsl: user interaction, destination selection, menu flow, dial/reset requests.
- stargate_lights_controller_v2.lsl: chevron and state lighting (OFF, CHARGE, LOCK, ACTIVE, FAIL).
- stargate_sound_controller_v2.lsl: lock/open/close/fail/interference sounds, looping gate hum.
- _eh.lsl: event horizon rez/de-rez and traveler/object detection.
- _shield.lsl: shield rez/de-rez and command parsing.
- stargate_gdo_idc_controller_v1.lsl: IDC/GDO auth policy and optional backend authorization.
- stargate_status_display_controller_v1.lsl: user-visible status and security messages.
- stargate_zpm_power_controller_v2.lsl: ZPM tracking and power authorization support.
- stargate_update_controller_v1.lsl: in-world script update coordination via manifest.
- stargate_vendor_controller_v1.lsl: distribution/packaging helper behavior.

## Core Channels and Message Buses
- -708004: API status/events (legacy bridge-facing).
- -708005: DHD to Gate dial/reset protocol channel.
- -708006: GDO/IDC secure authorization traffic.
- -708007: same-region gate discovery broadcast.
- -779901: owner security commands.
- -779902: owner IDC management (legacy/deprecated route).
- -779903: DHD manual dial mode override channel.
- -779904: direct owner dial commands.
- -779905: gate admin naming/routing/grid commands.
- -809005: power bus and power-state query channel.
- 55301: API bridge gate status/control channel.
- 55302: API bridge DHD address-book sync channel.
- 55305: API bridge self-listen/response channel.

## API Endpoints in Use
Base: https://api.exoticsg.net

- POST /api/gates/register
- POST /api/gates/heartbeat
- POST /api/gates/dial/authorize
- GET /api/gates/{gateId}/address-book
- GET /api/network/directory
- GET /health

Not currently implemented in esn-api (planned/documented elsewhere):
- GET /api/network/nearby?region=<name>
- POST /api/security/idc/authorize

## Dialing and Session Flow
1. DHD picks route from address book or manual symbols.
2. DHD emits DHD|DIAL on -708005.
3. Gate performs prechecks (availability, power, local constraints, security).
4. Atlantis-style chevron sequence starts (symbol progression with synchronized lights/sounds).
5. Gate requests backend route authorization.
6. On approve: open wormhole, rez event horizon, set active states.
7. On deny/fail: fail state and reset.
8. Session ends on timeout or reset command and effects de-rez.

## Atlantis AV Sequence Requirements
- Expected sequence includes symbol progression, chevron charge/lock phases, and final open state.
- Incoming route behavior differs from outgoing to avoid duplicate full symbol animation.
- Failure behavior should show FAIL light/sound and then recover to OFF/idle.
- Timing profiles and mapping are documented in stargate_atlantis_av_sequence_map.md.

## Power and ZPM Rules
- Local dial and hypergrid dial have different power requirements.
- Multi-device power aggregation is supported; priority and depletion rules are script-controlled.
- Server-side power authorization is the authoritative decision for protected operations.
- Gate should deny dialing when threshold power is not met.

## Security Defaults and Guardrails
- API registration uses per-gate identity/token material.
- Iris external/API control defaults are hardened in current controller baseline.
- Shield semantics are UP/DOWN and integrated with gate lifecycle.
- GDO/IDC can run static code checks, allow-lists, and backend callback auth.
- Duplicate/orphan helper cleanup behavior exists for startup protection.

## DNS and URL Status in Scripts
Current defaults use DNS hostnames, not hardcoded IPs.

- stargate_api_bridge_v1.lsl -> https://api.exoticsg.net
- stargate_gdo_idc_controller_v1.lsl -> https://api.exoticsg.net
- stargate_update_controller_v1.lsl -> https://api.exoticsg.net/api/updater/manifest

Important caveat: runtime overrides are possible.

- stargate_api_bridge_v1.lsl can set API_URL from config/notecard data.
- stargate_gdo_idc_controller_v1.lsl can set backend url via owner command.
- stargate_update_controller_v1.lsl can set manifest url via owner command.

## Known Risks and Practical Mitigations
- OpenSim linked-message differences can break parser assumptions.
  - Mitigation: parse text payload path first where applicable.
- Script memory/size constraints can affect high-fidelity orchestration.
  - Mitigation: keep modular script partitioning and offload state to API.
- In-world HTTP throttling can impact reliability.
  - Mitigation: cache address-book responses and use retry/backoff.
- Hypergrid endpoint volatility can cause routing failures.
  - Mitigation: backend validation and graceful fail messaging.

## Ops Commands to Keep Handy
- API bridge checks:
  - /55301 register
  - /55301 heartbeat_request
  - /55302 request_address_book
- Direct dial examples:
  - -779904 dial local|1,2,3,4,0
  - -779904 dial region|1,2,3,4,0|TARGET_SHORT
  - -779904 dial hg|1,2,3,4,5,6,7,8,0|Dest Sim|grid.host:port
- Security examples:
  - -779901 security on
  - -779901 idc code <value>
  - -779901 allow add <avatar_uuid>
- API smoke tests:
  - curl https://api.exoticsg.net/health
  - curl https://api.exoticsg.net/api/network/directory

## Container Name Status
- No docker compose container_name entry was found in this repository.
- If Proxmox-managed, use pct commands above to identify hostname and IP.

## Public SSH Key Provided in Chat
- ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHskJTvjUwDUOzcCRa6k27tufIZXkQ8evNHkJbz3fEHX kristy@cloudnigh.me

## High-Value Source Files
- install.md: architecture, roadmap, deployment, API and schema references.
- record.md: scope, risks, open questions, decision log, status snapshots.
- API_BRIDGE_INSTALL_GUIDE.md: bridge install/verification and production host notes.
- stargate_atlantis_av_sequence_map.md: animation and event mapping.
- stargate_hud_gdo_idc_spec.md: security and GDO/IDC behavior.
- stargate_local_vs_hypergrid_manual_dialing.md: dialing mode rules and commands.
- stargate_sim_performance_offload_guide.md: script budget and offload strategy.
- stargate_api_bridge_v1.lsl: API bridge implementation details.
- stargate_gate_controller_skeleton_v1.lsl: gate state and route control.
- stargate_dhd_controller_v3.lsl: DHD protocol and user flow.
- stargate_lights_controller_v2.lsl: light behavior.
- stargate_sound_controller_v2.lsl: sound behavior.
- _eh.lsl: event horizon behavior.
- _shield.lsl: shield behavior.

## Next Remote Session Checklist
1. Open this file first.
2. Verify DNS and TLS reachability for api.exoticsg.net.
3. Verify SSH access as esnAdmin.
4. If Proxmox-managed, confirm CTID hostname and current IP.
5. Confirm active script URLs were not overridden away from DNS.
6. Run API smoke tests before in-world dialing tests.

## Update Rule
When infrastructure, endpoint, script protocol, or security defaults change, update this file in the same commit.

## 2026-04-20 HUD Status Snapshot
- `stargate_wearable_dhd_hud_v1.lsl` now parses ESN API address-book responses where entries provide `gate_alias` and `symbols` arrays.
- Address book UI flow verified: HUD receives entries and presents destination selection instead of empty menus.
- Current local short-name mapping for gate selection/discovery is explicitly pinned to `CAST` and `CELESTIS` via HUD overrides.
- Address-book dial command delivery uses direct gate send plus fallback channel send for multi-prim listener layouts.
- HUD `Reset` now targets the last gate used for dial-out and sends reset using direct + fallback path for improved close reliability.