bro-ride

ride/ is the bro-ride uv workspace member. It publishes the top-level ride package, depends on the framework's bro distribution, and declares its own runtime/UI dependencies directly; bro never imports ride. It depends on no harness or provider. Harness distributions depend on this runtime and register their adapters through bro.harnesses. The root repository owns formatting, lint, typing, packaging policy, and the test gate. Build this member with uv build --package bro-ride; regenerate its scripts and committed ride/_entrypoints.py with sync-scripts --project ride.

Runtime map

• ride/cli.py — the ride dispatcher. solo is the one-shot mode verb, along the interactive mode verb; resume, list, clean, exec, check-clean, scope, missions, override, artifact, and banner are lifecycle verbs.
• ride/ask.py, ride/call.py — pure option-preserving aliases of ride solo and ride along. Their scripts live in this distribution and add no implied fast mode or other flags.
• ride/dive_in.py — task utility wrapper: prefetch, task-derived workspace naming, fresh-origin base selection, hold defaults, and forwarding to ride along with the project-default bro.
• ride/session.py — harness-neutral session lifecycle: recorded SessionSpec including isolation and the optional repository attachment, base resolution, auth/scope preflight, and the workspace lock, resume records, keep/drop finish behavior, and the one started-party launcher that prepares attached or detached workspaces in either isolation for roots and spawned children.
• ride/repository.py — path/URL attachment resolution, normalized managed-mirror keys, flocked no-prune fetches, committed-tree reads, and mirror cleanup. attachment_identities is the host-config identities an attachment matches project entries by, reading a checkout's origin for the URL one.
• ride/do_ride.py — the do-ride session executable every launcher runs inside a prepared workspace: its own parser and argv builder, the session environment and pid/start-time record, credential hooks, persona provisioning, the session broxy, and the owned watch store and session watch; plus the selected harness's preparation and SIGTERM-forwarded agent spawn. It touches the session's activity file at start and end, and hands its path to the harness on SessionRun to touch as the session works; ride list reads its age off that file.
• ride/errors.py — the runtime-path and workspace-record error wrapper shared by the distribution's public scripts.
• ride/scope.py — prospective credential scopes, the harness's ScopeRecipe, and credential-store views. scope_report.py accepts complete recipe text and reports its resolved recipe and source, or a refusal.
• ride/authority_reading.py — immutable root readings of host and project policy, store defaults, and installation registries. Broken personas and provider declarations are retained as unavailable with their fault; only launches selecting them are refused.
• ride/authority_scope.py — bro option defaults, credential gate-outcome manifests, wire mapping, existence checks, and layered bases.
• ride/authority_launch.py — request/gift/cap mapping, descriptor-based credential hydration, live authority views, and resume-layer replacement.
• ride/root.py — supervision of either neutral started-party launch for roots and manually launched children, behind the broker availability gate.
• ride/broker_root.py — broker-root composition over the installed bro.worker_types classes, the common launch control, and artifact kinds. The channel listener binds loopback plus the Docker bridge gateway when that is an address of this host.
• ride/bro_worker.py — the registered bro worker type and summon lowering: admitted descriptors, placement, the manual expectation, lifecycle projection, SummonLaunchSpec, and SummonSpawner. Started parties go through the common isolation-parameterized launcher and carry a resume spec; joined members run in the summoner’s existing tree with member-scoped records and no resume.
• ride/launch_control.py — starter attribution, common admission under the root reading, mission records, authority reads, operator commits, run lowering, and launch audit.
• ride/worker_container.py — container execution for core WorkerContainer declarations: off-loop broker lowering with coordinated image builds and pruning, detached throwaway workspaces, passed-instance store hydration, artifact views, and requested-or-available loopback port allocation and facts; plus a no-workspace foreground run whose piped exchange belongs to a host command.
• ride/overrides.py — ordered operator changes, checked candidates, and atomic authority-only operation records.
• ride/credential_overrides.py — pending credential operations, receipt settlement, and the manual applier's operator-channel protocol.
• ride/credential_applier.py — supervisor-owned publication into a process's private root or its container.
• ride/manual_credentials.py — the manual launcher's retained applier connection.
• ride/operator.py — root-lifetime operator channels, private control records and their cleanup, guarded operator request registration, and the mission-listing, joint-start commit/claim, and artifact share/get clients.
• ride/peer_facts.py — the mission-keyed generic worker facts and peer directory for one broker root: peer resolution through the journal worker binding, workspace/member/type attribution, type-owned extensions, ancestry, and per-member current-trail attribution shared by launch, artifacts, and audit.
• ride/artifacts.py — the ride's artifact store, the artifact.mint, artifact.get, owner-authorized artifact.share, and bro.export-gated artifact.export kinds, the operator's operator.artifact.share and operator.artifact.get, and the broker's JobOutput: reflink-or-copy ingest into content-addressed objects, per-peer view directories behind read-only mounts at each peer's declared artifact-view path, the sharing rules with their uniform denial, the byte cap, and the JSONL audit beside the store. A broker job's run directory is staged in the store and collected through the same ingest, reaching the peer that requested the job and its summoners. The peer wire and CLI are the framework's bro/artifact.py.
• ride/pending_launch.py — pending manual worker launches: the runtime-carrying generic record a launch token resolves to, including the type, talk, owner tree, environment, and type-owned JSON extension. The launch control writes it and an interactive or solo bro --summoned launch claims it once; that claim records the worker's workspace name — the attribution source for the expected peer.
• ride/trails.py — local-trails mounts for launch descriptions whose computed scope records locally.
• ride/identity.py — managed-session git identities: the bro a session commits as, and the launching human it credits, read from the attachment's own git configuration.
• ride/harness.py — the SessionHarness protocol (scope, auth, session reads, preparation, the runtime probe, host-cache cleanup, image/host/bundle provisioning, and the launch hooks), the metadata-derived harness roster, and the lazy checked resolver. The framework identity, prompt facts, and bro.harnesses registry live in bro/harness/__init__.py.
• ride/host_check.py — ride check-host: the host prerequisites a launch needs, each probed and given its macOS or Ubuntu fix; --install first runs the fixes that need no root.
• ride/provisioning.py — installed-harness host setup and relocatable-runtime asset installation with per-harness checksum records.
• ride/flags.py — common session, scope, LLM, and harness flag registration, and the default an omitted --hold resolves to.
• ride/session_env.py — the --env contract: assignment parsing for the CLI, and the validation every reader of a recorded mapping applies.
• ride/runtime_bundle.py — installation freeze, content-addressed bundle persistence and locking, runtime validation and re-exec, shared host/container materialization, session-command shims, runtime-volume lifecycle, and bundle GC.
• ride/listing.py, ride/clean.py, ride/scope_report.py — lifecycle implementations.
• ride/e2e_test.py — live Docker launch coverage, outside the default test roster.
• ride/workspace/ — managed workspace creation, provisioning, container execution, credential hydration, broker spawners, and teardown; see ride/workspace/AGENTS.md.
• ride/setup/ — packaged runtime/project image and managed-session entrypoint assets; see ride/setup/AGENTS.md.

The public authority reference is bro/reference/permissions.md; scenario-first setup instructions are in bro/reference/permissions_cheatsheet.md.

Invariants

• The neutral layer owns one started-party launcher parameterized by isolation; the harness seam supplies scope recipes, auth, recipe support checks, session preparation and the run under do-ride, runtime checks, host-cache cleanup, session-state reads, and per-harness launch extras. do-ride owns every session's common setup before asking the selected harness to prepare and run it. A managed boxed or unboxed workspace is always launched by ride; a summon child is spawned by summon — except a manual one, which the user launches with ride along --summoned <token> or the one-shot ride solo --summoned <token> against the summoner's provisioned channel.
• Every harness keeps its session state among the workspace's own records, so reclaiming a workspace is Workspace.remove() for all of them and no harness supplies a teardown of its own.
• Every outer root runs one runtime bundle for its full lifetime, re-executing its launcher from that bundle's ride: either a locked freeze of the invoking installation, materialized for the host before the re-exec, or the materialized venv/ + bin/ layout named by --runtime-bundle. A freeze taken from inside a frozen bundle's host venv must land on that bundle. Unboxed workspaces run its absolute host materialization; boxed workspaces require a frozen manifest, mount its named runtime volume read-only, and reuse the root's image tag and bundle hash for started children. A given runtime's unboxed sessions verify TLS against the certifi store it carries, set as SSL_CERT_FILE in their snapshot; a frozen runtime's sessions trust the host's own store. A manual token carries the frozen hash or given path, and its launch command names that runtime's own ride.
• A bro resume reads the session-published pointer from the workspace's session/ dir and continues that trail with its recorded resolved recipe and source, its set option values and newly computed defaults. --llm replaces the recipe on the recorded harness, with a same-wire check for native continuation. No pointer is published when trail recording is disabled.
• Workspace state is global under runtime_base()/workspaces/, with each workspace's optional repository attachment recorded in metadata. Runtime bundles live under runtime_base()/runtime/; managed URL mirrors under runtime_base()/repos/. Their flocks serialize fetch/cleanup, mirrors never prune, and ride clean removes one only when no workspace references its URL. Container trails use a dedicated fixed absolute mount.
• Every attached workspace tree is an independent clone on its recorded branch. A detached unboxed workspace may instead record one existing external tree outside the runtime root; one workspace records that path at a time, resume requires it to remain present, and workspace removal never removes it.
• A ride preflights its Docker daemon by reading a nonce through a bind of the runtime root, whenever a bundle's container runtime is not yet settled; one marker beside the bundle carries that verdict and the volume's materialization together, against the instance label the volume they were reached for was created with. The marker is one file across every Docker context while a volume belongs to one daemon and a name outlives whatever held it, so that label is what sends another daemon's namesake, or a replacement created in its place, back through both. A volume found unlabelled is one this runtime never created, and is replaced rather than trusted. Every boxed bind source must resolve under that root.
• Runtime, project, and worker image tags use stable host-wide lock paths under the runtime root. A process holds a shared tag lock from before ensure until exit, missing-tag builds serialize on a separate lock, and pruning keeps a non-blocking exclusive tag lock across removal. A foreground worker run resolves and holds the invoking installation's runtime and worker images through those locks but prunes none; it mounts only the runtime volume, publishes declared ports on loopback, pipes stdin and stdout, and removes its container on exit.
• Harness selection follows bro/reference/ride.md, "Harness selection"; it remains unset until a launch needs it.
• A root takes its reading after runtime re-exec and attachment resolution. Every child and manual commit uses that reading; a resume takes a new one. Hydration uses the admitted descriptor's exact picks, while instance material and minting sources stay live.
• Both isolations pass BRO_STORE and BRO_INSTALL_KINDS to do-ride, which installs the hooks through one applier into the named session environment directory, so a session's git and gh reach GitHub as the identity it was scoped with rather than through the operator's own configuration. An unboxed process gets a closed environment snapshot with its workspace as PWD; only the baseline roster and, for a session on the launcher's terminal, its identity cross from the ambient environment, and a launch's recorded --env additions sit beneath it all, carried by the root and every party member alike. Every unboxed session's store and install-hook output share a private temporary root removed by its supervisor; retained workspace records therefore carry no credential material.
• Mode verbs are detached unless --repo explicitly attaches a resolved checkout or git URL. Managed detached trees are plain directories, skip repository and persona provisioning, and are clean only while empty; an external --tree is clean when its last session ended cleanly. A URL attachment's user-facing identity stays the normalized URL while its git operations use the managed mirror.
• A pinned mode-verb workspace is never auto-dropped. An unpinned along workspace is kept unless --drop is explicit; an unpinned solo workspace is dropped after a clean exit unless --keep is explicit. Spawned-workspace credential-operation retention is described in bro/reference/permissions.md, "Credential changes and settlement".
• A solo resume becomes an along session and preserves its set hold value.
• Every reconstructed session argv and do-ride command restates the resolved --hold. The session executable has no placement flag from which to re-derive it.
• Every launcher exports RIDE_ISOLATION from the workspace record; session placement and the banner never infer it from the surrounding process.
• A joined member inherits its summoner’s workspace and isolation, runs no workspace provisioning, and keeps its session and Claude records under party/<member>/ — reached inside a boxed party through the /var/ride/party mount its container was created with. It has no resume record; clean exit removes its records, failure or kill keeps them, and an unboxed member's private credential root is always removed while a boxed member's store dies with the party's container. The party ends with its first session, so that session's teardown kills any members still running, whichever spawner runs them.
• Launch control runs normalization, the use and gift rules, and admission checks before worker code checks existence or starts work. Worker types declare options and runs, not permission checks. A manual token retains its prepared request until claim; the operator may retry a commit before the child starts. Resume records retain the resolved-recipe record, set values and principal attribution, gift/cap, and operator layers, not other resolved defaults.
• Every console script this distribution ships wraps its main in ride.cli.reports_runtime_errors, so unusable runtime locations and workspace records fail as CLI errors.