Neutral worker activation, caller-selected validation, and atomic claim #992

New Issue

2026-07-31T10:18:17-05:00

jcwalker3 commented

2026-07-31 10:18:17 -05:00

Parent umbrella: issue #989. Informative bootstrap evidence only, not a machine-enforced dependency; Child 1 delivers structured relationships and backfills this.

Problem

Two gaps compound. There is no way for an uncommitted worker to enter the Control Plane without already occupying a role-bound profile, so the charter's first step cannot be satisfied. And there is no single sanctioned protocol that takes a caller-selected task, derives its role, revalidates everything mutable, publishes authoritative ownership, and resolves contention as one fail-closed claim decision.

Charter connection

Roles — "An LLM never begins a cycle already holding one of these roles"; roles are temporary and derived strictly from the chosen task. Steps 5 through 8. Responsibilities — the MCP may reject an unsafe or stale choice but must not decide which task the LLM wants. Contention is normal — a failed claim is expected; the worker re-evaluates from fresh state rather than retrying. Identity and independence — the identity that authored or last pushed to a PR cannot review, approve, or merge it.

Verified current gap

Every worker namespace binds a fixed role profile at session start, and identity surfaces report a session role kind before any task is chosen. The pre-task router classifies a task against the already-active profile. Capability authorization is carried in global last-resolved-task state, so any intervening call invalidates it (#889), making correctness depend on emitting two adjacent tool calls. Mutation verification does not check the lock generation (#793 AC-C1). Claim primitives accept caller-named targets but have divergent shapes and derive no role.

Scope

A. Neutral entry. One entry path for a general, uncommitted worker: a base identity with read capability sufficient to inspect neutral project state, holding no task role and no role-scoped worker profile. Neutral means no task role has yet been adopted — it is not a new permanent role.

B. Task-scoped activation. After the caller selects a specific task and validation passes, the Control Plane derives the temporary role from that task and activates narrowly task-scoped capabilities bound to: worker identity, repository, selected issue or PR, derived role, permitted operations, pinned state or mutation grant, authoritative claim or lease, and expiration.

C. Lifecycle. Activation only after authoritative Gitea claim publication succeeds. Automatic expiration at cycle completion. Immediate revocation on release, block, failed validation, stale state, or ownership loss. Return to the neutral state after completion or release.

D. Independence. Identity-level author, reviewer, approver, and merger independence enforced regardless of the temporary role. No path yields reviewer, approver, or merger capability for work authored or pushed by the same identity.

E. Audit. Auditable Gitea lifecycle transitions for task ownership.

F. Atomic claim decision. This is not a distributed transaction across Gitea and the control-plane database. It is a fail-closed publication protocol whose externally visible result is either one authoritative acquired claim or a typed non-acquisition.

Pin or grant. Validation returns a pinned task-state fingerprint — identity, capability verdict, repository binding, parity revision, dependency-edge states, head SHA where applicable, claim generation — or consumes a single-use mutation grant (#889). No claim proceeds without one.
Revalidate at claim time. Nothing from inspection is trusted at claim; identity, parity, dependency state, head SHA, and claim state are re-read inside the claim operation.
Compare-and-swap acquisition against the pinned generation; a generation advance loses deterministically.
No substitution. The claimed target is identical to the validated target — kind, number, repository, head. No equivalent item, no scope widening between validation and acquisition.
Typed contention. On loss: a structured result naming the failed predicate, stating contention is a normal outcome, and requiring fresh inspection. It contains no suggested replacement task, and automatic retry of the same claim is prohibited by contract.

Non-goals

Selecting or ranking work. Creating a permanent neutral role. Replacing the individual lock and lease primitives — they remain independently callable. Re-owning #889's grant model, #890's ownership record, #793's fencing, or Child 1's claim record. Weakening exclusivity or independence.

Functional requirements

Role derivation is server-side and follows solely from the chosen task's kind and state. Typed failure classes are distinct and exhaustive: stale state, contention, policy, eligibility, authority. Rejection reasons must not vary in a way that routes workers toward particular tasks, and the rule set is a durable reviewable Gitea artifact so routing patterns can be audited.

Safety and authority boundaries

Validation may reject; it may never select. Before task selection, only the neutral base identity and read capability exist; no task-scoped mutation capability exists. Every activated task capability is scoped, bound, expiring, and revocable. Independence is enforced at identity level and cannot be escaped by role derivation.

Acceptance criteria

A worker enters with no task role and no role-scoped profile and can inspect neutral state.
No task-scoped capability exists before a task is selected and validated.
Activation binds all eight listed dimensions.
Activation is unavailable until the authoritative Gitea claim is published.
Capability expires automatically at cycle completion and is revoked immediately on release, block, failed validation, stale state, or ownership loss.
After completion or release the worker is neutral again, holding no task capability.
The same identity cannot obtain reviewer, approver, or merger capability for work it authored or pushed — asserted per role.
Role is derived server-side from the selected task.
All five claim-safety clauses hold, individually tested.
Foreign-claimed, dependency-gated, terminal, ineligible, and stale targets each fail closed with a distinct typed blocker.
Contention returns a typed result naming no substitute; automatic retry is impossible.
Two callers selecting one item yield exactly one winner; the loser receives a reassess-from-fresh-state result.
Read-only calls between selection and claim do not invalidate the claim.
Lock and lease primitives remain independently callable and behaviourally unchanged.
Lifecycle transitions are recorded auditably in Gitea.

Required tests and validation

Neutral entry holding no role. Capability absent before selection. Each activation binding. Activation refused while only a transient reservation exists. Expiration at cycle completion. Revocation on each of the five triggers. Return to neutral. Independence refusal for author-then-reviewer, author-then-approver, author-then-merger, and pusher-then-reviewer. Each claim-safety clause. A deliberate time-of-check/time-of-use substitution attempt. A generation advanced between pin and claim. Each fail-closed class. Two-worker and four-worker contention tests. An assertion that no refusal payload names a task other than the requested one. Read-only interleaving. Contract tests confirming the existing primitives remain schema-compatible and semantically equivalent under deterministic fixtures.

Dependencies

Until Child 1 delivers sanctioned structured relationship operations, the references below are informative bootstrap evidence only. They must not be treated as machine-enforced hard dependencies. Child 1 must backfill the appropriate structured relationships.

Hard: Child 1 (Gitea claim record and publication protocol), #889 grants, #890 ownership record, #793 read-side fencing. Also Child 2, the inventory a caller selects from.

Compatibility and rollout

Additive; the allocator is untouched here. Existing primitives keep documented fields and typed failure contracts. Any intentional change to an existing contract is versioned with a documented migration.

Rollback behavior

Reverting removes neutral entry and task-scoped activation and returns workers to the previous role-bound namespaces only as a stop-and-halt state, not as a supported operating mode: autonomous cycles stop safely. Rollback never re-authorizes allocator selection, allocator-created claims, permanent roles, or role-first discovery.

Documentation requirements

The neutral-entry contract. The task-scoped capability lifecycle including every binding, expiry, and revocation trigger. The claim contract and typed failure taxonomy. The published rejection-rule artifact.

Completion evidence

Neutral-entry and lifecycle test results, the independence refusal matrix, the two- and four-worker contention results, the substitution-attempt results, and the published rejection-rule artifact.

Reusable existing issues, PRs, and primitives

#889, #890, #793, #952. Live primitives: issue locking; reviewer, merger, and adoption lease operations; task capability resolution; PR eligibility checking; master-parity assessment; identity lookup.

Fundamental-workflow stage supported

choose -> derive role -> validate -> claim — charter steps 1, 5, 6, 7, and 8, plus Contention is normal and Identity and independence.

Parent umbrella: issue #989. Informative bootstrap evidence only, not a machine-enforced dependency; Child 1 delivers structured relationships and backfills this. ## Problem Two gaps compound. There is no way for an uncommitted worker to enter the Control Plane without already occupying a role-bound profile, so the charter's first step cannot be satisfied. And there is no single sanctioned protocol that takes a caller-selected task, derives its role, revalidates everything mutable, publishes authoritative ownership, and resolves contention as one fail-closed claim decision. ## Charter connection Roles — "An LLM never begins a cycle already holding one of these roles"; roles are temporary and derived strictly from the chosen task. Steps 5 through 8. Responsibilities — the MCP may reject an unsafe or stale choice but must not decide which task the LLM wants. Contention is normal — a failed claim is expected; the worker re-evaluates from fresh state rather than retrying. Identity and independence — the identity that authored or last pushed to a PR cannot review, approve, or merge it. ## Verified current gap Every worker namespace binds a fixed role profile at session start, and identity surfaces report a session role kind before any task is chosen. The pre-task router classifies a task against the already-active profile. Capability authorization is carried in global last-resolved-task state, so any intervening call invalidates it (#889), making correctness depend on emitting two adjacent tool calls. Mutation verification does not check the lock generation (#793 AC-C1). Claim primitives accept caller-named targets but have divergent shapes and derive no role. ## Scope **A. Neutral entry.** One entry path for a general, uncommitted worker: a base identity with read capability sufficient to inspect neutral project state, holding no task role and no role-scoped worker profile. Neutral means no task role has yet been adopted — it is not a new permanent role. **B. Task-scoped activation.** After the caller selects a specific task and validation passes, the Control Plane derives the temporary role from that task and activates narrowly task-scoped capabilities bound to: worker identity, repository, selected issue or PR, derived role, permitted operations, pinned state or mutation grant, authoritative claim or lease, and expiration. **C. Lifecycle.** Activation only after authoritative Gitea claim publication succeeds. Automatic expiration at cycle completion. Immediate revocation on release, block, failed validation, stale state, or ownership loss. Return to the neutral state after completion or release. **D. Independence.** Identity-level author, reviewer, approver, and merger independence enforced regardless of the temporary role. No path yields reviewer, approver, or merger capability for work authored or pushed by the same identity. **E. Audit.** Auditable Gitea lifecycle transitions for task ownership. **F. Atomic claim decision.** This is not a distributed transaction across Gitea and the control-plane database. It is a fail-closed publication protocol whose externally visible result is either one authoritative acquired claim or a typed non-acquisition. - **Pin or grant.** Validation returns a pinned task-state fingerprint — identity, capability verdict, repository binding, parity revision, dependency-edge states, head SHA where applicable, claim generation — or consumes a single-use mutation grant (#889). No claim proceeds without one. - **Revalidate at claim time.** Nothing from inspection is trusted at claim; identity, parity, dependency state, head SHA, and claim state are re-read inside the claim operation. - **Compare-and-swap** acquisition against the pinned generation; a generation advance loses deterministically. - **No substitution.** The claimed target is identical to the validated target — kind, number, repository, head. No equivalent item, no scope widening between validation and acquisition. - **Typed contention.** On loss: a structured result naming the failed predicate, stating contention is a normal outcome, and requiring fresh inspection. It contains no suggested replacement task, and automatic retry of the same claim is prohibited by contract. ## Non-goals Selecting or ranking work. Creating a permanent neutral role. Replacing the individual lock and lease primitives — they remain independently callable. Re-owning #889's grant model, #890's ownership record, #793's fencing, or Child 1's claim record. Weakening exclusivity or independence. ## Functional requirements Role derivation is server-side and follows solely from the chosen task's kind and state. Typed failure classes are distinct and exhaustive: stale state, contention, policy, eligibility, authority. Rejection reasons must not vary in a way that routes workers toward particular tasks, and the rule set is a durable reviewable Gitea artifact so routing patterns can be audited. ## Safety and authority boundaries Validation may reject; it may never select. Before task selection, only the neutral base identity and read capability exist; no task-scoped mutation capability exists. Every activated task capability is scoped, bound, expiring, and revocable. Independence is enforced at identity level and cannot be escaped by role derivation. ## Acceptance criteria - A worker enters with no task role and no role-scoped profile and can inspect neutral state. - No task-scoped capability exists before a task is selected and validated. - Activation binds all eight listed dimensions. - Activation is unavailable until the authoritative Gitea claim is published. - Capability expires automatically at cycle completion and is revoked immediately on release, block, failed validation, stale state, or ownership loss. - After completion or release the worker is neutral again, holding no task capability. - The same identity cannot obtain reviewer, approver, or merger capability for work it authored or pushed — asserted per role. - Role is derived server-side from the selected task. - All five claim-safety clauses hold, individually tested. - Foreign-claimed, dependency-gated, terminal, ineligible, and stale targets each fail closed with a distinct typed blocker. - Contention returns a typed result naming no substitute; automatic retry is impossible. - Two callers selecting one item yield exactly one winner; the loser receives a reassess-from-fresh-state result. - Read-only calls between selection and claim do not invalidate the claim. - Lock and lease primitives remain independently callable and behaviourally unchanged. - Lifecycle transitions are recorded auditably in Gitea. ## Required tests and validation Neutral entry holding no role. Capability absent before selection. Each activation binding. Activation refused while only a transient reservation exists. Expiration at cycle completion. Revocation on each of the five triggers. Return to neutral. Independence refusal for author-then-reviewer, author-then-approver, author-then-merger, and pusher-then-reviewer. Each claim-safety clause. A deliberate time-of-check/time-of-use substitution attempt. A generation advanced between pin and claim. Each fail-closed class. Two-worker and four-worker contention tests. An assertion that no refusal payload names a task other than the requested one. Read-only interleaving. Contract tests confirming the existing primitives remain schema-compatible and semantically equivalent under deterministic fixtures. ## Dependencies Until Child 1 delivers sanctioned structured relationship operations, the references below are informative bootstrap evidence only. They must not be treated as machine-enforced hard dependencies. Child 1 must backfill the appropriate structured relationships. Hard: Child 1 (Gitea claim record and publication protocol), #889 grants, #890 ownership record, #793 read-side fencing. Also Child 2, the inventory a caller selects from. ## Compatibility and rollout Additive; the allocator is untouched here. Existing primitives keep documented fields and typed failure contracts. Any intentional change to an existing contract is versioned with a documented migration. ## Rollback behavior Reverting removes neutral entry and task-scoped activation and returns workers to the previous role-bound namespaces only as a stop-and-halt state, not as a supported operating mode: autonomous cycles stop safely. Rollback never re-authorizes allocator selection, allocator-created claims, permanent roles, or role-first discovery. ## Documentation requirements The neutral-entry contract. The task-scoped capability lifecycle including every binding, expiry, and revocation trigger. The claim contract and typed failure taxonomy. The published rejection-rule artifact. ## Completion evidence Neutral-entry and lifecycle test results, the independence refusal matrix, the two- and four-worker contention results, the substitution-attempt results, and the published rejection-rule artifact. ## Reusable existing issues, PRs, and primitives #889, #890, #793, #952. Live primitives: issue locking; reviewer, merger, and adoption lease operations; task capability resolution; PR eligibility checking; master-parity assessment; identity lookup. ## Fundamental-workflow stage supported choose -> derive role -> validate -> claim — charter steps 1, 5, 6, 7, and 8, plus Contention is normal and Identity and independence.

Sign in to join this conversation.

Branches Tags

master

fix/issue-987-native-mcp-bootstrap

feat/issue-985-project-scoped-launcher-identity

fix/issue-983-cross-repo-base-ref

feat/issue-980-stale-worker-retirement

fix/issue-975-client-identity-heartbeat

fix/issue-973-cross-repo-canonical-roots

fix/issue-970-safely-resolve-missing-worktrees

fix/issue-969-native-mcp-bootstrap

feat/issue-664-break-glass-restart

feat/issue-708-mcp-namespace-attachment

feat/issue-665-restart-audit

fix/issue-700-durable-walls

fix/issue-704-prevent-env-workspace-bindings

feat/issue-707-cross-project-boundaries

fix/issue-690-review-profile-switch-guard

fix/issue-953-bootstrap-lock-provenance

feat/issue-949-native-fleet-inventory

fix/issue-943-runtime-context-helpers

fix/issue-945-owning-pr-renewal-evidence

fix/issue-941-scope-guard-bootstrap-wiring

docs/issue-930-remote-mcp-coupling-inventory

fix/issue-892-author-bootstrap-deadlock

fix/issue-686-detect-reject-manual-mcp

fix/issue-672-mcp-config-drift

fix/issue-689-deterministic-mcp-namespace

feat/issue-666-concurrent-mcp-restart-tests

feat/issue-659-maintenance-drain-mode

feat/issue-648-notifications-console

fix/issue-670-direct-master-incident

feat/issue-644-console-recovery

feat/issue-650-providers-insights

feat/issue-669-scoped-component-recovery

docs/issue-668-mcp-ha-rolling-restart

feat/issue-667-console-restart-controls

feat/issue-645-linkage-console

feat/issue-643-request-preview-initiate

fix/issue-897-permission-stale-runtime-classification

feat/issue-641-runtime-session-view

feat/issue-663-restart-classes

feat/issue-661-drain-proof-hard-gate

fix/issue-854-semantic-container-exclusion

issue-640

fix/issue-682-starlette-httpx2

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#992