Architecture

Pytxo follows a three-tier model:

Presentation  ->  Orchestration  ->  Execution
(Pytxo Desktop)   (pytxo-orchestrate)   (pytxo-runner + PTY)
       ^                  ^
   passive telemetry   MCP / CLI

This is the shipping repository architecture. It implements a narrow commit boundary through immutable review and journaled Apply. The proposed production effect architecture is intentionally not presented here as current behavior.

Crates

Data flow

1. CLI, MCP, or Desktop submits a bounded mission plan
2. Orchestrator validates unique task IDs, explicit path claims, dependencies, and an acyclic wave graph
3. SQLite persists the pinned base revision, validated plan, permission profile, and enforcement receipt as one run contract
4. Runner spawns agents in isolated workspaces and streams events to SQLite
5. Optional Pytxo Desktop reads the same contract through Tauri IPC; presentation code does not open the store directly
6. A successful Orbit or Galaxy run stores target blobs and an immutable manifest under .pytxo/data/reviews/<run-id>/
7. Run Review reads that package; Apply validates affected-path preimages and writes only the stored target blobs to that one repository root
8. Each attempt writes a durable journal. Reconciliation settles an interrupted process before another run or Apply in the execution domain

Unrelated dirty checkout files do not invalidate a package. Drift on an affected path marks the review stale. DeepSpace is non-flushable, and Supernova writes directly to the host tree.

The journal is a process-crash recovery mechanism, not a power-loss ACID or cross-filesystem durability guarantee. Cross-root transactions and partial-file acceptance are outside v1.1.

Optional Cloud path

Local PTY execution is the default. Cloud execution appears only when a non-noop dispatcher is configured; the default orchestrator does not send a run to a hosted sandbox.

Moat routing

All new orchestration features should route through Signal Core, Blast Shield, and Race Shield. Do not bypass them.

For future effect work, those controls are foundations. The additional product contract is effect-bound authorization, independent post-state verification, causal evidence, and explicit reversible, compensatable, or irreversible recovery behavior.

See repo layout for directory map.