vibey engine adapters

Vibey drives three autonomous session runners through five engine ids:
claudeloop and codexloop (tier PAID) make up the default pool,
DEFAULT_DESCRIPTORS (cursorloop and agyloop were retired by ADR-0078);
three local engines (tier LOCAL,
LOCAL_DESCRIPTORS) join them, each behind its own switch (ADR-0064):
gptossloop — the local runner on GPT-OSS 20B, the sovereign default, on
unless VIBEY_FEATURE_GPTOSSLOOP=0 / [features] gptossloop = false; qwenloop
— the same runner on a Qwen model (qwen3:14b), opt-in by
VIBEY_FEATURE_QWENLOOP=1 / [features] qwenloop = true (ADR-0015); and
claudeloop-local — the claudeloop binary run with a local backend profile
(--profile NAME), opt-in by
VIBEY_FEATURE_CLAUDELOOP_LOCAL / [features] claudeloop_local (ADR-0038).
Under sub-doctrine 8.a local engines are preferred first: selection runs
SWRR within the LOCAL tier and falls back to PAID only when no local engine is
eligible. gptossloop's model is also the sovereign DESIGN/DECOMPOSE provider
(gptossloop_design.py, gptossloop_decompose.py, ADR-0027), the default
--provider (--provider qwenloop is read as gptossloop). The runners' source lives in this
repository under src/vibey_runners/{claude,codex,qwen,common}
(ADR-0021); vibey drives the installed binaries, not those packages' Python
APIs. Each has its own CLI surface, effort vocabulary,
state directory, and done marker. Vibey abstracts these differences via
EngineAdapter, a Protocol defined in application/interfaces/engines.py
and re-exported from application/ports.py.

The adapter pattern

EngineAdapter (read the real definition before relying on this summary —
it's short):

• descriptor: EngineDescriptor — a property, the engine's static facts
• async def preflight() -> PreflightResult — runs <engine> doctor;
  classifies auth + availability
• async def start(spec: RunSpec) -> RunHandle — builds argv from
  descriptor.effort_projection + isolation flags, spawns the runner,
  returns a handle over its run directory
• def tail(handle: RunHandle) -> AsyncIterator[EngineEvent] — streams the
  runner's events.jsonl, translated into vibey's own event vocabulary
  through loop_events.py::LOOP_EVENT_MAP. Only the runner's own turn
  boundary maps to TurnCompleted, one per real turn, because the budget
  brake counts it; chatter and stream deltas that echo a turn's text map
  to TranscriptRecorded
• async def send_prompt(handle, text, *, now: bool) -> None — writes the
  runner's control-plane inbox
• async def stop(handle: RunHandle) -> StopSummary — soft-stops the run;
  collects stop-summary.md and the final snapshot
• async def snapshot(handle: RunHandle) -> SnapshotRef | None
• def classify(raw: Mapping[str, object]) -> CapacityState — maps a raw vendor
  error shape to Available | WindowExhausted | CreditsExhausted | AuthenticationFailed
• def attribute(exit_code: int, tail: str) -> FailureClass — attributes a dead
  process to a FailureClass (capacity, engine, work, vibey)

An engine session never inherits the worker's environment: every spawn (the run,
--version, doctor, --help) builds it through
LoopProcessAdapter.environment, an EngineEnvironmentPolicy
(infrastructure/engines/engine_environment.py) over the one builder,
infrastructure/process/child_environment.py::ChildEnvironment. It is an
allow-list: the system basics, the descriptor's env_passthrough and auth_env,
and the project's engine_environment additions, declared in vibey.toml's
[engine_environment] (copied into the record by vibey new) or the
VibeyProject spec's engineEnvironment — never hand-edited into the record.
VIBEY_*, PG* and anything DSN- or password-shaped can never be on it, so
VIBEY_PG_URL never reaches a model-driven process; a descriptor or overlay that
tries is refused when the adapter is built. The worker's startup preflight and
vibey doctor --record probe with the project's policy, so a declared credential
reaches the auth check too. A new engine declares what its runner and vendor CLI
read in env_passthrough; do not add a spawn path that passes env= itself.
vibey's own git calls (infrastructure/git/clean_env.py) and the az adapter
build their environments the same way, never from a copy.
LoopProcessAdapter.env_overlay is laid over that last (run and preflight alike) —
how gptossloop gets GPTOSSLOOP_BASE_URL/GPTOSSLOOP_MODEL, and qwenloop only
QWENLOOP_BASE_URL (never a model), from the one setting VIBEY_OLLAMA_URL
(local_engines.py::LocalEndpointEnvironment).
Preflight runs <binary> doctor plus descriptor.doctor_args
(claudeloop-local: --profile NAME).

Preflight's --version and doctor probes each lead a process group of their own.
On a timeout or a cancellation, infrastructure/process/reaper.py::ProcessReaper
kills the whole group and reaps it within LoopProcessAdapter.kill_grace_seconds,
logging engine_process_not_reaped if a descendant that left the group still holds
the pipes. The gate runner and the skills-context compiler use the same reaper.
Never hand-roll a kill followed by an unbounded process.wait() (#283, ADR-0017).
The run's environment strips the interpreter's prefix only when it is a venv
(infrastructure/process/python_env.py::OrchestratorPythonEnv, shared with the gate
runner), so a system-Python install keeps /usr/bin.

start() internally calls infrastructure/engines/argv.py::build_argv() —
that's a plain function, not an adapter method; it takes both the descriptor
and the RunSpec (build_argv(descriptor, spec)), not just the spec.

See application/interfaces/engines.py::EngineAdapter and
infrastructure/engines/scripted.py::ScriptedEngine (the fake runner used in
tests). infrastructure/engines/loop_process_adapter.py::LoopProcessAdapter
is the production adapter (it supersedes ClaudeLoopProcess): it spawns the
loop process, streams events.jsonl, detects done_marker, treats exit code 75
as wind-down, and classifies capacity through classify.py — one class driven
by descriptors, not one class per engine.

Engine choice for engine-driven BUILD jobs goes through
SelectingEngineProvider → application/engine_selector.py::EngineSelector
(SWRR over domain/rotation.py), wired in bootstrap.py. The selector builds a
candidate per eligible engine and domain/rotation.py::preferred_tier offers SWRR
only the first tier in TIER_PREFERENCE (LOCAL, PAID) holding a candidate that
can win. The provider passes its pool (adapters ∩ --engines) as the allow-list,
and refreshes every enabled local engine's health from its doctor before each
selection. Selection requires populated engine_health rows, so an engine with
no recorded conformance is never selected.

Hybrid dispatch (ADR-0079, sub-doctrine 8.k) sits on top: [engines] mode is
singleton (exactly the above), hybrid or auto (the default: hybrid only from a
current EngineDispatchMeasured ledger event, else singleton). Under hybrid,
domain/engine_dispatch.py::EngineDispatcher plans over the same candidates: local
engines fill their [engines.slots] first (1 local, 2 paid by default); with every
eligible local slot occupied a job is held (SlotHeld → CapacityDeferred, recorded once
per attempt as EngineSlotWaitStarted) until it has waited overflow_after_seconds, then
a paid engine with a free slot takes it as overflow — reserved under the project row's
lock against paid_daily_cap, counted from EngineOverflowSelected events for the UTC
day. Slots in use are the job table's unexpired leases per assigned_engine. The provider
takes dispatch= (application/engine_dispatch_service.py::EngineDispatchService, wired
by bootstrap._engine_dispatch); dispatch=None is today's selection, unconditionally.
Counts reach the domain as data; never read the queue or a clock from domain/.

Before build.implement seeds a fresh run, it can ask the vibey-skills CLI for
a skills-context packet (infrastructure/skills_context.py::VibeySkillsContextCompiler,
modes off/shadow/inject, budget 1,000–32,000 with a 6,000 default;
ADR-0031). The packet is recorded as a vibey_skills_context_packet artifact.

Engine descriptors

infrastructure/engines/descriptors.py defines CLAUDELOOP, CODEXLOOP,
GPTOSSLOOP, QWENLOOP, CLAUDELOOP_LOCAL — one
EngineDescriptor per engine. claudeloop-local's is built from [engines.claudeloop_local]
(profile, context_window, structured_verdict) by
ClaudeloopLocalDescriptors.build(); the constant is the default profile local.
GPTOSSLOOP is QWENLOOP with its own id, binary and GPTOSSLOOP_*
passthrough: one runner, whose run layout (.qwenloop/runs/), done marker and
events both engines share.
DEFAULT_DESCRIPTORS is the default pool of two, LOCAL_DESCRIPTORS the three
local ones, ALL_DESCRIPTORS all five, and BY_ENGINE_ID maps every
EngineId. The worker
adds adapters for the local engines that are switched on through
local_engines.py::LocalEngineSettings — the one resolver bootstrap, worker,
work and doctor share.

Each descriptor (domain/engine.py::EngineDescriptor) declares:

• engine_id, binary — the executable name (e.g., "claudeloop"), min_version
• state_dir — where runs are stored (e.g., ".claudeloop/")
• done_marker — the text signaling completion (e.g., "CLAUDELOOP_TASK_FULLY_COMPLETE")
• capabilities — which features it supports (savepoints, unwind, etc.). A
  claim must agree with the facts below (test_descriptors.py): mid_run_prompt
  exactly where controls.prompt is declared, attachments only where images
  or paste_images is proven True, web_search only where the runner's run
  takes --web-search
• effort_projection — how vibey's 5-level ladder (TRIVIAL, LOW, STANDARD, HIGH, MAX)
  maps to the engine's native flags
• auth_env — environment variables that must be set (empty for gptossloop and qwenloop)
• env_passthrough — the variables the engine's runner and vendor CLI read, passed
  to its sessions (a trailing * names a prefix); nothing else reaches a session
  unless the project declares it
• session_verb, isolation_flags (per IsolationLevel)
• cost_per_mtok_in/cost_per_mtok_out, context_window, base_weight (rotation weight)
• tier (EngineTier.PAID default, LOCAL for gptossloop, qwenloop and claudeloop-local) and
  doctor_args (extra doctor arguments; claudeloop-local: --profile NAME)
• supports_cwd_flag (default True; codexloop: False) and plan_flag
  (default None = positional plan path; no current engine sets one)
• affordances — EngineAffordances: images, files, paste_text,
  paste_images, plugins (PluginSystem) and mcp, each True, False or
  None (unknown, the default). evidence names, for every value that is set,
  where the runner's own code shows it; a set value without evidence fails a
  test. Never set one from memory or a vendor's marketing
• controls — EngineControls: stop, wind_down and prompt as argv
  templates after the binary ({run_id}, {cwd}, {text}), None where the
  runner has no such verb or does not act on it. Tests read every template against
  the runner's own Typer app the way click parses it
• events — EventLog: the path template of its events.jsonl and its
  envelope (EventEnvelope: type, event_type+payload, or event_type)

Effort projection example (claudeloop, as in descriptors.py):

effort_projection={
    Effort.TRIVIAL: EngineInvocation(("--preset", "low", "--effort", "low"), achieved=Effort.TRIVIAL),
    Effort.LOW: EngineInvocation(("--preset", "low", "--effort", "medium"), achieved=Effort.LOW),
    Effort.STANDARD: EngineInvocation(("--preset", "medium", "--effort", "high"), achieved=Effort.STANDARD),
    Effort.HIGH: EngineInvocation(("--preset", "high", "--effort", "high"), achieved=Effort.HIGH),
    Effort.MAX: EngineInvocation(("--preset", "high", "--effort", "max"), achieved=Effort.MAX),
}

gptossloop and qwenloop project effort onto --max-turns (8, 16, 40, 64, 96).
claudeloop-local passes --profile NAME --preset low|low|medium|high|high and
never --effort; HIGH and MAX report achieved=STANDARD, its honest ceiling.

If an engine saturates, the descriptor sets achieved to the tier it
actually delivers. codexloop is the extreme case: its run has no effort flag,
so every level projects to empty argv with achieved=Effort.STANDARD.
domain/rotation.py::fidelity_factor(descriptor, requested) computes the
Candidate.fidelity_factor that scales the effective weight of engines that
saturate below the requested effort; application/engine_selector.py applies
it.

See ADR-0006 (normalized effort ladder).

argv building

infrastructure/engines/argv.py::build_argv(descriptor, spec) takes an
EngineDescriptor and a RunSpec (fields: run_id, worktree_path,
prompt, effort, isolation, optional session_id to resume) and
produces the command line — read the real function, it is short. As of
2026-09-15 it emits, in order:

1. <binary> run, or <binary> resume <session_id> when spec.session_id is set.
2. For run only: the plan path <worktree>/.vibey/plans/<run_id>.md, prefixed
   by descriptor.plan_flag when an engine sets one,
   then --run-id <run_id> (so the adapter finds the run directory the process
   writes to).
3. descriptor.invoke(effort).argv.
4. descriptor.isolation_flags.get(isolation, ()).
5. --cwd <worktree_path>, only when descriptor.supports_cwd_flag (codexloop:
   False).

30 golden files under tests/infrastructure/engines/golden/ (5 engines × 6
efforts, ULTRA included; test_argv.py parametrizes over ALL_DESCRIPTORS) capture the
expected argv for each combination — the source of truth for the exact current
shape.

argv.py::RUN_ARGV_TEMPLATE (RunArgvTemplate) is build_argv's run line with
its per-run values as placeholders: {binary}, run, {plan_flag?} (only with a
plan_flag), {plan}, --run-id, {run_id}, {effort_argv...}, and --cwd {cwd} when supports_cwd_flag. It is what vibey loops publishes for a caller
that starts a runner itself, such as the VS Code extension. Tests compare it with
build_argv for every engine and effort, and read it, filled in at every effort
and isolation level, against the runner's own run definition.

What vibey loops reports

vibey loops [--json] (application/loops.py::LoopCatalog, cli/loops.py) lists
the two loops of sub-doctrine 8.c, each engine under the loop its tier puts it in,
with every effort's argv, achieved effort and model, and the descriptor's run
template, affordances, controls, events and env names (names only). It reads
the local switches (and whether each is on_by_default) and each local runner's
model through local_engines.py, the resolvers
vibey doctor reads. An engine canon 8.b repeals (REPEALED_FROM_LOOPS; empty
since OpenCode's engine was deleted) is listed with repealed: true and left out of
every by-effort view. The document for one
fixed environment is committed as tests/cli/golden/vibey-loops.json: after
changing a descriptor, regenerate it with
VIBEY_UPDATE_GOLDENS=1 uv run pytest tests/cli/test_loops_cli.py -k golden and
commit it with the change.

Capacity classification

infrastructure/engines/classify.py::classify_capacity(engine_id, raw) dispatches
to one private classifier per engine (claudeloop-local shares claudeloop's) and
maps vendor-specific error shapes to vibey's CapacityState. claudeloop writes
its capacity as the class name ("capacity": "CreditsExhausted"); both that and
the {"state": ...} mapping are read, and BackendMisconfigured maps to
AuthenticationFailed (terminal, never credits). Exit 78 (EX_CONFIG,
EXIT_CODE_BACKEND_MISCONFIGURED) is attributed to ENGINE, and an incomplete run
that exited 78 parks its BUILD job on an engine_misconfigured gate
(RunOutcome.misconfiguration_gate) instead of retrying:

Available | WindowExhausted | CreditsExhausted | AuthenticationFailed

The critical distinction: WindowExhausted has a resets_at deadline;
CreditsExhausted does not. A window exhaustion is waitable; credits
exhaustion requires a human top-up.

Each engine's classifier pattern is versioned in CREDITS_FIXTURES,
WINDOW_FIXTURES, AUTH_FIXTURES, and AVAILABLE_FIXTURES — shared between
the classifier's own tests and the conformance suite.

Note: these are synthesized fixture payloads, not captured real vendor
errors. If you get access to real *loop binaries or real captured error
payloads, this is the first thing to replace.

The conformance suite

application/conformance.py::run_conformance() runs 9 named checks per
engine (grep the file for the check-name strings if this list drifts):
binary (installed + version), flags (run --help exposes what the
descriptor claims), state_dir, run_dir_shape (a real run produces
meta.json/events.jsonl/snapshots/latest.json — this one races a real
subprocess's own startup time, not just an instant file check; read the
function if you're touching it), snapshot_schema, capacity_map,
done_marker, control_plane, structured_verdict.

A failing conformance check marks that engine ineligible rather than
letting it fail mid-cycle.

vibey doctor --conformance --record

--record persists the preflight and conformance result to engine_health.
Without a recorded pass the worker warns and never selects the engine for
engine-driven jobs.

Live runs of the suite are split in two modes (ADR-0030): tests/live/ with
@pytest.mark.live runs conformance and rotation against ScriptedEngine
and scripted stand-in binaries, with no model calls; @pytest.mark.paid spawns real binaries
against real models and is excluded by default.

See ADR-0001 (orchestrate, do not reimplement).

When to read this skill

Before:

• Adding a new engine.
• Changing effort mappings.
• Changing what an engine declares it can take, control or emit (affordances,
  controls, events), or anything vibey loops reports.
• Debugging why rotation is skipping an engine.
• Updating capacity classification patterns after a vendor API change.