Architecture
M8Shift is a local relay: a passive core owns the pen, while companions observe, prepare context, notify, or isolate parallel work without becoming a second writer.
Local by design
Every channel below is local: repository files, shell argv, JSON/stdin-stdout, exit codes, and git. The core relay has no hosted control plane, no network path, and no daemon. (The optional --with-rtk / --with-headroom installers perform install-time downloads, and the RFC 034 adapters run as pinned argv subprocesses — v3.40+; runtime stays offline.)
Module communication
RTK and headroom_ext are optional token-usage adapters. See Token adapters: RTK and Headroom.
Since v3.61.0 the runtime companion also carries the RFC 072 fleet layer and the RFC 073 provider-keyed adapter registry: managed agent CLIs launch through the vendor-neutral m8shift.agent-cli-adapter.v1 contract (launch_argv/stop/resume/health, shell-free argv), and fleet supervise --detach runs one durable control plane — a native launchd/user-systemd/Windows-service backend when available, an honestly weaker local detached fallback otherwise — over a crash-consistent .m8shift/runtime/fleet/ store. None of this adds a second pen: fleet enrollment is holder-attributed core roster add, and adapter health can never imply relay completion.
Inter-application agent flow
Verified channels
| Channel | Code path |
|---|---|
| agents / maintainer → core | m8shift.py command handlers such as claim, next, append, pause, resume |
| core → relay files | M8SHIFT.md state updates guarded by .m8shift.lock and atomic writes |
| runtime → core | m8shift-runtime.py run_core_json() calls [python, m8shift.py, ...] and parses JSON stdout |
| runtime → notifications | one-shot stdout/file/bell/OS/hook tiers; hooks return exit codes and never mutate relay state |
| core → guarded child | guard-exec checks the binding-resolved pen immediately before one shell-free exec; lease-keeper refreshes authority plus wrapper liveness while its child lives |
| runtime → gateway store/transport | immutable one-shot mandate/result records plus closed canonical push/comment/PR-create argv; integration and destructive actions remain non-mandatable |
| context → adapters | RFC 034 argv-only runner with bounded stdout/stderr and exit-code handling |
| context → compression store | compress writes raw/compact/record files; retrieve serves bounded, hash-verified content |
| worktree → git/core | git worktree/merge argv calls plus imported core helpers for serialized integration |
| runtime → agent CLIs | m8shift.agent-cli-adapter.v1 registry dispatch keyed by the validated provider row; launch_argv compiles one shell-free argv array, stop/resume/health mediate generic reconciliation without relay authority |
| runtime → fleet store | crash-consistent .m8shift/runtime/fleet/ records (control.json, lanes/, jobs/, attempts/, sessions/, events.jsonl) written with fsync + atomic replace; PID start-identity reconciliation fails closed to needs_reconciliation on ambiguous evidence |
| e2e → core | temp-copy scenarios driven by subprocess argv and exit codes |