glove/docs/architecture.md

Glove architecture

Scope

Glove provides three execution surfaces:

Surface	Purpose	Current boundary
glove run	Contain an agent and mediate MCP tool calls	Public CLI
glove exec	Contain a direct agent process	Public CLI
gloved	Validate Sage plans, persist sessions, and deliver receipts	Owner-local control service

The public CLI is usable for local containment. The distributed Sage session surface is incomplete and must not advertise remote-launch readiness. A remote_linux_container runtime can be constructed from validated operator configuration, but it is deliberately non-operational and advertises no lifecycle, runtime-adapter, resource-enforcement, or receipt capability.

Process model

operator or Sage controller
          │
          ▼
  Glove control plane ───────► audit and receipt journals
          │
          ├── policy engine
          ├── MCP extensions ─► upstream tool servers
          │
          ▼
  OS sandbox
          └── agent process

The control plane remains outside the sandbox. It owns policy evaluation, upstream transport, audit output, protected filesystem descriptors, and session state. The agent receives only the endpoints and paths required by its selected mode.

MCP upstreams are separate host processes. Glove filters requests to them, but does not sandbox the upstream processes themselves.

Platform isolation

Property	Linux	macOS
Process visibility	PID namespace	SBPL process policy
Filesystem	mount namespace, pivot_root, read-only binds, private writable mounts	deny-default SBPL path rules
Network	route-less network namespace; offline socket denial or private-loopback access to the authenticated audited proxy through an inherited Unix descriptor channel	deny-default SBPL network rules
Identity	user namespace and UID/GID mapping	invoking user
IPC and hostname	IPC and UTS namespaces	SBPL policy
Resource limits	private cgroup/quota/watchdog implementation	incomplete for the Sage six-limit contract

Linux launches the child through clone3, configures the namespace and mount perimeter, applies seccomp, then releases the child to execute. Writable materializations are quota-backed; retained copies use persistent hard-sized ext4 loop images while ephemeral copies use tmpfs. Read-only inputs are descriptor-pinned. For approved egress, a namespace-local helper passes accepted loopback sockets to a host relay with SCM_RIGHTS. The relay can connect only to the per-run authenticated proxy; it never exposes a host-network socket or DNS service to the agent. The namespace-local helper consumes one PID within the configured session PID limit. macOS constructs a deny-default sandbox profile and applies it before executing the child.

Components

Namespace	Responsibility
container	sandbox creation, mounts, limits, output accounting, terminal receipts
control	Unix control protocol, authentication, session registry, receipt delivery
supervisor	canonical plan validation, local alias resolution, bundle resolution
mcp	bounded JSON-RPC framing and upstream clients
policy	tool and argument authorization
kernel	extension registration and dispatch
audit	structured local activity records
run	CLI orchestration for run and exec
host	strict XDG configuration, machine setup, diagnostics, and local project enrollment
reflect	compile-time extension metadata experiments

Public headers live under include/glove/. Implementations mirror that layout in src/. Tests are separated by concern under tests/.

MCP request flow

For glove run:

1. Glove starts the configured upstream servers and completes MCP initialization.
2. The contained agent sends a bounded JSON-RPC request.
3. The kernel resolves the extension and tool name.
4. The policy engine validates tool access and configured argument rules.
5. The extension forwards an allowed request to the selected upstream.
6. Glove returns the response and appends the audit event.

Malformed frames, unknown tools, policy failures, transport errors, and audit append failures fail closed.

Historical synthetic status milestone

The former construction-only synthetic status stack and harness-shaped adapter were removed because they had no production composition or child descriptor mapping. Any future ephemeral query service must be built at a live composition seam and may share only the harness-neutral bounded guest-channel transport; payload semantics, persistence, and harness projection remain outside that transport.

The shared guest_channel_transport owns one connected Unix stream descriptor, verifies AF_UNIX, SOCK_STREAM, and the required peer UID, and performs only bounded four-byte big-endian framed I/O. Each receive or send uses its caller's absolute steady-clock deadline and stop token. The transport is single-thread confined and has no handler, exchange, or public close API; its owner stops and joins the worker before destruction closes the descriptor, avoiding concurrent close and descriptor-reuse races.

The observation server carries one absolute accept deadline through every retry and stop-aware transient backoff. After accept, receive and response send share one absolute I/O deadline. Stop/deadline checks immediately surround registry handling, but registry persistence is trusted synchronous local work and cannot be forcibly interrupted once started. The hard bound therefore covers accept, framed I/O, and cooperative cancellation—not arbitrary handler execution.

The Linux local-service proxy remains schema-generic. The compatibility transport, selected when an adapter omits transport_id, mounts only runtime-allowed alias sockets from a private owner-only directory and forwards one bounded G2 request/response without parsing the payload. Upstream parents are descriptor-pinned and endpoint identities are drift-checked around connect. Because portable pathname Unix sockets cannot prevent same-UID ABA replacement, the operator and service-UID processes are trusted endpoint authority; the checks do not authenticate an application process. Resolved path grants are compared by descriptor identity against every endpoint parent ancestor before filesystem materialization, preventing a grant from exposing the host socket directly.

An adapter may instead select inherited-stream-v1. Glove creates one owner-0600 connected AF_UNIX/SOCK_STREAM socketpair for the exact adapter-bound alias and keeps the supervisor peer outside the sandbox. Clone setup loads seccomp with the committed contiguous child-descriptor range, then installs the guest peer at descriptor 3 after internal setup descriptors close. Offline socket, connect, setsockopt, and peer inspection remain denied; only getsockname and getsockopt(SOL_SOCKET, SO_TYPE) are permitted on the exact committed inherited descriptors so Node/libuv can classify the already connected stream. The child receives only the compact one-entry GLOVE_LOCAL_SERVICE_FDS_V1 alias-to-descriptor map; no proxy path, other configured local service, or host endpoint metadata is projected. Clone setup preserves exactly that descriptor and closes every gap and all undeclared descriptors. The persistent stream accepts sequential existing G2 frames, rejects empty, oversized, trailing, or queued input at the request boundary and immediately before and after response release, uses one absolute deadline per exchange, and is poisoned on transport, identity, upstream, framing, timeout, or cancellation failure. The managed-launch binding commits the selector, alias and child descriptor, both socket identities, and manifest digest. User-supplied GLOVE_LOCAL_SERVICE_* variables and mixed pathname/inherited authority fail closed.

Guest-channel semantics enter only through an opaque adapter binding resolved in src/adapters/. A generic or arbitrarily named pi endpoint does not imply a Sage schema. The sealed capability requires inherited-stream-v1 plus the exact adapter binding, registry catalog, factory, concrete Linux runtime, and adapter/runtime endpoint intersection. Endpoint checks are construction and drift evidence, not process-authentication evidence.

Proxy audit uses a conservative three-phase sequence: durable non-success delivery_pending before release, a clean post-audit request boundary before send, delivered only after successful guest send plus an immediate clean post-send boundary, and best-effort delivery_failed after failure. Synchronous audit persistence checks the exchange deadline before and after the append, but a kernel-blocked fsync(2) is not cooperatively preemptible. A late append cannot release the response. Stream scheduling cannot prove whether a byte that arrives after the final post-send peek was written before or after the peer observed the response; that byte is never processed concurrently and the next request boundary still applies. A protocol that needs causal no-pipelining proof must add an explicit versioned credit or acknowledgement.

glove exec bypasses the MCP kernel. It is intended for agents that manage their own tool protocol, so its security boundary is the OS sandbox and explicit filesystem/environment exposure.

Sage session flow

gloved uses an owner-only Unix socket and a per-start bootstrap secret. Its public control methods provide capability discovery, canonical plan validation, durable create/status operations, bounded receipt pages, and exact acknowledgement.

glove setup creates owner-only XDG configuration, runtime/state directories, key material, and an optional protected-root policy. glove init then creates a generation-bound exposure through the authenticated local control socket. Project files are never configuration input, and raw paths never cross P2P.

glove daemon installs and controls a fixed per-user service through systemd on Linux or launchd on macOS. The CLI resolves the local gloved executable, binds it to the protected config, writes the service definition atomically, and invokes the service manager without a shell. It never accepts service labels, extra arguments, environment, or lifecycle requests from P2P. The Linux unit enters an unprivileged user namespace and a private mount namespace before executing gloved; that gives the current user namespace only the mount authority needed for quota-backed private session filesystems. Systemd separately delegates the cpu, memory, and pids controllers to the unit. On systemd 254 or newer the generated unit places gloved in the fixed glove-host delegate subgroup. Glove pins that subgroup and its parent cgroup, requires owner identity and process exclusivity, enables the three controllers only on the empty delegated parent, and creates session cgroups as siblings of the supervisor subgroup. This avoids moving the supervisor during service startup while preserving a process-free controller node. When the supervisor itself has a non-identity UID map, the kernel cannot combine nested UID mapping with CLONE_INTO_CGROUP; Glove instead creates a child whose first operation is a blocking read on a private sync pipe, writes the nested UID/GID maps, attaches the blocked child to its sealed session cgroup, and releases it only after the durable start gate succeeds. No child setup or agent instruction executes before cgroup attachment. Neither mechanism grants host-root authority.

When Sage configures glove_activation_mode = "user_service", saged first asks the platform user service manager to start the fixed local Glove unit. It waits for gloved.sock and bootstrap-secret before health and capability negotiation. The service label comes only from local Sage configuration and is restricted to a bounded identifier; remote requests cannot select a process, unit, or executable. connect_only preserves externally managed deployments.

When the Linux runtime is configured, the control service executes this lifecycle:

1. Validate the canonical identifier-only plan against local policy.
2. Persist the plan and both the controller BLAKE3 digest and Glove SHA-256 content digest.
3. Reserve a session for preparation; live host writes are never eligible.
4. Resolve generation-bound exposures and library bundles through pinned descriptors.
5. Compose mounts, cgroup limits, output accounting, and an immutable launch binding.
6. Start and recover the child through the executor and reconciler.
7. Append an authenticated terminal receipt before projecting terminal state.

refinement-eval-v1 is a Glove-owned declarative evaluator on the shipping Linux managed-session backend. The model and harness receive no evidence writer. Before launch, Glove reads the exact fixture projection through its pinned read-only bundle descriptor, strictly decodes a non-executable fixture DSL, and removes that supervisor-only projection from the child mount set. The selected base or candidate skill projection remains an ordinary immutable read-only projection.

The PTY drain worker feeds every raw byte to the evaluator before circular transcript eviction. After clean drain and resource finalization, Glove checks the trusted termination, exit code, wall latency, UTF-8 stream state, and required/forbidden transcript literals, then synthesizes the canonical outcome. PTY JSON is only text and cannot become evidence. An incomplete stream or invalid UTF-8 produces authenticated invalid evidence; resource termination overrides otherwise satisfied transcript assertions.

The distinct refinement envelope shares the receipt journal's global sequence and HMAC head but uses its own receipt and envelope domains. Recovery and audit paging preserve the receipt kind, and the session registry refuses a resource V1 envelope for a refinement plan. Capability discovery reports schema version 1 only when the Linux runtime and protected library projection store were both constructed.

The local protocol exposes attach, input, resize, signal, detach, stop, and cleanup only when the constructed runtime reports lifecycle_operational(). Pointer presence is not capability evidence. The remote runtime currently reports false, schema version 0, an empty managed-runtime set, and unavailable resource mechanisms; every lifecycle dispatch returns method_not_found without starting SSH. Sage wires only operational lifecycle and receipt reconciliation. Exposure create/revoke remains owner-local; peers may receive only the redacted catalog. Retained-change inspection and independently authorized apply remain separate launch gates.

Construction-only remote backend

When remote_backend is present, gloved validates it as mutually exclusive with local materialization and Apple Container configuration. It requires the container identity as an untagged canonical name@sha256:<64 lowercase hex> reference whose suffix exactly equals container_image_digest, retains both values in the runtime composition, and rejects tags or mismatches. It writes an isolated OpenSSH config and pinned known_hosts beneath the already verified owner-only runtime directory, then constructs the non-operational runtime. This step performs no DNS lookup, network probe, authentication, SSH process launch, or Docker operation.

The generated SSH configuration ignores global known-hosts files, accepts only ssh-ed25519 host keys, disables host-key learning, and disables connection sharing with GlobalKnownHostsFile none, HostKeyAlgorithms ssh-ed25519, UpdateHostKeys no, ControlMaster no, ControlPath none, and ControlPersist no. The forced remote executable accepts exactly --stdio, sets umask 077, and reads its expected executable and image SHA-256 digests only from the administrator-owned /etc/glove/remote-executor.identity source. It measures its opened executable and fails closed on missing, empty, malformed, writable, or mismatched identity. Before each frame read, it captures the monotonic receive start and channel deadline. Request-TTL conversion subtracts all frame-receive time and rejects a frame that consumed its TTL; response writes use only the resulting request deadline. Only remote_health is available and it always reports not_operational; lifecycle methods return method_not_found. This is construction evidence, not remote-launch readiness.

Library projection

Sage plans refer to bundle digests and destination aliases, never arbitrary host paths. Local policy maps each alias to a protected sandbox target. Glove opens a digest-named bundle beneath an owner-only root without following links, verifies its type, ownership, link count, size, identity, and SHA-256 digest, then mounts the descriptor as a read-only sandbox file.

The launch binding and terminal receipt commit the projection identifier, destination, target, and digest. Bundle expansion into harness-native prompt directories is not implemented; prompt_ref remains rejected.

Guest specialized-channel admission

The durable per-session queue is schema-generic: Glove core enforces only structural invariants (identifier charset, digest hex, TTL/skew arithmetic, capacity, idempotency) and delegates body semantics to a host-registered admission table (channel_descriptor{schema_id, body_validator, bounds}). A host must register every payload contract, propagate registration failures, and freeze the nonempty channel_host before registry construction. Schema strings never appear in core. Current admission rejects enqueue for every unregistered schema. Only an authentic intent already present in durable history may recover after its schema retires, and then solely as non-actionable quarantine metadata that cannot be enqueued again or launched.

The explicit Sage harness adapter under src/adapters/sage/ registers only the bounded, non-signing sage.glove-observation.v1 schema currently required for registry admission. Dormant proposal or mutation schemas are not registered, so current enqueue rejects them. Authentic historical records using a subsequently retired schema recover only as non-actionable quarantine metadata.

Glove commits admitted bodies with the shared length-prefixed digest algorithm and preserves the exact schema in the durable queue. Intents bind to the session's parsed runtime_id, so any managed guest runtime can carry a registered payload.

Capability discovery does not infer observation ingress from registry storage. On Linux, schema version 1 requires an opaque capability produced only by sealing the concrete lifecycle runtime against the exact registry, frozen catalog, preparer-owned proxy factory, managed runtime intersection, complete resource mechanisms, descriptor-pinned endpoint parents, and current rechecked socket identities. The opaque capability owns the runtime, which owns its preparer and registry; the preparer owns the factory, and the factory owns the same registry. No edge points back to the capability or runtime. Generic, remote, Apple, mismatched, unsealed, absent-config, and drifted compositions report 0.

The optional local-service proxy descriptor-pins each configured owner-0700 parent and records and rechecks the owner-only Unix socket's exact dev/ino/uid/mode/nlink before and after every connect. An allowed session gets one fresh owner-only directory mounted read-only at /run/glove-services/local and the fixed GLOVE_LOCAL_SERVICE_DIR environment. Alias listeners forward one bounded G2-framed opaque request and response under one absolute deadline with peer-UID checks on both sides. A fixed worker set is joined before inode-safe socket and directory cleanup. The launch digest commits the sorted runtime-filtered aliases, descriptor-pinned parent identities, recorded socket identities, and factory generation; no durable registry or receipt schema changes.

Persistence

Session and receipt journals are append-only and bounded. Recovery rejects corrupt, reordered, duplicated, truncated, or externally resized records. Authenticated terminal receipts form an HMAC chain anchored by Sage. The general JSONL activity log and session-state journal are not protected against a same-user host process that can rewrite them.

Detailed policy and file invariants are defined in session-policy.md.