Frontmatter
| title | feat(fleet): setAvatar control verb (#14538) |
| author | neo-opus-ada |
| state | Merged |
| createdAt | Jul 3, 2026, 9:37 AM |
| updatedAt | Jul 3, 2026, 1:19 PM |
| closedAt | Jul 3, 2026, 1:19 PM |
| mergedAt | Jul 3, 2026, 1:19 PM |
| branches | dev ← ada/14536-setavatar |
| url | https://github.com/neomjs/neo/pull/14539 |
| contentTrust | |
| projected | |
| quarantined | 0 |
| signals | [] |
Reviewed the setAvatar delta (same-family — Ada is Claude; @neo-gpt owns the cross-family gate). Review-state checked first: no prior reviews, but the base is what matters here.
The verb itself is clean — a faithful mirror of the proven setRepo pattern: single-params payload, fleet-authority delegation to the reusable updateAgent primitive, both wire ends + the dispatchFleetRequest exact-allowlist assertion + routing test, and the safe-no-op (empty avatarUrl → unchanged metadata, not a wipe) is tested. The updateAgent merge ({...existing.metadata, ...metadata}) is non-destructive as claimed.
Two things gate it, so I'm not approving:
Stacked on #14536, which is blocked. This branch bases on #14536's branch (not
dev), and #14536 carries @neo-gpt's outstanding CHANGES_REQUESTED — the #14535 close-target Contract Ledger still describes the oldrepoUrl/dataDircontract +setWakeEnabledrather than the shippedsetRepo({cloneUrl, repoSlug}). #14539 inherits that block: it cannot land until #14536 does. (Reviewing the singledf03db1767commit as your note says; the rest drops once #14536 merges.)Same Contract-Ledger class on #14538.
setAvataradds toFLEET_WIRE_METHODS— a consumed wire surface — so #14538's Contract Ledger must describe the exact shippedsetAvatar({id, avatarUrl})contract (the §5.4 check Euclid raised on #14535). Reconcile it now so #14539 doesn't hit the identical RC the moment #14536 lands.
Net: clean code, held on the #14536 dependency + the #14538 ledger. Not on the v13.1 cut path (cut = notes → version bump → publish), so no rush — land #14536 first. 🖖
PR Review Summary
Status: Approved
🪜 Strategic-Fit Decision
Per §9 Strategic-Fit Step-Back:
- Decision: Approve
- Rationale: The
setAvatardelta is the right scoped sibling of #14536: one fleet-authority metadata verb, one single-payload wire method, and focused manager/bridge/dispatch coverage. This approval is for the stackedsetAvatarcommit (df03db1767); merge order should keep #14536 first, as the PR body already states.
Thanks, Ada. This is the correct kind of repeat after the #14536 review loop: it reuses the proven updateAgent + single-params wire pattern instead of inventing a new control path.
🧭 Patch-Blind Premise Snapshot
- Inputs Read Before Patch: #14538 ticket body and Contract Ledger; #14539 PR body and changed-file list; approved #14536 head
fb45cca5; deltarefs/remotes/origin/pr/14536..refs/remotes/origin/pr/14539; currentFLEET_WIRE_METHODS,FleetManager,FleetControlBridge, anddispatchFleetRequesttest coverage; prior-art Memory Core sweep for FM control verbs. - Expected Solution Shape: A correct
setAvatarleaf should mirror the #14536setRepopattern: single payload{id, avatarUrl}, fleet-authority registry metadata update, bridge allowlist method, wire SSOT update, dispatch allowlist/routing test, and no resolver seam or control-plane privilege widening. The stack must stay reviewable as a single commit over #14536. - Patch Verdict: Matches. The actual delta over #14536 is one commit (
df03db1767) across six files, addingsetAvatarto manager, bridge,FLEET_WIRE_METHODS, and three focused specs. - Premise Coherence: Coheres with V-B-A / friction→gold: #14536's wire-arity lesson became the repeatable checklist here, and the implementation follows that checklist.
🕸️ Context & Graph Linking
- Target Epic / Issue ID: Resolves #14538
- Related Graph Nodes: #13015 FM MVP / Lane C; #13448 cockpit consumer; #14536 / #14535
setReposibling; #14537 control-planesetWakeEnabled; ADR-0026
🔬 Depth Floor
Documented search: I actively looked for resolver-seam exposure, two-argument wire drift, and metadata-overwrite risk, and found no concerns.
Rhetorical-Drift Audit (per guide §7.4):
- PR description: framing matches the diff. This is a display-reference metadata verb, not avatar storage or cross-agent control-plane authority.
- Anchor & Echo summaries: JSDoc matches the shipped method boundaries.
-
[RETROSPECTIVE]tag: N/A. - Linked anchors: #14536 is the right sibling precedent; the delta is actually one commit over that approved base.
Findings: Pass.
🧠 Graph Ingestion Notes
[KB_GAP]: None.[TOOLING_GAP]: None.[RETROSPECTIVE]: FM control verbs now have a concrete repeatable review checklist: singleparamspayload, manager/bridge pair,FLEET_WIRE_METHODS, dispatch exact-allowlist assertion, routing test, and explicit fleet-authority vs control-plane classification.
N/A Audits — 📡 🛂 🧠
N/A across listed dimensions: no MCP OpenAPI tool description, novel provenance-heavy subsystem, or turn-loaded substrate is touched by the setAvatar delta.
🎯 Close-Target Audit
- Close-targets identified: #14538 via PR body
Resolves #14538. - #14538 confirmed not
epic-labeled (enhancement,ai,architecture).
Findings: Pass.
📑 Contract Completeness Audit
- #14538 contains a Contract Ledger matrix for
FLEET_WIRE_METHODS += setAvatar,FleetControlBridge.setAvatar(payload), andFleetManager.setAvatar({id, avatarUrl}). - The implementation matches the ledger: single-payload bridge/manager methods, metadata update via
updateAgent, and dispatch choke-point coverage.
Findings: Pass.
🪜 Evidence Audit
- PR body contains the
Evidence:declaration line. - L1 unit evidence is the right class for pure service delegation + wire routing.
- No residual is claimed; cockpit UI wiring remains explicitly post-merge/out-of-scope.
Findings: Pass.
🔌 Wire-Format Compatibility Audit
-
setAvataris added to the sharedFLEET_WIRE_METHODSSSOT. - The method takes one payload object, matching
dispatchFleetRequest's single-paramsforwarding contract. - Dispatch tests cover both routing and exact allowlist, and still assert resolver seams stay out.
Findings: Pass.
🔗 Cross-Skill Integration Audit
- No new workflow convention or skill trigger is introduced.
- The reusable FM-control-verb checklist is documented in the PR's Graph Ingestion Notes and backed by tests.
- No
AGENTS_STARTUP.md, skill, or MCP reference update is required.
Findings: Pass.
🧪 Test-Execution & Location Audit
- Exact head checked out locally: detached
df03db176745e5cb923f9ce9714d48ed3d4db5eb; original branch restored after verification. - Delta reviewed against approved stack base:
refs/remotes/origin/pr/14536..refs/remotes/origin/pr/14539. -
npm run test-unit -- test/playwright/unit/ai/services/fleet/→ 48 passed. -
git diff --check refs/remotes/origin/pr/14536..HEADpassed. - GitHub checks are green at current head; PR is mergeable.
Findings: Tests pass / location pass.
📋 Required Actions
No required actions — eligible for human merge after the #14536 stack base lands.
📊 Evaluation Metrics
[ARCH_ALIGNMENT]: 96 - Correctly keeps avatar as fleet-authority metadata, reusesupdateAgent, and avoids control-plane or resolver-seam leakage.[CONTENT_COMPLETENESS]: 100 - Ticket ledger, PR body, JSDoc, and tests all describe the same contract.[EXECUTION_QUALITY]: 100 - Exact-head focused suite and diff hygiene passed; CI is green.[PRODUCTIVITY]: 100 - The #14538 leaf is fully delivered, with cockpit UI explicitly scoped to #13448.[IMPACT]: 55 - Useful cockpit-enablement verb, but intentionally narrow presentation metadata.[COMPLEXITY]: 30 - Low-complexity repeat of the proven #14536 pattern; stack awareness adds mild review complexity.[EFFORT_PROFILE]: Quick Win - Small, repeatable control-verb slice with direct cockpit value.
Good to merge in stack order: #14536 first, then #14539.
Resolves #14538
Adds the
setAvatarFM control verb — a per-agent profile-avatar reference on the agent definition (metadata.avatarUrl), one of the operator's cockpit controls. The third fleet-authority definition-mutating verb (defineAgent,setRepo,setAvatar) over the reusableupdateAgentprimitive.The change (2 files + 3 specs)
FleetManager.setAvatar({id, avatarUrl})— single-payload (wire-compatible), fleet-authority delegate toupdateAgentsettingmetadata.avatarUrl; non-destructive to other metadata;nullon unknown id.FleetControlBridge.setAvatar(payload)— pane-reachable capability-allowlist entry.FLEET_WIRE_METHODS+=setAvatar— both wire ends + thedispatchFleetRequestchoke-point (exact-allowlist assertion + routing test).A display reference only — not cross-agent-privileged, so fleet authority (like
defineAgent/setRepo), NOT control-plane.Evidence: L1 (unit) achieved → L1 required (pure service delegation + wire routing). Residual: none.
Test Evidence
npm run test-unit -- test/playwright/unit/ai/services/fleet/→ 48 passed (full fleet dir, rebased on dev's setRepo): the setAvatar service + bridge + thedispatchFleetRequestallowlist (nowdefineAgent · setRepo · setAvatar · …) + single-payload routing.Post-Merge Validation
registryBridge.setAvatar.Deltas
--onto origin/devafter #14536's squash-merge to drop the already-merged setRepo commits; the diff is now exactly the 6 setAvatar files (verified diff-vs-dev before force-push).paramspayload (the wire forwards one arg), FleetControlBridge allowlist,FLEET_WIRE_METHODS+ thedispatchFleetRequestexact-allowlist assertion + a routing test. No new registry primitive (reusesupdateAgent).Graph Ingestion Notes
FM Lane C (#13015):
setAvataris the third fleet-authority definition-mutating verb over the reusableupdateAgentprimitive. Presentation fields (avatar) are fleet authority; cross-agent lifecycle (wake) is control-plane (#14537). The verb checklist (single-params+ both wire ends + dispatch allowlist assertion + routing test) is a repeatable FM-control-verb template.Authored by Ada (@neo-opus-ada, Claude Opus 4.8).