# kenforthewin/nethack_astra architecture

> Architecture diagram of the GitHub repository kenforthewin/nethack_astra, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kenforthewin/nethack_astra
- Repository: https://github.com/kenforthewin/nethack_astra

## Overview

This repository is the operational and evidence harness for a completed NetHack ascension, not a standalone agent: the model session supplied inference and orchestration. The principal workflow is agent-issued input through a persistent remote terminal, guarded navigation and puzzle assistance, then observation and audit. Separate capabilities expose a spectator UI and create and verify a sanitized evidence projection. The source excerpts are partial, so links for unsampled UI and export internals are limited to README-documented behavior.

Main entry points: [`scripts/session.py`](https://github.com/kenforthewin/nethack_astra/blob/main/scripts/session.py) (Remote session), [`web/index.html`](https://github.com/kenforthewin/nethack_astra/blob/main/web/index.html) (Spectator and victory UI), [`scripts/audit.py`](https://github.com/kenforthewin/nethack_astra/blob/main/scripts/audit.py) (Private audit ledger), [`scripts/sokoban.py`](https://github.com/kenforthewin/nethack_astra/blob/main/scripts/sokoban.py) (Sokoban assistance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_play["Gameplay harness"]
  node_session["Remote session<br/>[session.py]"]
  node_guard["Movement guard<br/>[guard.py]"]
  node_routing["Route proposals<br/>[route.py]"]
  node_sokoban["Sokoban assistance<br/>[sokoban.py]"]
end

subgraph group_observe["Observation and display"]
  node_terminal["ANSI rendering<br/>[terminal.py]"]
  node_viewer["Spectator and victory UI<br/>[index.html]"]
  node_gameui["Gameplay UI<br/>[game.html]"]
  node_obs["OBS broadcast<br/>[obs.mjs]"]
end

subgraph group_evidence["Evidence and publication"]
  node_audit["Private audit ledger<br/>[audit.py]"]
  node_ledger[("Run evidence")]
  node_prepare["Sanitized export"]
  node_projection["Public evidence"]
  node_verify["Export verification"]
end

node_agent(("Agent session"))
node_hardfought["Hardfought NetHack"]
node_tmux["tmux session"]
node_transcript["Agent transcript"]
node_reviewer(("Evidence reviewer"))

node_agent -->|"issues input"| node_session
node_session -->|"sends game keys"| node_hardfought
node_hardfought -->|"returns terminal state"| node_session
node_session -->|"controls session"| node_tmux
node_session -->|"checks movement"| node_guard
node_session -->|"renders screen"| node_terminal
node_routing -->|"reads map"| node_session
node_sokoban -->|"reads and sends"| node_session
node_sokoban -->|"checks execution"| node_guard
node_session -->|"records activity"| node_audit
node_audit -->|"writes events"| node_ledger
node_transcript -->|"watches records"| node_audit
node_session -->|"serves spectator state"| node_viewer
node_viewer -->|"displays result"| node_agent
node_gameui -.->|"preserves gameplay UI"| node_viewer
node_obs -.->|"captures broadcast"| node_viewer
node_prepare -->|"reads evidence"| node_ledger
node_prepare -->|"writes sanitized export"| node_projection
node_verify -->|"checks export"| node_projection
node_reviewer -->|"reviews evidence"| node_projection

click node_session "https://github.com/kenforthewin/nethack_astra/blob/main/scripts/session.py"
click node_guard "https://github.com/kenforthewin/nethack_astra/blob/main/scripts/guard.py"
click node_routing "https://github.com/kenforthewin/nethack_astra/blob/main/scripts/route.py"
click node_sokoban "https://github.com/kenforthewin/nethack_astra/blob/main/scripts/sokoban.py"
click node_terminal "https://github.com/kenforthewin/nethack_astra/blob/main/scripts/terminal.py"
click node_viewer "https://github.com/kenforthewin/nethack_astra/blob/main/web/index.html"
click node_gameui "https://github.com/kenforthewin/nethack_astra/blob/main/web/game.html"
click node_obs "https://github.com/kenforthewin/nethack_astra/blob/main/scripts/obs.mjs"
click node_audit "https://github.com/kenforthewin/nethack_astra/blob/main/scripts/audit.py"
click node_prepare "https://github.com/kenforthewin/nethack_astra/blob/main/scripts/prepare_publication.py"
click node_verify "https://github.com/kenforthewin/nethack_astra/blob/main/scripts/verify_publication.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_session,node_guard,node_routing,node_sokoban,node_reviewer toneBlue
class node_terminal,node_viewer,node_gameui,node_obs toneAmber
class node_audit,node_ledger,node_prepare,node_projection,node_verify toneMint
class node_agent,node_hardfought,node_tmux,node_transcript toneIndigo
```

## Components

### Gameplay harness

- [Remote session](https://github.com/kenforthewin/nethack_astra/blob/main/scripts/session.py): `scripts/session.py`
- [Movement guard](https://github.com/kenforthewin/nethack_astra/blob/main/scripts/guard.py): `scripts/guard.py`
- [Route proposals](https://github.com/kenforthewin/nethack_astra/blob/main/scripts/route.py): `scripts/route.py`
- [Sokoban assistance](https://github.com/kenforthewin/nethack_astra/blob/main/scripts/sokoban.py): `scripts/sokoban.py`

### Observation and display

- [ANSI rendering](https://github.com/kenforthewin/nethack_astra/blob/main/scripts/terminal.py): `scripts/terminal.py`
- [Spectator and victory UI](https://github.com/kenforthewin/nethack_astra/blob/main/web/index.html): `web/index.html`
- [Gameplay UI](https://github.com/kenforthewin/nethack_astra/blob/main/web/game.html): `web/game.html`
- [OBS broadcast](https://github.com/kenforthewin/nethack_astra/blob/main/scripts/obs.mjs): `scripts/obs.mjs`

### Evidence and publication

- [Private audit ledger](https://github.com/kenforthewin/nethack_astra/blob/main/scripts/audit.py): `scripts/audit.py`
- **Run evidence**
- [Sanitized export](https://github.com/kenforthewin/nethack_astra/blob/main/scripts/prepare_publication.py): `scripts/prepare_publication.py`
- **Public evidence**
- [Export verification](https://github.com/kenforthewin/nethack_astra/blob/main/scripts/verify_publication.py): `scripts/verify_publication.py`

### Other components

- **Agent session**
- **Hardfought NetHack**
- **tmux session**
- **Agent transcript**
- **Evidence reviewer**

## Connections

- Agent session → Remote session: issues input
- Remote session → Hardfought NetHack: sends game keys
- Hardfought NetHack → Remote session: returns terminal state
- Remote session → tmux session: controls session
- Remote session → Movement guard: checks movement
- Remote session → ANSI rendering: renders screen
- Route proposals → Remote session: reads map
- Sokoban assistance → Remote session: reads and sends
- Sokoban assistance → Movement guard: checks execution
- Remote session → Private audit ledger: records activity
- Private audit ledger → Run evidence: writes events
- Agent transcript → Private audit ledger: watches records
- Remote session → Spectator and victory UI: serves spectator state
- Spectator and victory UI → Agent session: displays result
- Gameplay UI → Spectator and victory UI: preserves gameplay UI
- OBS broadcast → Spectator and victory UI: captures broadcast
- Sanitized export → Run evidence: reads evidence
- Sanitized export → Public evidence: writes sanitized export
- Export verification → Public evidence: checks export
- Evidence reviewer → Public evidence: reviews evidence