snapkitty-twin-mars-asm

x86_64 Assembly reconstruction of TWIN-MARS (Grok Build coding agent)

Assembly Author: Ahmad Ali Parr
Python Reconstruction: Kimi (Moonshot AI)
Trust: Bel Esprit D'Accord Irrevocable Trust · EIN 42-697643
Source: https://github.com/SNAPKITTYWEST/TWIN-MARS

Ahmad wrote the assembly. Kimi wrote the Python twin. The assembly is the real work — no libc, direct syscalls, behavior extracted from the installer and README alone.

---

What This Is

TWIN-MARS is SpaceXAI's Grok Build — an ~80-crate Rust terminal-based AI coding agent. This repository is Ahmad's x86_64 assembly reconstruction of that agent from the bottom of the stack up. Not a line-by-line Rust rewrite. A behavioral twin: observe the executable behavior, trace the syscall interface, implement in assembly, differential test.

The constraint that makes this interesting: The original source requires proprietary dependencies (DotSlash, protoc, xAI API credentials) and cannot be built externally. So Ahmad started from what's observable — the installer script, the README, the ABI — and reconstructed the machine-level behavior.

---

Reconstruction Method

flowchart LR
    OBS["Observable Evidence\nInstaller script\nREADME behavior\nCLI flags"] 
    ABI["System V AMD64\nSyscall ABI\nELF64 format"]
    TRACE["Behavioral Trace\n--version output\n--headless behavior\nTUI characteristics"]
    IMPL["Assembly Implementation\nNASM x86_64\nDirect syscalls\nNo libc"]
    BUILD["Build\nnasm + ld\nStatic ELF64\nbinaries/twin-mars"]
    DIFF["Differential Test\nOBSERVED vs twin\nExit codes\nStdout format"]

    OBS --> TRACE
    ABI --> IMPL
    TRACE --> IMPL
    IMPL --> BUILD
    BUILD --> DIFF
    DIFF -->|divergence found| IMPL

---

Architecture

graph TD
    subgraph ELF["ELF64 Static Binary"]
        BS["bootstrap.asm\n_start → main\nargc/argv/envp\nELF entry point"]
        MEM["memory.asm\nBump allocator\nbrk syscall\n4MB heap"]
        STR["strings.asm\nstrlen · str_eq\nstr_copy\nNo libc"]
    end

    subgraph CORE["Core Behavior"]
        MAIN["main.asm\nCLI dispatch\n--version\n--help\n--headless\n--stdio\n--leader"]
        TERM["terminal.asm\nRaw mode TCGETS/TCSETS\nAlt screen ANSI\nTUI event loop\nSlash commands"]
        STOR["storage.asm\ngetdents64 listing\nFile read/write\nCheckpoints"]
    end

    BS --> MAIN
    MEM --> MAIN
    STR --> MAIN
    MAIN -->|interactive| TERM
    MAIN -->|--headless| STOR
    TERM --> STOR

---

Syscall Interface

graph LR
    subgraph SYSCALLS["Direct Syscalls — no libc"]
        W["SYS_WRITE 1\nstdout output"]
        R["SYS_READ 0\nstdin input"]
        O["SYS_OPEN 2\nfile open"]
        C["SYS_CLOSE 3\nfd close"]
        IO["SYS_IOCTL 16\nTCGETS/TCSETS\nraw mode"]
        GD["SYS_GETDENTS64 217\ndirectory listing"]
        BRK["SYS_BRK 12\nheap allocation"]
        MK["SYS_MKDIR 83\ncheckpoint dirs"]
        EX["SYS_EXIT_GROUP 231\nclean exit"]
    end
    MAIN["main.asm"] --> W & R
    TERM["terminal.asm"] --> IO & W & R
    STOR["storage.asm"] --> O & C & GD & MK
    MEM["memory.asm"] --> BRK
    BS["bootstrap.asm"] --> EX

---

TUI State Machine

stateDiagram-v2
    [*] --> RAW_MODE: term_enable_raw\nTCGETS→modify→TCSETS
    RAW_MODE --> ALT_SCREEN: ESC[?1049h\nESC[?1000h mouse\nESC[?25l hide cursor
    ALT_SCREEN --> PROMPT_LOOP: clear + title
    PROMPT_LOOP --> READ_CHAR: SYS_READ 1 byte
    READ_CHAR --> APPEND: printable char
    READ_CHAR --> BACKSPACE: 0x7F / 0x08
    READ_CHAR --> ENTER: 0x0D / 0x0A
    READ_CHAR --> EXIT: ESC / Ctrl-C / Ctrl-D
    APPEND --> PROMPT_LOOP: echo char
    BACKSPACE --> PROMPT_LOOP: BSP SPC BSP
    ENTER --> SLASH_CMD: starts with /
    ENTER --> EXEC: regular prompt
    ENTER --> PROMPT_LOOP: empty
    SLASH_CMD --> PROMPT_LOOP: print + clear
    EXEC --> PROMPT_LOOP: execute + clear
    EXIT --> RESTORE: term_leave_alt\nESC[?1049l
    RESTORE --> [*]: term_disable_raw\nTCSETS restore

---

Who Built What

File	Author	Method	Evidence
asm/bootstrap.asm	Ahmad	DERIVED	ELF64 ABI documentation
asm/memory.asm	Ahmad	DERIVED	brk syscall interface
asm/strings.asm	Ahmad	DERIVED	Standard string primitives
asm/storage.asm	Ahmad	OBSERVED	README: "understands codebase, edits files"
asm/terminal.asm	Ahmad	OBSERVED	README: "fullscreen TUI, scrollback, prompt"
asm/main.asm	Ahmad	OBSERVED	README + installer: CLI flags, modes
Python twin (Rust)	Kimi	OBSERVED	Static analysis of ~80 Rust crates

Ahmad wrote all the assembly. Kimi wrote the Python/Rust twin reconstruction.

---

Evidence Table

Claim	Status	Source
CLI flags: --version, --help, --headless, --stdio, --leader	OBSERVED	README + installer
Binary ships as grok (xai-grok-pager)	OBSERVED	README
First launch opens browser for auth	OBSERVED	README line 86
Interactive TUI with fullscreen, scrollback, prompt	OBSERVED	README
Slash commands: /exit, /help, /clear	OBSERVED	README
x86_64 + aarch64 targets	OBSERVED	Installer OS detection
Raw mode via ioctl TCGETS/TCSETS	DERIVED	POSIX terminal ABI
Alt screen via ESC[?1049h	DERIVED	ANSI standard
Internal tool implementations	UNKNOWN	Source gated
ACP wire format details	UNKNOWN	Source gated
Auth token flow	UNKNOWN	Source gated

---

Build

# Requires: nasm, ld (binutils), Linux x86_64
make
./binaries/twin-mars --version
./binaries/twin-mars --help
./binaries/twin-mars --headless "list files"
./binaries/twin-mars   # interactive TUI (Ctrl-C or type exit to quit)

# Symbols + disassembly
make symbols

# Differential tests
make verify
make test

---

Related Repos

Repo	What
sovereign-apollo	AGC rebuilt by AI fleet
sovereign-doorbell	x86_64 MMIO doorbell, PTX, Lean 4
sovereign-fortran-agc	Fortran orbital mechanics corpus

---

© 2026 Bel Esprit D'Accord Irrevocable Trust · Patent Pending · θ = 89/2462