SOS

SOS is a research prototype for an agent-native operating experience: the user directs an agent that writes and evolves the visible environment, while separately installed providers remain authoritative over data and actions. It is not a launcher, a scriptable Android application, or a fixed catalog of generated widgets. The architectural north star is docs/vision.md.

Warning

SOS is experimental software, not a daily-driver phone OS. The physical-phone work uses an unlocked Galaxy A33 5G, custom recovery, community device trees, and prototype security boundaries. Bootloader unlocking wipes the device and permanently trips Samsung Knox. Do not flash a device without reading docs/samsung-sm-a336b.md and preparing an exact stock rollback path.

Current status

As of 2026-08-16, SOS has moved beyond its original Android application laboratory into the privileged system and native-ownership phase.

Track	Current evidence
Generated experience	Scene ABI v3 Luau revisions support responsive layout, paint, transforms, clips, host-shaped text, raw multi-pointer input, animation, semantics, text composition, and bounded image/font/shader sidecars. Revisions are validated and activated transactionally in one permanent Rust/GPUI host.
Android APK harness	The physical SM-A336B passed the stable-host regression, typed provider effect, durable state/authority recovery, and a 10,000-swap device soak. This remains a regression harness, not the product boundary.
Linux	A permanent GPUI/Wayland host, durable provider/state service, revision supervisor, resident Pi authoring agent, authenticated Smithay compositor, selectable GDM session, and Debian direct-DRM VM gate are implemented. Physical Linux hardware remains unproven.
AOSP Cuttlefish	Pristine Android 17, SOS-as-HOME, and an init-supervised on-device authority passed in x86-64 Cuttlefish.
Samsung a33x	The historical six-stage campaign was completed on physical hardware. Compat 1 is the accepted usable fallback and later passed live System Providers v1. Core 1 is the only active Core development target; Core 0A is archived and Core 0B is a frozen, opt-in migration oracle. Core 1 now builds the same provider ABI through native Health, Supplicant, audio, app-manifest, media, and attention adapters, but that slice has not passed its physical gate and Core 1 is not yet a usable unlocked OS.
Resident agent	Pi runs on Linux and as native ARM64/Bionic Node on the phone. A subscription-backed Codex flow produced and activated a live generated revision on-device without bypassing trusted validation.

The accepted physical fallback is Compat 1 revision sos.compat1.19d8a653fbd7.220e268c228f. It passed full-frame SOS HOME/workspace/attention, selected-application containment, redirected Android system-Activity blocking, HOME restart, native side-button lock/wake, and owner-confirmed touchscreen ENTER unlock on a no-credential test device. Core 1 intentionally remains locked: native synthetic-password/FBE unlock and the system-service replacements needed to remove Android safely do not exist yet. Provider-focused revision sos.compat1.a3f3bae010bf.b093c3a0b50a subsequently passed live clock/power/Wi-Fi/audio/attention facts, reversible typed actions, generated-revision failure recovery to signed stock, reboot persistence, and a 125-second refresh smoke soak. It does not supersede the broader fallback revision because successful media/application actions and physical ENTER were not repeated in that campaign.

The concise chronological record is docs/progress.md. The product boundary and exact physical results are in docs/android-product-split.md and docs/android-ui-ownership-stages.md.

Architecture

The normal mutation unit is a content-addressed experience revision, not a new APK or native binary:

user request
    ↓
bounded resident authoring agent
    ↓
Luau source + assets + migrations
    ↓
fresh-VM evaluation and capability validation
    ↓
permanent Rust/GPUI host prepares and presents a retained scene
    ↓
supervisor commits revision, provider effects, and durable state—or rolls back

Generated code does not receive a GPUI context, device handle, provider object, filesystem, or arbitrary socket. Fixed trusted code owns candidate validation, frame-boundary activation, recovery, credentials, system facts, and provider actions. Providers remain authoritative over resources, actions, and events; the generated experience owns their composition and presentation.

On the physical a33x target, SOS is split into two product families over the same hardware, services, host, and revision format:

SOS Compat
├── Compat 0  historical SOS-as-HOME bring-up with Android ceremonies
└── Compat 1  native SOS presentation + selected Android applications

SOS Core
├── Shadow    manual diagnostic probe with Android recovery UI
├── Core 0A   archived historical stage; no build product
├── Core 0B   frozen legacy migration oracle; explicit opt-in only
└── Core 1    active no-Zygote target; fixed locked/recovery surface

The historical rows remain evidence, not an obligation to maintain every intermediate as a current product. A runtime property cannot turn one ownership stage into another.

Choose a development path

Android application harness

The quickest physical-device path is still the non-system Android harness. It requires the Android SDK/NDK, Java, the Rust Android target, and an authorized ARM64 device:

./tools/sosctl doctor
./tools/sosctl m1-check
./tools/sosctl m1-run

m1-check exercises the Android compilation path without requiring a connected device. The other commands use ADB_SERIAL when more than one device is attached.

m1-run builds the APK, starts the workstation provider/state daemon, creates adb reverse tcp:47777 tcp:47777, installs the APK, and launches it. Use m1-run --no-follow to leave the managed daemon running, and stop the complete session with:

./tools/sosctl m1-stop

Replace only the experience while the same process and APK remain alive:

./tools/sosctl validate experiences/daily-flow-agent.luau
./tools/sosctl script experiences/timeflow.luau
./tools/sosctl agent-apply experiences/daily-flow-agent.luau
./tools/sosctl rollback
./tools/sosctl worker-restart
./tools/sosctl stress 10000

The original unmodified GPUI Mobile hardware spike remains available through ./tools/sosctl run; see docs/experiment.md.

Linux stable host

Inside an existing Wayland session, run the authority, coordinator, permanent host, and one generated experience:

./tools/sosctl linux-run --windowed

From another terminal, inspect or replace the active revision without replacing the process or window:

./tools/sosctl linux-script experiences/daily-flow.luau
./tools/sosctl linux-status
./tools/sosctl linux-stop

Run the resident-agent path deterministically without a model call:

./tools/sosctl linux-agent-test
./tools/sosctl linux-agent-run --fake experiences/daily-flow.luau

For a subscription-backed live model, authenticate with Pi's headless Codex device flow before starting the agent:

export SOS_AGENT_PROVIDER=openai-codex
export SOS_AGENT_MODEL=gpt-5.6-sol
unset SOS_AGENT_FAKE_SOURCE
./tools/sosctl linux-agent-login
./tools/sosctl linux-agent-run

The nested compositor gate is safe to run from a workstation Wayland session:

./tools/linux-compositor/verify-nested

To install SOS as a selectable GDM session without removing the existing desktop or changing the default boot target:

./tools/install-linux-login-session install

The direct-DRM acceptance command targets the disposable reference Debian VM:

./tools/linux-vm/verify-direct-session

See docs/linux-stable-host.md, docs/linux-compositor.md, docs/linux-vm.md, and docs/sos-agent.md for prerequisites and evidence limits.

AOSP Cuttlefish

The Android 17 Cuttlefish track uses a separate checkout, by default ~/dev/aosp-sos, while the small SOS product overlay remains in this repository:

./tools/aospctl image
./tools/aospctl doctor
./tools/aospctl init
./tools/aospctl sync
./tools/aospctl build-pristine
./tools/aospctl boot pristine
./tools/aospctl verify-pristine
./tools/aospctl stop

./tools/aospctl build-sos
./tools/aospctl boot sos
./tools/aospctl verify-sos
./tools/aospctl stop

The SOS image packages an x86-64 HOME APK and an init-supervised on-device provider/state/revision authority. Its verifier removes ADB reverse as a hidden dependency, kills the GPUI process, and requires HOME plus the durable revision to recover. See docs/aosp-cuttlefish.md.

Samsung SM-A336B images

The physical-image build is intentionally separate from Cuttlefish. By default, tools/a33xctl uses ~/dev/lineage-a33x, a pinned LineageOS 23 / Android 16 graph, and an Ubuntu 24.04 Podman image. The host gate requires x86-64, at least 300 GiB free below ~/dev, and at least 60 GB RAM.

./tools/a33xctl image
./tools/a33xctl doctor
./tools/a33xctl init
./tools/a33xctl sync

Build and inspect one explicit ownership stage:

./tools/a33xctl build-compat1
./tools/a33xctl inspect-compat1

./tools/a33xctl build-core1
./tools/a33xctl inspect-core1

The complete profile matrix is:

Stage	Lifecycle	Build	Inspect
Compat 0	Historical Compat bring-up	build-compat0	inspect-compat0
Compat 1	Active fallback/application island	build-compat1	inspect-compat1
Shadow	Diagnostic probe	build-core-shadow	inspect-core
Core 0A	Archived; product removed	—	—
Core 0B	Frozen legacy migration oracle	SOS_ENABLE_LEGACY_CORE0B_BUILD=1 ./tools/a33xctl build-core0b	inspect-core0b
Core 1	Active Core target	build-core1	inspect-core1

build-compat and build-sos are aliases for Compat 1; build-core is an alias for Shadow. Building or inspecting an OTA does not authorize flashing it. The recovery, rollback, exact-device, and irreversible- risk procedure is in docs/samsung-sm-a336b.md.

Repository map

Path	Purpose
apps/experience/	Permanent Rust/GPUI host and Android/Linux adapters
crates/runtime-luau/	Bounded Luau evaluation and Scene ABI decoding
crates/revision-supervisor/	Revision preparation, activation, and recovery
crates/provider-state-service/	Durable typed provider/state authority
crates/sos-compositor/	Authenticated Smithay compositor
services/sos-agent/	Resident Pi authoring service and Android runner
experiences/	Generated-experience examples and regression fixtures
aosp/device/sos/	Cuttlefish and a33x product overlays
aosp/device/sos/a33x/core/platform_adapter.cpp	Core 1 native System Providers v1 platform adapter
packaging/	Linux systemd and GDM session integration
tools/	Reproducible build, run, install, and verification entry points
docs/	Architecture decisions, gate reports, and chronological evidence

Build products and raw evidence belong in artifacts/, .cache/, or the documented external evidence directories and are intentionally not tracked.

Documentation map

• docs/vision.md defines the intended product and permanent versus generative boundary.
• docs/android-product-split.md defines SOS Compat, SOS Core, and the current physical gate matrix.
• docs/android-ui-ownership-stages.md records the exact six-image ownership campaign.
• docs/samsung-sm-a336b.md covers the physical device, reproducible build, rollback risk, and hardware evidence.
• docs/experience-api.md documents the Luau-facing capability API.
• docs/runtime-evaluation.md records why Luau was selected for the current experience runtime.
• docs/stable-host-device-gate.md and docs/stateful-experience-gate.md contain the physical stable-host and stateful-swap evidence.
• docs/linux-stable-host.md, docs/linux-compositor.md, and docs/linux-vm.md cover the Linux path.
• docs/aosp-cuttlefish.md covers the reproducible Android 17 system spike.
• docs/progress.md is the chronological index of material experiments, failures, artifacts, decisions, and next gates.

Known limitations

• The physical evidence is from one unlocked Samsung SM-A336B development handset. Desktop, VM, or Cuttlefish results are never treated as equivalent to a phone hardware gate.
• Compat 1 constrains visible Android presentation but is not yet a data sandbox for selected applications. Permission, chooser, IME, emergency/call, alarm, ANR, accessibility, and security containment brokers remain gates.
• The test handset has credential type NONE; real PIN/Gatekeeper throttling, fingerprint, authentication-bound Keystore release, and the physical Volume-Up+Volume-Down Recovery chord remain unproven.
• Core 1 proves the no-Zygote process and recovery boundary while remaining deliberately locked. Its native System Providers v1 adapter has build/ABI parity, not physical acceptance: saved-Wi-Fi provisioning, validated reachability, media/app owners, attention producers, and provider restart/ soak evidence remain open alongside native CE unlock.
• Core 0A is historical evidence only. Core 0B is retained solely as an opt-in comparison target until Core 1 owns native unlock and the displaced unlock, provider hardware behavior, call/alarm, session, update, and recovery services.
• Speaker, earpiece, Bluetooth/call audio, cellular calls/data, and longer suspend, thermal, and soak campaigns are not complete across all accepted ownership stages.
• Generated experiences and providers are still research-grade; do not use real personal data or consequential credentials beyond the explicitly documented, revocable test setup.