docs(corpus): compute layer — backend provider, kubernetes provider, lifecycle (#611) - #1902
serina-mcfall wants to merge 3 commits into
Conversation
Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
There was a problem hiding this comment.
Reviewed commit 3b984f4dc247101a6c4755a5ac042cc91506d405 against merge base 338b4d0cf2dd76cc43964bb717ce9f0a94a9c7a5.
Incomplete
This review is INCOMPLETE and must not be read as a full pass:
- no dimension was actually reviewed: the pipeline ran the 'default_reviewer' stub reviewer, which reports every dimension clean without reading it (a real dimension reviewer is #116)
Containment
No containment findings.
Fetched and empty: pr_issue_comments, pr_review_bodies, pr_review_comments.
Automated containment covers the delimiter boundary and unambiguous injection tells only. It does not cover injection phrased as ordinary, unremarkable prose. The absence of a containment finding is not evidence that this pull request contains no injection attempt.
tucktuck101
left a comment
There was a problem hiding this comment.
Panel review — fable + codex (gpt-5.6-sol)
Two independent reviewers read this PR (diff, linked issues #1041/#1042/#1043, and the current
crates/buzz-backend-kubernetes source) without seeing each other's output.
High — verified, security-relevant
lifecycle.md:179 overstates automatic secret cleanup. The doc says an orphaned Secret
(which holds the agent's nsec) from a terminated pod is "collected after 1200 seconds." I
confirmed this is false: crates/buzz-backend-kubernetes/src/gc.rs runs GC only as a preflight
step of a subsequent deploy (module doc: "GC runs on every deploy"; sole call site is
reconcile.rs:179, itself only reached from a deploy request) — there is no background/scheduled
sweep. A Secret referenced by any existing pod, including a terminated one, is explicitly
protected (gc.rs:70-82). If no further deploy happens for that agent, the terminated pod and its
nsec-bearing Secret are never cleaned up automatically. This is exactly the kind of claim an
operator would trust when reasoning about credential lifetime. [codex]
Medium
kubernetes-provider.md:101's evidence ledger callsDEFAULT_IMAGEa compile-time-pinned
runtime default; source calls it a UI schema prefill ("not a baked fallback") —
imageremains a required field that must arrive inprovider_config
(crates/buzz-backend-kubernetes/src/config.rs:37-44,121-139). Non-Desktop callers get no
provider-side safe default, which matters because digest pinning is the doc's own supply-chain
control. [codex]kubernetes-provider.md:157,229-242presents the systemd/SSH alternate provider's execution and
protocol behavior as verified current implementation, while the doc's own text at :292-295
admits PR block#3449 was never opened. Don't assert behavior for code you haven't read. [codex]kubernetes-provider.md:86's FACT entry says the provider "builds the pod entrypoint to exec
buzz-acp as PID 1" — backwards: the image owns the entrypoint, and the provider deliberately
never setscommand/args(pod.rs:111, testdoes_not_override_the_image_entrypointat
pod.rs:302-306). [fable]- All three
layers/compute/*docs in this batch merge together with zero relationship edges
between them, whilelifecycle.md:308-312asserts "nolayers/*sibling exists yet" — true at
the pinned revision, misleading in the merged tree (same stale-sibling-prose pattern seen in
other batches this sweep). [fable]
Low
lifecycle.md:30enumerates 8 of 11Substratetrait methods, omittinglist_secrets,
secret_exists,delete_secret(reconcile.rs:56-103). [fable]lifecycle.md:135undercounts thearchitecture/flowsfamily (12 vs. 14 at the pinned
revision). [fable]- Minor evidence-range imprecision on two Known-Defect citations, and one disclosed gap
(RESERVED_ENV_KEYS) that's actually already satisfied and should be promoted from gap to
FACT. [fable]
What looks good
- Provider discovery, executable filtering, ID validation, immutable staging, pre-secret protocol
negotiation, config secret-key rejection, ambient kubeconfig auth,inactivity_seconds: 0
refusal,restartPolicy: Never, pod hardening, digest enforcement, and fenced reconciliation
all check out against current source. All 9 named unit tests verified at exact line numbers.
Known-Defect-5 stale-drift finding is real and correctly escalated rather than silently patched.
No secrets, migrations, or runtime code changed by this diff itself.
Verdict
Request changes. Panel split (fable: comment / codex: request changes), settled by
independent verification: the secret-lifecycle claim is real, security-relevant, and would mislead
an operator about how long an nsec sits in a cluster after an agent stops being redeployed.
Summary
Authors three canonical corpus documents for Feature #611's compute layer — backend provider, Kubernetes provider, and compute-instance lifecycle — each with schema-valid front matter and evidence grounded in the current
buzz-backend-kubernetes/buzz-acpimplementation.Feature
#611
Related issue
Closes #1041
Closes #1042
Closes #1043
Issue type
Task
Agent provenance
Objective
Create
layers/compute/backend-provider.md,layers/compute/kubernetes-provider.md, andlayers/compute/lifecycle.mdas the canonical corpus nodes for issues #1041-#1043.Impacted components
Approach and rejected alternatives
Per Serina's confirmed choice (3-option AskUserQuestion) for this batch run: one draft PR per batch of ≤5 tasks, each task built independently in its own worktree without pushing, then integrated here by cherry-picking the individual signed commits onto one shared branch. Rejected: one-PR-per-task (the
corpus-batch-authorskill's literal default — 36 PRs across this Feature) as too many to triage; one giant PR for the whole Feature as impossible to review in one sitting. This Feature's 36 tasks are further split 5-per-dispatch-batch, 3+2 per PR within each dispatch batch, because a straight 5-doc PR measured at 2055 added lines / 10 files, over ADR-0052 part C's 1,500-line cap (per #610's own precedent for the same failure mode) — this PR is the "3" half of dispatch batch 1.Verification
Command run:
Raw output:
Command run:
Raw output:
Not verified
buzz-backend-kubernetescurrently ships in this repo; whether desktop onboarding UI surfaces the required trust warning before a user configures a provider.deploy_payload_jsonnow emits a completelaunchblock (spec names this as a known desktop-side defect at the recorded revision); whetherrestartPolicy: OnFailurehas since shipped; PR feat: remote agents over SSH — provider contract, buzz-backend-ssh, and where-runs-first block/buzz#3449's actual diff was not independently opened; no deploy was run against a live or fake cluster.docs/remote-agents.mdKnown Defects 6/7 are still open at this node's checked revision;RESERVED_ENV_KEYSmembership inenv_vars.rswas not directly opened; no cluster-integration test suite was found for the Kubernetes binding, only unit tests against a fakeSubstrate; the desktop-side staging/digest/protocol-version-negotiation code was located but not read line-by-line.corpus-batch-authorskill,review-adjudicateand a cross-model pass were not run per document — deferred to the batch owner's review before merge, same as feature: data and storage layer corpus exists #610.Authority
N/A - approved by a human directly
Deferred blockers
none
Security implications
None — these are documentation-only additions under
launchpad/docs/corpus/andlaunchpad/plans/; no runtime code, config, or secret-handling paths changed.Escalations
docs/remote-agents.md's own "Known Defects" section (pinned to commit28ae6cd21) still lists the pre-secret protocol-version check as missing, butbackend.rs'sprovider_deployalready implements it (fix landed in6530b58a6, confirmed a descendant viagit merge-base --is-ancestor). Not fixed here —docs/remote-agents.mdis out of this task's scope. Worth its own follow-up issue.ManagedAgentRecord.provider) may warrant its own corpus node given how easily its name collides with "backend provider" — left out per the corpus atomicity standard, noted for the batch owner to consider filing.type: layersto aflow.md-templated node rather than that template's own worked-skeleton default oftype: architecture— reasoned explicitly in the node's own "note on type" section (this Feature's taxonomy islayers, not the existingarchitecture/flows/*C4-Dynamic family the template's default precedent comes from). Flagged for reviewer confirmation, not decided unilaterally as settled.