buzz/docs/named-runtime-configurations.md

Named runtime configurations

A configuration chooses a host, harness, exact model/provider, optional workspace, and references to already-provisioned local credentials. Several configurations can target the same host. Identity, persona and community memory do not move or change when the next-launch selection changes.

Scope and persistence

ManagedAgentRecord.runtime_configurations contains owner → community → set. The existing agent identity remains global; the sets and Desktop IDs do not. Absent sets migrate to Default. No unscoped prototype configuration is silently assigned to the currently open community. Management verifies the active scope and signed ownership, replaces exactly one set under the store lock, and persists once. Host-local writes preserve other hosts' entries and reject changing them. New/changed entries receive a new revision; stale whole-record writes fail.

The effective resolver only consumes the native launch projection, never guesses a scope from the record's creation relay. Normal Start captures selection for its actual owner/community pair. Explicit Start takes an exact {id, revision}; null means Default, not “read selection again later”. The immutable PreparedLaunch is not serializable. The management IPC retains names of local credential references for editing, but no resolved values. Lifecycle catalogs omit workspace, credential references, environment and identity material entirely.

Launch and actual state

Preparation checks signed owner, exact local key identity, host, runtime, workspace, readiness and the selected runtime's catalog-declared MCP executable. Codex/buzz-agent declare buzz-dev-mcp; Goose/Claude do not declare a separate server. Named launches refuse a missing/nonexecutable declared tool and reassert its resolved command after inherited env. Default retains the existing optional MCP skip behavior; optional git credential helpers are not configuration tools.

App preparation also binds effective team instructions and channel/thread session partitioning: both change the session's instruction/context inputs. Edits to these apply on the next preparation, rather than changing an in-flight preflight. Other app state (replay floor, process nonce, logging, shutdown/admission fences) remains invocation/operational policy, not a snapshot of all app state.

Ordinary async mesh preflight runs outside the transition lock. Callers fence owner/community after await, then revalidate the plan under ordinary admission before shared spawn. Pair registration validates before reaping an existing child and shared spawn checks again. Stop timestamps alone do not invalidate a plan; changes to its launch inputs do. Scope changes and configuration revision changes cannot silently substitute another launch. Ordinary Default selection is fenced too, without imposing strict readiness on its legacy setup path. App-launch restore captures/preflights the scoped selection and checks the current record before terminating untracked pair state.

The running pair and durable runtime receipt stamp the launched reference. Selection and edits never rewrite that receipt. A different already-running configuration returns Stop-before-Start rather than satisfying the new request. The existing Stop/generation/authority fences still apply. Ordinary Default Start keeps its legacy setup behavior; explicit/catalog Default checks readiness.

A native spawned child is not proof of a successful ACP session or selected model. Strict model enforcement belongs to ACP's session boundary; no provider model fallback is an acceptable success for a named selection. The final native env sets BUZZ_ACP_REQUIRED_MODEL to the exact prepared wire ID after inherited, harness and mesh writes; non-Claude BUZZ_ACP_MODEL is pinned too. Default removes both strict variables. Claude retains A1 (ANTHROPIC_MODEL, no BUZZ_ACP_MODEL). ACP requires matching fresh session/current-model or verified switch evidence before any prompt, not merely catalog membership or a successful child spawn.

Remote Start credentials

Remote-initiated Start uses the same destination-local credential behavior as ordinary local Start. The owner must independently provision the agent's matching identity key on that host. Buzz does not transfer/distribute keys, issue a broker session, or enroll a host through lifecycle messages. The native shared launcher may pass that already-local key to its child just as ordinary Start does; lifecycle requests/results never carry keys, resolved credentials, or local paths.

Catalog and preflight require the exact owner/community/agent/host configuration ID and revision, matching local identity, executable harness/tools, workspace and runtime/provider prerequisites. Launch reads bypass a warm keyring cache and never migrate a missing key into existence. Missing, unreadable or wrong identity means ineligible, not an eligible inventory host. Catalog eligibility is revalidated after async preflight. It is advisory and expires, never launch authority.

Execution repeats those checks under the shared admission lock before destructive Restart and after teardown, so a revoked key cannot be recovered from a captured plan. Lifecycle success/failure, Stop, and cleanup save only metadata into a fresh raw store; it never persists captured/hydrated credentials or migrates keys. Ownership and generation reads likewise do not hydrate or migrate keys. The request deadline also survives through Stop into shared spawn. Failure after Stop is Failed, not Running or automatic resurrection. A missing key does not hide a still-running process or block ordinary owner-authorized Stop. Move preflights before source Stop and rechecks expiry and exact revision afterward; same-host switches use these same fences. General host inventory is retained; selection and running configuration are separate. No new provisioning UX is implied.

Regression evidence

runtime_configurations/tests.rs binds migration, scope-preserving writes, foreign refs/hosts, plan revalidation and shared child spawn. The child is a shell fixture, not a real model. RuntimeConfigurations.test.mjs mounts the editor with mock IPC and checks exact revision, next-launch-only writes, failure and unmount fences. runtime_configurations/tests/remote_credentials.rs exercises the signed receiver and shared launch with synthetic identities and bounded child processes, including actual Stop-time credential/executable loss and post-Stop expiry. Run it on Unix with cargo test --manifest-path desktop/src-tauri/Cargo.toml --no-default-features managed_agents::runtime_configurations::tests::remote_credentials -- --test-threads=1 (13 tests, including the credential-persistence child module; default system-keyring builds exclude the fixture). These fixture suites do not constitute real-model or two-Desktop acceptance.