docs(server): ManagerResolver nearest-ancestor contract + proto role-comment sweep (RIG-3080)

go/internal/linearagent/routing.go

@@ -46,7 +46,9 @@ type OwnershipIndex interface {
 // ManagerResolver walks a recorded authoring agent (possibly a peer) to its
 // owning Manager and returns that Manager's account id and home channel id.
 // It is its own narrow seam because no single store method spans the tree walk
-// (up parent_agent_id to a role="manager" agent) AND the home-channel read; the
+// (up parent_agent_id to the nearest tree ancestor — any Manager-class role,
+// not a role=="manager" filter, since every tree node is now Manager-class and
+// an owner parent must not be skipped) AND the home-channel read; the
 // driver backs it with the store's agent-tree + account reads at assembly.
 // store.ErrNotFound when the agent (or a walk ancestor) does not resolve.
 type ManagerResolver interface {

packages/compass-agent/src/gen/compass/v1/compass_pb.ts

@@ -1100,17 +1100,23 @@ export type ProvisionAgentWorkspaceRequest = Message<"compass.v1.ProvisionAgentW
   persona: string;
 
   /**
-   * The agent's operator-set role, selecting the container's block-0 system
-   * prompt at provision so it survives compaction (a system-prompt config block
-   * is not part of the message history a snapcompact archives). SERVER-
-   * AUTHORITATIVE: the Server is expected to populate this by reading
-   * AgentAccount.role from the store on the provision path and to overwrite any
-   * client-supplied value, so a caller cannot inject a role prompt — an
-   * invariant enforced by the server provision path (not by this wire-settable
-   * field). Where persona (field 3) is an APPEND overlay, role REPLACES block-0:
-   * the label selects config/prompts/<role>/SYSTEM.md, materialized by the
-   * Runner into the container's customSystemPrompt (compass-runner consumer).
-   * Empty = no role (default OMP block-0).
+   * The agent's role, selected at spawn from the closed taxonomy
+   * (supervisor/owner/manager) and server-validated, selecting the container's
+   * block-0 system prompt at provision so it survives compaction (a
+   * system-prompt config block is not part of the message history a snapcompact
+   * archives). The label's ORIGIN is spawner-selected: the spawn request
+   * carries a required label from the closed taxonomy, validated against the
+   * server's spawnableRoles set (INVALID_ARGUMENT on an unknown label) before
+   * it is stored. This provision field stays SERVER-AUTHORITATIVE: the Server
+   * populates it by reading the stored AgentAccount.role (the provision source
+   * of record) and overwrites any client-supplied value, so a caller cannot
+   * inject a role prompt via provision — prompt TEXT ships only in the
+   * operator-published config bundle. Where persona (field 3) is an APPEND
+   * overlay, role REPLACES block-0: the label selects
+   * config/prompts/<role>/SYSTEM.md, materialized by the Runner into the
+   * container's customSystemPrompt (compass-runner consumer). A role is
+   * required at spawn; this provision field is optional and an empty stored
+   * role yields the default OMP block-0.
    *
    * @generated from field: string role = 4;
    */

packages/compass-client/src/gen/compass/v1/compass_pb.ts

@@ -1100,17 +1100,23 @@ export type ProvisionAgentWorkspaceRequest = Message<"compass.v1.ProvisionAgentW
   persona: string;
 
   /**
-   * The agent's operator-set role, selecting the container's block-0 system
-   * prompt at provision so it survives compaction (a system-prompt config block
-   * is not part of the message history a snapcompact archives). SERVER-
-   * AUTHORITATIVE: the Server is expected to populate this by reading
-   * AgentAccount.role from the store on the provision path and to overwrite any
-   * client-supplied value, so a caller cannot inject a role prompt — an
-   * invariant enforced by the server provision path (not by this wire-settable
-   * field). Where persona (field 3) is an APPEND overlay, role REPLACES block-0:
-   * the label selects config/prompts/<role>/SYSTEM.md, materialized by the
-   * Runner into the container's customSystemPrompt (compass-runner consumer).
-   * Empty = no role (default OMP block-0).
+   * The agent's role, selected at spawn from the closed taxonomy
+   * (supervisor/owner/manager) and server-validated, selecting the container's
+   * block-0 system prompt at provision so it survives compaction (a
+   * system-prompt config block is not part of the message history a snapcompact
+   * archives). The label's ORIGIN is spawner-selected: the spawn request
+   * carries a required label from the closed taxonomy, validated against the
+   * server's spawnableRoles set (INVALID_ARGUMENT on an unknown label) before
+   * it is stored. This provision field stays SERVER-AUTHORITATIVE: the Server
+   * populates it by reading the stored AgentAccount.role (the provision source
+   * of record) and overwrites any client-supplied value, so a caller cannot
+   * inject a role prompt via provision — prompt TEXT ships only in the
+   * operator-published config bundle. Where persona (field 3) is an APPEND
+   * overlay, role REPLACES block-0: the label selects
+   * config/prompts/<role>/SYSTEM.md, materialized by the Runner into the
+   * container's customSystemPrompt (compass-runner consumer). A role is
+   * required at spawn; this provision field is optional and an empty stored
+   * role yields the default OMP block-0.
    *
    * @generated from field: string role = 4;
    */

proto/compass/v1/compass.proto

@@ -596,17 +596,23 @@ message ProvisionAgentWorkspaceRequest {
   // it into the container
   // (compass-runner consumer). Empty = no persona baked (default).
   string persona = 3;
-  // The agent's operator-set role, selecting the container's block-0 system
-  // prompt at provision so it survives compaction (a system-prompt config block
-  // is not part of the message history a snapcompact archives). SERVER-
-  // AUTHORITATIVE: the Server is expected to populate this by reading
-  // AgentAccount.role from the store on the provision path and to overwrite any
-  // client-supplied value, so a caller cannot inject a role prompt — an
-  // invariant enforced by the server provision path (not by this wire-settable
-  // field). Where persona (field 3) is an APPEND overlay, role REPLACES block-0:
-  // the label selects config/prompts/<role>/SYSTEM.md, materialized by the
-  // Runner into the container's customSystemPrompt (compass-runner consumer).
-  // Empty = no role (default OMP block-0).
+  // The agent's role, selected at spawn from the closed taxonomy
+  // (supervisor/owner/manager) and server-validated, selecting the container's
+  // block-0 system prompt at provision so it survives compaction (a
+  // system-prompt config block is not part of the message history a snapcompact
+  // archives). The label's ORIGIN is spawner-selected: the spawn request
+  // carries a required label from the closed taxonomy, validated against the
+  // server's spawnableRoles set (INVALID_ARGUMENT on an unknown label) before
+  // it is stored. This provision field stays SERVER-AUTHORITATIVE: the Server
+  // populates it by reading the stored AgentAccount.role (the provision source
+  // of record) and overwrites any client-supplied value, so a caller cannot
+  // inject a role prompt via provision — prompt TEXT ships only in the
+  // operator-published config bundle. Where persona (field 3) is an APPEND
+  // overlay, role REPLACES block-0: the label selects
+  // config/prompts/<role>/SYSTEM.md, materialized by the Runner into the
+  // container's customSystemPrompt (compass-runner consumer). A role is
+  // required at spawn; this provision field is optional and an empty stored
+  // role yields the default OMP block-0.
   string role = 4;
 }