buzz/docs/remote-agents.md

Remote Agents and Their Management: A Formal Specification

draft

Abstract

This document specifies the protocol by which Buzz Desktop delegates the execution of a managed agent to a remote substrate — any compute environment other than the local machine — through a backend provider binary, and specifies the lifecycle contract every provider and every remotely-run agent must satisfy. It covers three layers:

1. The provider protocol — a zero-registration plugin contract between the desktop and any executable named buzz-backend-<id>: discovery, the info and deploy operations, payload schema, and the security obligations on both sides of that boundary.
2. The remote lifecycle model — how a remote agent is started, observed, stopped, and reaped, given the deliberate design constraint that the desktop holds no management channel to the remote process. Relay presence is the sole status signal; shutdown is a relay message; liveness bounds are enforced by the agent harness itself, not by the desktop.
3. The Kubernetes binding — the first conforming provider, buzz-backend-kubernetes, which realizes the contract as a bare Pod running the sprig image.

We state five invariants — identity fail-closed, no secrets in configuration, presence-is-status, at-most-one-live-instance, and intentional-termination-is-final — and argue each from the protocol rules.

A scoping note that governs the whole document: the desktop is one launcher among many. What makes a process a live Buzz agent is a keypair, a NIP-OA auth tag, and a relay URL, handed as environment to the buzz-acp harness; anything that can set that environment and exec the harness — a bash script, a systemd unit, a CI job, or this document's provider protocol — is a conforming launcher. §Launchers states which obligations bind whom.

As with the git specification (git-on-object-storage.md), naming the trust boundary is part of the claim: a provider binary is arbitrary code that is handed an agent's private key, and this document states exactly which properties hold despite that, which hold only if the provider is honest, and which are explicitly the user's acceptance.

Scope and Non-Goals

This specification defines management-plane behavior: how agents get to a substrate, how their state is observed, and how their lifetime is bounded. It deliberately does not specify:

• Agent conversational behavior. What the agent does with events is governed by the ACP harness (buzz-acp) and the NIPs it implements (NIP-OA, NIP-AE, NIP-AA, …), unchanged by where the harness runs.
• Malicious-provider containment. A provider binary receives the agent's nsec by design — that is its job. The protocol bounds the desktop's exposure (discovery-only resolution, output caps, secret redaction, anti-secret config validation, an explicit UI trust warning) but cannot make a hostile provider safe. Choosing to run a provider is a trust decision the UI surfaces to the user; this document does not claim otherwise.
• Substrate security. Kubernetes RBAC, namespace isolation, and secret encryption at rest are cluster-operator concerns. The Kubernetes binding states its residual exposure (§K8s Secrets) rather than claiming isolation it does not provide.
• Liveness of the substrate. That a pod schedules, that an image pulls, that a cluster is reachable — empirical, not formal. The protocol specifies only how such failures are reported (structured error, redacted, fail-closed).

System Model

Five principals:

• Desktop D — the Buzz Desktop app. Holds the agent's identity (nsec in the OS keyring), its configuration record, and the only UI. Trusted.
• Provider P — an executable buzz-backend-<id> on D's machine. Invoked one process per operation: JSON request on stdin, JSON response on stdout, exit code carrying one bit (zero = output trustworthy, nonzero = failure regardless of stdout — §Invocation). Untrusted by D for everything except the job it is explicitly given (deploying the agent, which requires the key). All of P's output is treated as hostile (§Provider Output).
• Substrate S — the remote compute environment P deploys into (a Kubernetes cluster for the binding in this document). Opaque to D; D never talks to S.
• Agent A — a buzz-acp harness process (plus the ACP agent under it) running on S, holding the nsec it was given, connected to the relay.
• Relay R — the Buzz relay. The only channel that connects D to a running A. Everything D knows about a live remote agent, it learns from R.

The defining constraint, stated as a design axiom:

• (M1) No management channel. After a successful deploy, D holds no persistent management session to A on S, and the desktop↔provider protocol contains no substrate API: no status query, no exec, no log fetch, no kill. All post-deploy observation and control flows through R: status is relay presence (kind:20001), stop is a relay message (!shutdown), and reconfiguration is a future re-deploy. The reduction M1 buys is protocol surface, not credential absence: ambient substrate credentials may well exist on D's machine (the Kubernetes binding uses the user's kubeconfig by design), and D can always re-invoke P. What M1 guarantees is that nothing in this protocol — its persisted records, its wire operations, its stored backend_agent_id — constitutes or requires a channel to the substrate. The price is the staleness bounds in §Presence.

An agent's identity is a Nostr keypair. The agent record on D carries: name, relay_url, the nsec (keyring-hydrated), the NIP-OA auth tag attesting owner authorization, agent_command/agent_args (the ACP agent the harness spawns — goose, claude-agent-acp, codex-acp, buzz-agent, or any user-supplied command: this is the configurable harness requirement), effective system_prompt/model/provider, timeout and parallelism knobs, the respond_to gate, merged env_vars, and a backend discriminator: Local or Provider { id, config }.

Launchers

The five principals above describe the provider-managed launch path. That path is not the definition of a remote agent, and this section states the actual layering, because the obligations in this document do not all bind at the same layer. Three contracts, nested:

1. The agent/harness contract — binds every launcher. A live Buzz agent is a buzz-acp process holding a keypair, a NIP-OA auth tag (or resolved owner pubkey), and a relay URL, delivered as environment. The relay authenticates the keypair and the auth tag — never the launcher. At this layer live: fail-closed identity (I1's property, enforced wherever the env is assembled), presence publication (I3), owner-verified !shutdown, and intentional clean exit is terminal to automatic supervisor restart (I5). A bash script that exports BUZZ_PRIVATE_KEY, BUZZ_RELAY_URL, BUZZ_AUTH_TAG and execs the harness is a conforming launcher at this layer — today, with no code change.
2. The provider/deployer contract — binds provider-managed launches only. The two operations (info/deploy), the reconciliation loop, and at-most-one-live-instance per deploy scope (I4). Hand-launched agents sit outside it by construction: a launcher that bypasses the provider protocol takes on the uniqueness discipline itself, exactly as the cross-scope boundary in I4 already states. The protocol cannot and does not promise a global singleton across unrelated launchers of the same nsec.
3. The binding policy — per substrate. Fingerprints, fenced deletes and 409 discrimination, restart-policy selection, the default idle bound, and the grace budget are Kubernetes-binding policy (§The Kubernetes Binding). A different substrate (the systemd/SSH deployer of PR #3449 is the live example) conforms to layers 1–2 and writes its own layer 3; it is not "non-conforming" for lacking pods.

The desktop is therefore one launcher among many, and the provider protocol is the desktop's door to substrates, not the only door. §Conformance carries one checklist per layer.

Invariants

The protocol maintains five invariants. Each is stated with the mechanism that enforces it and the boundary beyond which it does not hold.

A design obligation governs the whole list: the complexity budget is spent in this document, not in the code. Every guarantee here was chosen because its enforcing mechanism is one small, boring thing — a refusal at payload construction (I1), a key-shape validator (I2), an ephemeral event the agent already publishes (I3), a deterministic name plus one annotation compare (I4), a timer that fires an existing shutdown channel (I5). The same rule holds below: the deploy state machine is one loop over seven ordered rows; the Secret scheme is "unique name, write first, reference exactly"; GC is one label-select with two filters (annotation, same-clock age). Where a richer property would have demanded machinery — Leases, controllers, ownerReferences, a management channel — the spec either found a name-and-timestamp argument that makes the machinery unnecessary or dropped the property and said so (§Non-Goals, M1). A conforming implementation that is not small is evidence of a spec bug; report it as one.

• (I1) Identity fail-closed. No agent is ever launched with an empty or missing private key: whatever assembles the harness environment — desktop, provider, bash script — MUST refuse rather than launch identityless (§Launchers, layer 1). In the provider path this is enforced at payload construction: if keyring hydration left the nsec empty, build_deploy_payload refuses (mirroring local spawn's spawn_key_refusal), so no deploy request is ever emitted with an empty key. Boundary: a provider that discards the key and launches an identityless pod is a broken provider; the payload rule governs what D sends, not what P does with it — which is why the property also binds at P's env assembly and at every non-provider launcher.

• (I2) No secrets in configuration. provider_config — the persisted, schema-rendered, UI-visible settings object — MUST NOT carry secrets. Enforced by validation: flat object, scalar values only, ≤20 fields, ≤64KB, and any key whose word-split contains secret|password|token|key|credential is rejected. The match is against key names, so it is a lint with false positives: a field like ssh_key_path holds a path, not a credential, and is refused anyway — a provider author hitting this MUST rename the field (e.g. identity_file), not weaken the validator; the rule's job is making "put the secret in config" fail closed, and cheap false positives are the accepted price. Secrets flow exclusively inside the deploy payload (private_key_nsec, auth_tag, env_vars), which is never persisted by D and never rendered. Corollary for providers: cluster credentials MUST come from ambient substrate config (e.g. kubeconfig resolution), never from provider_config.

• (I3) Presence is the status. D derives a remote agent's live state exclusively from relay presence events self-signed by the agent key: online/away/offline (kind:20001, ephemeral, WS-published). The deployment axis (deployed/not_deployed, from the stored backend_agent_id) is bookkeeping, not liveness. Staleness bound: presence can be wrong for the window between an abnormal agent death (SIGKILL, node loss) and the relay's presence expiry — 180 seconds (PRESENCE_TTL_SECS, buzz-pubsub/src/presence.rs:16; the vision's "a bounded wrong dot, never an indefinite one"), the accepted cost of M1. The specific number is a relay-wide constant, not a remote-agent choice: #3783 raised it from 90s to keep a three-heartbeat expiry window after the desktop heartbeat moved to 60s. What I3 promises is that the window is bounded, not its width. The Kubernetes binding minimizes the avoidable part of that window by sizing the termination grace period to the harness's full graceful-shutdown path (§K8s Grace). Two consequences the bound imposes: (a) the harness's presence-suppression knob, BUZZ_ACP_NO_PRESENCE, MUST join RESERVED_ENV_KEYS — locally the knob is cosmetic (the process and UI remain visible), but remotely M1 makes presence the only signal, so an unreserved user env var would convert "wrong for ≤180s" into "wrong indefinitely" and silently disarm the one bound in print; (b) presence is scoped to a community: the relay derives community from its host, so the deploy-time relay_url binds the body to one community for its whole life, and a workspace observing through a different community sees the agent offline while a deploy against it correctly no-ops — a known UX boundary (the cross-scope boundary I4 admits, seen from the status side), stated here so the two honest-but-conflicting readouts are diagnosable.

• (I4) At most one live instance per agent key per deployment scope. Within one provider's deployment scope (for Kubernetes: one namespace), there is never more than one Running instance of a given agent pubkey. Enforced by the deploy reconciliation loop (§Deploy State Machine): deploy is keyed on the derived pubkey, a live instance maps to strict no-op, and — because two deploys can race — create/delete conflicts MUST converge (re-read and return the winner) rather than fail; deterministic instance naming makes the substrate itself reject a second live instance. Boundary: the protocol cannot prevent the same nsec being deployed to two different scopes (two namespaces, two clusters, or remote

  • local simultaneously) — the relay tolerates multiple connections per key, and preventing this would require the global registry M1 forbids. Deploying one key twice is user error with confusing-but-safe results (both instances answer), not a safety violation.

• (I5) Intentional termination is final. A remote agent stops when told, stays down when it stops, and is never silently resurrected: an instance whose harness is live terminates on owner !shutdown or when a configured inactivity bound expires, and no supervisor restarts an instance that exited intentionally. "Final" means terminal to automatic supervisor restart — the owner may always issue a fresh Start; that is resurrection working as designed, not a violation.

  Lifetime is owner policy, not law. The inactivity bound is the harness's opt-in self-stop (§Auto-Stop, default disabled). An owner may always choose no inactivity bound — declaring an indefinitely-lived agent. How that choice is expressed is per-binding: the Kubernetes binding opts in with a 2h schema default because a pod is metered compute with nobody watching it, and spells "no bound" as its inactivity_seconds: 0 field (§Pod shape); a hand launcher simply never sets the reaper env. Either way it is a legitimate, explicit choice, not a conformance failure: the invariant was never "every instance terminates" (a continuously active agent is intentionally unbounded — that is the product); it is "termination, once intended, sticks".

  Restart policy follows lifetime policy. The distinction that makes indefinite agents safe is intent vs accident: dying on purpose (!shutdown, inactivity reap) is final; dying by accident (node eviction, OOM) may restart the body — same key, same agent, the resurrection story working for the owner. Stated launcher-neutrally: if a supervisor exists, its restart policy MAY revive an abnormal death and MUST NOT revive an intentional clean exit. A launcher with no supervisor at all — a hand-launched process on a VPS — satisfies this vacuously: nothing restarts anything. How bounded vs indefinite lifetime maps onto a concrete supervisor policy is binding policy ([L3]), realized and documented by each binding — this binding's mapping lives in §Pod shape; a systemd binding's in its unit directives. Any revive-on-abnormal-death policy carries a universal precondition: the supervisor can distinguish intent from accident only if the harness formally promises clean exit = exit code 0 on every intentional path and nonzero otherwise, pinned by test. At 28ae6cd21 that property is emergent, not defended (Known Defect 6); restart-on-failure before the pinned contract is how a refactor silently converts every clean stop into a restart loop with no failing test. Ordering is normative: exit-code contract first, restart-on-failure second — the identical seam in every supervisor that offers the distinction. An always-restart policy remains non-conforming at any layer: it resurrects after a clean exit, defeating !shutdown.

  Enforcement: the self-stop lives inside the harness (the only place that can see activity, per M1) (§Auto-Stop), and each binding makes it effective on its substrate by requiring that harness exit terminates the substrate's unit of execution (this binding's realization — the harness as the container's signal-receiving process — is §Pod shape, [L3]) and that any supervisor's restart policy respects intent as above. Boundaries: (a) the guarantee is conditional on a live harness event loop — a wedged process that cannot run its reaper timer cannot reap itself, and M1 means nothing else will (the mitigation is the substrate operator's, e.g. a namespace-level TTL policy, out of scope per §Non-Goals); (b) restart policy prevents resurrection, it does not prove process exit; (c) I5 bounds agent lifetime, not substrate residue — residue (in this binding, a Completed pod object) persists for forensics until the next deploy's GC (§K8s GC).

Provider Protocol

Discovery

D scans, in order: the directory containing the desktop executable, every entry of PATH, and ~/.local/bin, for executables named buzz-backend-<id>. The suffix after the prefix is the provider id and MUST match [a-z0-9][a-z0-9_-]*. On Windows, an .exe/.bat/.cmd extension MUST be stripped before the id is derived (see §Known Defects — as of 28ae6cd21 it is not, so Windows providers probe but cannot deploy). First hit per filename wins. Discovery executes nothing.

Shadowing and invalid candidates are diagnosable, not silent. First-hit wins is the right selection rule (it is kubectl's), but kubectl also warns when a later-PATH plugin is shadowed, and Docker's CLI reports invalid plugin candidates with reasons. Discovery MUST retain, and the UI and deploy-time errors MUST be able to surface: the selected binary's full path, any shadowed candidates for the same id (later-PATH duplicates), and candidates rejected for malformed names. A deploy error that names which binary ran answers the first question a user with two copies of buzz-backend-kubernetes will ask. (At 28ae6cd21 discovery records only the winning path — a desktop change alongside Known Defect 3's.)

Resolution rule. Every subsequent operation resolves the provider id against the current discovery set. A stored binary path on an agent record is a cache, revalidated against both the current candidates and the recorded id before every use. A record edit can therefore never redirect an operation to a binary discovery would not have found.

Pre-secret negotiation gate (normative). Declaring protocol_version is worthless if nothing checks it before the nsec crosses the trust boundary — and at 28ae6cd21 nothing does: provider_deploy invokes deploy directly, so a stale UI-time probe (or a binary replaced on PATH since that probe) can receive private_key_nsec unchecked (Known Defect 5). The deploy path MUST: resolve the provider id once; copy the resolved candidate into a desktop-owned, private, non-writable staging file, computing its digest during the copy; invoke info on the staged artifact; validate an explicit, supported protocol_version (§Info — absence is an error); invoke deploy on the same staged artifact; delete it afterward. Staged bytes are what "same executable identity" means here: the nsec goes to the exact bytes that answered info. Path-plus-metadata comparison (dev/inode, size, mtime) is NOT an acceptable substitute for this guarantee — unchanged metadata can miss an in-place content rewrite, and a pathname can be swapped between the check and the moment Command opens it, which is precisely the check-then-exec race the gate exists to close. A UI-time probe result MUST NOT satisfy this gate. If a platform makes staged execution impossible for some provider (e.g. an executable that only runs from its install location due to relative dependencies or signing constraints), the implementation MUST NOT silently fall back to metadata and still claim this gate: it degrades explicitly to accidental-replacement detection (path + file-identity compare), surfaces that weaker level in the deploy diagnostics, and the spec text for that platform carries the narrower claim. Remembered digest-based approval (Terraform-lock style) is a stronger follow-up, not a v1 requirement.

Invocation

One process per operation. D spawns P with cwd = the agent workdir, writes exactly one JSON object to stdin, closes stdin. P writes exactly one JSON object to stdout and exits. Requirements on D (all implemented):

• Bounded reads: stdout capped (1MB), stderr capped (64KB), no read_to_end on pipes a daemonizing child could hold open; deadline polling with try_wait.
• Non-zero exit is failure even if stdout parsed. Partial output from a crashed operation is never trusted.
• {"ok": false, "error": …} is the in-band failure form.
• Environment: P inherits D's environment. On macOS a GUI launch means launchd's minimal PATH; providers whose substrate credentials invoke helper binaries (kubeconfig exec plugins) MUST self-augment their PATH (§K8s Auth) rather than assume a login shell.

Provider Output Is Untrusted

Everything P emits — stderr, error strings, the response object — is scrubbed before storage or display: every value from the request's env_vars (longest-first, length ≥4) and every nsec1…/sprt_tok_… token is redacted. Rationale: P legitimately holds secrets during deploy; P echoing them (in a stack trace, a kubectl error, a debug line) must not propagate them into D's persisted last_error or logs.

info

request:  {"op": "info", "request_id": "<uuid>"}
response: {"ok": true, "name": str, "version": str,
           "protocol_version": int, "description": str,
           "config_schema": <JSON Schema>}
timeout:  10s

version is the provider's software version — useful in error reports, useless for compatibility. protocol_version (this document: 1) is the wire-contract version, following the pattern Docker's CLI plugins (SchemaVersion) and HashiCorp go-plugin (negotiated protocol version) both converged on: the desktop rejects a provider whose protocol_version it does not speak, with an error naming both versions and the binary path, instead of failing later inside a half-understood deploy. A missing protocol_version is an error, not a presumed 1: there is no deployed provider population to grandfather, and a gate that infers compatibility for exactly the class of binary that never declared any defeats its own pre-secret guarantee (§Discovery). Fail closed — it is also simpler: no migration clock, no "major cycle" to define.

config_schema drives the UI form: properties[*].default prefill, string/number/boolean coercion, required gating. A provider MAY compute defaults freshly per call (the Kubernetes binding generates a random namespace default this way — §K8s Namespace). The schema's fields are subject to I2 validation when the user's values come back in deploy.

deploy

request:  {"op": "deploy", "request_id": "<uuid>",
           "agent": <payload>, "provider_config": {…}}
response: {"ok": true, "agent_id": str}
timeout:  600s

The agent payload (field list per commands/agents_deploy.rs: deploy_payload_json at 28ae6cd21; the launch block is a normative addition not yet emitted — Known Defect 3):

field	meaning
name	display name
relay_url	concrete WS URL (workspace fallback materialized — the remote side has no workspace notion)
private_key_nsec	the identity (I1: never empty)
auth_tag	NIP-OA owner attestation
agent_command, agent_args	the ACP agent under the harness (configurable-harness support). At 28ae6cd21 these are raw record bytes — see Known Defect 3: the normative source is the resolved descriptor in launch
system_prompt, model, provider	effective values, live-persona-first resolution
turn_timeout_seconds, idle_timeout_seconds, max_turn_duration_seconds	harness timeout knobs
parallelism	concurrent-turn bound
respond_to, respond_to_allowlist	inbound author gate
env_vars	merged user env: global < persona < agent
launch	normative addition (§Launch data): the desktop-resolved launch contract — command (name, not path), normalized args, layered env, overridable policy_env, and owner_pubkey

Reserved-key rule (normative for providers). D strips BUZZ_PRIVATE_KEY, NOSTR_PRIVATE_KEY, BUZZ_AUTH_TAG, BUZZ_RELAY_URL, and the other reserved keys from env_vars before merge. A provider MUST construct the agent environment's identity variables from the top-level payload fields (private_key_nsec → BUZZ_PRIVATE_KEY/NOSTR_PRIVATE_KEY, auth_tag → BUZZ_AUTH_TAG, relay_url → BUZZ_RELAY_URL); reading env_vars for them yields an identityless agent. A related hardening D performs is part of the contract's rationale: env keys are validated as POSIX-shaped names before merge, because a key like BUZZ_AUTH_TAG=x smuggled through Command::env would bypass the reserved-key strip entirely. A provider materializing env_vars into a substrate object (e.g. a Kubernetes Secret) MUST likewise never let a user-supplied key collide with or reconstruct a reserved key.

agent_id is P's stable handle for the deployment (the Kubernetes binding returns the pod name). D stores it as backend_agent_id; its presence is the deployed axis of I3.

There is no undeploy op in v1. Deletion of a remote agent from D orphans the substrate objects; the UI therefore requires an explicit force_remote_delete confirmation, and the binding's GC + I5 bound the orphan's cost (the agent self-stops; the pod residue is reaped on the next deploy of the same key, or manually).

Launch data (launch)

Reproducing the local spawn's launch semantics requires state only the desktop can resolve: the runtime-metadata table (model_env_var, provider_env_var, provider_locked, default_env — discovery.rs:75-207), the six-layer env resolution, harness-definition command/args fallback, team instructions, session title, the respond-to gate's legacy owner fallback, and the mesh rewrite. A provider MUST NOT reimplement that derivation — it would be a second copy of desktop runtime discovery, drifting from the first. Instead the payload carries a typed launch block that D resolves with the same code paths as local spawn, and the provider applies it mechanically.

"launch": {
  "command":      str,          // command NAME (e.g. "goose"), never a host path
  "args":         [str],        // normalized args, definition fallback applied
  "env":          {str: str},   // layered env: baked → runtime metadata →
                                // definition → global → persona → agent
                                // (resolve_effective_harness_descriptor)
  "policy_env":   {str: str},   // overridable behavior defaults (tier 1, below):
                                // runtime default_env (e.g. GOOSE_MODE=auto),
                                // BUZZ_ACP_RELAY_OBSERVER, BUZZ_ACP_LAZY_POOL=true,
                                // BUZZ_ACP_SESSION_TITLE (resolved),
                                // BUZZ_ACP_TEAM_INSTRUCTIONS, BUZZ_ACP_MODEL,
                                // MCP_HOOK_SERVERS=* (mcp_hooks runtimes only)
  "owner_pubkey": str | null    // resolved workspace owner (hex) — legacy
                                // BUZZ_ACP_AGENT_OWNER fallback, non-secret
}

launch.command/launch.args come from resolve_effective_harness_descriptor (readiness.rs:125) — the same resolver local spawn uses — which fixes two silent divergences the raw record fields carry: a persona-derived agent_command is a blank record byte, and definition-provided agent_args are lost when the instance's own args are empty. launch.env is that descriptor's layered env, which is where per-runtime model/provider injection lives (GOOSE_MODEL/ GOOSE_PROVIDER for goose; nothing for provider_locked runtimes like Claude; BUZZ_AGENT_MODEL/BUZZ_AGENT_PROVIDER for buzz-agent). A fixed provider → BUZZ_AGENT_PROVIDER mapping is wrong for three of the four built-in runtimes and is why this block exists.

What policy_env carries — and deliberately does not. Its irreducible wire fields are exactly three scalars plus the metadata-derived defaults — plus the four record-derived behavior knobs that would otherwise be mis-tiered (below):

• BUZZ_ACP_TEAM_INSTRUCTIONS — the only truly non-reconstructible policy value: effective_team_instructions (spawn_hash.rs:41-52) needs the desktop's TeamRecord store, which no pod can reach.
• BUZZ_ACP_SESSION_TITLE — sent resolved (resolve_session_title, runtime/metadata.rs:45), not as its display_name/name inputs. The resolution strips control characters, and that property transfers: an interior NUL fails a local spawn at the env boundary, and would make the Kubernetes apiserver reject the whole pod spec — a rename must degrade, not turn into a deploy failure.
• owner_pubkey (block-level, not env) — the respond-to gate is otherwise fully reconstructible from payload fields (build_respond_to_env, runtime.rs:380-421); this is its one irreducible input.
• Runtime default_env (e.g. GOOSE_MODE=auto) — computed from the runtime metadata table only, unconditionally. The local spawn applies each default only if std::env::var(key).is_err() (runtime.rs:733-737) — a test of the desktop's own ambient environment. That makes "the resolved local env" not a pure function of the record; serializing it verbatim would bake a host accident into the pod. Launch data MUST be computed from record + config alone.
• BUZZ_ACP_LAZY_POOL=true — a deliberate pick, not a transcription: the two local paths disagree (manual Start is eager, runtime.rs:1001; launch restore is lazy, restore.rs:333, precisely to avoid "N idle brains on every launch"). Remote pods take the lazy arm: an idle LLM pool in a cluster is billable waste with no user watching it warm up.
• MCP_HOOK_SERVERS=* when the resolved runtime has mcp_hooks (runtime.rs:594-598; buzz-agent only at 28ae6cd21) — gates the _Stop/_PostCompact hook tools.
• BUZZ_ACP_SYSTEM_PROMPT, BUZZ_ACP_IDLE_TIMEOUT, BUZZ_ACP_MAX_TURN_DURATION, BUZZ_ACP_AGENTS — resolved by the desktop from the record's system_prompt / idle_timeout_seconds / max_turn_duration_seconds / parallelism (each omitted when null, matching the local spawn's conditional emission). BUZZ_ACP_AGENTS is the effective parallelism: min(record.parallelism, harness_cap) where the cap is harness-specific (e.g. OpenClaw is capped at 5). These are tier-1 control-plane keys: BUZZ_ACP_AGENTS is in RESERVED_ENV_KEYS (env_vars.rs) so the desktop-resolved effective value cannot be overridden by a definition env var; the others are tier-1 by local fact (written before the user env layer). A provider that independently mapped the top-level payload copies after launch.env would invert the precedence for those remaining keys — the structured field silently defeating an override that works locally — which is why the provider MUST NOT remap them (§Entrypoint mapping table).

BUZZ_ACP_DEDUP and BUZZ_ACP_MULTIPLE_EVENT_HANDLING are deliberately unset: the local spawn writes queue/steer (runtime.rs:730-731), and those are exactly the harness's clap defaults (config.rs:344,356) — a pod that omits both is behaviorally identical, and adding rows for them would imply a divergence that does not exist. BUZZ_MANAGED_AGENT is likewise deliberately absent remotely: it brands local harness processes so the desktop's orphan sweep and instance reaper can prove ownership by scanning process env (orphan_sweep.rs, instance_reaper.rs) — there is no local process to sweep.

Environment precedence (normative) — three tiers, later wins:

1. Overridable behavior defaults — launch.policy_env. Most keys here are deliberately non-reserved (env_vars.rs documents the narrow set that IS reserved): power users may bypass the dedicated UI fields for system prompt, model, idle timeout, etc. Locally the user env is written after them (runtime.rs:860 and its comment). A policy-wins order here would make remote agents ignore overrides local agents honor. Exception — BUZZ_ACP_AGENTS: this key IS reserved (env_vars.rs:RESERVED_ENV_KEYS) so the desktop-controlled effective parallelism (applying any per-harness cap) cannot be bypassed by a user-supplied definition env var. The reserved-key strip removes any user copy before serialization, so the tier-1 value survives.
2. User/layered env — launch.env. User env_vars need no separate slot: the descriptor's layering already merged them (global < persona < agent), so a provider applies launch.env and MUST NOT re-merge the legacy env_vars field on top.
3. Authoritative — unoverridable at every layer, written last and backed by the reserved-key strip: the identity variables from top-level payload fields (§Reserved-key rule), the respond-to gate values, BUZZ_ACP_AGENT_OWNER, the inactivity bound, BUZZ_ACP_MCP_COMMAND, and BUZZ_MANAGED_AGENT_START_NONCE. For the nonce, the provider MUST set it to the attempt's generation token (§K8s Secrets): the harness stamps it into every observer lifecycle frame (buzz-acp/lib.rs:1501), so the Secret generation and the lifecycle correlator become one identity instead of an empty string.

Host-resolved values MUST NOT be forwarded and MUST be re-derived in-image. The local spawn sets several variables to absolute paths on the desktop's filesystem; forwarding them into a container is a guaranteed failure. The provider/image re-derives:

• the harness and agent binaries: launch.command is a name, resolved against the image's own PATH (BUZZ_ACP_AGENT_COMMAND), and BUZZ_ACP_MCP_COMMAND=buzz-dev-mcp likewise;
• CLAUDE_CODE_EXECUTABLE — a resolve_command() host path (configure_runtime_cli, runtime.rs:424-446), same class as the command paths: image-local resolution or unset;
• PATH itself (the desktop's augmented PATH is meaningless in the image);
• git credential/signing helper locations — the relay-URL scoping of the credential config is normative (never a global helper), the helper path is image-local (§Image);
• BUZZ_ACP_SETUP_PAYLOAD is desktop-computed readiness state and MUST NOT appear in a remote pod.

Owner resolution (normative): the provider MUST have either a non-null auth_tag (→ BUZZ_AUTH_TAG) or a non-null launch.owner_pubkey (→ BUZZ_ACP_AGENT_OWNER) before any mutation; if both are null it MUST refuse the deploy. Without an owner the harness cannot match !shutdown (buzz-acp/src/lib.rs: resolve_agent_owner, main-loop owner check) and the agent answers its own stop command conversationally — §Stop would be describing a mechanism that does not work. BUZZ_ACP_AGENT_OWNER is a reserved key, so this value can only arrive as authoritative launch data, never through user env.

Buzz shared compute (relay-mesh) is non-deployable, and this is forced, not chosen. The mesh rewrite resolves to an OpenAI-compatible transport at http://127.0.0.1:9337/v1 (relay_mesh.rs: RELAY_MESH_API_BASE_URL) — a loopback proxy on the desktop. Serializing that policy into a pod points the agent at its own localhost, where nothing listens. D already rejects mesh-configured creates on non-local backends (agents.rs: normalize_relay_mesh); the deploy path MUST equally fail closed — before any mutation — when the effective provider resolves to relay-mesh, rather than passing relay-mesh through as if it were a runtime provider. Remote mesh transport is a possible v2 (an in-image mesh client), not a v1 silent breakage.

The governing invariant: a remote agent's environment differs from the same record's local spawn only where the substrate forces it (paths, PATH, readiness). Anyone adding a local behavior knob adds it to the shared resolver, and both spawn paths inherit it; there are not two derivations to keep in sync.

Deploy State Machine

start on any non-Local agent unconditionally issues deploy — the desktop does not track substrate state (M1). Deploy is therefore not "create": it is converge to at-most-one-live-instance (I4), implemented as a reconciliation loop keyed on the agent's identity within the provider's scope.

Step 0 — derive and verify identity. The payload carries the nsec, not the pubkey. Before any substrate read or mutation, the provider MUST parse private_key_nsec and derive the public key from it; a malformed or undecodable key is an immediate in-band error. Every selector, name, and comparison below uses the derived pubkey — never a caller-supplied one.

Step 1 — select and authenticate candidates. Candidate objects are selected by the (truncated) identity label, then each candidate's full-pubkey annotation MUST be compared against the derived pubkey before it is treated as belonging to this agent. Truncated selectors are collision-resistant, not collision-free: the annotation check is what makes them safe. An object whose annotation does not match MUST NOT be no-op'd against, deleted, GC'd, or have its Secret touched; the provider MUST either ignore it or fail with an explicit collision error. Only annotation-verified objects proceed.

Auto-repair is fenced to Buzz-authored, positively identified residue (normative). The destructive rows below (delete residue, replace a never-started body, GC a Secret) are legitimate only because every object they touch carries positive protocol ownership evidence — and identity evidence alone is not ownership evidence. The identity label, the full-pubkey annotation, and the create-intent fingerprint prove "matches our schema for this public identity"; all three are public, so any cluster writer can reproduce them on an object this provider never created. Every object this provider creates therefore also carries an explicit management marker — app.kubernetes.io/managed-by: buzz-backend-kubernetes plus a binding schema-version label (§Pod shape) — and no destructive repair or GC action fires unless the marker is present, on top of the annotation check and the UID+resourceVersion fence every delete already requires. This is protocol evidence, not cryptographic proof: a cluster writer can forge metadata by definition, and an actor with write access to the namespace can already delete the pod outright — the marker's job is making accidental schema collisions and third-party objects fail closed, not defeating a hostile admin. The vision's rule that a never-started body is substrate-operator residue survives with one qualifier: Buzz-authored create-state (a Secret our provider wrote, a pod carrying our verified annotations and marker) is the reconciler's to clear, because it is state the user cannot reasonably clear themselves; substrate wreckage — anything unowned, unmarked, unannotated, or ambiguously identified — still fails closed to the operator. A provider that cannot positively identify an object as its own output does not repair around it; it reports it.

Step 2 — reconcile. Ordered rules, evaluated against the verified observation; on any conflict, re-enter from step 1 rather than fail:

observed	action	rationale
instance marked for deletion (deletionTimestamp set, any phase)	wait for actual disappearance, then re-enter	the user pressed Start and the old instance is unrecoverable; returning the dying instance's id records a success that evaporates. Note: in Kubernetes there is no Terminating phase — a pod being gracefully deleted stays in phase Running for its whole grace period. The deletion mark MUST be checked before phase, or this row is mistaken for the no-op row
no instance	create, then verify startup (below)	first deploy / after GC
terminated (Succeeded/Failed)	delete residue, wait for disappearance, re-enter (→ create)	the normal restart path: how a user revives a reaped or shut-down agent
live and started (harness container running)	strict no-op; return existing agent_id	Start must never silently kill a live agent mid-turn; "already running" is the honest answer, consistent with I3
exists but never started, provably non-recoverable — referenced Secret confirmed absent (by a consistent read, below), or invalid image reference	delete (preconditioned, below), wait for disappearance, re-enter (→ create)	a pod whose harness never ran is not a live agent: nothing can be killed mid-turn (I3), it never held the identity (I4), auto-stop cannot bound it (I5's reaper lives in the harness), and no-op'ing it would return a permanently inert instance as success on every future Start. "Provably" means the provider verified the referenced object's absence or the spec-level defect itself — never a reason string alone
exists, never started, recoverable, fingerprint matches current desired create intent (below) — self-healable startup states: Unschedulable (scale-from-zero autoscaling), image pull / ImagePullBackOff, transient CreateContainerConfigError	observe until started or the operation deadline expires, then return the latest redacted condition — never delete, on this call or any later one	these states routinely self-heal — an autoscaler provisions the node, the pull retries, the kubelet re-resolves the Secret (it retries a never-created container regardless of restartPolicy). And recoverable-timeout MUST stay observational across calls: any finite pod-age threshold can collide with the cluster's own pod-age thresholds (Cluster Autoscaler's --new-pod-scale-up-delay / per-pod pod-scale-up-delay annotation — the FAQ's example is "600s"), and delete-recreate resets exactly the age the autoscaler keys on, converting a slow cold start into a livelock in which every individual decision is correct. A later deploy re-reads: started → strict no-op; still recoverable and same intent → observe under the new call's deadline without resetting pod age; provably non-recoverable → the non-recoverable row. Repeated identical Starts can therefore never delete anything, whatever the pod's age — a genuinely slow cluster persists until it heals or an operator acts, and M1 already makes substrate residue the operator's boundary
exists, never started, recoverable, fingerprint differs or absent — the recorded create-intent fingerprint does not match what this deploy would create	delete (preconditioned, below), wait for disappearance, re-enter (→ create)	this is not the same generation the user is waiting on — it is a pod built from configuration the user has since changed, and without this row the change can never materialize: the pod name is deterministic, GC only reaps terminated pods, Stop needs a live harness, I5's reaper lives in the harness, and there is no undeploy — so a never-started pod wedged by its own config (a memory_request no node satisfies, a quota-blocked namespace) would swallow every future edit while reporting only "startup not confirmed", indistinguishable from a slow cluster. Divergence is evidence, not a clock — but it has two sources, not one: a user config change, and a provider upgrade that moves the baked default image digest (§K8s image; the default is compile-time provider state, so upgrading the provider changes the computed intent with no user action). Both are deliberate: the second is the only escape from a wedge caused by a bad baked default (unpullable digest, wrong arch) — a fingerprint blind to the default resolution would hand that wedge back to exactly the population that cannot override image. The accepted cost is that a provider upgrade mid-cold-pull discards in-flight startup progress; neither source is clocked to anything the cluster keys on, so no threshold exists to collide with the autoscaler. A started pod is never touched by this row: live → strict no-op regardless of divergence (edits reach it via the documented next-generation consequence)

Startup is part of create — phase is not readiness. Pending (and even Running at the pod level) does not mean the harness started: a pod can sit in ImagePullBackOff, CreateContainerConfigError (e.g. a missing envFrom Secret), or unschedulable Pending forever, and I5's inactivity reaper cannot bound a harness that never began. Therefore deploy MUST NOT report success at pod acceptance: it succeeds only when the harness container has actually started (container state.running), bounded by the operation deadline. On failure or deadline expiry it MUST return an in-band error carrying the actionable condition (the container waiting reason / pod condition), not a generic timeout. "Live" in the no-op row above means started, for the same reason — this is the lesson ephemeral-runner controllers learned upstream (inspect container state, not pod phase). Classification MUST combine container state, pod conditions, referenced-object existence, and the recorded create-intent fingerprint — reason strings alone are not a stable fatality taxonomy, and pod age is never one (age triggers nothing destructive; see the recoverable rows and the controlled-view rule below). In particular, Unschedulable is not fatal: a scale-from-zero pod reports it while the autoscaler provisions capacity, and the kubelet retries a container that never got a container status regardless of restartPolicy: Never (ShouldContainerBeRestarted returns true for a nil status before the restart-policy check — kubelet/container/helpers.go), which is exactly why a briefly-missing Secret self-heals. restartPolicy: Never suppresses restarting a container that ran and died; it says nothing about one that never started. A consequence to state plainly: once success includes container start, the 600s operation deadline is the cold-start budget — image pull on a fresh node, scale-from-zero scheduling, all of it. But the deadline bounds how long one Start waits synchronously, nothing more. Deadline expiry on a still-progressing startup is reported as "startup not confirmed within the deadline", and MUST NOT trigger cleanup or forced recycle — on this call or any later one (the recoverable rows above — what replaces a never-started pod is a config change, never a deadline): the next deploy's reconciler observes whatever the startup became and takes the matching row, preserving the pod's creationTimestamp for whatever cluster machinery keys on it. Whether ten minutes fits the intended cluster class is a product ruling, not a correctness one.

One create attempt per call (normative). The replacement rows above — terminated, never-started provably broken, never-started divergent — exist to clear residue from a previous life. Once a deploy call has created its own pod, a classification that would replace that pod means the attempt this call just made has already failed: the harness started, rejected its configuration, and exited (the deterministic startup failure), or the pod was proven broken. Re-running the identical create against the same cluster inside the same call cannot produce a different outcome; what it produces is a hot delete/mint/create cycle every poll interval for the whole operation deadline, one immutable Secret per cycle (measured live: 107 Secrets in a single 600s call), every one younger than §K8s GC's orphan age gate — a bounded-call resource DoS and nsec-bearing-Secret amplifier. A binding MUST NOT delete-recreate a pod created by the same deploy call: it MUST return the in-band error carrying the latest condition (for a terminated container, the exit code and reason — never the terminated message, which is process-composed output under the same redaction rule as pull messages). The failed attempt's pod and Secret are deliberately left in place: the pod is terminated, so the next Start's preflight GC collects the pod and its referenced Secret together before that call's own single attempt — retry is thereby gated on fresh owner intent, and litter is bounded at one pod plus one Secret per press, not per poll. This bounds attempts, not observation: the recoverable rows still observe a slow startup for the full deadline, and residue from previous lives is still replaced exactly once on the way to this call's attempt.

Destructive decisions come from views you control — reads and writes both (normative). This is one rule with three instances, stated once so nobody optimizes an instance away. §K8s GC's same-clock rule is the time instance. The other two live here:

• Reads: every read whose result can authorize a deletion — the Secret-absence confirmation above, and the candidate list the GC pass filters — MUST use most-recent semantics (resourceVersion unset, a quorum read). resourceVersion: "0" is served from the watch cache, which the Kubernetes API contract explicitly allows to be much older than anything the client has already observed; a stale Secret-absence read would delete a pod whose Secret exists and whose container was about to start — the GC race again, arriving through read consistency instead of a clock.
• Writes: a fresh read is necessary but not sufficient — the kubelet can start the container between observation and delete. Every DELETE authorized by a classification MUST carry preconditions.uid and preconditions.resourceVersion from that exact observation (metav1.Preconditions supports both), making the edge a compare-and-delete. A failed precondition is neither an error nor permission to retry the delete: re-enter from step 1 and classify the object that exists now. The full-pubkey annotation check remains — the precondition pins when, the annotation pins whose.

The 409 discriminator is Status.reason, never the status code (normative). Two rules in this section require opposite actions on the same HTTP status: a failed delete precondition and a create-conflict are both 409 (NewConflict and NewAlreadyExists each carry Code: http.StatusConflict — apimachinery/pkg/api/errors/errors.go). The discriminator is the Kubernetes API Status.reason field: Conflict → abandon the delete and re-enter from step 1; AlreadyExists on create → the convergence rule below (clean up only the losing attempt's Secret, re-read, adopt the winner). An implementation that branches on the code alone will eventually take the adoption path on a failed delete or vice versa. This does not contradict the reason-strings warning above: API Status.reason is a machine-readable contract token defined by metav1.Status; container waiting reasons are kubelet-produced strings with no such contract — the spec distrusts the latter, not the former.

Create-intent fingerprint (normative). The divergence discriminator in the never-started rows is a recorded annotation, buzz.block.xyz/create-intent, written at pod create — the same shape as the image-reference and pubkey annotations the pod already carries. Its value is an unkeyed SHA-256 over a canonical serialization of the provider's non-secret create-intent template, computed before the create call. The scope rule that makes a plain hash safe: the input covers exactly the provider-controlled fields that can affect scheduling or container creation — resolved image reference, resource requests/limits, service account, PodSpec command/args, volumes/mounts, security context, and the provider's other pod-shape knobs — and never Secret data or attempt identity. Secret values cannot cause the never-started wedge this discriminator exists to clear (scheduling reads pod fields, not Secret values; a bad launch value produces a started container that fails at the relay — a different row), so hashing them buys nothing and a plain hash over low-entropy secrets published in a world-readable annotation would be a dictionary oracle; excluding them removes the oracle and with it any need for an HMAC key or nsec-derived key material. Two normalization requirements, or every attempt diverges by construction: the per-attempt Secret name in envFrom MUST be replaced by a fixed placeholder (or the pre-binding template serialized instead of the concrete PodSpec), and API metadata / server- and admission-produced output (UID, resourceVersion, timestamps, defaulted fields, the fingerprint annotation itself) is excluded structurally — the serializer never sees it, an invariant checkable by inspection. Comparison is always recorded-annotation vs freshly-computed intent, never a diff against the live pod spec: admission defaulting and mutation would make every pod look divergent, which is why the fingerprint is computed pre-create. A missing referenced Secret stays handled by the most-recent absence check (the non-recoverable row), not by fingerprint divergence; and divergence authorizes deletion only through the never-started recoverable row — a started pod is strict no-op whatever its fingerprint says.

No-op means zero mutation. The live-instance row MUST NOT replace or patch the Secret, patch metadata, or delete anything belonging to the observed live generation. Configuration and environment edits apply only to the next fresh generation (see the documented consequence below).

Conflicts converge, never fail. Two provider processes can concurrently observe "no instance" or "terminated" — the deterministic instance name prevents two live instances, but one caller loses the race. The provider MUST treat create-conflict (already exists) by re-reading and, if the winner is an annotation-verified live instance, returning it as the no-op row would — cleaning up only its own losing attempt's residue, never the winner's (the Kubernetes binding makes this concrete via per-attempt Secret names, §K8s Secrets); it MUST treat delete-not-found as success; and it MUST loop until a stable outcome or the operation deadline (600s) expires. One deliberate asymmetry: the create loser does not apply the fingerprint-divergence row to the pod that just beat it, even when the winner's fingerprint differs from its own intent — it adopts or reconciles the elected winner. Two contenders with different payloads would otherwise ping-pong deletes through the conflict path. A subsequent deploy that walks in and observes that never-started divergent winner replaces it normally. Without this rule, "two deploys return an agent_id" (the idempotency claim below) is false under concurrency.

Documented consequence. Because live → no-op, configuration edits to a running remote agent do not take effect until it next exits (unlike local agents, which re-resolve on every spawn). This is an accepted v1 tradeoff; a deliberate "recycle" affordance (stop-then-start) is the v2 path to immediate application. [DECISION E, ruled: per-binding policy — this binding keeps no-op; the universal property is that no sequence of Starts yields two live instances in one scope.] Note the asymmetry is deliberate and points the right way: an edit cannot reach a started pod until it exits, but it can reach a never-started one immediately (fingerprint divergence) — the never-started pod is the one the user is editing because it did not start.

Idempotency in the protocol sense: any number of concurrent or sequential deploys with the same payload converge to one live instance, and every non-erroring call returns an agent_id naming it; no sequence of deploys can yield two live instances in one scope.

Stop and Delete

• Stop is not a provider operation. D publishes !shutdown mentioning the agent on R; the harness verifies the sender is the owner and exits through its graceful path: agent-pool shutdown, drain of in-flight turns, publish presence offline, close relay connection. The spec does not derive an upper bound for this path from its segment timeouts, because review proved that arithmetic wrong twice: the visible constants (30s drain, 2s presence, 5s relay close) omit terms that are variable, not constant — at 28ae6cd21 the post-drain reap segment (late-arriving reap lib.rs:2664, idle-slot reap loop :2670, respawn drain :2684-2688) runs outside the 30s drain timeout (opened at :2636, closed at :2657) and serially awaits a 5s post-SIGKILL wait per occupied pool slot (acp.rs:436). That segment alone can reach 30 + 5×parallelism + 7 — ~87s at the desktop's default parallelism of 10 (DEFAULT_AGENT_PARALLELISM, types.rs:814; lowered from 24 by #3038), ~197s at the harness cap of 32 (config.rs:293) — already exceeding a 60s grace. And it is a lower bound on the tail, not the worst case: the same path runs earlier segments before the prompt drain even opens — a separate 30s wake-task drain (:2612) followed by serial shutdown of any awakened pools (:2620-2624), whose per-slot acp.shutdown() loop (:3747-3751) has no timeout of its own. The total tail is not bounded by today's segment timeouts at all. The requirement is therefore stated as a budget, not a sum (Known Defect 7): the harness MUST bound its total shutdown tail — every post-signal segment, including per-slot reaping — under one shared deadline no greater than the declared grace budget, and the budget MUST include a reserved finalization slice held back for presence offline publish and relay close, no smaller than those finalizers' declared bounds — currently 2s + 5s = 7s — which child cleanup may never consume: child reaping degrades first (skip remaining per-slot waits, force-kill), because a shared deadline without the reservation can legally spend all 60s reaping children and hit SIGKILL before the one action the grace period exists to protect. The binding declares the budget (§K8s Grace: 60s); anyone re-deriving "~37s" from the segment constants is reading numbers without their variables. The desktop's local stop command rejects remote agents.
• Delete with a live backend_agent_id requires force_remote_delete: true from the UI's orphan-warning confirmation — a buggy IPC caller cannot silently orphan substrate objects.

Auto-Stop (Inactivity Self-Termination)

I5's enforcement point. A new harness knob:

--exit-after-inactivity <secs>   /   BUZZ_ACP_EXIT_AFTER_INACTIVITY

• Default 0 = disabled. The flag ships in the harness every local agent also runs; a reaper bug must not be able to kill a laptop agent. Remote providers opt in (the Kubernetes binding's inactivity_seconds config field, schema default 7200 = 2h, feeds this env var directly). inactivity_seconds: 0 is likewise a legal, blessed value meaning "no inactivity bound" — the explicit opt-in to an indefinitely-lived agent (I5's lifetime-is-policy rule); it is not a misconfiguration and MUST NOT be rejected by provider-side validation.
• "Inactivity" is defined as: no events dispatched to the agent and no turns in flight. Raw relay traffic does not count — an agent lurking in a busy channel it never answers is exactly the waste this bounds.
• Mechanism: on expiry of the bound, the harness fires the same shutdown channel !shutdown uses — so inactivity exit gets in-flight drain, presence→offline, and graceful relay close identically to an owner stop. The expiry check MUST NOT depend on pool readiness. This is a design constraint learned by inspection, not a transcription: the harness's existing 30s maintenance tick is gated on pool_ready (lib.rs:1743), which under lazy_pool starts false (:1320) and flips true only on a wake (:2570) — and wakes require pending work (pool_lifecycle.rs:42). A reaper riding that tick composes with the mandated BUZZ_ACP_LAZY_POOL=true (§Launch data) into a deadlock in I5's single most important case: a never-mentioned lazy pod never runs the tick, so the idle agent the reaper exists to kill is exactly the one it can never evaluate. The reaper therefore runs on its own timer, independent of pool state (an idle-pool check needs no pool). Check granularity makes the effective bound t ∈ [T, T+interval), immaterial at T=7200.
• Reserved keys: BUZZ_ACP_EXIT_AFTER_INACTIVITY MUST join RESERVED_ENV_KEYS (env_vars.rs) when it lands — it is tier-3 authoritative (§Launch data), and without reservation a user env var could disable the reaper and reopen unbounded lifetime through the front door. BUZZ_ACP_NO_PRESENCE (config.rs:378) MUST join in the same change, for the same shape of reason at I3 instead of I5: unreserved, it lets user env silently defeat the 180s presence bound (I3). One knob guards "knows when to leave", the other "you can see that it left"; both are promises users must not be able to un-make by typo.
• Distinctness note: this is a fourth timeout concept, deliberately named away from the existing three (--idle-timeout = per-turn ACP wire silence, 900s; turn_timeout; max_turn_duration = 7200s — numerically equal to the default inactivity bound and semantically unrelated). Sharing a flag or env name with any of them is how the bug ships.

The harness exiting MUST terminate the substrate's unit of execution, and — equally load-bearing — the substrate's termination signal MUST reach the harness process itself; any wrapper MUST forward it. A wrapper that runs the harness as a child without forwarding signals silently voids both I5's substrate half and the graceful-shutdown budget: the termination signal lands on the wrapper, the harness never learns to shut down, and the force-kill leaves presence stale-online — exactly the staleness window the grace period exists to close. This binding's realization — the harness as the container's signal-receiving process (PID 1 or the signal target) — is §K8s Entrypoint's exec rule and §Pod shape ([L3], L1 item 3 for the universal form). With the supervisor policy that matches the lifetime policy (this binding's [L3] mapping — bounded → Never, indefinite → OnFailure after both prerequisites, §Pod shape; the universal rule is I5's), harness exit completes the pod on every intentional path — turning agent-level I5 into substrate-level I5.

The Kubernetes Binding (buzz-backend-kubernetes)

The first conforming provider: a Rust crate in block/buzz, distributed as a standalone binary. Everything above is the contract; this section is its realization.

Cluster auth

Standard kubeconfig resolution ($KUBECONFIG → ~/.kube/config) via kube-rs. provider_config carries context and namespace only (I2: credentials never transit config). Because kubeconfigs at Block near-universally use exec credential plugins (aws eks get-token, gke-gcloud-auth-plugin) that resolve via PATH, and the provider inherits a Finder-launched desktop's minimal PATH, the provider MUST prepend /opt/homebrew/bin, /usr/local/bin, and ~/.local/bin to its own PATH before building the client, and on exec-plugin failure MUST name the missing plugin binary in the error rather than surfacing a kube-rs stack.

Namespace

One stable namespace per user-visible choice; the provider emits a freshly generated buzz-agents-<rand6> as the namespace field's schema default on every info call, so the UI prefills a visible, editable random name with zero UI changes ("random default" satisfied at the schema layer). If the namespace does not exist the provider attempts to create it; on RBAC denial it MUST fail with the literal kubectl create namespace <name> command to run — it MUST NOT fall back to default.

Image

ghcr.io/block/buzz-sprig: Alpine base + bash (required by the dev-MCP shell tool) + git + CA certificates + the static musl sprig multicall binary with its personality links (buzz-acp, buzz-agent, buzz-dev-mcp, rg, tree, buzz, git-credential-nostr, git-sign-nostr) + a baked system gitconfig wiring the nostr signing and credential helpers. The baked credential-helper config MUST be scoped to the relay's git URL — mirroring the local spawn's credential.<relay-url>/git.helper scoping — never a global credential.helper: a global nostr helper would answer for every remote, including github.com. ~15–25MB; not FROM-scratch (bash and git preclude it). Sprig-only: alternate-harness dependencies (node for Claude Code / Codex) come via the image override field, not a fatter default. Tagging follows the relay image's matrix — sha-<short> on main, semver on sprig-v* tags (the sprig tarball's +git.<sha> version string is not a legal Docker tag). The default image reference MUST be pinned by digest, not tag: the provider bakes, at compile time, the multi-arch manifest digest of the image built from its own commit and defaults image to ghcr.io/block/buzz-sprig@sha256:<that-digest> — a sha-<git-sha> tag is traceable but still movable (registry tags are mutable pointers; Kubernetes distinguishes movable tags from immutable digests for exactly this reason), and the object holding it runs with an nsec. The provider records the reference it used in a pod annotation, and rejects :latest. User image overrides accept tag, digest, or full custom registry reference — visibly the user's trust decision, with the resolved image ID recorded in the same annotation for post-hoc attribution. An image override MUST contain the runtime ABI — the buzz-acp entrypoint and everything §Entrypoint and launch ABI requires — not merely alternate-harness dependencies. A conforming custom image is "buzz-sprig plus your tools", never "your tools instead".

Entrypoint and launch ABI

Two conforming implementations must produce interchangeable pods, so the launch contract is normative.

Entrypoint. The container runs the harness as its signal-receiving process. Sprig is a multicall binary with no supervisor personality — nothing reaps children or forwards signals — so the entrypoint MUST end in exec:

#!/bin/bash
set -e
# nest scaffolding, if DECISION A lands, goes here
exec buzz-acp   # exec, not a call — buzz-acp must be PID 1

bash -c "setup && buzz-acp" (no exec) is non-conforming: bash becomes PID 1, and a PID-1 bash with no trap never delivers SIGTERM to the harness (PID 1 receives kernel-level default-handler signal immunity), so the pod rides out the entire grace period and is SIGKILLed with presence still online — voiding I5's substrate half and the very staleness window terminationGracePeriodSeconds: 60 was sized to close. The entrypoint shape and the grace period are one requirement, not two.

Payload → environment mapping. The provider builds the pod environment (via the per-agent Secret, §K8s Secrets) by applying the §Launch data three-tier precedence — launch.policy_env (overridable defaults), then launch.env (user/layered), then the authoritative tier from top-level fields per the reserved-key rule. Only the non-launch scalars and the substrate-forced re-derivations are mapped individually:

source	env var
relay_url	BUZZ_RELAY_URL
private_key_nsec	BUZZ_PRIVATE_KEY and NOSTR_PRIVATE_KEY (the git helpers read the latter)
auth_tag	BUZZ_AUTH_TAG (omitted when null; then launch.owner_pubkey → BUZZ_ACP_AGENT_OWNER is REQUIRED — §Launch data owner rule)
launch.command	BUZZ_ACP_AGENT_COMMAND — the name, resolved against the image's own PATH; never a forwarded host path
launch.args	BUZZ_ACP_AGENT_ARGS, comma-joined
launch.env, launch.policy_env	verbatim, at their precedence tiers
generation token (§K8s Secrets)	BUZZ_MANAGED_AGENT_START_NONCE — the lifecycle-frame correlator and the Secret generation are one identity (§Launch data tier 3)
system_prompt, idle_timeout_seconds, max_turn_duration_seconds, parallelism	not mapped by the provider — the desktop resolves these into launch.policy_env (BUZZ_ACP_SYSTEM_PROMPT, BUZZ_ACP_IDLE_TIMEOUT, BUZZ_ACP_MAX_TURN_DURATION, BUZZ_ACP_AGENTS). BUZZ_ACP_AGENTS carries the effective parallelism (min(record.parallelism, harness_cap)), is reserved (env_vars.rs:RESERVED_ENV_KEYS), and cannot be overridden by user env. The remaining knobs are tier-1 by local fact (written before user env); a provider that mapped the top-level copies after launch.env would silently defeat local overrides. The top-level fields remain as display/bookkeeping inputs only
turn_timeout_seconds	not mapped — deprecated upstream and ignored; the local spawn also does not emit it
respond_to	BUZZ_ACP_RESPOND_TO
respond_to_allowlist	BUZZ_ACP_RESPOND_TO_ALLOWLIST, comma-joined
—	BUZZ_ACP_MCP_COMMAND=buzz-dev-mcp (image-local; the dev-MCP requirement)
provider_config.inactivity_seconds	BUZZ_ACP_EXIT_AFTER_INACTIVITY (schema default 7200; the I5 opt-in, §Auto-Stop — the config field and this env var are one knob, not two)

The top-level model/provider payload fields are display/bookkeeping inputs; the environment consequence of model and provider selection (per-runtime vars, provider_locked suppression, BUZZ_ACP_MODEL) arrives resolved inside launch.env/launch.policy_env. A provider MUST NOT map provider to any env var itself — that mapping is per-runtime and lives in the desktop's resolver (§Launch data).

Encoding honesty note. BUZZ_ACP_AGENT_ARGS is comma-delimited by the harness's CLI parser, and the desktop's local spawn performs the same comma-join — an argument containing a comma is unrepresentable in both paths. This is a harness interface limitation the binding inherits and matches, not one it introduces; a provider MUST NOT invent a private escaping scheme the harness would not decode.

Working directory. HOME is set to a writable path backed by the workspace emptyDir (e.g. /home/agent), and the harness runs with cwd = HOME — mirroring the local spawn's agent-workdir convention. The baked system gitconfig references the nostr helpers by absolute path so it works regardless of HOME.

Pod shape

• Bare Pod; restartPolicy follows lifetime policy (I5). No Job, no controller — controller-grade restart machinery (Restart=always-shaped) would resurrect what !shutdown and auto-stop terminate, violating I5. Within the bare pod, the policy is selected from inactivity_seconds:
  • Bounded lifetime (inactivity_seconds > 0, the default): Never. The reaper's clean exit must complete the pod; any restart would undo the reap. Accidental death is handled by intent, not machinery: eviction → presence offline (I3) → user hits Start → the reconciler's terminated arm re-creates. That sequence is rescheduling-after-accident gated on a fresh owner intent — apt for an agent whose owner already accepted "not running" as its default state.
  • Indefinite lifetime (inactivity_seconds: 0): OnFailure — once the harness exit-code contract is pinned (I5 ordering rule; until then the provider MUST refuse the combination rather than ship OnFailure against an undefended exit convention). OnFailure restarts the in-place abnormal deaths — process crash, container OOM-kill — and honors the intentional ones (clean exit completes the pod): I5's intent-vs-accident distinction, realized. Second prerequisite — reconciler classification: OnFailure introduces a pod state the deploy state machine's rows do not cover — a crash-looping harness sits in phase Running with state.waiting{reason: CrashLoopBackOff}, restartCount > 0: not deletion-marked, not terminated (the kubelet keeps restarting it), not "live and started" (state.running is false), and not never-started (it started, repeatedly) — and it fails the startup success criterion while the kubelet is actively reviving it. Before the binding ships OnFailure, the state machine MUST gain a crash-loop classification row and the started-criterion's treatment of restartCount > 0 MUST be specified; the exit-code contract alone is not the green light. Honest limit: restartPolicy is kubelet-level and cannot survive node-level loss — a drain or API-initiated eviction deletes a bare pod outright, and no restart policy reschedules a deleted pod. Full "continuous need" across node loss requires controller-grade machinery this binding deliberately does not use in v1 (the same machinery I5 distrusts); the v1 promise for indefinite agents is restart-on-crash, with node loss surfacing as presence offline awaiting a fresh Start.
• Naming/labeling — the exact contract (63-char label-value limit; a hex pubkey is 64 chars, one over):
  • pod name: buzz-agent-<first-12-hex-of-pubkey> — also the returned agent_id
  • label buzz.block.xyz/agent-pubkey: <first-32-hex> — the selector key for reconciliation and GC. 128 bits is collision-resistant, not collision-free, which is why the annotation check below is normative, not decorative
  • label app.kubernetes.io/managed-by: buzz-backend-kubernetes and label buzz.block.xyz/binding-version: <schema-version> — the management marker (§Deploy State Machine auto-repair fence): present on every pod and Secret this provider creates, and required before any destructive repair or GC action. Identity labels/annotations prove identity; the marker asserts protocol ownership — without it, an object that merely matches our schema fails closed to the operator
  • annotation buzz.block.xyz/agent-pubkey-full: <full-64-hex> — load-bearing: per §Deploy State Machine step 1, every label-selected object's annotation MUST equal the derived pubkey before the provider no-ops against it, deletes it, mutates its Secret, or returns its name
  • annotation buzz.block.xyz/create-intent: <sha256-of-intent-template> — the recorded create intent (§Deploy State Machine, create-intent fingerprint), written at pod create; the divergence discriminator for never-started pods
  • Secret name: buzz-agent-<first-12-hex>-<gen>, where <gen> is a random per-create-attempt generation token — unique, never reused, carrying the same labels (identity + management marker) and annotation. The pod's envFrom references this exact Secret name. Deterministic pod name + unique Secret name is what makes payload and Secret atomic at the pod-spec boundary (§K8s Secrets)
• Deletion semantics the reconciler must respect. A Kubernetes DELETE returns success immediately while the object still exists; the name stays taken until the kubelet finishes the grace period. Two consequences: (a) a pod being gracefully deleted has deletionTimestamp set but remains in phase Running — the reconciler MUST check the deletion mark before phase (there is no Terminating phase to match on); (b) after deleting a live pod, a naive immediate create gets AlreadyExists for up to the full grace period — the reconciler MUST poll for actual disappearance (GET → 404) before creating. The delete call MUST use the object's own grace period (kube-rs: DeleteParams { grace_period_seconds: None, .. }); the tempting shortcut of passing 0 to skip the poll is a force-kill that discards the 60s shutdown grace pinned below — the poll is mandatory precisely because the fast path is wrong. For terminal (Succeeded/Failed) pods — and for unscheduled pods (no assigned node: unschedulable or quota-blocked Pending, a state users hit while setting up a namespace) — the apiserver zeroes the grace period and deletes immediately, so the normal restart path needs no meaningful wait — do not add a fixed sleep, and do not use zero-grace cleanup as a reason to skip the poll in the live-pod arm.
• terminationGracePeriodSeconds: 60 — a declared budget the harness MUST honor, not a sum the spec derived. Kubernetes' default 30s grace would SIGKILL the harness mid-drain, leaving presence stale-online — the avoidable half of I3's staleness window — so the binding declares 60s. But the shutdown tail is variable, not constant (§Stop: the post-drain reap segment alone reaches ~87s at default parallelism at 28ae6cd21, and earlier untimed segments precede it — the total is not bounded by today's segment timeouts), so no fixed grace can be proven sufficient by adding segment timeouts. The two halves of the requirement: the binding declares the budget here, and the harness enforces it — one shared deadline across the entire post-signal path, with a reserved finalization slice (≥ the finalizers' declared bounds, currently 7s) for presence offline and relay close, child cleanup degrading first (§Stop, Known Defect 7). Until the harness enforcement lands, 60s is an operational margin that the tail can exceed.
• Hardening defaults (normative). The workload is a prompted coding agent running repository and tool code while holding an nsec; the pod MUST NOT hand it ambient cluster credentials or kernel privilege on top: automountServiceAccountToken: false (Kubernetes mounts a ServiceAccount token unless told otherwise — an API-stealable credential the agent never needs), runAsNonRoot: true with a fixed nonzero UID/GID, allowPrivilegeEscalation: false, capabilities drop-all, seccompProfile.type: RuntimeDefault; never privileged, hostPID, hostNetwork, or hostPath. readOnlyRootFilesystem is not required in v1 — the sprig toolchain writes outside the workspace mount — but is a named candidate once the image's write surface is mapped. The service_account config field selects an identity for scheduling/RBAC purposes only; it MUST NOT silently re-enable token mounting — API-token access, if ever wanted, is a separate explicit opt-in, not a side effect of naming an SA.
• Resources: requests 1 cpu / 2Gi, limits 2 cpu / 4Gi, all four configurable (cargo build in an agent workspace makes 500m/1Gi requests unrealistic).
• Workspace: emptyDir. Checkouts and scratch die with the pod; agent memory is relay-persisted (NIP-AE) and unaffected. PVC support is a deferred knob. [DECISION A — how remote pods get the nest workspace (AGENTS.md etc.) that local agents get from the desktop's ensure_nest; current recommendation is a desktop-stated protocol field, not image-side scaffolding — §Open Decisions.]

Secrets

Per-agent Secret containing the identity variables (built from top-level payload fields per the reserved-key rule) plus env_vars; consumed via envFrom.

Secret creation is per-attempt, immutable, and uniquely named (buzz-agent-<first-12-hex>-<gen>, §Pod shape). The rationale is a concurrency race a deterministic shared Secret name cannot survive: two concurrent deploys carrying different payloads would both write the shared Secret, the loser's write could land last, and the winner's pod — deterministic name, winner's spec — would resolve the loser's identity/config through envFrom. The losing caller would have mutated the winning generation despite strict no-op. Unique names close this: each create attempt writes its own Secret first, then attempts the deterministic pod create with a spec referencing exactly that Secret. Pod creation elects the winner; payload and Secret are atomic at the pod-spec boundary, with no Lease or CAS machinery.

Lifecycle rules that follow:

• Winner: pod + its referenced Secret live together; GC deletes them together.
• Losing contender (create-conflict): annotation-verify the winning pod, return its agent_id per the convergence rule, and delete only its own now-unreferenced Secret — never the winner's, never any Secret referenced by an existing pod. "Existing" deliberately includes not-yet-started pods: an envFrom reference from a pod still pulling its image is exactly as load-bearing as one from a running pod.
• Live no-op arm: no Secret is written at all (zero mutation).
• GC: also deletes annotation-verified orphan Secrets — those whose generation token no existing pod references — covering contenders that crashed between Secret create and their conflict cleanup. But only when age-eligible: see the normative age gate in §K8s GC — "unreferenced" is not "orphaned" while a concurrent attempt may still be between its Secret create and its pod create.

Fresh configuration therefore materializes exactly when a fresh generation does. Residual exposure, stated: any principal with pod-exec or secret-read in the namespace can read the nsec. This is the substrate-security boundary from §Non-Goals — the namespace is the isolation unit, and users deploying to shared namespaces accept its ambient RBAC. The in-pod narrowing that sprig's dev-MCP shim performs (strips the key from its own env, re-materializes as a 0600 keyfile for the git helpers) limits accidental leakage into subprocess environments, not hostile cluster access.

Garbage collection

A generation is one pod-create attempt and the uniquely-named Secret it references; the Secret's generation token is the generation's identity, and the current generation is the one referenced by the existing pod's envFrom.

GC is a preflight reconciliation pass, not a post-deploy afterthought: on every deploy, after identity derivation and before the state transition, the provider deletes terminated pods (and their referenced Secrets) that match the pubkey label, pass the full-pubkey annotation check, and carry the management marker (§Pod shape; the auto-repair fence applies to GC identically), plus annotation-verified, marker-bearing orphan Secrets whose generation token no existing pod references (§K8s Secrets). It never touches the current generation. Mismatched annotations are never GC'd (§Deploy State Machine step 1), and an unmarked object is never GC'd regardless of its labels.

Orphan-Secret age gate (normative). An unreferenced Secret is GC-eligible only when its server-assigned creationTimestamp is older than twice the deploy operation deadline (2 × 600s). Rationale — without the gate, GC composes with per-attempt Secrets into a legal interleaving that strands a deploy: attempt A creates Secret A; concurrent attempt B runs its preflight GC before A creates its pod, sees Secret A unreferenced, and deletes it as an "orphan"; A's pod is then accepted referencing a missing Secret and sits in CreateContainerConfigError until a later deploy repairs it by delete-recreate (§Deploy State Machine never-started rows) — a stranded deploy either way. Unique Secret names made payload↔Secret atomic at the pod-spec boundary, but Secret-create→pod-create is not atomic against an independent GC pass — the standard controller lesson that observations may be stale and reconciliation must tolerate in-flight peers. The age bound makes "unreferenced" mean "provably abandoned": any attempt that could still reference the Secret has exceeded its own deadline. A losing contender's immediate cleanup of its own Secret is exempt — ownership, not age, is its safety argument. (A Lease per agent identity would also close this race; the age gate achieves the same with no extra machinery.)

Same-clock rule (normative). The age comparison has two operands and both MUST come from the apiserver's clock. creationTimestamp is server-assigned; the comparison instant MUST be derived from the HTTP Date response header on the very list/get call the GC pass performs (RFC 9110 §6.6.1 — origin-server message-origination time), never from the provider's local now(). The provider runs on a user's desktop, and a local clock fast by more than the margin doesn't race — it deterministically computes every in-flight Secret as expired and deletes them all, silently, on every pass, reopening exactly the interleaving the gate exists to close. With both operands from one clock, skew cancels. (kube's Client::send returns the raw http::Response with headers, so this costs one header read, not a departure from the typed API.) If the Date header is absent or unparseable, the provider MUST skip orphan-Secret GC for that pass — never fall back to local time. A deferred cleanup is free; a wrong deletion is not.

Alternative considered — ownerReferences, omitted in v1. Kubernetes' native GC (a Secret owned by its attempt's Pod is deleted when the owner is verified absent) cannot replace the age gate: an ownerReference needs the owner's UID, which exists only after pod create, so primary reliance on it would flip the ordering to Pod-first-then-Secret. The reason that flip loses is diagnostics, not repairability: a never-started winner is recoverable (the kubelet retries a config-failed container indefinitely, and the amended no-op rule lets a later deploy delete-and-recreate it with its own payload), but Pod-first routes every healthy deploy through CreateContainerConfigError — the exact condition the startup classifier treats as an actionable failure signal — so the classifier could no longer believe that reason without waiting out the deadline, on every deploy. That trades away normative diagnostics for a cleanup the age gate already provides. A supplementary post-create attachment (patch the Secret with the winning pod's UID; Secret metadata stays patchable when immutable and data are untouched) is sound but adds no required property: the pre-pod crash window still needs the age-gated sweep as backstop, so v1 omits it under the complexity budget. Any future implementation that adds it MUST set blockOwnerDeletion: false explicitly (true requires update on pods/finalizers — an RBAC verb nothing else here needs — and a Secret should never delay its pod's deletion), MUST keep owner and dependent in the same namespace (a cross-namespace owner is treated as absent, turning the safety net into an immediate-delete instruction), and MUST treat attachment failure as non-fatal cleanup, never a deploy error.

Running GC first gives concurrency and Secret ownership one unambiguous order: reconcile always observes a world with at most one candidate generation older than the gate. Completed pods from the current generation are left in place — their logs are the only forensics M1 permits. That forensic window is deliberately fragile: next-deploy GC, node loss, or namespace deletion erases it, and M1 means there is no log operation to reach for. Cluster-native log shipping is therefore a production prerequisite, not an optional nicety — the ephemeral-runner lesson: disposable generations still need durable diagnostics, forwarded off the pod by the cluster operator's stack. The binding's contribution is correlation, not transport: the pod carries the full-pubkey annotation, the generation token (doubling as BUZZ_MANAGED_AGENT_START_NONCE, so lifecycle frames and pod logs share a correlator), the provider version, and the resolved image reference (§Image) — enough to attribute any shipped log line to an exact identity, generation, and binary, with no secret in any of it. GC on next-deploy also self-heals the missing undeploy: delete-then-recreate converges, and a deleted-forever agent's residue is one Completed pod that never restarts (I5) plus one Secret, removable with kubectl delete.

provider_config v1 fields

context, namespace, image, cpu_request, memory_request, cpu_limit, memory_limit, inactivity_seconds, service_account — 9 of the 20-field validation cap. Node selectors, tolerations, and PVCs are deliberately baked out of v1 to preserve budget.

Distribution

Its own release workflow (macOS arm64/x64 + Linux musl; the sprig workflow's ubuntu × musl matrix cannot produce the laptop-side binary), artifacts attached to releases, installed to ~/.local/bin (already on the discovery path). v1 ships no Windows binary [DECISION B]; desktop bundling into the .app (discovery already prepends the bundle dir) is deferred [DECISION D].

Conformance

Obligations are split by layer per §Launchers: the [L1] agent/harness contract binds every launcher; the [L2] provider/deployer contract binds provider-managed launches; the [L3] binding policy here is the Kubernetes binding's own. A non-provider launcher (bash script, systemd unit) owes only the L1 items; a provider on a different substrate owes L1 + L2 and writes its own L3 realization of the generic L3 property.

[L1] Launcher conformance — every launcher

A launcher — desktop, provider-deployed pod, systemd unit, bash script — is conforming iff:

1. It launches the harness with a valid, nonempty identity: a parseable private key, a relay URL, and an auth tag or resolved owner pubkey — refusing to launch rather than launching identityless (I1's property, enforced wherever the env is assembled).
2. It does not suppress the harness's promises on a remote agent: presence stays enabled (BUZZ_ACP_NO_PRESENCE never set — remotely, presence is the only signal, I3), and the inactivity knob (BUZZ_ACP_EXIT_AFTER_INACTIVITY) carries the owner's deliberate lifetime policy, never an accidental passthrough of user env (I5; the reserved-key rule is the provider path's realization of this).
3. The substrate's termination signal reaches the harness process, with enough grace for its full graceful shutdown before force-kill (I3 staleness minimization). "Allows" is not enough — a wrapper that swallows the signal conforms to nothing.
4. Intentional termination (owner !shutdown, inactivity reap) exits through the harness's graceful path under the pinned clean-exit contract (intentional exit ⇒ exit code 0 — Known Defect 6 until the contract lands).
5. Any supervisor the launcher configures never restarts an intentional clean exit (I5). Restart=always and equivalents are non-conforming at this layer no matter what the substrate calls them.

[L2] Provider conformance — provider-managed launches

A provider is conforming iff, in addition to deploying only L1-conforming invocations:

1. info and deploy implement the wire contract (§Provider Protocol), including one-JSON-in/one-JSON-out and in-band {"ok": false} errors. Exit codes carry exactly one bit — zero = the operation's output is trustworthy, nonzero = failure regardless of stdout (§Invocation's rule restated from the provider's side): a provider MUST exit nonzero on any crash path and MUST NOT encode structured meaning in nonzero values, because D discards partial output rather than interpreting codes.
2. It never requests or accepts credentials through provider_config (I2).
3. It builds agent identity env from top-level payload fields, never from env_vars (reserved-key rule), applies §Launch data mechanically — three-tier precedence, host-resolved re-derivation, no re-merge of legacy env_vars, no provider-side model/provider mapping — and refuses a deploy that resolves neither auth_tag nor launch.owner_pubkey, or whose provider is relay-mesh.
4. deploy implements the reconciliation loop (I4), stated substrate-neutrally: identity derived from the nsec before any mutation; candidates verified by full-identity evidence before any action; live (= started: the harness process confirmed running, not merely the body accepted) → strict no-op (zero mutation); never-started states classified by evidence, not by substrate status strings (provably-broken → fenced replace; recoverable + same recorded create intent → observe, never delete, on this call or any later one; recoverable + divergent intent → fenced replace); every read that can authorize a destruction uses most-recent semantics; every destructive write is fenced to the exact observation that authorized it (compare-and-delete — the write fails if the object changed since the read) and touches only objects carrying the provider's management marker (the auto-repair fence, §Deploy State Machine); same-status-code conflicts discriminated by a machine-readable conflict discriminator, never the status code alone; success only on confirmed harness start; conflicts converge by re-entry; delete-of-absent is success.
5. It emits no secret material in any output (belt to D's redaction suspenders).
6. Generic L3 obligation: its binding documents how it realizes each L2 term on its substrate, and how the owner's lifetime policy (bounded vs indefinite) and clean-exit restart behavior are realized there — stating the properties in its own vocabulary, not skipping them.

[L3] Kubernetes binding conformance — this binding

The realization the two lists above require, in this binding's vocabulary:

1. Each L2 item-4 term maps to the mechanism in §Deploy State Machine: full-pubkey annotation for identity evidence, container state.running for "started", resourceVersion-unset quorum reads for most-recent semantics, UID+resourceVersion delete preconditions for fencing, Status.reason as the 409 discriminator, and the app.kubernetes.io/managed-by + binding-version labels as the management marker.
2. The deployed invocation realizes the lifetime policy the owner chose (I5) through this binding's inactivity_seconds field: > 0 → a working inactivity bound and restartPolicy: Never; 0 (the blessed indefinite opt-in) → no bound and restartPolicy: OnFailure, only after both prerequisites land — the pinned exit-code contract (I5 ordering rule) and the crash-loop classification row (§Pod shape); until then the provider MUST refuse the combination.
3. The harness is the deployed container's signal-receiving process (PID 1 or the target of the pod's termination signal — §K8s Entrypoint's exec rule), and terminationGracePeriodSeconds carries the declared grace budget (§Pod shape).

Conformance is testable without mechanization: a fake-provider harness can exercise L2 items 1–3 and 5 over the wire contract — including the pre-secret negotiation gate (§Discovery): an incompatible or absent protocol_version MUST be rejected before any request carrying private_key_nsec is sent; a same-inode content rewrite of the resolved binary after resolution MUST NOT reach the deploy invocation (the staged artifact still carries the bytes that answered info); and a pathname swap after validation — the resolved path re-pointed at a different file between the gate's checks and process spawn — likewise MUST NOT redirect the nsec (both cases are exactly what path+metadata comparison misses) — and an envtest/kind suite can drive L2 item 4's reconciler against a real apiserver — concurrent deploys, a deletion-marked pod, terminal restart, an annotation-mismatch collision, and SIGTERM→presence-offline for the L3 items. Three families of cases are mandatory because they were the review-found failure modes: startup discrimination (slow-but-valid scheduling → poll-then-succeed; Unschedulable during scale-from-zero → observed until the autoscaler provisions capacity, then success — never delete, including when provisioning completes only after the 600s deadline: the original pod identity and creationTimestamp survive the expired call and become the no-op winner on a later deploy, the case that pins the anti-livelock rule; a label-and-annotation-matching object without the management marker → never deleted, never GC'd, reported (the auto-repair fence under test); referenced Secret confirmed absent → preconditioned delete-recreate or actionable error, never silent success or no-op; a never-started winner is repairable — pod exists, Secret absent, container never started: a later deploy MUST delete-and-recreate rather than no-op, the test that pins started-not-phase as the no-op criterion; and the classification→DELETE race — the container transitions to running between the classifying read and the delete: the UID+resourceVersion precondition MUST fail and the live agent MUST be preserved) and the GC/attempt interleaving (attempt B's preflight GC running between attempt A's Secret create and pod create MUST NOT delete Secret A — the §K8s GC age gate under test; provider death after Secret create → the age gate protects, then a later GC reaps; and a provider local clock fast beyond the margin MUST NOT delete an in-flight Secret — cheap with a fake clock, and the same-clock rule's skip-on-absent-Date arm is exercised by stripping the header). A third family pins the divergence discriminator and the 409 split: a failed delete precondition (code 409, reason Conflict) → re-read and re-classify, never the create-conflict cleanup/adoption path; a create conflict (code 409, reason AlreadyExists) → loser-Secret cleanup and winner adoption, never treated as a failed delete; identical desired intent + permanently-Pending pod → no delete across arbitrarily many Starts, regardless of age; a resource/image correction against a never-started pod → fingerprint differs, preconditioned delete-and-recreate (the wedge-escape case); same user config but the provider's baked default image digest changed (provider upgrade) against a never-started pod → divergence, replace (the second intent source — the only escape from a bad-default-image wedge); the same correction against a started pod → strict zero-mutation no-op; admission defaulting/mutating the live pod → no false divergence (the comparison uses the recorded annotation); the fingerprint serializer property, asserted structurally — changing only Secret values or the generated Secret name leaves the fingerprint unchanged, changing any fingerprinted pod-create field changes it (equivalently: the serializer has no access to Secret data or attempt identity); and the conflict-path asymmetry — two no-instance contenders with different payloads: the create loser adopts the elected winner rather than deleting it for divergence, while a subsequent deploy observing that never-started divergent winner replaces it. A model checker is the wrong tool here: the failure modes found in review were wrong abstractions of Kubernetes (a nonexistent Terminating phase, non-atomic delete, phase-as-readiness, non-atomic Secret→pod against GC), which a hand-written model would have reproduced convincingly.

Known Defects (at 28ae6cd21)

Citation pin: every file:line reference in this document was verified against 28ae6cd21 — the commit at which this spec merged to main. References are to that tree; a later commit may offset them.

Desktop- and harness-side, discovered during this design:

1. Windows discovery id pollution: the .exe suffix survives into the provider id, which then fails id validation at deploy — dropdown-visible, probe-fine, deploy-broken. Fix is a suffix strip in discovery. (v1 provider scope is macOS+Linux regardless — [DECISION B].)
2. Provider env inheritance: invoke_provider passes the desktop's environment through unmodified; combined with launchd's minimal PATH this breaks kubeconfig exec plugins. Mitigated provider-side (§K8s Auth); a desktop-side PATH augmentation would fix the class.
3. Deploy payload bypasses the launch resolver (the prerequisite this spec names for §Launch data — a desktop code change, not spec text). At 28ae6cd21, deploy_payload_json serializes raw record bytes and a three-layer merged_user_env where the local spawn uses resolve_effective_harness_descriptor's six-layer resolution. Concrete consequences, each verified in review: (a) no per-runtime model/provider env — a remote goose agent silently ignores the user's model choice, and provider_locked runtimes would receive vars the desktop deliberately withholds; (b) persona-derived agent_command and definition-provided agent_args serialize as blank/empty — a different command line than the identical local agent; (c) no owner_pubkey — a null-auth_tag agent cannot match !shutdown (it answers it), stranding §Stop; (d) spawn policy (BUZZ_ACP_RELAY_OBSERVER, runtime default_env such as GOOSE_MODE=auto, team instructions, session title, lazy-pool selection) is absent — remote pods run different observer/approval semantics (BUZZ_ACP_DEDUP/BUZZ_ACP_MULTIPLE_EVENT_HANDLING are not on this list: the local writes match the harness defaults, §Launch data); (e) a mesh-provider agent deploys pointed at a loopback URL that cannot exist in the pod instead of being refused. Until deploy_payload_json emits the launch block, no provider can conform to §Launch data, and the current payload MUST be treated as insufficient for a semantics-preserving remote launch. Security follow-through: once secrets can arrive via launch.env, desktop redaction MUST collect candidate values from launch.env (and launch.policy_env) as well as legacy agent.env_vars — at 28ae6cd21, env_secrets_from_request reads only agent.env_vars (backend.rs), leaving a definition/persona-layer secret outside the literal-value scrub. Conformance: a provider that echoes a launch-only secret into an error must come back redacted.
4. The I5 reaper does not exist, and its natural home is a trap (harness code prerequisite). BUZZ_ACP_EXIT_AFTER_INACTIVITY appears nowhere in the harness at 28ae6cd21; §Auto-Stop is a design, not a description. Worse, the obvious attachment point — the existing 30s maintenance tick — is gated on pool_ready (lib.rs:1743), which under lazy_pool only becomes true when work arrives, so a never-mentioned lazy pod would never evaluate the bound: I5 dead in its most important case (§Auto-Stop mechanism rule). The implementation MUST run the expiry check on a pool-independent timer and MUST add the env var to RESERVED_ENV_KEYS in the same change.
5. The deploy path never checks protocol_version (desktop code prerequisite). provider_deploy (backend.rs) sends the nsec-bearing deploy request without any preceding info on the same resolved executable; §Discovery's pre-secret negotiation gate is a design, not a description, until the deploy command performs resolve-once → stage-and-digest → info → explicit-version check → deploy, both invocations running the staged bytes.
6. The clean-exit contract is emergent, not defended (harness code prerequisite; gates OnFailure). At 28ae6cd21: the graceful path returns Ok(()) (lib.rs:2723), and owner !shutdown (:2045), Ctrl-C (:1635), and SIGTERM (:1644) all route into the same shutdown channel — so clean stops exit 0 today, but no distinguished exit code exists and no test pins "intentional exit ⇒ 0"; every process::exit(1) in the crate is a startup failure. Until a pinned, tested exit-code contract lands, no supervisor restart policy (restartPolicy: OnFailure, systemd Restart=on-failure) may be deployed against the harness: a refactor returning Err from a drain timeout would silently convert every clean stop into a restart loop — I5 defeated with no failing test (I5 ordering rule).
7. The shutdown tail overruns the declared grace budget at default config (harness code prerequisite). At 28ae6cd21: the post-drain reap segment (lib.rs:2664-2688) runs after the 30s drain timeout closes (:2636,:2657) and serially awaits a 5s post-SIGKILL wait per occupied slot (acp.rs:436) — that segment alone reaches ~87s at the desktop's default parallelism of 10 (types.rs:814; #3038 lowered it from 24), ~197s at the harness cap of 32 (config.rs:293), against the binding's 60s grace; and it is not the whole tail — the wake-task drain (:2612) and awakened-pool shutdown (:2620-2624, per-slot loop :3747-3751, no timeout) precede it (§Stop), so the total is unbounded by today's segment timeouts. The fix is one shared deadline across the entire post-signal path with a reserved finalization slice (≥ the finalizers' declared bounds, currently 2s presence + 5s relay close = 7s) for presence offline and relay close, child cleanup degrading first (§Stop); natural home is the same harness change as the I5 reaper (defect 4).
8. Cleared numeric config fields ship as strings (desktop code prerequisite, raised by blessing 0). coerceConfigValues (desktop/src/features/agents/ui/ProviderConfigFields.tsx:6 at 28ae6cd21) skips numeric coercion when the value is "", so a cleared numeric field reaches the provider as a JSON string instead of a number. Blessing inactivity_seconds: 0 makes clearing that field a legitimate user action, so the empty-string arm now sits on a documented path: the provider receives "" where the schema says integer, and "0 MUST NOT be rejected" cannot protect a value that never parses as 0. Fix is desktop-side (map cleared numeric → omit-or-default, never ""); provider-side, a non-numeric value for a numeric field is an in-band error, not a silent default.

Implementation Correspondence

spec concept	code
Discovery, resolution rule	desktop/src-tauri/src/managed_agents/backend.rs (discover_provider_candidates, resolve_provider_binary)
Invocation, output caps, exit rule	backend.rs (invoke_provider)
Pre-secret negotiation gate	to be added: backend.rs deploy path — resolve-once → stage-and-digest → info → explicit-version check → deploy on the staged bytes (Known Defect 5)
Redaction	backend.rs (redact_secrets_with)
I2 validation	backend.rs (validate_provider_config)
I1 refusal, payload	desktop/src-tauri/src/commands/agents_deploy.rs
Launch resolver (shared with local spawn)	desktop/src-tauri/src/managed_agents/readiness.rs (resolve_effective_harness_descriptor); launch block emission to be added to agents_deploy.rs (Known Defect 3)
Mesh rewrite (why relay-mesh is non-deployable)	desktop/src-tauri/src/managed_agents/relay_mesh.rs; create-time rejection in commands/agents.rs (normalize_relay_mesh)
Reserved-key strip	desktop/src-tauri/src/managed_agents/env_vars.rs (RESERVED_ENV_KEYS)
Unconditional deploy on Start	desktop/src-tauri/src/commands/agents.rs (start_managed_agent)
Presence publish / offline-on-exit	crates/buzz-acp/src/lib.rs (publish_presence, shutdown path)
!shutdown owner check	crates/buzz-acp/src/lib.rs (main loop)
Graceful shutdown path (budget enforcement to be added — Known Defect 7)	crates/buzz-acp/src/lib.rs (pool shutdown, then drain / reap / presence / relay close)
Clean-exit exit-code contract	to be added: crates/buzz-acp distinguished exit codes + pinning test (Known Defect 6; gates OnFailure)
Auto-stop flag	to be added: crates/buzz-acp/src/config.rs + a pool-independent timer (NOT the pool_ready-gated maintenance tick — Known Defect 4) + RESERVED_ENV_KEYS entry
Kubernetes binding	to be added: crates/buzz-backend-kubernetes
Sprig image	to be added: Dockerfile.sprig + workflow

Open Decisions

Marked [DECISION] inline; consolidated:

• A. Nest scaffolding — should the image entrypoint scaffold the agent workspace (AGENTS.md, RESEARCH/, …) that the desktop's ensure_nest provides locally? Recommendation (revised): workspace becomes a protocol field the desktop states, not an image-baked behavior — the desktop resolves the nest content it would have written locally and carries it in the launch data, so every substrate materializes the same workspace from the same source of truth and the image stays scaffold-free. An image-side template crate was the earlier recommendation; it loses because it forks the nest definition into a second implementation that drifts from ensure_nest.
• B. Windows scope — fix the .exe discovery bug in the desktop now; ship Windows provider binaries only on demand. Recommended as stated.
• C. Config budget — the 9-field v1 set above. Recommended as stated.
• D. Desktop bundling — ~/.local/bin install only for v1. Recommended as stated.
• E. Running-pod semantics — no-op (recommended, both reviewers) vs forcible recycle on Start. Ruled: per-binding policy, with one universal property every binding must preserve — no sequence of Starts yields two live instances in one scope (I4). The Kubernetes binding keeps strict no-op in v1; a recycle affordance, if a binding adds one, is stop-then-start, never delete-under-a-live-agent.
• F. Mesh deployability — the spec refuses relay-mesh agents pre-mutation in v1 (§Launch data: the transport is desktop loopback; serializing it fails identically but invisibly). Reviewer consensus is refusal; ratification requested because it makes a visible product cut (shared-compute agents are local-only until an in-image mesh client exists).
• G. Remote override semantics — the spec keeps local semantics: user env continues to beat Buzz behavior defaults remotely (three-tier precedence, §Launch data), because the alternative is a quiet behavior fork between local and remote spawns of the same record. Flagged because it is a policy statement about what power users may do to remote pods.
• H. Startup budget — with deploy success now requiring container start (§Deploy State Machine), the 600s operation deadline is the de facto cold-pull / scale-from-zero budget. The spec fixes the semantics narrowly: the deadline bounds how long one Start waits synchronously — never when anything is destroyed (recoverable startup is observational across calls, so a cluster whose autoscaler new-pod-scale-up-delay exceeds 600s degrades to "Start reports unconfirmed, a later Start adopts the now-running pod", not a livelock). The remaining SLO ruling is UX-only: is ten minutes of synchronous waiting the right ceiling for the intended cluster class?
• I. Never-started escape hatch — the create-intent fingerprint (§Deploy State Machine) lets a config change replace a never-started pod, closing the config wedge. Ruled on the vision-consistency half: Start-time auto-repair of never-started bodies is legitimate, fenced to Buzz-authored, positively identified residue (§Deploy State Machine auto-repair rule) — the vision's "never-started body is operator residue" line gains that qualifier rather than being waived. The remaining product question: does v1 owe users an explicit in-product "clear this stuck deployment" affordance for a never-started pod whose config they have not changed (a genuinely slow or broken cluster)? Both reviewers agree on the mechanism; this is the remaining product question layered on top of it.

Summary

Remote agents extend Buzz's managed-agent model across a deliberately thin boundary: one untrusted binary, two JSON operations, and a relay. The desktop's obligations end at a well-formed, fail-closed deploy payload; the provider's obligations are convergence and honesty about state; the agent's obligation is to honor its owner's lifetime choice — bounded by default, indefinite by declaration, and in either case final when told to stop. Everything else — status, control, memory — was already on the relay, which is why the design holds: the relay was the management plane all along, and the desktop was only ever one of its doors.