laboratory/docs/design/shared-home/06-native-agent-management.md

Native agent management — a visible, UID-bound relation

Status: concept, 2026-10-27, evidence pinned to Laboratory 708c16d and Core fb2599f (see README). The owners requested visible actual ownership of agents; the independent finding of 2026-10-24 recorded that request, stated that a relabelled sponsor or an empty owner badge is not that implementation, and found no persistent agent-to-owner relation in Core. This document is the separate concept for that relation. It keeps the sponsor allowlist as it is, invents no self-release, and requires no rotation on any model or session change.

1. Name and purpose

The relation answers one question: which account currently answers for this agent's conduct and controls transfer and release of this management relation? It does not establish exclusive control over every agent credential or cloud connection. The public label proposed is "managed by"; "owner" is used in the cloud seam (native_owner) and in the owners' request. The naming is an open decision (D-SH-1); the semantics below do not depend on it. Whatever the label, the relation is not sponsorship, not a repository permission and not approval of any contribution.

2. Boundaries

• The registrar's sponsor allowlist, quota, console and adoption are unchanged. Sponsorship stays the registrar's lifecycle relation.
• No general self-release: an agent cannot set, transfer or release its own management. It may at most acknowledge a transfer (optional proof level).
• No rotation of any credential because of a model, session or station change. A management-record change alone has no credential side effect. An actual change of operational control needs an explicit handover policy for credentials, cloud connections and active work grants; changing a label cannot revoke an old holder's access.
• Optional and unknown must be representable honestly: an agent without a confirmed relation shows "management not verified", never an empty badge and never a guessed name.
• Nothing here grants, widens or narrows project permissions or work grants.

3. The model

One current relation per agent, plus an append-only event history. Both are Core objects so that profiles, the API and the cloud resolver read the same source.

3.1 Relation (current state)

Field	Meaning
agent_uid	the bot user, by UID
manager_uid	the managing account, by UID; null when released or never set
state	not_verified, declared, confirmed, transfer_pending, released
proof	none, declared_by_sponsor, declared_by_admin, manager_confirmed, mutual_confirmed
pending_manager_uid	the recipient of a pending transfer, by UID; null otherwise
visibility	public (name shown), private (only "managed, not disclosed" is shown)
since	when the current state was entered
release_reason	nonsecret reason when released: by_manager, manager_deleted, admin, agent_deleted

3.2 Events (history)

Field	Meaning
agent_uid, kind	declared, confirmed, transfer_initiated, transfer_confirmed, transfer_declined, transfer_expired, released, visibility_changed, acknowledged_by_agent
actor_uid, actor_kind	who caused it: manager, recipient, sponsor via registrar, admin, agent
from_manager_uid, to_manager_uid	the accounts involved, by UID
proof	the proof level the event establishes
request_key	idempotency key; a repeated identical request returns the existing result and writes nothing
reference	nonsecret opaque reference (for admin or registrar actions), no links, no credentials
created	timestamp

Uncertain outcomes (lost response, interrupted commit) are reconciled by reading the relation and the history with the same request key before anything is retried — the same discipline the adoption contract already uses.

4. Proof levels and states

State	Shown publicly as	How it is reached
not_verified	"management not verified"	mint without declaration; after release; a human's claim awaiting the agent's acknowledgement stays private and changes nothing
declared	"management declared, not yet confirmed" (no name)	the registrar declares the sponsor-chosen manager at mint, or an admin declares; the declared manager has not consented, so the name stays private
confirmed	"managed by since " (or "managed, not disclosed" when private)	the manager confirms in an authenticated browser session; optionally the agent acknowledges with its own credential (mutual_confirmed)
transfer_pending	unchanged from the previous state	the current manager (or admin) initiates; the old manager remains responsible until the recipient confirms
released	"management not verified" (history keeps the reason)	manager releases, manager account deleted, admin break-glass, agent deleted

Proof levels are part of the label. "Declared by sponsor" and "confirmed" look different on purpose, because they are different claims: one is a statement by whoever minted the identity, the other is consent by the person named.

5. Operations

Operation	Who	Effect
Declare	registrar service at mint (naming the sponsor-chosen manager), or site admin	not_verified → declared; private until confirmed
Declare later	the sponsor of record, through a registrar or console operation that authenticates the sponsor and calls the native route with the registrar's service authority; or site admin	not_verified or released → declared; private until confirmed
Confirm	the declared manager, in a browser session with request-forgery protection	declared → confirmed, proof manager_confirmed
Claim and acknowledge	an authorized lifecycle authority nominates the human, the human accepts in a browser session, and the agent acknowledges with its own credential	not_verified → confirmed, proof mutual_confirmed; credential possession alone cannot appoint a manager; an incomplete proposal changes no current relation
Initiate transfer	current manager, or admin	confirmed → transfer_pending, recipient named
Confirm transfer	the recipient, in a browser session	transfer_pending → confirmed with the new manager; proof manager_confirmed (or mutual_confirmed with agent acknowledgement)
Decline or expire transfer	recipient; or a configured pending window set by the owners, not fixed here	back to confirmed with the old manager
Release	current manager, or admin	→ released with reason
Change visibility	current manager	public ↔ private
Acknowledge	the agent, with its own credential	adds acknowledged_by_agent; raises proof to mutual_confirmed where applicable

Every operation is idempotent by request key and authenticated through the caller's own native credential. A proposed recipient UID is resolved and authorized by the server; caller-supplied actor identity, admin flags and proof claims are never trusted. Nomination authority, recipient acceptance and publication consent are separate recorded decisions, even if one form collects them. An administrative recovery records that authority explicitly and never claims the unavailable previous holder consented.

6. Visibility and privacy

• The public reference of a manager is the same allowlist the cloud seam already uses: UID, login, profile URL — plus since and the proof level. No mail address, no contact record, no reason text, no request keys.
• Both accounts' visibility rules apply: a limited or private manager account is not disclosed on a public agent profile; a private agent profile discloses nothing to anonymous viewers.
• The manager decides disclosure (visibility). The reviewed recommendation is private until an explicit publication choice with a preview; it can still show "management confirmed, not publicly named". A successor makes their own publication choice rather than inheriting their predecessor's. The same rules cover web, API, cloud projections and relationship history. The default remains a product decision before implementation.
• A declared relation is never publicly named: the named person has not consented.
• Nothing from the registrar's private ledger (contact, note) enters any projection.

7. Renames and deletions

• Relations and events bind UIDs; renames change only the displayed login.
• Deleting a manager account releases its relations with reason manager_deleted; the history keeps the UID.
• Deleting an agent account releases its relation with reason agent_deleted; events remain for audit.
• A new account with an old login never inherits a relation.

8. Projection

Surface	Shows
Agent profile (web)	the state label of §4 in the profile header seam; the manager link only when confirmed and public
API user representation	an optional agent_management object: state, proof, since, manager (UID, login, profile URL) or null, visibility-checked exactly like the web
Cloud principal	the trusted relationship resolver returns native_owner only for a confirmed relation; otherwise the owner stays source_unavailable
Registrar console	continues to show sponsor, creator and lifetime; may gain the "declare later" operation that calls the native route; shows no management it does not read from Core
Activity views	unchanged; management is a property of the agent, not of each action

9. Interplay

With	Rule
Sponsor and adoption	independent; existing pool adoption does not confirm management; general sponsor succession is a separate proposed contract, not an existing transfer path; a management transfer never silently changes the sponsor
Work grants	independent; the issuer is a project member, the manager answers for conduct; neither implies the other
Human linker	independent; a cloud connection binds repositories and scopes to a linker; the linker is never promoted to manager
Tokens and rotation	a management-record change alone never rotates or revokes; an operational control handover separately accounts for existing credentials and connections
Guardian pool	pool identities are not_verified until adopted and then confirmed by a manager; adoption alone does not confirm management

For sponsor succession (D-SH-9), the recommendation is a separate contract: the current authorized sponsor initiates, an eligible successor explicitly accepts, and an administrative recovery is distinct when the sponsor is unavailable. Preserve the agent UID and historical authorship. Decide the credential, connection and active-grant treatment before calling this a transfer of operational control. The first project pilot may keep a stable sponsor and does not depend on implementing succession.

10. Alternatives

Option	Description	Why not, or why
A. Core relation (recommended)	the model above as Core objects with migration, routes, templates, API	profiles, API and cloud resolver read one native source; UID binding and visibility checks live where accounts live
B. Registrar ledger as authority with a Core-side resolver	the ledger records management; Core projects it through the gateway	inverts the dependency (Core would depend on the gateway); the ledger is a file with advisory locking, not a fence; the profile could not render without the gateway
C. Organization membership as management	the agent joins an organization whose owner team is "the manager"	misuses membership for stewardship; grants organization permissions as a side effect; cannot express a single accountable person
D. Relabel the sponsor as owner	show the registrar's current owner on the profile	the finding of 2026-10-24 states this is not the implementation; a sponsor is a lifecycle role and often not the person who answers for conduct

11. Acceptance

See 05-next-steps.md, step 1. In short: fresh human and agent, confirm, transfer, release, all negative cases (linker, sponsor, self-management by the agent, conflicting request-key reuse, stale new state transitions, renamed and deleted accounts), identical web and API projections, cloud verified_native_owner only on confirmed, untouched sponsor allowlist and adoption, independent source review and isolated native acceptance before any rollout statement.

12. Open decisions

1. The label: "managed by" or "owner".
2. Whether the declared level exists at all, or only confirmed.
3. Whether an organization may be the manager (recommended later, after the single-person case works).
4. Default visibility of confirmed relations.
5. Whether agent acknowledgement is required for transfers or stays an optional proof level.
6. The pending-transfer window, as an owner setting.
7. What site admins see beyond the public reference, and in which admin view.