llms.txt

# system-gap-master

## Last-checked: 2026-08-22

## Verification

176 tests passed, 42 subtests passed, and 1 Windows symlink-platform test was
skipped because the current account lacks the required symlink privilege;
Ruff, pytest, unittest, and `compileall` passed cleanly on 2026-08-22.

## Canonical repository

https://github.com/ellmos-ai/system-gap-master

## Summary

system-gap-master is a serverless cross-machine sync protocol for users who run
several machines and several AI agents. It uses one human-readable transfer
yard, host-owned slots, delete-after-read message channels, agent-rule
snapshots and a once-per-day gate script to keep machines from drifting into
separate state silos.

## Primary files

- `README.md` — overview, quick start and security notes.
- `README_de.md` — vollständige deutsche Dokumentation & Schnellstart.
- `PROTOCOL.md` — full protocol and design rationale.
- `SKILL.md` — daily sync ritual for agents.
- `scripts/system_gap_daily_check.py` — zero-dependency daily gate script.
- `scripts/config_snapshot.py` — provider-neutral, allowlisted configuration
  snapshots and a comparable deviation report; generated state is derived.
- `system_gap_master/conflict_copy_reconciler.py` — policy-driven safe
  conflict-copy scan/plan/apply/verify/rollback API and CLI.
- `docs/conflict-copy-reconciler.md` — merge classes, safety gates, owner
  lease and desktop/macOS adapter contract.
- `system_gap_master/trusted_peer_paths.py` — read-only host-owned registry
  validation and deterministic, non-executable pull-preparation CLI/API.
- `system_gap_master/trusted_peer_sftp_executor.py` — separately authorized,
  signature-verified, one-shot and no-overwrite SFTP single-file executor.
- `docs/trusted-peer-sftp-executor.md` — signature namespaces, host-local
  credential binding, replay ledger, transfer and receipt boundaries.
- `docs/trusted-peer-path-registry.md` — trusted-peer threat model, setup,
  direct-pull boundary and SQLite adapter rule.
- `system_gap_master/republica_transit.py` — resolves the R9 tool-owned
  `db-transit/<namespace>` zone for the Republica showcase fallback and
  validates that a `republica_root` destination stays outside the yard; pure
  path arithmetic, no hard dependency on sqlite-transit-sync.
- `system_gap_master/ticket_route_adapter.py` — validates ticket-master 1.11
  route intents and hands the unchanged payload to an injected existing
  transport; it owns no ticket queue, fan-out, lifecycle or completion state.
- `docs/ticket-route-intent-adapter.md` and `_de.md` — cross-repository pin,
  retry/idempotency contract and responsibility boundary.
- `schemas/trusted-peer-*.schema.json` — machine-readable registry,
  host-local policy and no-transfer receipt contracts.
- `template/` — copy-ready yard skeleton.
- `examples/config-state.providers.example.json` — neutral provider-table
  example for the configuration-state showroom.
- `docs/adapting-your-agents.md` — integration notes for agent rule files and
  session-start hooks.

## Safety model

- No credentials, tokens, private case data or live databases belong in the
  sync yard.
- Each machine writes only its own host slot plus shared drop zones.
- Integrated transfer items are archived, not silently deleted.
- Hot SQLite files and other open data stores must use snapshot-based transit
  tooling instead of direct file-sync.
- Conflict discovery never proves canonicality. Automatic mutation requires
  an allowlisted root, authoritative mapping, safe deterministic merge class,
  one explicit mutating owner, a shared local lease, HMAC-bound plan/manifest,
  no symlink/reparse traversal, backup, verification and rollback.
- The trusted-peer planner is read-only: it validates owner slot, expiry,
  pinned signature reference, digest, known-host pin, peer and exact path
  allowlists. It never reads referenced files or contacts a peer.
- `pull-plan` requires `direct_pull=true` but produces only a deterministic,
  non-executable receipt. The optional executor re-runs it and additionally
  requires detached registry/grant signatures, an exact short-lived one-shot
  grant, host-local credentials, a presented host-key match, a regular remote
  file, size bounds, private staging and atomic no-replace commit. SQLite and
  WAL/SHM paths remain discovery-only and use `sqlite-transit-sync` through R9
  `db-transit/<namespace>`.
- Republica (the sqlite-transit-sync showcase mode) is a permanent fallback
  layer, not a stopgap: a direct SSH/Tailscale tunnel and a Republica
  showcase over the yard are meant to run side by side, so a failure in one
  does not stop the other. `republica_transit.py` only resolves where the
  R9 zone lives inside a given yard; encryption, publish/list/import and the
  sealed-envelope courier remain sqlite-transit-sync's responsibility.

## Search phrases

```text
serverless multi machine sync protocol
AI agent sync yard
cross machine agent state transfer
daily sync gate script
plain file agent handoff protocol
host slot sync protocol
multi agent state persistence
cross host slot isolation
trusted peer path metadata registry
read only SFTP pull preparation receipt
signed one shot SFTP pull executor
semi trusted yard registry authenticity
republica showcase fallback database sync
serverless database sync without a tunnel
```